fix: v0.47.1 — gate AST_INDEX_WALK_UP on .git marker + deterministic CLI tests

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot — save 60-90% tokens when AI reads code",
-    "version": "0.47.0"
+    "version": "0.47.1"
   },
   "plugins": [
     {
       "name": "token-pilot",
       "source": "./",
       "description": "Reduces token consumption by 60-90% via AST-aware lazy file reading, structural symbol navigation, and cross-session tool-usage analytics. 24 MCP tools + 25 subagents + budget watchdog hooks.",
-      "version": "0.47.0",
+      "version": "0.47.1",
       "author": {
         "name": "Digital-Threads"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.47.0",
+  "version": "0.47.1",
   "description": "Saves 60-90% tokens on AI code reading. AST-aware lazy reads, symbol navigation, find_usages, structural git diff/log, edit-safety guard, Task-routing matcher, cross-session telemetry (errors + diagnostics), 25 tp-* subagents tiered to haiku/sonnet/opus with budget watchdog.",
   "author": {
     "name": "Digital-Threads",

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.47.1] - 2026-06-24
+
+### Fixed — gate AST_INDEX_WALK_UP on the `.git` marker (nested-worktree escape)
+
+`exec()` set `AST_INDEX_WALK_UP=1` unconditionally. The flag tells ast-index to
+traverse past nested VCS markers and reuse a parent-level index — it exists for
+bare monorepo subdirs (no `.git`, no local DB). But forcing it when `projectRoot`
+is itself a git repo/worktree root let a worktree nested under the main repo
+(`main-repo/.worktrees/feature`) walk up past its own `.git` and **escape to the
+main repo's index, returning the wrong files**. Now the flag is set only when
+`projectRoot` has no `.git` marker of its own (a `.git` dir or worktree gitlink
+file both count). See `docs/adr/0002-ast-index-multi-root-scoping.md` — also
+records the deferred `--local`/subtree plan for multi-repo parents.
+
+### Fixed — deterministic CLI tests under parallel sharding
+
+`index.test.ts` / `installer.test.ts` now neutralise `CLAUDE_PROJECT_DIR` and
+`CLAUDE_PLUGIN_ROOT` in setup so the git-detection and install assertions don't
+flake when another suite leaks those env vars into a shared vitest worker.
+
 ## [0.47.0] - 2026-06-24
 
 ### Added — `explore` tool: one-shot ranked context + graph blast-radius

agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 requiredMcpServers:
   - "token-pilot"

agents/tp-audit-scanner.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 requiredMcpServers:
   - "token-pilot"

agents/tp-commit-writer.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"

agents/tp-context-engineer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 requiredMcpServers:
   - "token-pilot"

agents/tp-dead-code-finder.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 requiredMcpServers:
   - "token-pilot"

agents/tp-debugger.md

@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 requiredMcpServers:
   - "token-pilot"

agents/tp-dep-health.md

@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"

agents/tp-doc-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 requiredMcpServers:
   - "token-pilot"

agents/tp-history-explorer.md

@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 requiredMcpServers:
   - "token-pilot"

agents/tp-impact-analyzer.md

@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 requiredMcpServers:
   - "token-pilot"

agents/tp-incident-timeline.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 requiredMcpServers:
   - "token-pilot"

agents/tp-incremental-builder.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 requiredMcpServers:
   - "token-pilot"

agents/tp-migration-scout.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 requiredMcpServers:
   - "token-pilot"

agents/tp-onboard.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 requiredMcpServers:
   - "token-pilot"

agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 requiredMcpServers:
   - "token-pilot"

agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 requiredMcpServers:
   - "token-pilot"

agents/tp-refactor-planner.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 requiredMcpServers:
   - "token-pilot"

agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 requiredMcpServers:
   - "token-pilot"

agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 requiredMcpServers:
   - "token-pilot"

agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 requiredMcpServers:
   - "token-pilot"

agents/tp-ship-coordinator.md

@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
 requiredMcpServers:
   - "token-pilot"

agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 requiredMcpServers:
   - "token-pilot"

agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 requiredMcpServers:
   - "token-pilot"

agents/tp-test-triage.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 requiredMcpServers:
   - "token-pilot"

agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.47.0"
+token_pilot_version: "0.47.1"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 requiredMcpServers:
   - "token-pilot"

docs/adr/0002-ast-index-multi-root-scoping.md

@@ -0,0 +1,107 @@
+# ADR 0002 — ast-index multi-root scoping (walk-up gate + subtree plan)
+
+**Status:** Accepted (Decision 1, walk-up gate) / Proposed (Decision 2, subtree scoping)
+**Date:** 2026-06
+**Supersedes:** nothing
+
+## Context
+
+token-pilot wraps the third-party `@ast-index/cli` binary. It always
+runs the binary with `cwd` set to the detected project root (the git
+toplevel, when there is one). Two related multi-root problems sit on
+top of that single-index assumption:
+
+**(a) Cross-project index bleed.** When the detected `projectRoot` is a
+non-git PARENT directory holding several sibling repos
+(`work/repo-a`, `work/repo-b`, …), a single ast-index DB rooted at the
+parent would mix symbols from unrelated projects. token-pilot mitigates
+this today by detecting that shape (`isMultiRepoParent`,
+`src/core/validation.ts`) and DISABLING ast-index for that root — search
+falls back to the regex parser. Correct, but it means zero ast-index
+benefit on those layouts.
+
+**(b) Nested-worktree escape.** `exec()` in
+`src/ast-index/client.ts` used to set `AST_INDEX_WALK_UP=1`
+unconditionally. That flag tells the binary's read-commands to traverse
+PAST nested VCS markers and reuse a parent-level index — it exists so a
+bare monorepo SUBDIR (no `.git`, no local DB) can find the root index.
+But forcing it on every spawn is wrong when `projectRoot` is itself a
+git repo/worktree root: a git worktree nested under the main repo
+(e.g. `main-repo/.worktrees/feature`) would walk up past its own `.git`
+marker and escape to the MAIN repo's parent index, returning the wrong
+files.
+
+## Decision 1 — gate AST_INDEX_WALK_UP on the `.git` marker (Accepted, shipped here)
+
+`exec()` now sets `AST_INDEX_WALK_UP=1` ONLY when `projectRoot` has no
+`.git` marker of its own. The marker is computed once
+(`computeHasGitMarker`, re-evaluated in `updateProjectRoot` after a
+branch/root change) as `existsSync(resolve(projectRoot, ".git"))` — a
+`.git` DIRECTORY (normal repo) or a `.git` FILE (worktree / submodule
+gitlink) both count.
+
+Why this is safe:
+
+- token-pilot already sets `cwd` to the git toplevel. For a repo or
+  worktree root, the binary finds the local index without walking up,
+  so the flag was at best a no-op there.
+- Walk-up only ever HELPED the bare-subdir case (no marker, no local
+  DB) — exactly the case the gate still enables.
+- For repo/worktree roots the flag's only observable effect was the
+  escape bug in (b). Skipping it removes that bug without removing the
+  subdir benefit.
+- When a marker is present we simply refrain from FORCING the flag; a
+  value the user set in the environment themselves is left untouched.
+
+This is a behaviour fix with no config surface and no rooting-model
+change. Covered by unit tests in `tests/ast-index/client.test.ts`
+(marker present → flag absent; no marker → flag set; `computeHasGitMarker`
+across `.git` dir / file / absence).
+
+## Decision 2 — subtree scoping to re-enable ast-index on multi-root parents (Proposed, deferred)
+
+Adopt ast-index 3.47's subtree model plus the `--local` / `--subtree`
+query flags to RE-ENABLE ast-index on multi-repo and worktree-parent
+layouts instead of disabling it:
+
+1. Index the parent directory once.
+2. Register each child project as a named subtree.
+3. Scope every read query (`exec`/`search`/`usages` in
+   `src/ast-index/client.ts`) with `--local` / `--subtree` so results
+   never bleed across siblings.
+
+This would let `isMultiRepoParent` roots keep ast-index instead of
+falling back to regex, and would give nested worktrees a first-class
+scoped index rather than relying on the walk-up gate.
+
+Why deferred:
+
+- It requires a rooting-model rework: how the index root is chosen, and
+  the `isMultiRepoParent` → disable path
+  (`src/core/validation.ts`), both have to change so the parent is
+  indexed-and-scoped rather than skipped.
+- `--local` is a no-op without the subtree registration step, so the
+  flag alone buys nothing — the whole model has to land together.
+- The Decision 1 gate already closes the correctness hole (the escape
+  bug) cheaply, which removes the urgency.
+
+## Consequences / follow-ups
+
+- Shipped: nested worktrees and repo roots no longer escape to a parent
+  index; bare subdirs keep walk-up.
+- Still open: `isMultiRepoParent` roots get no ast-index benefit
+  (regex-only). The subtree model in Decision 2 is the planned fix;
+  file it as a tracked task before starting the rooting rework.
+- If a future ast-index release changes walk-up semantics or ships the
+  subtree flags, revisit both decisions here.
+
+## Alternatives considered
+
+- **Keep forcing `AST_INDEX_WALK_UP=1` and special-case worktrees
+  elsewhere.** Rejected: the marker check is the same signal
+  `isMultiRepoParent` already uses, so gating at the env-construction
+  point is the smallest, most consistent change.
+- **Disable ast-index for worktree roots too** (mirror the multi-repo
+  parent mitigation). Rejected: a worktree root owns a perfectly good
+  local index; disabling would throw away real benefit to avoid a bug
+  the gate already prevents.