wu:recover

Recover WU state, including restoring missing active worktrees. Same-user continuation is limited to resume and requires the authenticated target-WU caller, assigned Git user, and live origin claim.

pnpm wu:recover --id <wuId>

Integration target binding

Active-claim recovery uses the claim’s pinned integration target (remote, branch, repository identity), never the current workspace default. --action resume refuses a claim whose pinned target cannot be proven, and no recovery action retargets a claim.

For active pre-binding claims: 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.

For a done ordinary worktree with a genuine pre-binding seed, --action retire uses fresh configured delivery proofs (normally origin/main), rather than an absent claim pin: the done record and stamp, exact registered path, landed lane HEAD, no remote claim and no visible directory occupant must be provable. Modern metadata is never treated as legacy absence. See retire a done worktree with a pre-binding seed.

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
`-a, --action <action>`	Recovery action: resume (same-user continuation requires an authenticated session for this WU, the assigned Git identity and a live origin claim; when the claim session is proven dead — its record is gone (a clean agent:session-end removes it), predates this host boot, or names an owner process the launcher declared at registration (see the lifecycle docs) that has exited — the assigned user needs no session: resume mints one through the agent:session —resume path, keeps the worktree, and prints the export and wu:brief commands; a claim you blocked is continued the same way and stays blocked until wu:unblock; a live session or another user is refused), restore, reset, nuke, cleanup, reconcile (non-destructively unstage a proven rolled-back completion tuple), retire (non-destructive, never forced — remove the worktree and local lane branch of a WU already settled on main: released/cancelled/done, proven durable on a branch or tag that git ls-remote shows on origin, or, for a done WU, because every change on the lane is already on the delivery branch (a squash-landed copy); a local-only ref alone never counts and refuses with RETIRE_NOT_DURABLE_ON_REMOTE, naming the unlanded commits; a stale policy pin never refuses a settled WU; a worktree registered inside another worktree is retired only when its WU is done and its HEAD is on the delivery branch, no claim marker exists on the remote and no live process uses it, and the removal writes an audit record; an ordinary done worktree with a genuinely pre-binding seed is retired by the same freshly fetched delivery proofs with an exact recorded path, no modern claim metadata, and legacy_seed_landed_proof audit entries (RETIRE_LEGACY_UNPROVEN on an unprovable fact); malformed modern bindings never use this legacy route; the leftover directory of a done WU that git no longer registers is deleted only when it is inside the worktrees root, no worktree is registered inside it and no process uses it, else it refuses with RETIRE_LEFTOVER_UNPROVEN)	No
`-f, --force`	Required for destructive actions (reset, nuke)	No
`--discard-changes`	Allow reset to proceed even if worktree has uncommitted changes	No
`-j, --json`	Output as JSON	No
`--override-owner`	Override ownership check (requires —reason)	No
`-r, --reason <reason>`	Reason for action (required with —skip-gate, —override-owner)	No
`--handoff-receipt <receipt>`	Consume a durable wu:brief handoff receipt for cross-session recovery	No
`--publication-attempt <attemptId>`	Freshly reattest one exact claim publication attempt during authenticated resume recovery; settles every attestable retained attempt of the same claim generation	No

← Back to CLI Commands