Run any Skill in Manus with one click

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

Stars2

Forks0

UpdatedJuly 8, 2026 at 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

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

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

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