wu:claim

Claim WU and create worktree

pnpm wu:claim --id <wuId>

From --help:

Retained-work reclaim: after wu:release --keep-branch, the original assigned user continues the same WU in place with this ordinary claim when its lane branch and worktree keep unlanded source.

Refusals, each before any change: a Git user other than the assigned and original owner (caller-identity); a live competing claim on origin, proved against the current claim generation (live-competing-claim); missing or conflicting claim history (provenance-missing, provenance-conflict); a mismatched WU, lane, branch, worktree or integration target, including a released claim pinned to another target (target-mismatch); an unreadable worktree record, or one with uncommitted changes (malformed-binding); an unreadable origin (origin-unreadable); an origin copy of the lane that diverged (remote-diverged). A competing lane owner is refused by the lane lock.

Origin copy of the lane: an ancestor of the retained branch is fast-forwarded. A retained branch that is a governed rebase of it (each origin-only commit has a patch-identical twin on the branch, or touches only lifecycle bookkeeping and this WU record) is published under a lease on the observed origin tip, with no reset and no force push. A genuinely divergent copy is refused with both tips named; re-run with --replace-remote-lane to reclaim from the retained branch, which keeps the origin tip under refs/lumenflow/lane-backups/<WU>/<sha> in this repository. Nothing is discarded silently.

Atomic boundaries: verification and the re-attestation are read-only. The canonical claim push to origin is the single commit point; on every attempt it re-checks that the Ready record and claim generation are still the proven ones. The claim mints a fresh session and a new claim generation; the released generation stays dead. Adoption re-checks the target, branch and tip, then adds one lane commit that changes only the WU record, set to the new generation's canonical record. This claim makes and judges that commit itself, as a temporary-branch lifecycle transaction, so a lane cut with an older CLI (whose own hooks cannot recognize it) is reclaimed too; no hook is skipped, and a commit with any other path or a record origin never published is refused. If that commit is refused, the worktree and index are unchanged and the claim is rolled back and read back from origin until it is verified Ready (re-run on the current origin when another push raced it). The branch, the index entries and every staged, unstaged and untracked byte are kept; nothing is deleted. A claim whose rollback could still not be verified is released by its own session with wu:release --keep-branch, then reclaimed with this command.

Claim-source publication: the first claim into a draft or open initiative moves that initiative to in_progress in the same claim commit. The claim ref, lane and genesis then publish in one atomic push; a refusal before any publication journal exists is retried in place up to 5 times, re-reading origin between attempts, and a journaled refusal is never retried. A failed phase prints its cause. When retries are exhausted the claim stays on origin and the output names the cause and the next command, wu:release --id <WU>.

Integration target binding

The claim pins its integration target (remote, branch, repository identity and baseline), its metadata authority and its trusted policy identity for its whole life. Later changes to the workspace defaults, a remote alias or initiative membership never retarget it: every later lifecycle command uses the pinned target.

Refusal: a new claim is refused, before any change, while another active claim holds a different integration target (remote, branch or repository identity), or is a pre-binding claim whose original destination Git history cannot prove (an unproven destination is never permission; a pre-binding claim is compared by its proven remote/branch pair). The proof is read-only and never acts as the claim holder. The refusal names each such WU. Finish (wu:prep, then wu:done) or release (wu:release) those claims, or have their owners bind them, then claim again. An existing origin/main workspace and another preconfigured remote and trunk each stay compatible with their own claims; a claim never moves between topologies inline.

Repair: a claim that predates integration-target binding is upgraded through the governed same-target route. Run pnpm wu:repair --id WU-XXXX --claim --integration-target --check first, then the same command without --check. It adopts only the destination and policy that canonical and remote evidence prove, and refuses guesses and conflicts. No command retargets an active claim.

Stale-generation claim marker

A claim policy refresh whose publication failed (for example at a pre-push hook) leaves the remote marker refs/lumenflow/claims/<WU> at the previous generation while the local claim moved on. wu:release deletes that marker, and wu:claim replaces it, only on positive proof that it is not live: its generation is the newest in the claim generation history chain of the WU, it has the same repository identity and lane branch, and the canonical ledger records a claim of that generation by the same user followed by a release. The delete or the replacement leases the observed marker sha. A marker that cannot be proven (another user, history missing, no recorded release) is kept and the refusal names the marker generation, the claim generation, the missing evidence and the one next step.

Options:

Flag	Description	Required
`-i, --id <wuId>`	Work Unit ID. Required except on wu:create, which auto-generates the next sequential ID when omitted.	Yes
`-l, --lane <lane>`	Lane name (e.g., “Operations: Tooling”)	No
`-w, --worktree <path>`	Set the local worktree path; claims verify its confined realpath and exact Git registration	No
`-b, --branch <branch>`	Set the effective claim branch; local worktree claims persist its verified binding	No
`--branch-only`	Use branch-only mode without a claimed lane worktree; completion publishes from an isolated temporary worktree	No
`--pr-mode`	Use PR mode (create PR instead of auto-merge)	No
`--no-auto`	Skip auto-updating YAML/backlog/status	No
`-f, --force`	Force operation	No
`--force-overlap`	Override a code-path overlap on generated outputs, lockfiles, ledgers or baselines (requires —reason); not needed for ordinary source, where overlap is advisory	No
`--fix`	Auto-fix common YAML validation issues	No
`-r, --reason <reason>`	Reason for action (required with —skip-gate, —override-owner)	No
`--allow-incomplete`	Allow claiming with incomplete spec (bypasses spec completeness, NOT schema errors)	No
`--cloud`	Use cloud/branch-pr mode: no worktree; the claim commits the WU record, projections and events ledger together on the active branch, and completion is PR-based (cloud agents and MCP callers)	No
`--resume`	Resume a WU from a crashed/killed agent (handoff) by taking over the existing worktree and updating the lock with new PID. Fails if original PID is still running (safety) or worktree does not exist.	No
`--skip-setup`	Skip automatic pnpm install in worktree after creation (faster claims when deps already built)	No
`--no-push`	Skip pushing claim branch or canonical updates (air-gapped/offline)	No
`--wait-for-lane`	Queue the claim while an in-progress WU overlaps an unmergeable path (lockfiles, generated output, ledgers, baselines) and auto-fire once every blocker WU has merged; ordinary-source overlap never queues	No
`--wait-timeout-seconds <seconds>`	Maximum seconds to wait for blocker WUs to merge before giving up (default 3600, used with —wait-for-lane)	No
`--cancel-queue`	Cancel an active queued claim for —id (pairs with —wait-for-lane)	No
`--sandbox`	Launch a post-claim session via wu:sandbox (use — <command> to override the default shell)	No
`--replace-remote-lane`	Retained-work reclaim only: when origin holds a lane copy that diverged from the retained branch, reclaim from the retained branch, publish it under a lease on the observed origin tip, and keep that tip under a local backup ref	No
`--dispatch-key <key>`	Host dispatch key recorded atomically with the claim (with —worker-id); a host that lost the claim acknowledgment adopts only its own claim	No
`--worker-id <id>`	Stable worker execution id recorded with —dispatch-key on the claim	No

← Back to CLI Commands