一键在 Manus 中运行任何 Skill

harness-read-write-base-repo-path-in-worktree-stale-tree

星标2

分支0

更新时间2026年7月8日 11:09

In a git-worktree session, your OWN Read/Write/Edit tool calls that use a BASE-repo absolute path (one MISSING the `.claude/worktrees/<name>/` segment) silently operate on the base repo's working tree — a DIFFERENT, often month-stale branch sharing the same `.git`. Use when: (1) a `Read`'s line numbers / function locations don't match a `grep` you ran in the worktree cwd (Bash sees the worktree; Read with a base path sees the base repo); (2) a `Write`/`Edit` "succeeds" but the file never appears in the worktree's `git status -sb` (it landed in the base repo, untracked there); (3) a review/subagent (or a fresh checkout) reports a file you just wrote "doesn't exist"; (4) a file looks surprisingly smaller/older than expected (e.g. bq_queries.py 7228 lines via base path vs 8434 in the worktree). Root cause: harness file tools take absolute paths verbatim and do NOT pin to the worktree; the base repo is a separate checkout, usually parked on another branch. Fix: build EVERY file path under the worktree root (the e

安装

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

在 Manus 中运行

来源

wan-huiyan

wan-huiyan/agent-traffic-control

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

下载

在 Manus 中运行

Read/Write/Edit with a base-repo path silently hits the stale base tree in a worktree session

Problem

You're working in a worktree (<repo>/.claude/worktrees/<name>/). Your Bash tool runs with cwd = the worktree, so grep/git/wc see the worktree's branch. But Read/Write/Edit take absolute paths verbatim — if you write /…/<repo>/path (the BASE repo path, missing the .claude/worktrees/<name>/ segment) you operate on the base repo's working tree, a different checkout that shares the same .git and is usually parked on an unrelated, often month-stale branch. The two trees diverge silently and you don't get an error.

Context / Trigger Conditions

A Read's line numbers or the functions it shows disagree with a grep/wc you ran in the worktree cwd (e.g. def get_top_drivers at L2926 via Read vs L3795 via grep).
A Write reports success but the new file is absent from git status -sb in the worktree (it was created in the base repo, untracked there).
A Write to an existing file's path "works" but later edits to "the same file" via worktree-relative paths don't see your change.
A review panel / dispatched subagent / fresh git checkout reports a file you KNOW you wrote as "absent from the working tree" / "doesn't exist on any ref" (it's sitting untracked in the base repo).
A file looks much smaller/older than the current branch should have.

Solution

Always prefix file paths with the worktree root — the value the environment prints as "Primary working directory" (/…/<repo>/.claude/worktrees/<name>/…), never the bare /…/<repo>/…. Bash is fine with worktree-relative paths (cwd is already the worktree); Read/Write/Edit need the full worktree-prefixed absolute path.
Cross-check on first Read of any file: if its line numbers don't match a grep -n you ran in the worktree cwd, you read the wrong tree — re-read via the worktree path.
After any Write/new file: confirm it shows in the worktree's git status -sb before relying on it (and before dispatching a review that needs it).
Confirm the divergence when suspicious: git -C <base-repo> rev-parse --abbrev-ref HEAD vs the worktree's branch — if they differ, base-path reads/writes are operating on that other branch's content.

Verification

A worktree-path Read's line numbers match grep -n <symbol> <worktree-path>.
A just-written file appears in git status -sb of the worktree.
wc -l (worktree cwd) and the Read agree on file size.

Example

Session worktree on feat/X (current origin/main); base repo parked on a month-old branch. Read('/Users/me/repo/…/bq_queries.py') returned a function at L2926 and 7228 total lines, while grep -n 'def get_top_drivers' (Bash, worktree cwd) said L3795 and wc -l said 8434. A spec Write('/Users/me/repo/docs/plans/…md') "succeeded" but never showed in git status, and the review panel reported it "absent from every ref." Cause: all three used the base path. Fix: re-Read/Write via /Users/me/repo/.claude/worktrees/<name>/… — line numbers matched and the file appeared in status.

Notes

Distinct from the bash-cwd worktree traps (main-bash-cwd-persists-nested-worktree, subagent-bash-cd-wrong-worktree) — those are about cd and shell cwd; THIS is about the harness Read/Write/Edit tools taking an absolute path that points at the base repo.
Distinct from preview-mcp-reads-base-repo-launch-json (an MCP reading the base repo) and from the file:// URL staleness lesson (browser bookmarks reflecting a stale branch).
See also: dispatched-bash-agent-git-checkout-clobbers-uncommitted-edit (a subagent reverting your uncommitted edit), concurrent-session-checkout-clobbers-shared-worktree.
Also captured as a rule in ~/.claude/lessons.md ("Worktree sessions: tool-call paths must be worktree-prefixed").

同仓库更多 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	harness-read-write-base-repo-path-in-worktree-stale-tree
description	In a git-worktree session, your OWN Read/Write/Edit tool calls that use a BASE-repo absolute path (one MISSING the `.claude/worktrees/<name>/` segment) silently operate on the base repo's working tree — a DIFFERENT, often month-stale branch sharing the same `.git`. Use when: (1) a `Read`'s line numbers / function locations don't match a `grep` you ran in the worktree cwd (Bash sees the worktree; Read with a base path sees the base repo); (2) a `Write`/`Edit` "succeeds" but the file never appears in the worktree's `git status -sb` (it landed in the base repo, untracked there); (3) a review/subagent (or a fresh checkout) reports a file you just wrote "doesn't exist"; (4) a file looks surprisingly smaller/older than expected (e.g. bq_queries.py 7228 lines via base path vs 8434 in the worktree). Root cause: harness file tools take absolute paths verbatim and do NOT pin to the worktree; the base repo is a separate checkout, usually parked on another branch. Fix: build EVERY file path under the worktree root (the env's "Primary working directory"), and cross-check Read line numbers against a cwd-relative grep.
author	Claude Code
version	1.0.0
date	"2026-06-23T00:00:00.000Z"
disable-model-invocation	true

Read/Write/Edit with a base-repo path silently hits the stale base tree in a worktree session

Problem

Context / Trigger Conditions

A Read's line numbers or the functions it shows disagree with a grep/wc you ran in the worktree cwd (e.g. def get_top_drivers at L2926 via Read vs L3795 via grep).
A Write reports success but the new file is absent from git status -sb in the worktree (it was created in the base repo, untracked there).
A Write to an existing file's path "works" but later edits to "the same file" via worktree-relative paths don't see your change.
A review panel / dispatched subagent / fresh git checkout reports a file you KNOW you wrote as "absent from the working tree" / "doesn't exist on any ref" (it's sitting untracked in the base repo).
A file looks much smaller/older than the current branch should have.

Solution

Always prefix file paths with the worktree root — the value the environment prints as "Primary working directory" (/…/<repo>/.claude/worktrees/<name>/…), never the bare /…/<repo>/…. Bash is fine with worktree-relative paths (cwd is already the worktree); Read/Write/Edit need the full worktree-prefixed absolute path.
Cross-check on first Read of any file: if its line numbers don't match a grep -n you ran in the worktree cwd, you read the wrong tree — re-read via the worktree path.
After any Write/new file: confirm it shows in the worktree's git status -sb before relying on it (and before dispatching a review that needs it).
Confirm the divergence when suspicious: git -C <base-repo> rev-parse --abbrev-ref HEAD vs the worktree's branch — if they differ, base-path reads/writes are operating on that other branch's content.

Verification

A worktree-path Read's line numbers match grep -n <symbol> <worktree-path>.
A just-written file appears in git status -sb of the worktree.
wc -l (worktree cwd) and the Read agree on file size.

Example

Notes

Distinct from the bash-cwd worktree traps (main-bash-cwd-persists-nested-worktree, subagent-bash-cd-wrong-worktree) — those are about cd and shell cwd; THIS is about the harness Read/Write/Edit tools taking an absolute path that points at the base repo.
Distinct from preview-mcp-reads-base-repo-launch-json (an MCP reading the base repo) and from the file:// URL staleness lesson (browser bookmarks reflecting a stale branch).
See also: dispatched-bash-agent-git-checkout-clobbers-uncommitted-edit (a subagent reverting your uncommitted edit), concurrent-session-checkout-clobbers-shared-worktree.
Also captured as a rule in ~/.claude/lessons.md ("Worktree sessions: tool-call paths must be worktree-prefixed").