Digital-Threads · Shahinyanm · May 8, 2026 · May 8, 2026 · May 8, 2026 · May 8, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.32.0"
+    "version": "0.33.0"
   },
   "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. 22 MCP tools + 19 subagents + budget watchdog hooks.",
-      "version": "0.32.0",
+      "version": "0.33.0",
       "author": {
         "name": "Digital-Threads"
       },

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Saves 60-90% tokens when AI reads code. AST-aware lazy reading, symbol navigation, cross-session tool-usage analytics, 22 subagents (haiku/sonnet/opus-tiered) with budget watchdog.",
   "author": {
     "name": "Digital-Threads",

diff --git a/.gitignore b/.gitignore
@@ -45,3 +45,4 @@ docs/code-review-report.md
 .claude/
 .token-pilot.json
 .token-pilot-fingerprint.json
+tp-report.txt
diff --git a/agents/tp-api-surface-tracker.md b/agents/tp-api-surface-tracker.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 ---
 

diff --git a/agents/tp-audit-scanner.md b/agents/tp-audit-scanner.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 ---
 

diff --git a/agents/tp-commit-writer.md b/agents/tp-commit-writer.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 ---
 

diff --git a/agents/tp-context-engineer.md b/agents/tp-context-engineer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 ---
 

diff --git a/agents/tp-dead-code-finder.md b/agents/tp-dead-code-finder.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 ---
 

diff --git a/agents/tp-debugger.md b/agents/tp-debugger.md
@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 ---
 

diff --git a/agents/tp-dep-health.md b/agents/tp-dep-health.md
@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 ---
 

diff --git a/agents/tp-doc-writer.md b/agents/tp-doc-writer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 ---
 

diff --git a/agents/tp-history-explorer.md b/agents/tp-history-explorer.md
@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 ---
 

diff --git a/agents/tp-impact-analyzer.md b/agents/tp-impact-analyzer.md
@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 ---
 

diff --git a/agents/tp-incident-timeline.md b/agents/tp-incident-timeline.md
@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 ---
 

diff --git a/agents/tp-incremental-builder.md b/agents/tp-incremental-builder.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 ---
 

diff --git a/agents/tp-migration-scout.md b/agents/tp-migration-scout.md
@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 ---
 

diff --git a/agents/tp-onboard.md b/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.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 ---
 

diff --git a/agents/tp-performance-profiler.md b/agents/tp-performance-profiler.md
@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 ---
 

diff --git a/agents/tp-pr-reviewer.md b/agents/tp-pr-reviewer.md
@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 ---
 

diff --git a/agents/tp-refactor-planner.md b/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.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 ---
 

diff --git a/agents/tp-review-impact.md b/agents/tp-review-impact.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 ---
 

diff --git a/agents/tp-run.md b/agents/tp-run.md
@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 ---
 

diff --git a/agents/tp-session-restorer.md b/agents/tp-session-restorer.md
@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 ---
 

diff --git a/agents/tp-ship-coordinator.md b/agents/tp-ship-coordinator.md
@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
 ---
 

diff --git a/agents/tp-spec-writer.md b/agents/tp-spec-writer.md
@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 ---
 

diff --git a/agents/tp-test-coverage-gapper.md b/agents/tp-test-coverage-gapper.md
@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 ---
 

diff --git a/agents/tp-test-triage.md b/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.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 ---
 

diff --git a/agents/tp-test-writer.md b/agents/tp-test-writer.md
@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.32.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 ---
 

diff --git a/docs/issues/2026-05-08-mcp-issues.md b/docs/issues/2026-05-08-mcp-issues.md
@@ -0,0 +1,137 @@
+# MCP Issues — 2026-05-08
+
+External code-review report received 2026-05-08 from a WSL setup
+(Windows 11 host, Ubuntu WSL2 guest, repo accessed via UNC share
+`\\wsl.localhost\ubuntu\...`). All four functional issues were
+reproduced from `tp-report.txt` audit data; each is now tracked as
+a beads issue and addressed in v0.33.0.
+
+## Status overview
+
+| # | Issue | Beads | Status | Commit |
+|---|-------|-------|--------|--------|
+| 1 | `project_overview` returns `C:\Windows` root | token-pilot-lpp (B8) | **FIXED** | v0.33.0 |
+| 2 | `smart_log` / `smart_diff` fail on UNC paths | token-pilot-z7p (B6) + token-pilot-5jh (B7) + token-pilot-lpp (B8) | **FIXED** | v0.33.0 |
+| 3 | `read_range` rejects valid `start_line` | token-pilot-5lw (B9) | **FIXED** | v0.33.0 |
+| 4 | `find_usages` requires manual `init()` | token-pilot-vax (B10) | **FIXED** | v0.33.0 |
+| 5 | Version mismatch 0.1.1 vs package.json 0.8.3 | — | **NOT APPLICABLE** | belongs to a different package (`epitaxy`) — token-pilot is at 0.33.0 |
+
+## Issue 1 — `project_overview` catches `C:\Windows`
+
+**Original report:**
+> При вызове `project_overview` без аргументов на проекте, открытом из
+> WSL UNC-пути (`\\wsl.localhost\ubuntu\home\shahinyanm\www\token-pilot`),
+> сервер отвечает `PROJECT: Windows v0.0.0` `TYPE: unknown (no config files
+> found)`.
+
+**Root cause confirmed:** `startServer()` walked `cwd` / `INIT_CWD` /
+`PWD` candidates without rejecting Windows system paths. From a WSL
+launch the cwd was `C:\Windows\System32` (or `/mnt/c/Windows/...` from
+the WSL view) and `git rev-parse --show-toplevel` either failed or
+silently returned the Windows tree.
+
+**Fix (v0.33.0, commit on `v0.33.0-bugfix-batch`):**
+- `src/index.ts` — preferred ordering changed to
+  `CLAUDE_PROJECT_DIR > INIT_CWD > PWD > cwd`. Claude Code reliably
+  exports `CLAUDE_PROJECT_DIR`; nothing else is trustworthy on WSL.
+- New helper `isWindowsSystemPath(candidate)` filters
+  `C:\Windows\…`, `C:\Program Files\…`, `/mnt/c/windows/…`, and any
+  `\\…` UNC path before the candidate reaches git-detect.
+- v0.34.0 Pack 2 emits a `wsl_path_rejected` diagnostic per filtered
+  candidate so we can see in `stats` how often this fires in the wild.
+
+## Issue 2 — `smart_log` / `smart_diff` fail on UNC paths
+
+**Original report:**
+> `git log failed: ... fatal: not a git repository`
+> `git diff failed: ... warning: Not a git repository.`
+
+**Root cause confirmed:** two separate bugs amplified each other.
+1. `smart_log` built `gitArgs` as
+   `['log', …flags, '--', ref]` and (with a path arg) appended a second
+   `'--', path` separator. Git interpreted `HEAD` as a pathspec and
+   silently returned empty; with a path the double `--` made it
+   reject the call.
+2. Both handlers DID call `execFile('git', …, { cwd: projectRoot })`,
+   so the symptom on WSL was Issue 1 leaking through: `projectRoot`
+   resolved to a Windows system path, every git call in that tree
+   failed.
+
+**Fix (v0.33.0):**
+- `src/handlers/smart-log.ts` — drop the leading `'--'` so the args
+  are `['log', …flags, ref]` then optional `'--', args.path`.
+- `smart_diff` already uses `cwd: projectRoot`; it inherits the
+  Issue 1 fix automatically.
+
+## Issue 3 — `read_range` rejects valid `start_line`
+
+**Original report:**
+> `read_range({path, start_line: 95, end_line: 240})` →
+> `Required parameter "start_line" must be a positive integer.`
+
+**Root cause confirmed:** `validateReadRangeArgs` required
+`typeof === "number"`. Some MCP clients (and most non-trivial transport
+shims) round-trip integer arguments through JSON or environment
+variables and re-emit them as strings (`"95"`).
+
+**Fix (v0.33.0):**
+- New helper `coerceIntFromAny(value)` in `src/core/validation.ts`
+  accepts numeric strings (`"95"` → `95`), rejects everything else
+  (decimals, `"95abc"`, `NaN`, etc.).
+- `validateReadRangeArgs` now coerces both `start_line` and `end_line`
+  through it.
+
+## Issue 4 — `find_usages` requires manual `init()`
+
+**Original report:**
+> `find_usages(...)` → `Error: ast-index not initialized. Call init() first.`
+
+**Root cause confirmed:** `server.ts` calls `astIndex.init()` once at
+startup. When that init failed silently (binary download flake, FS
+permissions, postinstall didn't run), every subsequent MCP call kept
+throwing `not initialized` until the user manually re-invoked
+`token-pilot install-ast-index` and restarted Claude Code.
+
+**Fix (v0.33.0):**
+- `src/ast-index/client.ts` — `exec()` now lazy-retries `init()` once
+  on missing `binaryPath`. On second failure surfaces a friendlier
+  error message pointing at `npx token-pilot install-ast-index`.
+
+## Issue 5 — Version mismatch 0.1.1 vs 0.8.3
+
+**Original report:**
+> Token-pilot версия: 0.1.1 (по `project_overview`), при этом
+> package.json — 0.8.3 (рассогласование версий).
+
+**Not applicable.** token-pilot is at v0.33.0 in this branch and the
+sources never had `0.1.1` or `0.8.3` anywhere. The reported numbers
+match a different package (`epitaxy`) — the report appears to have
+captured a `project_overview` from another project alongside ours.
+
+If similar-looking numbers reappear in a real token-pilot session,
+file a fresh issue with the exact `project_overview` JSON output and
+the `package.json` hash so we can trace which detector returned the
+fake version.
+
+## Verification
+
+- 1269/1269 unit tests pass on the v0.33.0 branch
+  (`npx vitest run`).
+- Build clean (`npm run build` writes 25 composed agents).
+- Manual repro for Issues 1-2 still requires a WSL host — added a
+  diagnostic event so we can verify in real-world telemetry that the
+  reject path is no longer firing on a normal Linux/macOS launch.
+
+## How to verify post-merge
+
+1. Pull v0.33.0 on the WSL machine.
+2. `npm install -g token-pilot@latest`.
+3. `token-pilot migrate-hooks` to clean stale npx-cache hook entries.
+4. Restart Claude Code on the affected project.
+5. Confirm:
+   - `project_overview()` returns the WSL path, not `C:\Windows`.
+   - `smart_log()` returns commits.
+   - `read_range({ path, start_line: 95, end_line: 240 })` works.
+   - `find_usages("Foo")` succeeds even on a fresh shell.
+   - `token-pilot doctor` shows zero stale hook entries and the
+     correct cwd.