token-pilot 0.31.0 → 0.33.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.31.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.31.0",
+      "version": "0.33.0",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.31.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",

package/agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: dd184501203fa7f3c73f419c4ffbe33c4be75400cb64a7a51733a3fe23f6e085
 ---
 

package/agents/tp-audit-scanner.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: d172f600bf32277ea6eb4cbbee4542ddd698a986dcd96997d33930561964569b
 ---
 

package/agents/tp-commit-writer.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 ---
 

package/agents/tp-context-engineer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 68b32af2dacd82ebe52c4eec93edb903d452688274c3065218270627c564d8b0
 ---
 

package/agents/tp-dead-code-finder.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Read
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: d9b7f5b7ae6f4ae21305c775361bcab097cc774370a6d976c093571d46d55021
 ---
 

package/agents/tp-debugger.md

@@ -12,7 +12,7 @@ tools:
   - Read
   - Bash
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 052413de8d92377edcde6ae5c823f5378db304baccfa29e8866467f42553a500
 ---
 

package/agents/tp-dep-health.md

@@ -9,7 +9,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 ---
 

package/agents/tp-doc-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Glob
 model: haiku
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 57d741794ab40e31a7ac49c68ea39a9088f5827cdef866ce81bfca1b7c9180cf
 ---
 

package/agents/tp-history-explorer.md

@@ -10,7 +10,7 @@ tools:
   - Bash
   - Read
 model: haiku
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 7b70fa76a60e3c58a1de4f56c32c0f166424137e203a0cf1c8654e7c9235d904
 ---
 

package/agents/tp-impact-analyzer.md

@@ -12,7 +12,7 @@ tools:
   - mcp__token-pilot__read_symbols
   - Read
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 351a987e11eba63852f5431a16d8eb53104f4f689f82fdcc5a2bf4db948ba92f
 ---
 

package/agents/tp-incident-timeline.md

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: inherit
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: de5722bfea374eaab096c1ae635c37879e7a91370ee3cd0532f4240be03c91eb
 ---
 

package/agents/tp-incremental-builder.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 375a824d0d847bb5453ec594c7a62ad566ee7e4d92717b0473f771f1a0477c60
 ---
 

package/agents/tp-migration-scout.md

@@ -11,7 +11,7 @@ tools:
   - Grep
   - Glob
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 0334de1bf99b431b65359637d125cda7c44c6f780eb92c57cc538715b1939536
 ---
 

package/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.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 ---
 

package/agents/tp-performance-profiler.md

@@ -11,7 +11,7 @@ tools:
   - Bash
   - Read
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: b61f06380d80798fa2e49d37bcba0653495bee04dd6bdbc1feff9a75607b0508
 ---
 

package/agents/tp-pr-reviewer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: f83f50d05b4f70285ae7afed2b1a406fc436df56e61a0aedbfb31edc7f2b6e66
 ---
 

package/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.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 ---
 

package/agents/tp-review-impact.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__module_info
   - Bash
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 8ef3c3341cbfed4eb8dd130126a9683edc57e378c92ff0ca764d584fd941c55c
 ---
 

package/agents/tp-run.md

@@ -16,7 +16,7 @@ tools:
   - Glob
   - Bash
 model: haiku
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 2b08618d34a61f00aafccbda9fed6d83243296dedb83440edbd2d5c28bb6dbc4
 ---
 

package/agents/tp-session-restorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 529374ed728f5eed5b758b3be3da65624783c0bf0c1a253d7d661a843eb5f767
 ---
 

package/agents/tp-ship-coordinator.md

@@ -11,7 +11,7 @@ tools:
   - Read
   - Grep
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: a60f6ae110eb3138064bce074e8ba26fa0ce5f4659df1624a9d9d3646803391b
 ---
 

package/agents/tp-spec-writer.md

@@ -9,7 +9,7 @@ tools:
   - Read
   - Write
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: c7a4e8b39228fd5158528f389c924c5ff2d98c4b9b05ee0106d54a26c5dc1350
 ---
 

package/agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: be81eed53a3720d146cf89e4a14a7a56577633f7c84c234c412ab70d64c05b11
 ---
 

package/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.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 ---
 

package/agents/tp-test-writer.md

@@ -13,7 +13,7 @@ tools:
   - Edit
   - Bash
 model: sonnet
-token_pilot_version: "0.31.0"
+token_pilot_version: "0.33.0"
 token_pilot_body_hash: 269f2fe22ff4517c277d3f56ca67d8a5527b93290ab21079a83ba7af22c1b5a9
 ---
 

package/dist/ast-index/client.js

@@ -739,8 +739,24 @@ export class AstIndexClient {
         this.indexed = false;
     }
     async exec(args, timeoutMs) {
+        // v0.33.0 (B10) — lazy retry. server.ts calls init() at startup,
+        // but it can fail silently (binary download flaky, permissions
+        // on shared FS, or the user invoked us before postinstall ran).
+        // Subsequent MCP calls would otherwise throw "not initialized"
+        // forever. Try once more here; on failure surface a friendlier
+        // error pointing at the install command.
         if (!this.binaryPath) {
-            throw new Error("ast-index not initialized. Call init() first.");
+            try {
+                await this.init();
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`ast-index not initialized — auto-init also failed: ${msg}\n` +
+                    `Run: npx token-pilot install-ast-index`);
+            }
+            if (!this.binaryPath) {
+                throw new Error("ast-index not initialized. Run `npx token-pilot install-ast-index`.");
+            }
         }
         // ast-index v3.39+ honours AST_INDEX_WALK_UP=1 — read-commands then
         // traverse past nested VCS markers (submodule .git, inner Cargo.toml,

package/dist/cli/install-agents.d.ts

@@ -55,6 +55,24 @@ export declare function installAgents(opts: InstallOptions): Promise<InstallResu
  * levels up to reach the repo/package root, then into `agents/`.
  */
 export declare function resolveDistAgentsDir(scriptUrl: string): string;
+/**
+ * v0.33.0 — locate the freshest tp-* template source available on disk.
+ *
+ * The plugin cache (`~/.claude/plugins/cache/token-pilot/token-pilot/<v>/agents/`)
+ * almost always trails or matches the version of the running binary, but
+ * users with a stale npm-global token-pilot (e.g. v0.20.1 — see beads B1)
+ * end up running a binary whose own `agents/` directory contains an old
+ * subset of templates while the plugin cache holds the up-to-date 25-agent
+ * set. Probe both, pick whichever has the higher version (or, when
+ * versions cannot be read, the more complete set).
+ *
+ * Pure: never throws — returns the script-relative dir as fallback when
+ * the cache cannot be read.
+ */
+export declare function pickFreshestAgentsSource(scriptUrl: string, homeDir: string): Promise<{
+    dir: string;
+    source: "self" | "plugin-cache";
+}>;
 /**
  * Yes/no prompt used by other CLI entry points that want to offer
  * an opt-in step (e.g. `token-pilot init` → "install agents now?").

package/dist/cli/install-agents.js

@@ -189,6 +189,80 @@ export function resolveDistAgentsDir(scriptUrl) {
     const here = dirname(fileURLToPath(scriptUrl));
     return join(here, "..", "..", "agents");
 }
+/**
+ * Compare two semver-ish version strings. Returns positive if `a > b`,
+ * negative if `a < b`, 0 if equal. Tolerates non-semver suffixes by
+ * stripping anything past `-` or `+`. Pre-release / metadata are
+ * ignored. Used only for picking the highest version of a directory
+ * sibling list — bullet-proofness not required.
+ */
+function compareVersions(a, b) {
+    const norm = (s) => s
+        .split(/[-+]/)[0]
+        .split(".")
+        .map((p) => (Number.isFinite(parseInt(p, 10)) ? parseInt(p, 10) : 0));
+    const [ax, ay, az] = norm(a);
+    const [bx, by, bz] = norm(b);
+    if (ax !== bx)
+        return ax - bx;
+    if (ay !== by)
+        return ay - by;
+    return az - bz;
+}
+/**
+ * v0.33.0 — locate the freshest tp-* template source available on disk.
+ *
+ * The plugin cache (`~/.claude/plugins/cache/token-pilot/token-pilot/<v>/agents/`)
+ * almost always trails or matches the version of the running binary, but
+ * users with a stale npm-global token-pilot (e.g. v0.20.1 — see beads B1)
+ * end up running a binary whose own `agents/` directory contains an old
+ * subset of templates while the plugin cache holds the up-to-date 25-agent
+ * set. Probe both, pick whichever has the higher version (or, when
+ * versions cannot be read, the more complete set).
+ *
+ * Pure: never throws — returns the script-relative dir as fallback when
+ * the cache cannot be read.
+ */
+export async function pickFreshestAgentsSource(scriptUrl, homeDir) {
+    const selfDir = resolveDistAgentsDir(scriptUrl);
+    const cacheRoot = join(homeDir, ".claude", "plugins", "cache", "token-pilot", "token-pilot");
+    let cacheVersion = null;
+    let cacheDir = null;
+    try {
+        const versions = (await readdir(cacheRoot)).filter((v) => /\d+\.\d+/.test(v));
+        if (versions.length > 0) {
+            versions.sort(compareVersions);
+            cacheVersion = versions[versions.length - 1];
+            cacheDir = join(cacheRoot, cacheVersion, "agents");
+        }
+    }
+    catch {
+        /* no plugin cache — keep self */
+    }
+    if (!cacheDir)
+        return { dir: selfDir, source: "self" };
+    // Compare counts of tp-*.md to spot the obvious "stale binary" case
+    // where the running CLI is old but plugin cache is current.
+    let selfCount = 0;
+    let cacheCount = 0;
+    try {
+        selfCount = (await readdir(selfDir)).filter((f) => f.endsWith(".md") && f.startsWith("tp-")).length;
+    }
+    catch {
+        /* selfDir missing — pick cache */
+    }
+    try {
+        cacheCount = (await readdir(cacheDir)).filter((f) => f.endsWith(".md") && f.startsWith("tp-")).length;
+    }
+    catch {
+        return { dir: selfDir, source: "self" };
+    }
+    if (cacheCount > selfCount) {
+        return { dir: cacheDir, source: "plugin-cache" };
+    }
+    // Tie or self has more — keep self (newer un-released templates win).
+    return { dir: selfDir, source: "self" };
+}
 /** Read one line from an interactive TTY prompt. */
 async function promptLine(question) {
     process.stderr.write(question);
@@ -356,7 +430,20 @@ export async function handleInstallAgents(argv, opts) {
             scope = await promptScope();
         }
     }
-    const distAgentsDir = opts?.distAgentsDir ?? resolveDistAgentsDir(import.meta.url);
+    // v0.33.0 (B1+B3) — explicit override wins; otherwise probe the
+    // plugin cache and pick whichever has more tp-*.md templates. This
+    // protects users with stale npm-global token-pilot from copying
+    // an outdated 6-agent subset when the bundled plugin already
+    // shipped the full 25.
+    let distAgentsDir = opts?.distAgentsDir;
+    if (!distAgentsDir) {
+        const picked = await pickFreshestAgentsSource(import.meta.url, homeDir);
+        distAgentsDir = picked.dir;
+        if (picked.source === "plugin-cache") {
+            process.stderr.write(`[token-pilot] using agents from plugin cache: ${distAgentsDir}\n` +
+                `  (running CLI's own agents/ has fewer templates — bundled plugin is fresher).\n`);
+        }
+    }
     try {
         const result = await installAgents({
             scope,

package/dist/cli/stats.js

@@ -11,7 +11,7 @@
  * formatStats() is pure (events in → string out) so tests drive it
  * directly without touching the filesystem.
  */
-import { loadEvents } from "../core/event-log.js";
+import { loadEvents, loadEventsTree, } from "../core/event-log.js";
 function sumSaved(events) {
     return events.reduce((sum, e) => sum + e.savedTokens, 0);
 }
@@ -161,7 +161,14 @@ function parseFlag(argv, key) {
  */
 export async function handleStats(argv, opts) {
     const projectRoot = opts?.projectRoot ?? process.cwd();
-    const events = await loadEvents(projectRoot);
+    // v0.33.0 (B5) — `--no-merge` disables the repo-tree walk and reads
+    // only the top-level `.token-pilot/hook-events.jsonl`. Default is to
+    // merge events from every subdirectory log so monorepo subdir
+    // sessions show up in the same totals.
+    const noMerge = argv.includes("--no-merge");
+    const events = noMerge
+        ? await loadEvents(projectRoot)
+        : await loadEventsTree(projectRoot);
     const session = parseFlag(argv, "session");
     const byAgent = parseFlag(argv, "by-agent");
     const tasks = parseFlag(argv, "tasks");

package/dist/core/error-log.d.ts

@@ -0,0 +1,86 @@
+/**
+ * v0.34.0 — error / diagnostic channel for token-pilot hooks + CLI.
+ *
+ * Why a separate file from `hook-events.jsonl`:
+ *   - hook-events lives in `<projectRoot>/.token-pilot/`. When the hook
+ *     itself fails BEFORE projectRoot is resolved (B8 WSL detection,
+ *     missing dir, ENOENT), there is nowhere to write the regular log.
+ *   - Errors must outlive a single project — when a user reports
+ *     "nothing logs anymore" we want one absolute path to look at.
+ *
+ * Layout:
+ *   ~/.token-pilot/hook-errors.jsonl
+ *
+ * Format: one JSON record per line. Schema in `HookErrorRecord` below.
+ *
+ * Discipline:
+ *   - Never throws. The error logger is itself the last line of defence —
+ *     a throw here would defeat the wrapper that calls it.
+ *   - Cap-and-rotate: when the file passes MAX_BYTES the writer renames
+ *     it to `hook-errors.<ts>.jsonl` and starts fresh. Old archives
+ *     past RETENTION_MS are pruned best-effort on each append.
+ *   - `TOKEN_PILOT_NO_ERROR_LOG=1` opts out entirely.
+ *
+ * Privacy:
+ *   - The `input` field is whatever the hook chose to record. Callers
+ *     MUST sanitize before passing it in — no full paths, no file
+ *     content, no prompts. Helpers `safeBasename()` / `safePathInfo()`
+ *     are provided for the common cases.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+export type ErrorLevel = "info" | "warn" | "error";
+export interface HookErrorRecord {
+    ts: number;
+    hook: string;
+    level: ErrorLevel;
+    code: string;
+    msg: string;
+    stack?: string;
+    input?: Record<string, unknown>;
+    pluginVersion?: string;
+    nodeVersion?: string;
+    platform?: NodeJS.Platform;
+}
+export declare function errorLogDir(): string;
+export declare function errorLogPath(): string;
+/**
+ * Reduce a path to its basename. Use everywhere a path could leak:
+ * the user's project tree, file content, anything not strictly an
+ * identifier. Returns `"<empty>"` for missing input rather than null
+ * so the field stays shape-stable.
+ */
+export declare function safeBasename(p: unknown): string;
+/**
+ * Capture only the metadata about a path — basename + length + ext —
+ * dropping the absolute path entirely. Useful when the analysis
+ * benefits from "kind of file" without revealing where it lived.
+ */
+export declare function safePathInfo(p: unknown): {
+    name: string;
+    ext: string;
+};
+/**
+ * Map a thrown value to a stable, searchable `code`. The classifier
+ * is intentionally simple — node ErrnoException codes pass through,
+ * everything else falls into a coarse bucket. New cases land here
+ * only when a pattern shows up repeatedly in the wild.
+ */
+export declare function classifyError(err: unknown): string;
+export declare function appendError(rec: HookErrorRecord): Promise<void>;
+export interface LoadErrorsOptions {
+    /** Limit to the last N records (most recent first). */
+    tail?: number;
+    /** Filter by `code`. */
+    code?: string;
+    /** Filter by `hook` name. */
+    hook?: string;
+    /** Filter by `level`. */
+    level?: ErrorLevel;
+    /** Override the default current-log path (testing). */
+    path?: string;
+}
+export declare function loadErrors(opts?: LoadErrorsOptions): Promise<HookErrorRecord[]>;
+export declare function formatErrorList(records: HookErrorRecord[]): string;
+export { existsSync, resolve, dirname };
+//# sourceMappingURL=error-log.d.ts.map