v0.38.0: fleet workflows — token-pilot owns the workflow boundary (#33)

Implements the fleet design note (Phase 1+2) with the dependency
inverted. The original blocker was "does Claude Code's /workflow
propagate a workflow-id env var?" — inspecting the installed 2.1.131
bundle confirmed it does NOT. Rather than build against an interface
that may never exist (the v0.34.0-args trap), token-pilot OWNS the
workflow boundary: `workflow start/end` sets TOKEN_PILOT_WORKFLOW_ID
itself, so the feature works under any orchestration and composes
with CC's /workflow if it ever sets CLAUDE_CODE_WORKFLOW_ID.

New: src/core/workflow.ts
  - WorkflowEnvelope persisted to .token-pilot/workflows/<id>.json
  - startWorkflow / endWorkflow / loadWorkflow / listWorkflows
  - computeWorkflowStatus (pure) + workflowStatus (I/O)
  - isWorkflowNearBudget, activeWorkflowId, makeWorkflowId, formatters

Event tagging
  - HookEvent gains optional workflow_id
  - appendEvent auto-tags from TOKEN_PILOT_WORKFLOW_ID /
    CLAUDE_CODE_WORKFLOW_ID, so every existing call site (task,
    denied, diagnostic) participates with zero change

CLI: `token-pilot workflow <start|end|status|list>`
  - start "<goal>" [--budget=N] [--max-parallel=N] → prints an
    `export TOKEN_PILOT_WORKFLOW_ID=<id>` line for eval
  - status/end default to the active env id
  - registered in typo-guard KNOWN_COMMANDS

Budget guard (advisory, never hard-blocks)
  - PreToolUse:Task appends a wind-down note + logs a
    workflow_near_budget diagnostic at >=90% of ceiling
  - renderPreTaskOutput gains an optional trailing append arg

Workflow-aware sessionTitle
  - SessionStart title switches to `[TP] wf · N tasks · X%` when a
    workflow is active

Verified end-to-end against the built dist: start → tagged Task event
→ status (4k used / 40% of 10k ceiling, also confirming the v0.37.0
totalTokens extraction) → list → end.

Deliberately NOT built (still gated on real data): fleet memory
rendezvous + ast-index cross-worker cache (SessionCache already
dedups within a process; no data yet on cross-worker duplication),
and a WorkflowComplete polyfill.

Docs: README "Fleet workflows" section; design note Decision updated
to "implemented, dependency inverted".

Tests: 1316/1316 pass (+17 workflow + typo-guard).
Build: clean (25 agents under 0.38.0).

Author: Shahinyanm

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

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

README.md

@@ -269,6 +269,45 @@ 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.
+
+If Claude Code ever sets its own workflow-id env var
+(`CLAUDE_CODE_WORKFLOW_ID`), token-pilot reads that too — no config
+change needed.
+
 ## Troubleshooting
 
 ```bash

agents/tp-api-surface-tracker.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__read_symbol
   - Bash
 model: haiku
-token_pilot_version: "0.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.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.37.0"
+token_pilot_version: "0.38.0"
 token_pilot_body_hash: e14dc57493d816f8c2e017963e2ef5f66bea50fd0b805a80e8a0d97c968427e7
 requiredMcpServers:
   - "token-pilot"