--- name: subagent-driven-branch-ref-froze-stranded-commits description: | Diagnose and recover from "PR merged, but half my work is missing from main" cases in `superpowers:subagent-driven-development` (or similar one-fresh- subagent-per-task) sessions, where committed work survives in the worktree's `HEAD` chain but never makes it into the pushed branch ref. Use when ANY of these appears: (1) `gh pr view ` body claims "M files changed, N insertions" but `gh pr diff --name-only | wc -l` returns a smaller number than you expect (canary: PR-body file count > actual squash-commit file count), (2) the merged squash commit on main is MISSING entire files you remember creating (Dockerfile, route handler, deploy artefact, etc.) — and you wrote AND committed them per the subagent reports, (3) `git rev-parse HEAD` ≠ `git rev-parse ` in the worktree (HEAD is ahead), (4) `git reflog show ` ends earlier than `git log --oneline` on the same worktree (reflog gap = stranded zone), (5) tests that passed locally during the session now fail on main because files referenced by the committed code never landed, (6) the receiving session (or human running CI) discovers `ModuleNotFoundError`, `sql_path missing`, or similar "file referenced by code does not exist" symptom on freshly-pulled main. Root cause: one of the implementer subagents committed in a detached-HEAD state (e.g., after a `git checkout `, post-stash, post-cherry-pick abort, or an internal worktree reset by a tool). Subsequent subagents inherit the detached HEAD; each `git commit` advances HEAD but never updates the named branch. `git log` (without an explicit ref) walks from HEAD, so every per-task diagnostic looked correct. `git push ` ships the branch ref — i.e. the truncated tree. The squash captures only the truncated portion. Sister to `working-tree-edits-stranded-on-squash-merge` (uncommitted Edit() — different mechanism, same symptom class) and `pr-followup-commit-stranded-after-squash` (commits pushed after merge — different timing). Distinct from `pr-hijack-via-stale-worktree-branch-ref` (which is about overwriting a different branch upstream). author: Claude Code version: 1.0.0 date: 2026-05-18 --- # Subagent-driven session left commits stranded — branch ref froze while worktree HEAD advanced ## Problem You ran a long `superpowers:subagent-driven-development` (or similar fresh- subagent-per-task) session in a worktree. Each subagent did its task, committed its work, the controlling session ran spec + code-quality review per task, all green. At the end you pushed the worktree's branch to origin, opened a PR, CI went green, you squash-merged. Hours or one session later, somebody runs `pytest` on freshly-pulled main and gets a `ModuleNotFoundError`, a missing-file assertion, or a `sql_path missing` error pointing at code that **was definitely committed** during the session. `git log` in your old worktree still shows all the commits at the top of the branch. But on main, half of them are gone. The squash commit on main contains only the early portion of your work — typically the first N tasks before some specific transition point. Tasks after that point exist as commits in the worktree (`git log` shows them) but did not reach origin, did not reach the PR, did not reach the merge. ## Context / Trigger Conditions Strong signal **after** the merge: 1. `gh pr view ` body claims a file count (e.g. "55 files changed") that doesn't match the actual squash-commit file count (`git diff-tree --no-commit-id --name-only -r | wc -l`). 2. A test that passed locally during the session now fails on main because a file the test depends on isn't there. 3. Receiving session's first `pip install` or `pytest` surfaces `ModuleNotFoundError`, `sql_path missing`, or "no such file" referencing work the previous session reported as DONE. Strong signal **during** the session (catch it before pushing): 4. `git rev-parse HEAD` ≠ `git rev-parse ` in the worktree. The branch ref is behind. 5. `git reflog show ` has a reflog gap — the most recent `worktree-...@{0}` entry is older than the most recent commit shown by `git log`. The commits between branch-ref's frozen point and current HEAD are stranded. 6. `git status` in the worktree may or may not report `HEAD detached at ` — sometimes the detach happened mid-stream and a later subagent created the symbolic-ref linkage on its own, leaving an inconsistent state. Strong signal **across sessions**: 7. The pattern is specific to subagent-driven sessions because each subagent's tool calls run in an isolated process tree. A detached-HEAD transition introduced by one subagent (e.g. for a quick `git show` or post-stash recovery) propagates silently to every later subagent. A single human running the same workflow would notice the prompt change to `(HEAD detached at )`. ## Solution ### Prevention (the cheap path) Add an explicit pre-merge verification step before any `gh pr merge`: ```bash # 1. All three of these should produce the SAME sha: git rev-parse HEAD git rev-parse git rev-parse origin/ # 2. This should print NOTHING (zero commits ahead of remote): git log origin/..HEAD --oneline # 3. PR body file-count canary: # "N files changed" in the PR body should match gh pr diff --repo / --name-only | wc -l # 4. Reflog must extend to current HEAD: # Compare the topmost entry from each — they should agree. git reflog show | head -1 git log -1 --oneline ``` If any one of those is misaligned, **STOP**. Do not merge. Recover with the hotfix path below before pushing the merge button. ### Recovery (post-merge) If the merge already happened and you're seeing the symptom: ```bash # 0. Confirm the diagnosis. git -C rev-parse HEAD # the "true" tip git -C rev-parse # the frozen ref # If these differ, you have stranded commits. # 1. List exactly which commits are stranded (in topological order). git -C log ..HEAD --oneline # 2. Branch a recovery branch from current origin/main. git fetch origin git checkout -B recover/ origin/main # 3. Cherry-pick the stranded commits in order. git cherry-pick .. # (or list them individually if the range is non-linear) # 4. If the cherry-picks reference paths that have moved on main since # the original work was authored (common when other PRs landed # concurrently and reorganized files), add a follow-up commit that # fixes the path references. Don't try to fix them inside the # cherry-picks — that breaks the audit trail. # 5. Run tests against the merged result of recovery + main. # 6. Push, PR, merge. git push -u origin recover/ gh pr create --base main --title "fix: recover commits stranded by PR # squash" \ --body "" ``` The recovery PR should bundle BOTH the cherry-picks AND any path fixes required for the merged tree to function. Splitting them produces a half-broken main between the two merges. ### Forensic verification You can confirm the diagnosis precisely: ```bash # The reflog gap tells you WHERE the freeze happened. git -C reflog show | head -1 # vs git -C log --oneline -1 # The gap is everything between those two. # Pre-squash file count vs post-squash file count. gh pr diff --repo / --name-only | wc -l # what GitHub saw git -C diff-tree --no-commit-id --name-only -r | wc -l # These should agree. If both are smaller than your mental model, the # strand is the gap to your mental model. ``` ## Verification After the recovery PR lands: - `git diff origin/main origin/recover/` (BEFORE the recovery merge) should show only the stranded commits + the path fix. - After merge, the receiving session's pytest should be green. - `git -C ls-tree -r --name-only main | grep ` should return the file. - The original symptom (e.g. `sql_path missing`, `ModuleNotFoundError`) is gone. ## Example the-handover-repo project, session 6 (2026-05-18). Plan B's 18 TDD tasks executed via `superpowers:subagent-driven-development` in a worktree at `.claude/worktrees/plan-b-brief-runner` on branch `worktree-plan-b-brief-runner`. Each implementer subagent reported DONE with a commit SHA. The controlling session's per-task reviewers ran `pytest` from inside the worktree and saw all green. At the end, the controlling session ran: ```bash git push -u origin worktree-plan-b-brief-runner gh pr create --title "feat(plan-b): brief-runner core backend" ... # CI green; squash-merge. ``` PR [#9](https://github.com/wan-huiyan/the-handover-repo/pull/9) merged at `d84ceee7032f73a60dc0bb2af57939aa3f987625`. The PR body claimed "55 files changed, 2,295 insertions" — but the merge commit's file list had only 42. Diagnosis post-merge: ``` $ git rev-parse HEAD # in worktree b31d37349c8a1316883014d50108f90eb52f93f8 # Task 18 ✓ $ git rev-parse worktree-plan-b-brief-runner # in worktree e9bb471acdac9d14c2114097f3230e00a11bc493 # Task 11 ← FROZEN $ git reflog show worktree-plan-b-brief-runner | head -3 e9bb471 worktree-plan-b-brief-runner@{0}: commit: feat(brief-runner): CUSTOM_PARAMETER ... 2dbed0e worktree-plan-b-brief-runner@{1}: commit: feat(brief-runner): inline SQL parametrizer ... # No reflog entries for Tasks 12-18, but they exist as commits! ``` The seven commits between e9bb471 (Task 11) and b31d373 (Task 18) — sql_hash, Run Pack generator, all four route handlers, Dockerfile + cloudbuild + .gcloudignore + deploy runbook — were stranded. Recovery via [PR #14](https://github.com/wan-huiyan/the-handover-repo/pull/14) (squash `d808859`): ```bash git checkout -B recover/s5-plan-b-stranded-commits origin/main git cherry-pick bc9748b 947315a 77ff3ce 0a66933 29ff572 5972d34 b31d373 # All cherry-picks applied cleanly. # Then a follow-up commit to repoint analysis/SQL/*.registry.toml # sql_path values to analysis/SQL/handover/.sql, because PR #11 # had moved the SQL files under us during the original session. pytest -q # 166 passed, 1 skipped git push -u origin recover/s5-plan-b-stranded-commits gh pr create ... gh pr merge --squash --delete-branch ``` Time from discovery to recovered-on-main: ~25 minutes. Full post-mortem with forensics in `docs/analysis/2026-05-18-pr-9-stranded-commits.md` of the the-handover-repo repo. ## Notes - **The reflog gap is the single most reliable forensic.** `git log` walks from HEAD and shows everything. `git reflog show ` shows only what the branch ref actually saw — and a detached-HEAD commit doesn't update the branch ref. The asymmetry is your tell. - **`gh pr merge` will not warn you.** GitHub's merge button operates on the remote branch state, which is exactly what you pushed. The mismatch between your local worktree HEAD and the pushed ref is invisible to GitHub. - **The PR-body file count is the second canary.** Many session-handoff-style PR bodies summarize "M files changed, N insertions" from the controlling session's mental model. If that number is higher than `gh pr diff --name-only | wc -l`, something is wrong. - **A controlling session's `git log` is a false positive for "everything is fine".** Without `--branches=` it walks from HEAD. To validate the push will ship what you think, always compare against `origin/` explicitly. - **Subagents may detach HEAD for innocuous reasons.** A subagent that runs `git show ` followed by an interrupted `git checkout` (or relies on a tool that does so internally) can leave HEAD detached. Subsequent subagents will commit on the detached HEAD and never restore the branch ref. Adding `git symbolic-ref HEAD || echo DETACHED` to each implementer subagent's opening diagnostic catches this before the first commit. - **Concurrent PRs amplify the damage.** If main moved while your worktree was open, the squash-merge silently reconciles your truncated tree against the new main — sometimes producing functioning but partial output, sometimes producing broken-reference output. See the example above where PR #11 moved SQL files under PR #9 while it was open; both the strand AND the path drift bit at once. ## References - the-handover-repo [PR #9](https://github.com/wan-huiyan/the-handover-repo/pull/9) (the truncated original) and [PR #14](https://github.com/wan-huiyan/the-handover-repo/pull/14) (the cherry-pick recovery). - the-handover-repo post-mortem at `docs/analysis/2026-05-18-pr-9-stranded-commits.md` (full forensic timeline + remediation recipe). - Sister skills: [`working-tree-edits-stranded-on-squash-merge`](../working-tree-edits-stranded-on-squash-merge/SKILL.md) (uncommitted Edit() — different mechanism), [`pr-followup-commit-stranded-after-squash`](../pr-followup-commit-stranded-after-squash/SKILL.md) (commits pushed after merge — different timing), [`pr-hijack-via-stale-worktree-branch-ref`](../pr-hijack-via-stale-worktree-branch-ref/SKILL.md) (overwriting someone else's branch upstream — different problem entirely). - `superpowers:subagent-driven-development` skill — where this pattern emerges. Worth adding the pre-merge verification snippet to that skill's "Common Mistakes" section. - Pro Git §3.5 — [Remote Branches](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) on why `git log` and `git reflog show ` can disagree.