token-pilot 0.36.0 → 0.39.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Token Pilot \u2014 save 60-90% tokens when AI reads code",
-    "version": "0.36.0"
+    "version": "0.39.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. 22 MCP tools + 19 subagents + budget watchdog hooks.",
-      "version": "0.36.0",
+      "version": "0.39.1",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -269,6 +269,48 @@ tp-* agents that already declared `model: haiku` keep their cheaper
 tier (90 %+ of the agent roster); the few sonnet/opus-tier ones
 ride the upgrade automatically.
 
+## Fleet workflows (v0.38.0)
+
+When you fan a task across many subagents — via Claude Code's
+`/workflow`, the Agent tool, or your own orchestration — token-pilot
+can treat the whole run as one budgeted, telemetry-tagged unit.
+
+token-pilot **owns** the workflow boundary, so this works regardless
+of whether Claude Code propagates a workflow id. You wrap the batch:
+
+```bash
+# Start a workflow — prints an export line you eval into your shell
+eval "$(token-pilot workflow start "review every PR from last sprint" --budget=2000000)"
+
+# ...now run your fan-out work. Every hook event is tagged with the
+#    workflow id automatically (TOKEN_PILOT_WORKFLOW_ID is set).
+
+token-pilot workflow status      # live budget + task counts
+token-pilot workflow list        # all recorded workflows
+token-pilot workflow end         # stamp it finished + print summary
+```
+
+While a workflow is active:
+
+- Every `event:"task"` / `denied` / `diagnostic` row in
+  `hook-events.jsonl` carries `workflow_id`, so you can slice one
+  fan-out run out of the global log.
+- The PreToolUse:Task hook watches the token ceiling. At ≥90 % it
+  appends a wind-down note to its routing advice ("finish in-flight
+  work rather than starting new branches") and logs a
+  `workflow_near_budget` diagnostic — visible in `workflow status`.
+  Dispatch is never hard-blocked on budget (a half-finished fan-out
+  is worse than a small overrun).
+- The window title switches to `[TP] wf · N tasks · X%` so a long run
+  shows live progress.
+
+Claude Code's own `/workflow` (2.1.154+) does **not** expose a
+per-workflow id env var to subagents (verified against the 2.1.161
+bundle — it has only a `CLAUDE_CODE_WORKFLOWS` feature flag). So
+token-pilot's workflows are independent: they rely on our own
+`TOKEN_PILOT_WORKFLOW_ID`. If CC adds a per-workflow env var later,
+`activeWorkflowId()` already probes for it — no config change needed.
+
 ## Troubleshooting
 
 ```bash

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

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

package/agents/tp-audit-scanner.md

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

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.36.0"
+token_pilot_version: "0.39.1"
 token_pilot_body_hash: de64a406b5176de19f7422619c7de7949b1f28865f225402c9cea9255f377428
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-context-engineer.md

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

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

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

package/agents/tp-debugger.md

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

package/agents/tp-dep-health.md

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

package/agents/tp-doc-writer.md

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

package/agents/tp-history-explorer.md

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

package/agents/tp-impact-analyzer.md

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

package/agents/tp-incident-timeline.md

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

package/agents/tp-incremental-builder.md

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

package/agents/tp-migration-scout.md

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

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.36.0"
+token_pilot_version: "0.39.1"
 token_pilot_body_hash: 832e95633fbc8e9b0c10f3e540a327d4be062fb4b3f17a6cce6be13f414e2927
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-performance-profiler.md

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

package/agents/tp-pr-reviewer.md

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

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.36.0"
+token_pilot_version: "0.39.1"
 token_pilot_body_hash: c5f6fc122c89e16e5cf774045f92169ee3468555320b898171ba13eca5323550
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-review-impact.md

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

package/agents/tp-run.md

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

package/agents/tp-session-restorer.md

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

package/agents/tp-ship-coordinator.md

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

package/agents/tp-spec-writer.md

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

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

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

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.36.0"
+token_pilot_version: "0.39.1"
 token_pilot_body_hash: 362ecf4cb03b059421ea26933473700900073dc38b3a7fe271208dfb1ae14f90
 requiredMcpServers:
   - "token-pilot"

package/agents/tp-test-writer.md

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

package/dist/cli/stats.d.ts

@@ -22,6 +22,8 @@ export interface StatsOptions {
     byAgent?: boolean;
     /** v0.31.0 — Task-routing view: subagent_type usage + miss-rate. */
     tasks?: boolean;
+    /** v0.39.0 — aggregate of `event:"workflow"` completion rows. */
+    workflows?: boolean;
 }
 /**
  * Pure formatter. Takes the full event list and options; returns the

package/dist/cli/stats.js

@@ -67,6 +67,36 @@ export function formatStats(events, opts) {
     const total = sumSaved(scope);
     const sessionSuffix = sessionLabel ? ` (session ${sessionLabel})` : "";
     lines.push(`token-pilot stats${sessionSuffix} — ${scope.length} event${scope.length === 1 ? "" : "s"}, ~${total} tokens saved`);
+    if (opts.workflows) {
+        // v0.39.0 — workflow completion view. Each `event:"workflow"` row is
+        // a frozen summary written by `workflow end`.
+        const wf = scope.filter((e) => e.event === "workflow");
+        if (wf.length === 0) {
+            return lines[0] + "\n\nNo completed workflows yet.";
+        }
+        let totalUsed = 0;
+        let totalTasks = 0;
+        let totalOver = 0;
+        const rows = [];
+        for (const e of wf) {
+            const d = (e.detail ?? {});
+            const used = d.used_tokens ?? e.estTokens ?? 0;
+            const tasks = d.task_count ?? 0;
+            const over = d.over_budget_workers ?? 0;
+            totalUsed += used;
+            totalTasks += tasks;
+            totalOver += over;
+            const pct = d.pct != null ? ` (${d.pct}%)` : "";
+            rows.push(`  ${e.workflow_id ?? "?"}  ${tasks} tasks · ~${used} tok${pct}` +
+                (over > 0 ? ` · ${over} over-budget` : "") +
+                (d.goal ? `  — ${d.goal}` : ""));
+        }
+        lines.push("");
+        lines.push(`Completed workflows: ${wf.length} · ${totalTasks} tasks · ~${totalUsed} tokens · ${totalOver} over-budget`);
+        lines.push("");
+        lines.push(...rows);
+        return lines.join("\n");
+    }
     if (opts.tasks) {
         // v0.31.0 — Task-routing view. Scope to event:"task" records only.
         const taskEvents = scope.filter((e) => e.event === "task");
@@ -172,10 +202,12 @@ export async function handleStats(argv, opts) {
     const session = parseFlag(argv, "session");
     const byAgent = parseFlag(argv, "by-agent");
     const tasks = parseFlag(argv, "tasks");
+    const workflows = parseFlag(argv, "workflows");
     const rendered = formatStats(events, {
         session: session === undefined ? undefined : session,
         byAgent: byAgent === true,
         tasks: tasks === true,
+        workflows: workflows === true,
     });
     process.stdout.write(rendered + "\n");
     return 0;

package/dist/cli/typo-guard.d.ts

@@ -17,7 +17,7 @@
  * Everything else passes through untouched — a real project root like
  * `/home/user/my-project` or `./subdir` goes to startServer as before.
  */
-export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-pre-bash", "hook-pre-grep", "hook-pre-task", "hook-post-bash", "hook-post-task", "hook-session-start", "hook-bootstrap", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "tool-audit", "save-doc", "list-docs", "init", "migrate-hooks", "errors", "--version", "-v", "--help", "-h"];
+export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-pre-bash", "hook-pre-grep", "hook-pre-task", "hook-post-bash", "hook-post-task", "hook-session-start", "hook-bootstrap", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "tool-audit", "save-doc", "list-docs", "init", "migrate-hooks", "errors", "workflow", "--version", "-v", "--help", "-h"];
 export interface TypoGuardResult {
     kind: "pass-through" | "typo";
     suggestion?: string;

package/dist/cli/typo-guard.js

@@ -51,6 +51,8 @@ export const KNOWN_COMMANDS = [
     // v0.33.0
     "migrate-hooks",
     "errors",
+    // v0.38.0 — fleet workflow lifecycle
+    "workflow",
     "--version",
     "-v",
     "--help",

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

@@ -38,6 +38,13 @@ export interface HookEvent {
      * never populate it; events stay shape-compatible.
      */
     parent_agent_id?: string | null;
+    /**
+     * v0.38.0 — id of the token-pilot workflow this event belongs to,
+     * when one is active (TOKEN_PILOT_WORKFLOW_ID set). Lets fleet-level
+     * budget + telemetry slice a fan-out run out of the global log.
+     * Optional — absent when no workflow is active.
+     */
+    workflow_id?: string;
     event: "denied" | "allowed" | "bypass" | "pass-through" | "task" | "diagnostic" | string;
     file: string;
     lines: number;

package/dist/core/event-log.js

@@ -108,9 +108,18 @@ async function rotateIfNeeded(projectRoot, thresholdBytes = ROTATION_THRESHOLD_B
  */
 export async function appendEvent(projectRoot, event) {
     try {
+        // v0.38.0 — auto-tag with the active workflow id so every event
+        // emitted inside a `token-pilot workflow` boundary is sliceable.
+        // Read the env var directly here to keep call sites unchanged; an
+        // explicit workflow_id on the event always wins.
+        const wf = event.workflow_id ??
+            process.env.TOKEN_PILOT_WORKFLOW_ID ??
+            process.env.CLAUDE_CODE_WORKFLOW_ID ??
+            undefined;
+        const tagged = wf ? { ...event, workflow_id: wf } : event;
         await ensureLogDir(projectRoot);
         await rotateIfNeeded(projectRoot);
-        const line = JSON.stringify(event) + "\n";
+        const line = JSON.stringify(tagged) + "\n";
         await fs.appendFile(currentLogPath(projectRoot), line);
     }
     catch {

package/dist/core/workflow.d.ts

@@ -0,0 +1,117 @@
+/**
+ * v0.38.0 — fleet workflow lifecycle.
+ *
+ * The fleet design note (docs/design/2026-06-tp-fleet-dynamic-workflows.md)
+ * flagged one blocker: it assumed Claude Code's `/workflow` would set a
+ * propagated workflow-id env var on dispatched subagents. The 2.1.131
+ * bundle has no such variable, so building tagging/budget against it
+ * would be the v0.34.0-args mistake again (shipping against an
+ * interface that may not exist).
+ *
+ * Resolution: token-pilot OWNS the workflow boundary. A user wraps a
+ * batch of fan-out work with `token-pilot workflow start` / `end`,
+ * which writes an envelope file and exports `TOKEN_PILOT_WORKFLOW_ID`.
+ * Every hook reads that env var and tags its events. No dependency on
+ * Claude Code's `/workflow` — and if CC ever propagates its own
+ * workflow id env var, we read that too (see activeWorkflowId).
+ *
+ * State lives in `<projectRoot>/.token-pilot/workflows/`:
+ *   <id>.json                 — the envelope (goal, budget, started/ended)
+ * Events stay in the normal hook-events.jsonl, tagged with workflow_id.
+ *
+ * Pure-ish: all filesystem helpers swallow errors (telemetry must
+ * never break a hook). The `now`/`id` injection points keep the unit
+ * tests deterministic.
+ */
+import { type HookEvent } from "./event-log.js";
+export declare const WORKFLOW_SUBDIR = ".token-pilot/workflows";
+export interface WorkflowEnvelope {
+    workflow_id: string;
+    started_at: number;
+    ended_at: number | null;
+    goal: string;
+    budget_tokens: number | null;
+    max_parallel: number | null;
+}
+export interface WorkflowBudgetStatus {
+    workflow_id: string;
+    goal: string;
+    budget_tokens: number | null;
+    used_tokens: number;
+    pct: number | null;
+    event_count: number;
+    task_count: number;
+    over_budget_workers: number;
+    ended: boolean;
+}
+/**
+ * Resolve the active workflow id. token-pilot's own env var takes
+ * precedence.
+ *
+ * Note (verified against CC 2.1.161): Claude Code's `/workflow` does
+ * NOT export a per-workflow id env var to dispatched subagents — the
+ * bundle only has the `CLAUDE_CODE_WORKFLOWS` feature flag and an
+ * internal `WorkflowId`. The extra names below are a harmless
+ * forward-compat probe (they return null today); token-pilot's fleet
+ * workflows are independent and rely solely on our own
+ * `TOKEN_PILOT_WORKFLOW_ID`. Returns null when none is set.
+ */
+export declare function activeWorkflowId(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Build a workflow id. Format `wf-<base36 ts>-<suffix>`. `now` and
+ * `suffix` are injectable for deterministic tests; production passes a
+ * timestamp + a short random token.
+ */
+export declare function makeWorkflowId(now: number, suffix: string): string;
+export interface StartWorkflowInput {
+    projectRoot: string;
+    goal: string;
+    budgetTokens?: number | null;
+    maxParallel?: number | null;
+    /** Injectable for tests. */
+    now?: number;
+    /** Injectable for tests. */
+    idSuffix?: string;
+}
+/**
+ * Create a workflow envelope and return it. The caller is responsible
+ * for exporting `TOKEN_PILOT_WORKFLOW_ID=<id>` into the environment of
+ * the work that follows (the CLI prints an `export` line for this).
+ */
+export declare function startWorkflow(input: StartWorkflowInput): Promise<WorkflowEnvelope>;
+export declare function loadWorkflow(projectRoot: string, id: string): Promise<WorkflowEnvelope | null>;
+/**
+ * Mark a workflow ended (stamps ended_at) and emit a frozen
+ * `event:"workflow"` completion record into hook-events.jsonl.
+ *
+ * v0.39.0 — the envelope stores only the static plan (goal, budget,
+ * timestamps); the aggregates (tokens used, task count) are computed
+ * live from tagged events. Freezing them in a single summary row at
+ * end time makes historical analysis cheap and survives event-log
+ * rotation (which could otherwise drop the underlying per-task rows).
+ * Returns the updated envelope, or null when the id is unknown.
+ */
+export declare function endWorkflow(projectRoot: string, id: string, now?: number): Promise<WorkflowEnvelope | null>;
+/** List all workflow envelopes, newest first. */
+export declare function listWorkflows(projectRoot: string): Promise<WorkflowEnvelope[]>;
+/**
+ * Pure aggregation of a workflow's status from its envelope + the set
+ * of events tagged with its id. Separated from I/O so tests drive it
+ * directly.
+ */
+export declare function computeWorkflowStatus(envelope: WorkflowEnvelope, events: HookEvent[]): WorkflowBudgetStatus;
+/**
+ * Load a workflow's live status from disk (envelope + tagged events
+ * across the repo tree). Returns null when the id is unknown.
+ */
+export declare function workflowStatus(projectRoot: string, id: string): Promise<WorkflowBudgetStatus | null>;
+/**
+ * Returns true when the workflow's used tokens are within `nearPct`
+ * percent of its ceiling (or over). Used by the pre-task hook to warn
+ * the fleet to wind down before the ceiling is breached. False when no
+ * budget is set.
+ */
+export declare function isWorkflowNearBudget(status: WorkflowBudgetStatus, nearPct?: number): boolean;
+export declare function formatWorkflowStatus(status: WorkflowBudgetStatus): string;
+export declare function formatWorkflowList(workflows: WorkflowEnvelope[]): string;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/core/workflow.js

@@ -0,0 +1,269 @@
+/**
+ * v0.38.0 — fleet workflow lifecycle.
+ *
+ * The fleet design note (docs/design/2026-06-tp-fleet-dynamic-workflows.md)
+ * flagged one blocker: it assumed Claude Code's `/workflow` would set a
+ * propagated workflow-id env var on dispatched subagents. The 2.1.131
+ * bundle has no such variable, so building tagging/budget against it
+ * would be the v0.34.0-args mistake again (shipping against an
+ * interface that may not exist).
+ *
+ * Resolution: token-pilot OWNS the workflow boundary. A user wraps a
+ * batch of fan-out work with `token-pilot workflow start` / `end`,
+ * which writes an envelope file and exports `TOKEN_PILOT_WORKFLOW_ID`.
+ * Every hook reads that env var and tags its events. No dependency on
+ * Claude Code's `/workflow` — and if CC ever propagates its own
+ * workflow id env var, we read that too (see activeWorkflowId).
+ *
+ * State lives in `<projectRoot>/.token-pilot/workflows/`:
+ *   <id>.json                 — the envelope (goal, budget, started/ended)
+ * Events stay in the normal hook-events.jsonl, tagged with workflow_id.
+ *
+ * Pure-ish: all filesystem helpers swallow errors (telemetry must
+ * never break a hook). The `now`/`id` injection points keep the unit
+ * tests deterministic.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { appendEvent, loadEventsTree, } from "./event-log.js";
+export const WORKFLOW_SUBDIR = ".token-pilot/workflows";
+// ─── env access ──────────────────────────────────────────────────────
+/**
+ * Resolve the active workflow id. token-pilot's own env var takes
+ * precedence.
+ *
+ * Note (verified against CC 2.1.161): Claude Code's `/workflow` does
+ * NOT export a per-workflow id env var to dispatched subagents — the
+ * bundle only has the `CLAUDE_CODE_WORKFLOWS` feature flag and an
+ * internal `WorkflowId`. The extra names below are a harmless
+ * forward-compat probe (they return null today); token-pilot's fleet
+ * workflows are independent and rely solely on our own
+ * `TOKEN_PILOT_WORKFLOW_ID`. Returns null when none is set.
+ */
+export function activeWorkflowId(env = process.env) {
+    return (env.TOKEN_PILOT_WORKFLOW_ID ||
+        env.CLAUDE_CODE_WORKFLOW_ID ||
+        env.CLAUDE_WORKFLOW_ID ||
+        null);
+}
+// ─── id generation ───────────────────────────────────────────────────
+/**
+ * Build a workflow id. Format `wf-<base36 ts>-<suffix>`. `now` and
+ * `suffix` are injectable for deterministic tests; production passes a
+ * timestamp + a short random token.
+ */
+export function makeWorkflowId(now, suffix) {
+    return `wf-${now.toString(36)}-${suffix}`;
+}
+// ─── paths ───────────────────────────────────────────────────────────
+function workflowDir(projectRoot) {
+    return join(projectRoot, WORKFLOW_SUBDIR);
+}
+function envelopePath(projectRoot, id) {
+    return join(workflowDir(projectRoot), `${id}.json`);
+}
+/**
+ * Create a workflow envelope and return it. The caller is responsible
+ * for exporting `TOKEN_PILOT_WORKFLOW_ID=<id>` into the environment of
+ * the work that follows (the CLI prints an `export` line for this).
+ */
+export async function startWorkflow(input) {
+    const now = input.now ?? Date.now();
+    const suffix = input.idSuffix ?? Math.floor(now % 1_000_000).toString(36).padStart(4, "0");
+    const envelope = {
+        workflow_id: makeWorkflowId(now, suffix),
+        started_at: now,
+        ended_at: null,
+        goal: input.goal,
+        budget_tokens: input.budgetTokens ?? null,
+        max_parallel: input.maxParallel ?? null,
+    };
+    try {
+        await fs.mkdir(workflowDir(input.projectRoot), { recursive: true });
+        await fs.writeFile(envelopePath(input.projectRoot, envelope.workflow_id), JSON.stringify(envelope, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort — never block the caller */
+    }
+    return envelope;
+}
+export async function loadWorkflow(projectRoot, id) {
+    try {
+        const raw = await fs.readFile(envelopePath(projectRoot, id), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.workflow_id === "string")
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mark a workflow ended (stamps ended_at) and emit a frozen
+ * `event:"workflow"` completion record into hook-events.jsonl.
+ *
+ * v0.39.0 — the envelope stores only the static plan (goal, budget,
+ * timestamps); the aggregates (tokens used, task count) are computed
+ * live from tagged events. Freezing them in a single summary row at
+ * end time makes historical analysis cheap and survives event-log
+ * rotation (which could otherwise drop the underlying per-task rows).
+ * Returns the updated envelope, or null when the id is unknown.
+ */
+export async function endWorkflow(projectRoot, id, now = Date.now()) {
+    const env = await loadWorkflow(projectRoot, id);
+    if (!env)
+        return null;
+    env.ended_at = now;
+    try {
+        await fs.writeFile(envelopePath(projectRoot, id), JSON.stringify(env, null, 2) + "\n");
+    }
+    catch {
+        /* best-effort */
+    }
+    // Freeze the aggregates into a completion event.
+    try {
+        const events = await loadEventsTree(projectRoot);
+        const status = computeWorkflowStatus(env, events);
+        const summary = {
+            ts: now,
+            session_id: "workflow",
+            agent_type: null,
+            agent_id: null,
+            workflow_id: id,
+            event: "workflow",
+            file: "",
+            lines: 0,
+            estTokens: status.used_tokens,
+            summaryTokens: 0,
+            savedTokens: 0,
+            level: "info",
+            code: "workflow_complete",
+            detail: {
+                goal: env.goal,
+                budget_tokens: env.budget_tokens,
+                used_tokens: status.used_tokens,
+                pct: status.pct,
+                task_count: status.task_count,
+                over_budget_workers: status.over_budget_workers,
+                duration_ms: env.ended_at - env.started_at,
+            },
+        };
+        // Pass the workflow_id explicitly so appendEvent keeps it even if
+        // the env var has already been unset by the time `end` runs.
+        await appendEvent(projectRoot, summary);
+    }
+    catch {
+        /* completion telemetry is best-effort */
+    }
+    return env;
+}
+/** List all workflow envelopes, newest first. */
+export async function listWorkflows(projectRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(workflowDir(projectRoot));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const env = await loadWorkflow(projectRoot, name.replace(/\.json$/, ""));
+        if (env)
+            out.push(env);
+    }
+    out.sort((a, b) => b.started_at - a.started_at);
+    return out;
+}
+// ─── budget + telemetry ──────────────────────────────────────────────
+/**
+ * Pure aggregation of a workflow's status from its envelope + the set
+ * of events tagged with its id. Separated from I/O so tests drive it
+ * directly.
+ */
+export function computeWorkflowStatus(envelope, events) {
+    const mine = events.filter((e) => e.workflow_id === envelope.workflow_id);
+    let used = 0;
+    let taskCount = 0;
+    let overWorkers = 0;
+    for (const e of mine) {
+        if (e.event === "task") {
+            taskCount++;
+            used += e.estTokens || 0;
+            if (e.overBudget)
+                overWorkers++;
+        }
+    }
+    const pct = envelope.budget_tokens && envelope.budget_tokens > 0
+        ? Math.round((used / envelope.budget_tokens) * 100)
+        : null;
+    return {
+        workflow_id: envelope.workflow_id,
+        goal: envelope.goal,
+        budget_tokens: envelope.budget_tokens,
+        used_tokens: used,
+        pct,
+        event_count: mine.length,
+        task_count: taskCount,
+        over_budget_workers: overWorkers,
+        ended: envelope.ended_at != null,
+    };
+}
+/**
+ * Load a workflow's live status from disk (envelope + tagged events
+ * across the repo tree). Returns null when the id is unknown.
+ */
+export async function workflowStatus(projectRoot, id) {
+    const envelope = await loadWorkflow(projectRoot, id);
+    if (!envelope)
+        return null;
+    const events = await loadEventsTree(projectRoot);
+    return computeWorkflowStatus(envelope, events);
+}
+/**
+ * Returns true when the workflow's used tokens are within `nearPct`
+ * percent of its ceiling (or over). Used by the pre-task hook to warn
+ * the fleet to wind down before the ceiling is breached. False when no
+ * budget is set.
+ */
+export function isWorkflowNearBudget(status, nearPct = 90) {
+    if (status.budget_tokens == null || status.budget_tokens <= 0)
+        return false;
+    return status.used_tokens >= status.budget_tokens * (nearPct / 100);
+}
+// ─── formatting ──────────────────────────────────────────────────────
+function humanTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}k`;
+    return `${n}`;
+}
+export function formatWorkflowStatus(status) {
+    const lines = [];
+    lines.push(`workflow ${status.workflow_id}${status.ended ? " (ended)" : ""}`);
+    lines.push(`  goal:        ${status.goal}`);
+    const budget = status.budget_tokens != null
+        ? `${humanTokens(status.budget_tokens)} ceiling`
+        : "no ceiling";
+    const pct = status.pct != null ? ` (${status.pct}%)` : "";
+    lines.push(`  budget:      ${budget} · ${humanTokens(status.used_tokens)} used${pct}`);
+    lines.push(`  tasks:       ${status.task_count} dispatched · ${status.over_budget_workers} over-budget`);
+    lines.push(`  events:      ${status.event_count} tagged`);
+    return lines.join("\n");
+}
+export function formatWorkflowList(workflows) {
+    if (workflows.length === 0)
+        return "No workflows recorded.";
+    const lines = [`${workflows.length} workflow(s):`];
+    for (const w of workflows) {
+        const state = w.ended_at ? "ended " : "active";
+        const budget = w.budget_tokens != null ? `${humanTokens(w.budget_tokens)} ceiling` : "—";
+        lines.push(`  [${state}] ${w.workflow_id}  ${budget}  ${w.goal}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=workflow.js.map

package/dist/hooks/post-task.d.ts

@@ -19,9 +19,24 @@ export declare const OVER_BUDGET_LOG = "over-budget.log";
 export declare const OVER_BUDGET_TOLERANCE = 0.1;
 export declare function parseAgentBudget(body: string): number | null;
 /**
- * Count approx tokens in the `tool_response.content[*].text` blocks of a
- * PostToolUse hook input for the Task tool. Returns null for anything
- * other than a well-formed Task response.
+ * Extract the subagent's token count from a PostToolUse:Task hook input.
+ *
+ * v0.37.0 — the Task tool's `tool_response` carries an authoritative
+ * `totalTokens` field. Verified by inspecting the Claude Code 2.1.131
+ * bundle: the Task result object is
+ *   { agentId, agentType, content, totalDurationMs, totalTokens, totalToolUseCount, usage }
+ * Earlier versions of this function only summed `content[*].text`
+ * lengths / 4 — a rough heuristic that returned 0 whenever the
+ * response wasn't a `{content:[{text}]}` array, leaving the budget
+ * watchdog and task token-weighting permanently at zero.
+ *
+ * Resolution order:
+ *   1. `tool_response.totalTokens` (exact, preferred)
+ *   2. `tool_response.usage.output_tokens` (exact, alternate shape)
+ *   3. char/4 over `content[*].text` (legacy heuristic fallback)
+ *   4. char/4 over a plain string `content`
+ *
+ * Returns null only when no signal at all is available.
  */
 export declare function extractSubagentTokens(input: {
     tool_name?: string;

package/dist/hooks/post-task.js

@@ -30,9 +30,24 @@ export function parseAgentBudget(body) {
     return Number.isFinite(n) && n > 0 ? n : null;
 }
 /**
- * Count approx tokens in the `tool_response.content[*].text` blocks of a
- * PostToolUse hook input for the Task tool. Returns null for anything
- * other than a well-formed Task response.
+ * Extract the subagent's token count from a PostToolUse:Task hook input.
+ *
+ * v0.37.0 — the Task tool's `tool_response` carries an authoritative
+ * `totalTokens` field. Verified by inspecting the Claude Code 2.1.131
+ * bundle: the Task result object is
+ *   { agentId, agentType, content, totalDurationMs, totalTokens, totalToolUseCount, usage }
+ * Earlier versions of this function only summed `content[*].text`
+ * lengths / 4 — a rough heuristic that returned 0 whenever the
+ * response wasn't a `{content:[{text}]}` array, leaving the budget
+ * watchdog and task token-weighting permanently at zero.
+ *
+ * Resolution order:
+ *   1. `tool_response.totalTokens` (exact, preferred)
+ *   2. `tool_response.usage.output_tokens` (exact, alternate shape)
+ *   3. char/4 over `content[*].text` (legacy heuristic fallback)
+ *   4. char/4 over a plain string `content`
+ *
+ * Returns null only when no signal at all is available.
  */
 export function extractSubagentTokens(input) {
     if (input.tool_name !== "Task")
@@ -40,15 +55,33 @@ export function extractSubagentTokens(input) {
     const resp = input.tool_response;
     if (!resp || typeof resp !== "object")
         return null;
-    const parts = Array.isArray(resp.content) ? resp.content : [];
-    let chars = 0;
-    for (const p of parts) {
-        if (typeof p?.text === "string")
-            chars += p.text.length;
+    // 1. Authoritative totalTokens.
+    if (typeof resp.totalTokens === "number" && resp.totalTokens > 0) {
+        return Math.round(resp.totalTokens);
     }
-    if (chars === 0)
-        return null;
-    return Math.ceil(chars / 4);
+    // 2. usage shape (alternate / future-proof).
+    const usage = resp.usage;
+    if (usage && typeof usage === "object") {
+        const out = usage.total_tokens ?? usage.output_tokens;
+        if (typeof out === "number" && out > 0)
+            return Math.round(out);
+    }
+    // 3. Legacy heuristic over content[*].text.
+    if (Array.isArray(resp.content)) {
+        let chars = 0;
+        for (const p of resp.content) {
+            if (p && typeof p.text === "string") {
+                chars += p.text.length;
+            }
+        }
+        if (chars > 0)
+            return Math.ceil(chars / 4);
+    }
+    // 4. Plain-string content.
+    if (typeof resp.content === "string" && resp.content.length > 0) {
+        return Math.ceil(resp.content.length / 4);
+    }
+    return null;
 }
 export function decideBudgetAdvice(input) {
     if (input.budget == null || input.budget <= 0) {

package/dist/hooks/pre-task.d.ts

@@ -63,9 +63,14 @@ export declare function decidePreTask(input: PreTaskInput, ctx: PreTaskContext):
 /**
  * Render the Claude Code hook JSON response.
  *
- * - allow  → no output (pass-through)
- * - advise → permissionDecision=allow + additionalContext
- * - deny   → permissionDecision=deny + reason
+ * - allow  → no output (pass-through), UNLESS `append` carries a fleet
+ *            budget note — then emit an allow + additionalContext so the
+ *            note still reaches the agent.
+ * - advise → permissionDecision=allow + additionalContext (+ append)
+ * - deny   → permissionDecision=deny + reason (+ append)
+ *
+ * v0.38.0 — `append` is an optional trailing string (the workflow
+ * near-budget wind-down note). Empty / omitted leaves output unchanged.
  */
-export declare function renderPreTaskOutput(decision: PreTaskDecision): string | null;
+export declare function renderPreTaskOutput(decision: PreTaskDecision, append?: string): string | null;
 //# sourceMappingURL=pre-task.d.ts.map

package/dist/hooks/pre-task.js

@@ -132,19 +132,34 @@ export function decidePreTask(input, ctx) {
 /**
  * Render the Claude Code hook JSON response.
  *
- * - allow  → no output (pass-through)
- * - advise → permissionDecision=allow + additionalContext
- * - deny   → permissionDecision=deny + reason
+ * - allow  → no output (pass-through), UNLESS `append` carries a fleet
+ *            budget note — then emit an allow + additionalContext so the
+ *            note still reaches the agent.
+ * - advise → permissionDecision=allow + additionalContext (+ append)
+ * - deny   → permissionDecision=deny + reason (+ append)
+ *
+ * v0.38.0 — `append` is an optional trailing string (the workflow
+ * near-budget wind-down note). Empty / omitted leaves output unchanged.
  */
-export function renderPreTaskOutput(decision) {
-    if (decision.kind === "allow")
-        return null;
+export function renderPreTaskOutput(decision, append = "") {
+    const extra = append || "";
+    if (decision.kind === "allow") {
+        if (!extra)
+            return null;
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                additionalContext: extra.trimStart(),
+            },
+        });
+    }
     if (decision.kind === "advise") {
         return JSON.stringify({
             hookSpecificOutput: {
                 hookEventName: "PreToolUse",
                 permissionDecision: "allow",
-                additionalContext: decision.message,
+                additionalContext: decision.message + extra,
             },
         });
     }
@@ -152,7 +167,7 @@ export function renderPreTaskOutput(decision) {
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "deny",
-            permissionDecisionReason: decision.reason,
+            permissionDecisionReason: decision.reason + extra,
         },
     });
 }

package/dist/hooks/session-start.js

@@ -318,6 +318,18 @@ export async function handleSessionStart(opts) {
                         : `${surfaced}`;
                 sessionTitle = `[TP] ${human} saved`;
             }
+            // v0.38.0 — when a fleet workflow is active, prefer a
+            // workflow-progress title so a long fan-out run shows live
+            // task count + budget in the window title.
+            const { activeWorkflowId, workflowStatus } = await import("../core/workflow.js");
+            const wfId = activeWorkflowId();
+            if (wfId) {
+                const st = await workflowStatus(opts.projectRoot, wfId);
+                if (st) {
+                    const pct = st.pct != null ? ` · ${st.pct}%` : "";
+                    sessionTitle = `[TP] wf · ${st.task_count} tasks${pct}`;
+                }
+            }
         }
         catch {
             /* sessionTitle is best-effort decoration; never block startup */

package/dist/index.d.ts

@@ -58,6 +58,20 @@ export declare function runHookReadDispatch(filePathArg: string | undefined, mod
  * (file existence, prep-state lookup, env vars).
  */
 export declare function handleHookEdit(): void;
+/**
+ * v0.38.0 — `token-pilot workflow <subcommand>` CLI.
+ *
+ *   start <goal> [--budget=N] [--max-parallel=N]
+ *       Create a workflow envelope and print an `export
+ *       TOKEN_PILOT_WORKFLOW_ID=<id>` line. Wrap a fan-out batch with
+ *       this so every hook event gets tagged with the id.
+ *   end [<id>]      Stamp the workflow ended (defaults to active env id).
+ *   status [<id>]   Show live budget + task counts (defaults to env id).
+ *   list            All recorded workflows, newest first.
+ *
+ * Returns a process exit code.
+ */
+export declare function handleWorkflowCli(argv: string[]): Promise<number>;
 export declare function handleInstallHook(projectRoot: string): Promise<void>;
 export declare function handleUninstallHook(projectRoot: string): Promise<void>;
 export declare function handleInstallAstIndex(): Promise<void>;

package/dist/index.js

@@ -27,6 +27,7 @@ import { installHook, uninstallHook, cleanStaleHookEntries, isTokenPilotPluginEn
 import { runHookEntryPoint } from "./hooks/safe-runner.js";
 import { loadErrors, formatErrorList } from "./core/error-log.js";
 import { appendDiagnostic } from "./core/event-log.js";
+import { startWorkflow, endWorkflow, listWorkflows, workflowStatus, formatWorkflowStatus, formatWorkflowList, } from "./core/workflow.js";
 import { findBinary, installBinary, checkBinaryUpdate, isNewerVersion, } from "./ast-index/binary-manager.js";
 import { loadConfig } from "./config/loader.js";
 import { isDangerousRoot } from "./core/validation.js";
@@ -229,7 +230,30 @@ export async function main(cliArgs = process.argv.slice(2)) {
                         /* never block dispatch on telemetry */
                     });
                 }
-                const rendered = renderPreTaskOutput(decision);
+                // v0.38.0 — fleet budget guard. When a workflow is active and
+                // its token ceiling is within reach, append a wind-down note
+                // to whatever the routing decision produced. The dispatch is
+                // never hard-blocked on budget (a half-finished fan-out is
+                // worse than a small overrun) — we advise, and surface an
+                // over-budget diagnostic so `workflow status` reflects it.
+                const { activeWorkflowId, workflowStatus, isWorkflowNearBudget } = await import("./core/workflow.js");
+                const wfId = activeWorkflowId();
+                let budgetNote = "";
+                if (wfId) {
+                    const st = await workflowStatus(process.cwd(), wfId);
+                    if (st && isWorkflowNearBudget(st)) {
+                        budgetNote =
+                            `\n\n[token-pilot] workflow ${wfId} is at ${st.pct ?? "~"}% of its ` +
+                                `${st.budget_tokens} token ceiling — finish in-flight work and ` +
+                                `report rather than starting new branches.`;
+                        appendDiagnostic(process.cwd(), {
+                            code: "workflow_near_budget",
+                            level: "warn",
+                            detail: { workflow_id: wfId, pct: st.pct, used: st.used_tokens },
+                        }).catch(() => { });
+                    }
+                }
+                const rendered = renderPreTaskOutput(decision, budgetNote);
                 if (rendered)
                     process.stdout.write(rendered);
             });
@@ -348,6 +372,15 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.stdout.write(formatErrorList(records) + "\n");
             return;
         }
+        case "workflow": {
+            // v0.38.0 — fleet workflow lifecycle. token-pilot owns the
+            // workflow boundary (we set TOKEN_PILOT_WORKFLOW_ID ourselves),
+            // so this works regardless of whether Claude Code's /workflow
+            // propagates an env var. Subcommands: start / end / status / list.
+            const code = await handleWorkflowCli(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
         case "migrate-hooks": {
             // v0.33.0 — clean stale npx-cache / pinned-version token-pilot
             // hook entries from user-level + project-level settings.json so
@@ -903,6 +936,101 @@ export function handleHookEdit() {
         process.stdout.write(rendered);
     process.exit(0);
 }
+/**
+ * v0.38.0 — `token-pilot workflow <subcommand>` CLI.
+ *
+ *   start <goal> [--budget=N] [--max-parallel=N]
+ *       Create a workflow envelope and print an `export
+ *       TOKEN_PILOT_WORKFLOW_ID=<id>` line. Wrap a fan-out batch with
+ *       this so every hook event gets tagged with the id.
+ *   end [<id>]      Stamp the workflow ended (defaults to active env id).
+ *   status [<id>]   Show live budget + task counts (defaults to env id).
+ *   list            All recorded workflows, newest first.
+ *
+ * Returns a process exit code.
+ */
+export async function handleWorkflowCli(argv) {
+    const projectRoot = process.cwd();
+    const sub = argv[0];
+    const flag = (k) => {
+        for (const a of argv) {
+            if (a.startsWith(`--${k}=`))
+                return a.slice(k.length + 3);
+        }
+        return undefined;
+    };
+    const envId = process.env.TOKEN_PILOT_WORKFLOW_ID ||
+        process.env.CLAUDE_CODE_WORKFLOW_ID ||
+        undefined;
+    switch (sub) {
+        case "start": {
+            const goal = argv.slice(1).filter((a) => !a.startsWith("--")).join(" ");
+            if (!goal) {
+                process.stderr.write('workflow start: a goal is required — `token-pilot workflow start "review last sprint"`\n');
+                return 1;
+            }
+            const budgetRaw = flag("budget");
+            const parallelRaw = flag("max-parallel");
+            const env = await startWorkflow({
+                projectRoot,
+                goal,
+                budgetTokens: budgetRaw ? Number(budgetRaw) : null,
+                maxParallel: parallelRaw ? Number(parallelRaw) : null,
+            });
+            // The id goes to stdout as an `export` line so a user can do
+            //   eval "$(token-pilot workflow start '...')"
+            // and have the env var set for the fan-out that follows.
+            process.stdout.write(`export TOKEN_PILOT_WORKFLOW_ID=${env.workflow_id}\n`);
+            process.stderr.write(`[token-pilot] workflow ${env.workflow_id} started` +
+                (env.budget_tokens ? ` · ${env.budget_tokens} token ceiling` : "") +
+                `\n`);
+            return 0;
+        }
+        case "end": {
+            const id = argv[1] && !argv[1].startsWith("--") ? argv[1] : envId;
+            if (!id) {
+                process.stderr.write("workflow end: no id given and TOKEN_PILOT_WORKFLOW_ID not set.\n");
+                return 1;
+            }
+            const env = await endWorkflow(projectRoot, id);
+            if (!env) {
+                process.stderr.write(`workflow end: unknown workflow "${id}".\n`);
+                return 1;
+            }
+            const status = await workflowStatus(projectRoot, id);
+            if (status)
+                process.stdout.write(formatWorkflowStatus(status) + "\n");
+            process.stderr.write(`[token-pilot] workflow ${id} ended.\n`);
+            return 0;
+        }
+        case "status": {
+            const id = argv[1] && !argv[1].startsWith("--") ? argv[1] : envId;
+            if (!id) {
+                process.stderr.write("workflow status: no id given and TOKEN_PILOT_WORKFLOW_ID not set.\n");
+                return 1;
+            }
+            const status = await workflowStatus(projectRoot, id);
+            if (!status) {
+                process.stderr.write(`workflow status: unknown workflow "${id}".\n`);
+                return 1;
+            }
+            process.stdout.write(formatWorkflowStatus(status) + "\n");
+            return 0;
+        }
+        case "list": {
+            const workflows = await listWorkflows(projectRoot);
+            process.stdout.write(formatWorkflowList(workflows) + "\n");
+            return 0;
+        }
+        default:
+            process.stderr.write("Usage: token-pilot workflow <start|end|status|list>\n" +
+                '  start "<goal>" [--budget=N] [--max-parallel=N]\n' +
+                "  end [<id>]\n" +
+                "  status [<id>]\n" +
+                "  list\n");
+            return sub ? 1 : 0;
+    }
+}
 export async function handleInstallHook(projectRoot) {
     // v0.26.5 — plugin-aware early-return. If we're running as a Claude
     // Code plugin (CLAUDE_PLUGIN_ROOT set) the hooks are already declared

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.36.0",
+  "version": "0.39.1",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",