token-pilot 0.35.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.35.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.35.0",
+      "version": "0.39.1",
       "author": {
         "name": "Digital-Threads"
       },

package/.claude-plugin/plugin.json

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

@@ -232,6 +232,85 @@ lines instead of bouncing the call. The structural summary still
 rides along in `additionalContext`. Default OFF because the field
 is undocumented and may change.
 
+## What's new for Claude Code 2.1.151+
+
+These notes are about behaviour you'll see automatically once you
+update both Claude Code and `token-pilot@latest`. No extra
+configuration required.
+
+### Session title badge (`[TP] Nk saved`)
+
+The SessionStart hook now sets the window/tab title to the cumulative
+token savings for the current project, using Claude Code 2.1.152's
+`hookSpecificOutput.sessionTitle` field. You'll see a badge like
+`[TP] 1.2M saved` in the title bar so you can confirm at a glance
+that the plugin is doing its job.
+
+### Hardened skills (`disallowed-tools`)
+
+The three bundled skills (`guide`, `install`, `stats`) declare
+`disallowed-tools` (Claude Code 2.1.152+) so a runaway model can't
+issue `Write` / `Edit` / `Task` while the skill is on display. The
+install skill keeps `Bash` because it has to run
+`npx token-pilot install-ast-index`; the other two have Bash
+disallowed too.
+
+### Auto mode on third-party providers
+
+Claude Code 2.1.158 opened auto mode to Bedrock / Vertex / Foundry
+on Opus 4.7 + 4.8. If you're on one of those, opt in with
+`CLAUDE_CODE_ENABLE_AUTO_MODE=1`. token-pilot's deny-Read /
+deny-Bash gates still run on top — auto mode never bypasses them.
+
+### Opus 4.8 as fast-mode default
+
+Claude Code 2.1.154 made Opus 4.8 the default for high effort. The
+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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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.35.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