Worktrees and resources

Start with discern status and the lifecycle command's result. Ask your agent:

Identify the affected task and what discerndiscernA tool that installs and runs an agent development practice in a project. observed. Preserve its work, follow the named recovery, and tell me whether the change has landed separately from whether cleanup finished.

Keep the task's existing worktreeWorktreeA separate working copy and branch for one effort. where available. A clean or idle-looking row may belong to another effortEffortOne task carried through implementation and review: the work a worktree, its branch, and its submission all belong to.. The cases below help you choose the right repair without reconstructing the task from scratch.

A lifecycle command refuses

Read the named condition before retrying:

Condition	Next action
The worktree has uncommitted changes	Review and commit intended work. Preserve unfamiliar files and resolve their ownership before removing them.
The shared branch moved after the task's Proof	Have the agent run `discern update`, re-read the overlapping files it names, then run `discern done` and `discern accept` again.
The main checkout has local changes or is on another branch	Resolve those changes with their owner and return main to the trunkTrunkThe shared branch that accepted work joins, usually `main`. before retrying the operation that needs it.
Generated output needs repair	Run the named generator or refresh action, review its changes, and complete validation on the intended result.
Landing authorityLanding authorityPermission for a particular change to join the trunk. is missing	Review the proposed change and the requested consent. Passing Proof alone does not authorize landing; the submissionSubmissionAn effort's recorded request to land one exact commit. waits for you.

Acceptance reports on the task it was run for. Landing result fields give the structured contract.

Acceptance was interrupted partway

Read status and the acceptance result before attempting another landing. Ask whether the change landed, whether its Proof noteProof noteA durable copy of landed Proof, attached to the commit in Git. was recorded locally, and whether its worktree was removed.

discern records the landing before moving the shared branch, so a retry either finishes the remaining steps or rolls the attempt back. It never lands the same change twice and never spends your permission again. If landing did not happen, resolve the named blocker and follow the returned acceptance action.

Recover an interrupted acceptance walks through the full procedure.

Removal failed, or a removed path came back

Removal reports a remaining path or registration. Read which check failed. Close the editor, watcher, or shell still writing to that path, or perform the specific Git registration repair named in the result. Then repeat the reported lifecycle action.

Success means both the filesystem path and Git's registration are absent. If the same writer recreates the files, address that writer before trying again. Deleting a parent directory or clearing Git metadata bypasses the checks that distinguish this checkout from other work.

A removed directory reappeared. An editor can save into a checkout after it was removed. When discern has recorded that removal, status can identify the reappeared path. Close its writer and inspect the cleanup plan:

discern worktree prune --dry-run

Review the exact paths before authorizing the prune. It uses discern's own removal records and rechecks Git registration and filesystem state. A similar-looking neighboring directory is outside that authority. Unreadable paths, paths containing Git metadata, or paths that change during inspection are kept.

Success is the recorded path absent and its status finding cleared. If it appears again, the writer still needs attention.

A finished stage's checkout is taking space

Preview the available cleanup:

discern worktree prune --dry-run

A contained worktree has a clean, idle checkout whose committed work is already included in another live branch. The plan names that containing branch. If you no longer need the earlier checkout or its local files, preview its explicit reclaim option:

discern worktree prune --contained --dry-run

Reclaim removes the checkout, its resources, and its worktree-local Proof after confirmation. Its branch ref remains available for discern start --from <branch>. A later discern await --green watch on the removed checkout refuses and points to the containing branch.

For finished work ready to land, use acceptance first. A landing removes the worktree, its resources, and its branch when the branch holds nothing beyond the landed submission.

A healthy task should pause without its checkout

Use Park when the unlanded branch should remain resumable but its checkout and resources are no longer needed:

discern worktree park <target> --dry-run
discern worktree park <target>

Review the preview before confirming. It names the kept branch and commit, retained task wording, destroyed resources, removed checkout, and consumed worktree-local Proof, submission, and landing grant. Park refuses a dirty, unreadable, setup-incomplete, trunk, detached, or branch-mismatched checkout. It has no force option: a branch cannot preserve uncommitted files.

After success, open the deskDeskAn interactive view of the project's tasks and the actions available for them.'s commands menu and choose Resume for the branch, or resume directly:

discern start --from <parked-branch>

The saved title and brief become defaults when the branch still points at the parked commit. Use Reclaim for a contained stageStageA group in the order the gate runs work. and Drop for an effort you intend to discard.

Cleanup kept something you expected it to remove

Read the reason it was kept. Automatic cleanup needs recorded ownership, matching identity, and the relevant current-state checks. A merged branch or a familiar name alone cannot establish that discern owns its checkout.

For a deliberately chosen foreign checkout, discern worktree drop <worktree> accepts its exact id, path, local branch, or full local ref. Review that destructive action explicitly. When discern cannot prove ownership of the branch, it keeps the branch ref.

For a landed task, a worktree that stayed because its branch holds unlanded commits and a worktree whose cleanup needs recovery are different outcomes. The first is a protection; the second names unfinished cleanup to resolve. Use the returned reason rather than assuming every remaining directory is a failed removal.

A landed task's worktree stayed behind

The change is on the shared branch, and its worktree is still there. The landing result and discern status say why in one sentence. The reasons, and what finishes cleanup:

Why it stayed	What finishes cleanup
The branch gained commits after the submission	Those commits never landed. Preserve them; the agent runs `discern done` and then `discern accept` for them from that worktree.
Removal could not complete	Stop the preview or other program still writing in the directory, resolve any resource the result names, then run `discern worktree prune` from the main checkout.

Neither undoes the landing, and neither needs the change approved again. If the result says cleanup needs recovery rather than that the worktree stayed, follow the named recovery instead.

A branch or worktree was dropped by mistake

Find the recovery ref printed by discern worktree drop. The dropped-branch recovery procedure shows how to list the retained refs and restore committed work.

Those refs preserve committed tips, with a bounded retention count. They cannot recover uncommitted, untracked, or ignored files discarded by a forced drop. For a ref lost outside discern's lifecycle, investigate Git's reflog before further cleanup.

A resource, port, or environment value is wrong

Run these from the affected worktree, using the resource name from its configuration:

discern identity
discern identity --resource <name>

Have the agent compare those values with what the application actually reads. For example, a preview showing another task's saved recipes may be connected to that task's database. Finding the mismatch is more useful than creating another resource immediately.

Symptom	Next action
Resource creation failed or its outcome is uncertain	Read the failing output and recorded recovery. A retry first uses the destroy action recorded before creation to reconcile uncertain state. If that is unavailable or fails, resolve the named resource before another create attempt.
An inherited environment value is missing	Check that its key is in `[worktree].inherit_env` and is defined in main's configured env files. Only named values are copied, not entire files.
The wrong env value wins	Check the ordered `[worktree].env_files` list. The last file defining a key supplies its value. See the env rules.
A resource remains after its worktree vanished	Preview `discern worktree prune --dry-run` and inspect the recorded resource. Garbage collection acts on eligible recorded resources; a resource configured out of it needs the project's own teardown.

Changing a value in main does not update an existing worktree automatically. Make the intended correction in the affected worktree, following the project's configuration, and verify the application now uses its own identity and resource.

Keep the resource ledger during recovery. It stores the recorded teardown action; uninstall refuses while recorded resources remain.

Ignored files changed under a worktree

Read the named files before removing the checkout. Ignored files may hold local settings or data that no commit preserves. Copy out anything you want to keep.

When enabled, discern compares ignored files with the baseline recorded during worktree setup. That comparison is advisoryAdvisoryA finding that suggests attention without blocking work.; it does not preserve the file contents for you.

For the optional comparison setting, see [worktree].track_ignored_drift in the configuration reference. Disabling the report does not turn local-only files into recoverable Git history.

A fleet row looks wrong

discern status from the main checkout surveys every worktree. Open the row in discern desk and choose Show recovery steps when it reports broken setup, incomplete setup, a missing checkout, or unreadable Git state. The recovery view separates what discern observed from what remains unavailable:

the exact Git or setup failure and command;
Git registration, branch reachability, and filesystem presence;
checkout, branch, task, and resource identities;
setup-ready marker and step-journal evidence;
the last lifecycle result and one next command.

Retry setup is available when no setup step remains ambiguous. A journal with a running one-shot step serves the specific owner-confirmed recovery command. A missing journal beside configured one-shot steps serves discern worktree setup begin --dry-run for inspection. An unreadable Git registration serves its failed Git command or discern doctor. The task remains intact while those checks are unresolved.

If main has local changes or unreadable Git state, choose Inspect main checkout. Its detail can show status and diff or open a shell or editor at main. It also names the landing and cleanup operations that remain blocked. Main stays outside the task list, and agent work remains in linked worktrees.

After a refused repair or cleanup, the desk surveys again. Task changed; refreshed means the selected row changed or disappeared. A parked task opens its resumable branch. A task found in local landing evidence reports Task landed; refreshed and remains available under Recent completed tasks.

Never adopt another effort's worktree because it looks idle or clean. Do not repair a confusing row by deleting a path or Git registration by hand. Follow its diagnosis first. Park, Reclaim, Drop, and prune each apply their own ownership and final-state checks.

When to stop

Pause destructive cleanup when you cannot account for the work or path it would remove, or when the reported owner confirmation has not been given. Resolve an active writer, ambiguous setup effect, or uncertain external resource before retrying its teardown.

If the supported recovery still fails, keep discern status --json and the lifecycle result for investigation. Preserve the named state; deleting Git records by hand can remove the evidence the recovery needs.