Run any Skill in Manus with one click

subagent-read-stale-worktree-needs-head-pin

Stars2

Forks0

UpdatedJuly 8, 2026 at 11:09

Read-only subagents (Explore / code-explorer / general-purpose dispatched to AUDIT or READ code, not write) silently return line numbers and "what exists" claims from the WRONG git worktree in a repo with many worktrees — confidently-wrong stale data, no error. Use when: (1) you dispatched 1+ read/audit subagents and their cited file:line numbers, function locations, or "X is/isn't present" claims DON'T match what you read directly in your pinned worktree; (2) `git worktree list` shows 2+ paths (especially a `.claude/worktrees/` fan-out); (3) a subagent reports an issue is "not implemented" / "missing" when you can see it on fresh main; (4) two parallel audit subagents disagree with each other or with origin/main. Fix: every read-subagent prompt must pin the ABSOLUTE worktree path AND require the agent to run `git -C <path> rev-parse HEAD` and confirm the expected SHA before reading. Distinct from subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (`ls`

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

wan-huiyan

wan-huiyan/agent-traffic-control

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	subagent-read-stale-worktree-needs-head-pin
description	Read-only subagents (Explore / code-explorer / general-purpose dispatched to AUDIT or READ code, not write) silently return line numbers and "what exists" claims from the WRONG git worktree in a repo with many worktrees — confidently-wrong stale data, no error. Use when: (1) you dispatched 1+ read/audit subagents and their cited file:line numbers, function locations, or "X is/isn't present" claims DON'T match what you read directly in your pinned worktree; (2) `git worktree list` shows 2+ paths (especially a `.claude/worktrees/` fan-out); (3) a subagent reports an issue is "not implemented" / "missing" when you can see it on fresh main; (4) two parallel audit subagents disagree with each other or with origin/main. Fix: every read-subagent prompt must pin the ABSOLUTE worktree path AND require the agent to run `git -C <path> rev-parse HEAD` and confirm the expected SHA before reading. Distinct from subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (`ls` outside any worktree), and multi-worktree-file-url-stale-content (browser file:// bookmark).
author	Claude Code
version	1.0.0
date	"2026-06-01T00:00:00.000Z"
disable-model-invocation	true

Read-subagent reads a stale worktree — pin the path AND verify HEAD

Problem

In a repo with many git worktrees (e.g. a .claude/worktrees/ fan-out of 20+ checkouts, many on stale feature branches), a read-only subagent dispatched to audit/read code can resolve the target files inside the wrong worktree and return confidently-wrong results: line numbers from an old checkout, "function X is at line 1029" when on fresh main it's 1473, or "cov_intel is NOT passed to the template" when it demonstrably IS. There is no error — the agent reads real files and reports real (but stale) facts. This is worse than the bash-cd worktree trap, which at least commits to a visibly-wrong branch; here the only signal is that the cited lines don't match reality.

Context / Trigger Conditions

You fanned out 1+ Explore / code-explorer / general read subagents to audit issues, map a feature, or check "what already exists vs what's missing."
A subagent's cited file:line, function location, or presence/absence claim contradicts your own direct Read-tool read of the same file in the worktree you're operating in.
git worktree list shows 2+ working trees; the repo has a .claude/worktrees/<name>/ style fan-out, or sibling clones of the same project exist on disk.
Two parallel audit subagents disagree with each other, or with git show origin/main:<path>.
A subagent claims an already-shipped feature is "not implemented" (it read a pre-feature branch).

Solution

Prevention (do this in every read-subagent dispatch):

Put the absolute worktree path in the prompt and say "operate ONLY in this dir; use absolute paths under it."
Add a hard gate: "Before reading anything, run git -C <abs-path> rev-parse HEAD and confirm it equals <expected-sha>. If it doesn't, stop and report the mismatch."
For "what's on main" audits, tell the agent to read via git -C <path> show origin/main:<file> rather than the working tree, so a stale checked-out branch can't mislead it.

Recovery (when you suspect a stale-read already happened):

Trust your own direct read over the subagent's. If the subagent's line numbers don't match what you just Read, the subagent is stale — not you.
Re-verify the specific claim directly: git -C <your-worktree> rev-parse HEAD, git show origin/main:<path>, gh pr view <N> --json state,mergedAt, targeted grep.
Discard the stale audit's specifics (line numbers, "missing" claims); keep only conclusions you independently re-confirmed.

Verification

The subagent echoes the expected HEAD SHA at the top of its report (proves it read the right tree).
Re-running the same audit with the pin produces line numbers that match your direct reads.
The "missing feature" claim flips to "present at " once read from the right tree.

Example

S84 (the-causal-impact-repo, ~25 worktrees): 3 parallel Explore agents audited issues #178/#181/#191 against origin/main. Two returned stale line numbers (features() "at 1029", cov_intel "not passed") from an old worktree — I'd directly Read it at line 1473 with cov_intel passed. Caught it because the cited lines didn't match my read; re-verified directly (gh pr view 231/232 both merged; prep.py keys) and ignored the stale audits. The 3 review subagents dispatched afterward all carried git -C <path> rev-parse HEAD == <sha> gates and were reliable. Net: pin + HEAD-verify every read-subagent in a multi-worktree repo; distrust subagent line numbers that don't match your own.

Notes

The same pin protects review subagents (reviewing a diff/commit): pass the worktree path + the commit SHA, and have them confirm git rev-parse HEAD before git show <sha>.
Background subagents can't write, but they CAN read the wrong tree — pinning matters even for read-only fan-outs.
See also: subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (ls from outside any worktree), multi-worktree-file-url-stale-content (browser file:// bookmark), flask-debug-cross-worktree-edit-stale (server reload reads wrong worktree), stale-backlog-triage-adversarial-verify (verify "what's already shipped" against live main).

More from this repository

same repository

gh-pr-merge-worktree-checkout-trap

wan-huiyan/agent-traffic-control

Diagnose and bypass `gh pr merge --squash --delete-branch` failing with "failed to run git: fatal: 'main' is already used by worktree at ..." when another git worktree has main checked out. Use when: (1) you run gh pr merge and see this exact error, (2) you have multiple worktrees in the repo (e.g. `.claude/worktrees/*`), (3) the error appears even though the GitHub merge itself looks fine. The merge SUCCEEDED on GitHub — only gh's local-side effect (post-merge `git checkout main`) failed. Verify via `gh pr view N --json state,mergedAt`; if state=MERGED, you're done. This also applies to `gh pr checkout` and any other `gh` subcommand that tries to touch the local main branch while another worktree has it claimed. v1.2.0 (2026-05-26) adds the sequential-error variant: if you re-run from the main-repo worktree after the first error, you can then hit "cannot delete branch <feature-branch> used by worktree at <feature-worktree>" — same one-checkout-per-branch invariant, this time applied to the feature branch. Cl

2026-07-102

cjk-structured-llm-output-truncates-json-needs-2x-tokens

wan-huiyan/agent-traffic-control

When generating LONG Chinese/Japanese/Korean (CJK) STRUCTURED output (a big JSON report, a multi-section document) from an LLM chat API, the response truncates mid-JSON and your parser throws "no parseable JSON" / "Expecting ',' delimiter" / JSONDecodeError — even though the SAME prompt in English worked. Root cause: CJK is token-heavy (≈1–2 tokens per character vs ≈0.25 for English), so a report that fit your max_tokens in English overflows it in Chinese. Some models ALSO hard-cap output well below what you request (e.g. qwen-max caps at 8192) and silently truncate. Use when: a zh/ja/ko structured-generation run fails JSON parsing, worked in English, or a specific model truncates while others on the same prompt succeed. Covers the ~2× token budget rule, per-model output caps, and a salvage that recovers the complete sections from a truncated object.

2026-07-082

design-subagent-with-plan-schema-executes-and-deploys-live-infra

wan-huiyan/agent-traffic-control

Catch the failure where a subagent dispatched ONLY to DECIDE/DESIGN (a judge, a design-panel synthesizer, a "pick the mechanism" agent) instead EXECUTES the plan — and, having full Bash/gcloud/bq, provisions LIVE infrastructure (creates a BQ dataset/table, a DTS scheduled query, a log metric, a paging alert policy) and even git-commits code — when you only wanted a recommendation. Use when: (1) you author a Workflow/Agent whose structured-output schema has a field that reads as an execution mandate ("this_session_plan", "exact ordered steps", "deploy_steps", "what was provisioned") and the agent has mutate-capable tools; (2) a design/judge agent's result says "DONE — created X" / "provisioned live" instead of "recommend X"; (3) you are about to trust a decision agent's self-report of what it changed. The agent treats a "plan/steps" output field as a TODO to carry out, not a proposal. Fix: constrain design/decision subagents READ-ONLY in the prompt (explicitly: "do NOT run any mutating bq/gcloud/git command; S

2026-07-082

git-add-u-after-async-post-commit-hook

wan-huiyan/agent-traffic-control

Prevent (and recover from) `git add -u` + `git commit --amend` + `git push --force-with-lease` catastrophically rolling thousands of unrelated tracked-file deletions into an amended commit when the project has an async post-commit hook that mutates tracked files (e.g. regenerates `docs/site/*.html`, `docs/site/index.html`, `MEMORY.md`, or any other tracked artefact in a background `&` / `nohup` / "running … in background" process). Use when: (1) you just made a small commit, the post-commit log line says `[post-commit] … running … in background`, and you're about to amend with corrected message / typo / issue ref; (2) `git commit --amend` output reports `1000+ files changed, … insertions, NNN,NNN deletions(-)` when you only intended a 6-file change; (3) the force-pushed branch on origin shows a massive deletion diff and `git status` after the amend shows previously-tracked files like `MEMORY.md`, `.github/`, `.cursor/`, `scripts/` as Untracked; (4) you ran `git add -u` reflexively before `--amend` on a projec

2026-07-082

main-bash-cwd-persists-nested-worktree

wan-huiyan/agent-traffic-control

Prevent and diagnose nested git worktrees created at the wrong filesystem path when orchestrating parallel work from the main Claude Code agent. Use when (1) you ran `git worktree add .claude/worktrees/<name> ...` from the main agent's Bash tool, (2) `git worktree list` shows the new worktree at an unexpected nested path like `.claude/worktrees/<previous-worktree>/.claude/worktrees/<name>` instead of the intended top-level location, (3) a subagent dispatched to the intended path reports "worktree path mismatch" or operates from a longer nested path. Root cause: the main agent's Bash tool **persists cwd between calls** (per its docstring: "The working directory persists between commands"). An earlier `cd /abs/path && cmd` changes the main shell's cwd; a later `git worktree add <relative-path> ...` resolves against that persisted cwd rather than the project root, silently creating nested layouts. This is the **inverse** of the subagent variant (subagent-bash-cd-wrong-worktree) — subagent shells reset per call,

2026-07-082

merged-pr-not-deployed-gate-label-missing

wan-huiyan/agent-traffic-control

Diagnose "I merged my PR + CI is green but the live service still doesn't show my changes." Use when: (1) a code-bearing PR has been squash-merged into main with all required status checks passing, (2) the user reports the change is still missing from the deployed environment minutes-to-hours later, (3) the repo has a `pull_request: types: [closed]` workflow gated on a label (typically `auto-deploy`, `deploy`, `ship-it`) and/or a path filter, (4) the deploy workflow's run row in `gh run list` shows `conclusion=skipped` for your PR's branch — visually identical to `success` in the run summary. Distinct from `gha-auto-deploy-never-ran-skipped-mask` (sister skill: same "skipped masks failure" symptom class but different cause — that skill is about the FIRST time the gate fires and the deploy step then hits a permission gap; THIS skill is about the routine case where the gate correctly works and the PR simply didn't satisfy it). Trigger phrases: "I can't see the changes live", "merged but not deployed", "PR shipp

2026-07-082

name	subagent-read-stale-worktree-needs-head-pin
description	Read-only subagents (Explore / code-explorer / general-purpose dispatched to AUDIT or READ code, not write) silently return line numbers and "what exists" claims from the WRONG git worktree in a repo with many worktrees — confidently-wrong stale data, no error. Use when: (1) you dispatched 1+ read/audit subagents and their cited file:line numbers, function locations, or "X is/isn't present" claims DON'T match what you read directly in your pinned worktree; (2) `git worktree list` shows 2+ paths (especially a `.claude/worktrees/` fan-out); (3) a subagent reports an issue is "not implemented" / "missing" when you can see it on fresh main; (4) two parallel audit subagents disagree with each other or with origin/main. Fix: every read-subagent prompt must pin the ABSOLUTE worktree path AND require the agent to run `git -C <path> rev-parse HEAD` and confirm the expected SHA before reading. Distinct from subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (`ls` outside any worktree), and multi-worktree-file-url-stale-content (browser file:// bookmark).
author	Claude Code
version	1.0.0
date	"2026-06-01T00:00:00.000Z"
disable-model-invocation	true

Read-subagent reads a stale worktree — pin the path AND verify HEAD

Problem

Context / Trigger Conditions

You fanned out 1+ Explore / code-explorer / general read subagents to audit issues, map a feature, or check "what already exists vs what's missing."
A subagent's cited file:line, function location, or presence/absence claim contradicts your own direct Read-tool read of the same file in the worktree you're operating in.
git worktree list shows 2+ working trees; the repo has a .claude/worktrees/<name>/ style fan-out, or sibling clones of the same project exist on disk.
Two parallel audit subagents disagree with each other, or with git show origin/main:<path>.
A subagent claims an already-shipped feature is "not implemented" (it read a pre-feature branch).

Solution

Prevention (do this in every read-subagent dispatch):

Put the absolute worktree path in the prompt and say "operate ONLY in this dir; use absolute paths under it."
Add a hard gate: "Before reading anything, run git -C <abs-path> rev-parse HEAD and confirm it equals <expected-sha>. If it doesn't, stop and report the mismatch."
For "what's on main" audits, tell the agent to read via git -C <path> show origin/main:<file> rather than the working tree, so a stale checked-out branch can't mislead it.

Recovery (when you suspect a stale-read already happened):

Trust your own direct read over the subagent's. If the subagent's line numbers don't match what you just Read, the subagent is stale — not you.
Re-verify the specific claim directly: git -C <your-worktree> rev-parse HEAD, git show origin/main:<path>, gh pr view <N> --json state,mergedAt, targeted grep.
Discard the stale audit's specifics (line numbers, "missing" claims); keep only conclusions you independently re-confirmed.

Verification

The subagent echoes the expected HEAD SHA at the top of its report (proves it read the right tree).
Re-running the same audit with the pin produces line numbers that match your direct reads.
The "missing feature" claim flips to "present at " once read from the right tree.

Example

Notes

The same pin protects review subagents (reviewing a diff/commit): pass the worktree path + the commit SHA, and have them confirm git rev-parse HEAD before git show <sha>.
Background subagents can't write, but they CAN read the wrong tree — pinning matters even for read-only fan-outs.
See also: subagent-bash-cd-wrong-worktree (write/commit to wrong branch), worktree-outer-ls-mistaken-for-main-state (ls from outside any worktree), multi-worktree-file-url-stale-content (browser file:// bookmark), flask-debug-cross-worktree-edit-stale (server reload reads wrong worktree), stale-backlog-triage-adversarial-verify (verify "what's already shipped" against live main).