feat: v0.47.0 — explore tool + ast-index 3.48.1 + rebuild resilience (#55)

* feat: v0.47.0 — `explore` tool + ast-index 3.48.1 + rebuild resilience

Leverage ast-index 3.48 in token-pilot:

- feat(explore): new MCP tool `explore` — one-shot ranked context. Wraps
  ast-index's `explore --rwr`: ranked symbols + top-file source heads + graph
  neighbours (callers/subclasses = blast radius via RWR) + related tests, in one
  compact block. Replaces find_usages → read_symbol → call_tree chaining. Graph
  on by default; degrades with a clear "requires ast-index >= 3.48" note on an
  older binary. Client method + types + handler + server registration + tests.

- chore(deps): bump @ast-index/cli ^3.44 → ^3.48.1 (TS-indexing fix, rebuild
  swap-and-restore, memory caps, FUSE-safe canonicalize). npm audit still 0.

- fix(buildIndex): trust the binary's swap-and-restore — on rebuild failure use
  the preserved index instead of throwing and falling back to raw reads. Lock
  and generic recovery paths unified.

Deferred: --local / subtree scoping (multi-repo/worktree) needs a rooting rework.

Full suite: +5 new tests; 23 failures unchanged (pre-existing env-only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test: repair stale statusline assertions + harden install-test env isolation

Pre-existing CI breakage surfaced while landing 0.47.0 (master CI has been red
since the "label savings + efficiency %" badge change):

- statusline.test.ts: badge now renders `· saved <N>` (labelled) plus an
  efficiency `%` for tool-call-backed totals. Updated the 8 stale regexes to
  match the current format; EFF-bearing cases assert ` \d+%`.

- installer.test.ts / index.test.ts: installHook branches on
  CLAUDE_PLUGIN_ROOT. When another test sharing the vitest worker leaks that
  env var, the standalone-install assertions failed (sharding-dependent).
  beforeEach now neutralises it and afterEach restores — deterministic
  regardless of file-to-worker distribution.

No production code change. The 2 git-root tests that flake under parallel load
(real `git` subprocess, 3s timeout) are unrelated and pre-existing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: shahinyanm <mher.shahinyan@12go.asia>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot — save 60-90% tokens when AI reads code",
-    "version": "0.46.1"
+    "version": "0.47.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. 23 MCP tools + 25 subagents + budget watchdog hooks.",
-      "version": "0.46.1",
+      "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",
       "author": {
         "name": "Digital-Threads"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "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,34 @@ 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.0] - 2026-06-24
+
+### Added — `explore` tool: one-shot ranked context + graph blast-radius
+
+New MCP tool **`explore`** wraps ast-index 3.48's `explore` command: for a query
+it returns ranked relevant symbols, the source heads of the top files, **graph
+neighbours (callers + subclasses — the blast radius, via RWR over the
+call/inheritance graph)**, and related test files — in a single compact block.
+Replaces the common `find_usages` → `read_symbol` → `call_tree` chain with one
+call. `graph` defaults on; `max_files` caps the source heads. Falls back to a
+clear "requires ast-index >= 3.48" message when an older binary is resolved.
+
+### Changed — bump `@ast-index/cli` to 3.48.1
+
+Picks up the upstream TypeScript-indexing fix, the rebuild **swap-and-restore**
+guard (a failed rebuild no longer wipes the index), memory caps, and FUSE-safe
+canonicalisation. `npm audit` stays at 0 vulnerabilities.
+
+### Changed — `buildIndex` trusts swap-and-restore
+
+When a rebuild fails, `buildIndex` now checks for the index the binary preserved
+and uses it (instead of throwing and falling back to raw reads). The lock-case
+and generic-failure recovery paths are unified.
+
+_Deferred:_ `--local` / subtree query scoping (to re-enable ast-index on
+multi-repo / worktree parents instead of disabling it) needs a rooting-model
+rework and ships separately.
+
 ## [0.46.1] - 2026-06-18
 
 ### Fixed — node:test (`node --test`) TAP output parsing

agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 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.46.1"
+token_pilot_version: "0.47.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"