subagent-driven-branch-ref-froze-stranded-commits

Diagnose and recover commits stranded when a worktree HEAD advances past a frozen branch ref.

3|Updated May 8, 2026
One-click install
npx skills add https://github.com/wan-huiyan/agent-traffic-control --skill subagent-driven-branch-ref-froze-stranded-commits-wan-huiyan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: subagent-driven-branch-ref-froze-stranded-commits
Source: https://github.com/wan-huiyan/agent-traffic-control/tree/main/plugins/agent-traffic-control/skills/subagent-driven-branch-ref-froze-stranded-commits
Command: npx skills add https://github.com/wan-huiyan/agent-traffic-control --skill subagent-driven-branch-ref-froze-stranded-commits-wan-huiyan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? In long subagent-driven development sessions, a detached-HEAD transition can cause later commits to advance the worktree HEAD while the named branch ref stays frozen, so the pushed branch and squash merge silently omit committed work and main ends up missing files. ## Core Features & Use Cases - Detection canaries: Compare git rev-parse HEAD against the branch ref and origin/<branch>, check git reflog show <branch> for gaps, and cross-check the PR body file count against gh pr diff --name-only | wc -l. - Pre-merge verification gate: A four-step preflight (ref equality, zero commits ahead of remote, PR file-count canary, reflog alignment) that blocks merging a truncated tree. - Post-merge recovery: Branch from origin/main, cherry-pick each verified stranded commit oldest-first, fix path drift from intervening PRs in a follow-up commit, run tests, and ship a recovery PR. - Use Case: After merging a PR from a subagent-driven session, a fresh checkout of main fails with ModuleNotFoundError; use this Skill to confirm the reflog gap, cherry-pick the missing commits onto a recovery branch, and restore the files. ## Quick Start Ask the agent to verify whether my worktree HEAD, feature branch, and origin ref all point to the same commit and to recover any stranded commits before I merge the PR.

Frequently Asked Questions about subagent-driven-branch-ref-froze-stranded-commits

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I recover commits missing from main after a squash merge?▼

Confirm the strand by comparing `git rev-parse HEAD` with the branch ref in the worktree, then branch from `origin/main` and cherry-pick each verified missing commit oldest-first by full SHA. Run tests against the combined tree and ship a recovery PR that also fixes any path drift from intervening PRs.

Why does git log show my commits but the merged PR is missing files?▼

`git log` walks from HEAD, so it shows commits made on a detached HEAD that never updated the named branch ref. The push ships only the branch ref, so the squash merge captures the truncated tree while the extra commits remain stranded in the worktree.

How do I detect a detached HEAD before pushing a feature branch?▼

Check that `git rev-parse HEAD`, `git rev-parse <branch>`, and `git rev-parse origin/<branch>` all return the same SHA, and that `git log origin/<branch>..HEAD --oneline` prints nothing. Adding `git symbolic-ref HEAD || echo DETACHED` to each subagent's opening diagnostic catches detachment before the first commit.

What is the reflog gap that indicates stranded commits?▼

The reflog gap is when `git reflog show <branch>` ends earlier than `git log --oneline` on the same worktree. Because detached-HEAD commits never update the branch ref, the reflog records only what the ref actually saw, and the difference is exactly the stranded zone.

Does GitHub warn about a mismatch between local HEAD and the pushed branch?▼

No. GitHub's merge button operates on the remote branch state exactly as pushed, so a mismatch between local worktree HEAD and the pushed ref is invisible. The PR-body file count exceeding `gh pr diff <N> --name-only | wc -l` is a useful secondary canary.

When should I not use a commit range for cherry-picking stranded work?▼

Avoid `oldest..newest` ranges because they exclude the oldest commit, and inspect merge commits separately since cherry-picking one requires choosing a mainline parent. Cherry-pick each verified SHA explicitly, oldest first, to preserve a clean audit trail.