Recover Stalled Subagent

You are a recovery operator. Your job is to take a single stalled subagent's branch name, salvage any uncommitted work in its worktree into a WIP commit pushed to origin, then remove the worktree cleanly — leaving the orchestrator a 6-line STATE_HANDOFF block it can drop into state.json's notes field for the affected initiative.

This skill does not query GitHub, reconcile plan state, edit state.json / plan.md / backlog.md / CHANGELOG.md, or decide whether the initiative should be retried / deferred. Those are orchestrator decisions. This is a worktree-rescue primitive.

Why this exists

Cold-subagent stalls (~1 in 10 spawn rate observed across 2026-04-17+18 passes) can emit a thought-fragment final message without the <<<RESULT>>> sentinel — see ~/.claude/prompts/_subagent-result-protocol.md Appendix B's malformed-result detection (the subagent result protocol extracted from backlog-sweep-execute.md). The orchestrator then cannot parse a PR URL, but the subagent may have already produced real edits in its worktree. 2026-04-18 pass-3 init-5 stranded 729 insertions across 4 prod files + 1 test file before a 3-turn manual recovery dance.

Manual recovery steps (each with its own foot-gun):

1. cd .worktrees/<id> and git status --porcelain — fine.
2. Stage files. If the operator reaches for git add -A, they pick up stray .vs/ caches, bin/, obj/, or other ignored-but-dirty paths. Explicit per-file git add -- <path> is mandatory.
3. Commit with a well-formed WIP message citing the original branch.
4. Push to origin (so the WIP is durable before worktree removal).
5. cd back to primary repo root — NOT from inside the worktree, or the next step fails.
6. dotnet build-server shutdown before git worktree remove --force, or the Windows testhost/VBCSCompiler file lock on tests/RoslynMcp.Tests/bin/{Debug,Release}/net10.0/ leaves a stale .worktrees/<id> directory that the orchestrator must rm -rf manually (Device or resource busy on git worktree remove). This is the fix shipped by initiative 5 in PR #288; see ~/.claude/prompts/backlog-sweep-execute.md § Worktree cleanup for the canonical discipline.
7. git worktree remove --force .worktrees/<id>.
8. Emit a STATE_HANDOFF block the orchestrator can paste into state.json.initiatives[n].notes.

The skill compresses steps 1-8 into one invocation that refuses cleanly on ambiguous state rather than partially-recovering.

Input

$ARGUMENTS is a single token: the remediation branch name created by the stalled subagent. It may be given with or without the remediation/ prefix:

• /recover-stalled-subagent remediation/foo-bar
• /recover-stalled-subagent foo-bar

Both resolve to branch remediation/foo-bar and worktree path .worktrees/foo-bar.

Required. If $ARGUMENTS is empty, print usage and exit without touching anything.

Preconditions (HARD GATES — refuse if any fail)

Refuse cleanly and emit nothing else if any of these hold. Never partially-recover.

1. Running inside a git repository. git rev-parse --git-common-dir must succeed. If not: "Refusing: not inside a git repository.".
2. Not already inside the target worktree. The skill operates from the primary repo root. If the current directory resolves under .worktrees/<id> for the target id, refuse: "Refusing: already inside .worktrees/<id>. cd back to the primary repo root and re-invoke.".
3. Worktree directory exists. .worktrees/<id> must be a directory on disk. If not: "Refusing: worktree .worktrees/<id> not found. Nothing to recover — the subagent may not have created a worktree, or it was already cleaned.". This is not a bug — sometimes a subagent stalls before git worktree add — it just means there is no recovery to do.
4. Branch matches worktree. git worktree list --porcelain must show .worktrees/<id> bound to refs/heads/remediation/<id>. If the worktree is bound to a different branch (stale reuse, manual edit), refuse: "Refusing: worktree .worktrees/<id> is bound to branch <other>, not remediation/<id>. Resolve manually.".
5. Branch is unpushed or ahead of origin. The skill's purpose is to durably save LOCAL work. If git log remediation/<id> --not origin/remediation/<id> --oneline is empty AND git status --porcelain is also empty (checked in Step 1 below), the skill reports "nothing to recover" and skips to Step 6 (worktree removal). If local is ahead of origin (commits not yet pushed), the skill pushes them in Step 4 regardless of whether there is additional uncommitted work.

Preconditions 1-4 block all action. Precondition 5 just affects which branches of the workflow run.

Workflow

Step 1 — Inspect worktree state

From the primary repo root, run:

git -C .worktrees/<id> status --porcelain
git -C .worktrees/<id> log remediation/<id> --not origin/remediation/<id> --oneline 2>/dev/null || true

Classify the recovery situation:

Print the classification (one line) before proceeding so the user can see the decision.

Step 2 — Stage explicit paths only

For full-recovery only.

Parse git -C .worktrees/<id> status --porcelain. Each line is <XY> <path> where XY is the two-column status code. For each path, issue an explicit git -C .worktrees/<id> add -- <path>. Handle deletions via git -C .worktrees/<id> rm -- <path> (for D / D). Handle renames by adding both source and dest.

Never use `git add -A` or `git add .`. Ignored-but-dirty paths under .vs/, bin/, obj/, .idea/ commonly appear in a stalled subagent's working tree; -A will pick them up and bloat the WIP commit with machine-specific cache data.

If the porcelain output is 200+ lines, print a one-line summary (count per status code) rather than dumping the full list; the full list is already in the git state.

Step 3 — Create the WIP commit

For full-recovery only.

Derive a <scope> token from the branch name: strip the remediation/ prefix, then take the first hyphen-delimited word as the scope. Examples:

If the scope heuristic produces an obviously-wrong token (e.g. a non-word like dr-9-12, a numeric-only prefix), fall back to wip as the scope.

Commit with message:

wip(<scope>): <branch>-partial (subagent stalled)

Recovered by /recover-stalled-subagent after the initiative-executor subagent emitted a malformed or missing <<<RESULT>>> sentinel. This commit preserves the working-tree edits as they were at the stall. The orchestrator must decide whether to retry the initiative (rebasing or continuing from this tip), hand-finish on this branch, or abandon and defer.

Use a heredoc for the message so the second paragraph's line breaks survive. Do NOT add a Co-Authored-By trailer — this is a recovery commit, not an authored change.

Step 4 — Push to origin

For full-recovery and push-only.

git -C .worktrees/<id> push -u origin remediation/<id>

If the push fails (auth expiry, network, existing branch on origin with divergent history), STOP and emit a failure STATE_HANDOFF — do NOT remove the worktree yet. The user must resolve the push manually before the worktree is safe to delete, or the recovered work is lost.

Step 5 — cd back to primary repo root and run build-server shutdown

After Step 4 (or immediately from Step 1 for nothing-to-recover):

cd "$(git rev-parse --git-common-dir)/.."   # from anywhere; resolves to primary repo root
dotnet build-server shutdown

dotnet build-server shutdown releases testhost.exe / VBCSCompiler.exe file locks left behind by verify-release.ps1 (and any dotnet test a subagent ran mid-stall). On Windows this is the only reliable way to release the locks on tests/RoslynMcp.Tests/bin/{Debug,Release}/net10.0/ that block git worktree remove --force. The command is a no-op when no build-server is running, so it is always safe to prepend.

The command prints one informational line even in the no-op case (e.g. "Build server didn't shut down due to an error or it wasn't running.") — ignore this; it is not an error.

See ~/.claude/prompts/backlog-sweep-execute.md § Worktree cleanup for the canonical shipped discipline (initiative 5 / PR #288).

Step 6 — Remove the worktree

git worktree remove --force .worktrees/<id>

If this still fails with Device or resource busy after Step 5's build-server shutdown, STOP and emit a failure STATE_HANDOFF — do NOT fall back to rm -rf .worktrees/<id> without the git metadata update, or the worktree will appear stale in git worktree list. The user must identify the remaining lock-holder (look for dotnet.exe / testhost.exe processes via tasklist | grep -i dotnet on Windows) and terminate it before re-running the skill.

Do NOT delete the branch remediation/<id>. The orchestrator's retry or defer decision is made from the full plan-state view; the branch (now carrying the WIP tip on origin) is the durable record the orchestrator needs.

Step 7 — Emit STATE_HANDOFF

Print exactly 6 lines, prefixed STATE_HANDOFF:, for the orchestrator to paste into state.json.initiatives[n].notes. The 6-line shape is a stable visual contract: the orchestrator reads the block to update notes — there is no automated parser for it. (The orchestrator's malformed-result handling lives in ~/.claude/prompts/_subagent-result-protocol.md Appendix B, cited above — NOT Appendix C, which is the cold-reviewer briefing and never parses this block.)

STATE_HANDOFF:
recovery: <full-recovery | push-only | nothing-to-recover | failed>
branch: remediation/<id>
wip-commit: <sha or "none">
origin-status: <pushed | not-pushed>
worktree: <removed | stale-blocked>

• recovery — which branch of the workflow ran.
• branch — always the full remediation/<id>, even when $ARGUMENTS omitted the prefix.
• wip-commit — SHA of the commit created in Step 3, or none for push-only / nothing-to-recover.
• origin-status — pushed if Step 4 succeeded or was skipped because origin was already up-to-date, not-pushed on Step 4 failure.
• worktree — removed if Step 6 succeeded, stale-blocked on failure (Step 5 + 6 exhausted without success).

After the STATE_HANDOFF block, emit a one-line human summary for the console (e.g. "Recovered 729 insertions across 5 files -> pushed as <sha> -> worktree removed cleanly.").

Non-goals

• Do NOT edit `state.json`, `plan.md`, `backlog.md`, `CHANGELOG.md`. The orchestrator drops the STATE_HANDOFF block into state.json's notes; this skill does not touch those files.
• Do NOT delete the `remediation/<id>` branch (local or remote). The branch tip is the durable record the orchestrator uses for retry/defer/hand-finish.
• Do NOT merge anything. There is no PR to open — this is pre-PR recovery.
• Do NOT decide retry vs defer. That is an orchestrator judgement based on plan state + the recovered WIP diff; the skill has neither.
• Do NOT run `verify-release.ps1` or any test. The WIP commit is known-partial; validating it defeats the purpose (the orchestrator expects to rebuild from this tip, not inherit its pass/fail status).

Refusal cases (explicit)

• Empty `$ARGUMENTS` → print usage and exit without touching anything.
• Not in a git repo → Precondition 1 refusal.
• Invoked from inside the target worktree → Precondition 2 refusal.
• Worktree directory does not exist → Precondition 3 refusal (reports "nothing to recover", exits 0 — not a failure mode).
• Worktree bound to wrong branch → Precondition 4 refusal with the actual bound branch.
• Push fails in Step 4 → stop; emit STATE_HANDOFF: with origin-status: not-pushed and worktree: stale-blocked; do NOT remove the worktree.
• Worktree removal fails after `build-server shutdown` → stop; emit STATE_HANDOFF: with worktree: stale-blocked so the orchestrator can surface it to the human operator in the Step 10 report.

Example

Input: /recover-stalled-subagent remediation/workspace-health-triage-subagent

Classification: full-recovery (4 modified files, 0 unpushed commits).
Staging explicit paths:
  A  .claude/agents/workspace-health-triage.md
  M  ai_docs/prompts/backlog-sweep-execute.md
  M  ai_docs/workflow.md
  M  README.md
Committing as wip(workspace): remediation/workspace-health-triage-subagent-partial (subagent stalled)... 1f3a9c2
Pushing to origin... ok
cd back to primary repo root...
Running dotnet build-server shutdown... (Build server didn't shut down due to an error or it wasn't running.)
Removing worktree .worktrees/workspace-health-triage-subagent... ok

STATE_HANDOFF:
recovery: full-recovery
branch: remediation/workspace-health-triage-subagent
wip-commit: 1f3a9c2
origin-status: pushed
worktree: removed

Recovered 4 modified files (623 insertions, 41 deletions) -> pushed as 1f3a9c2 -> worktree removed cleanly.

Distinct from related skills

• `/reconcile-backlog-sweep-plan` — reconciles state.json + plan.md against gh pr view reality. Runs AFTER recovery, not before. Use this skill first to rescue the worktree and save the WIP to origin; then run /reconcile-backlog-sweep-plan to update plan-state with the retry/defer decision (including the STATE_HANDOFF block in notes).
• `/close-backlog-rows` — deletes rows from ai_docs/backlog.md atomically. Unrelated — this skill does not touch backlog.md. A stalled initiative whose row is already closed in backlog.md is still recoverable; a stalled initiative whose row is still open is also recoverable. The row's status and the worktree's recoverability are orthogonal.
• `/ship` — commits+pushes+opens PR+merges. Runs ONLY when a subagent completed cleanly (it produced a <<<RESULT>>> with success: + a PR URL). A stalled subagent is the opposite case — no PR, no merge; recover via this skill instead.