一键在 Manus 中运行任何 Skill

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

星标2

分支0

更新时间2026年7月8日 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`

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

wan-huiyan

wan-huiyan/agent-traffic-control

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

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).

同仓库更多 Skills

同仓库

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).