token-pilot 0.35.0 → 0.39.1

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

@@ -274,11 +274,72 @@ export async function handleSessionStart(opts) {
             ".token-pilot/snapshots/latest.md",
             ".token-pilot/hook-events.jsonl",
         ];
+        // v0.36.0 — sessionTitle was added in Claude Code 2.1.152. We surface
+        // the cumulative saved-token count for this project so users see the
+        // payoff at a glance in their window/tab title. Best-effort — if the
+        // savings file is unreadable we fall back to a neutral title.
+        let sessionTitle;
+        try {
+            const { loadSessionStats } = await import("../core/session-savings.js");
+            // Sum savings across all sessions in this project, not just one.
+            const stats = loadSessionStats(opts.projectRoot, "");
+            // sessionId="" makes loadSessionStats short-circuit; use a tiny
+            // dedicated reader instead.
+            const { readFileSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            let total = 0;
+            try {
+                const raw = readFileSync(join(opts.projectRoot, ".token-pilot", "hook-events.jsonl"), "utf-8");
+                for (const line of raw.split("\n")) {
+                    if (!line)
+                        continue;
+                    try {
+                        const ev = JSON.parse(line);
+                        if (typeof ev.savedTokens === "number")
+                            total += ev.savedTokens;
+                    }
+                    catch {
+                        /* skip malformed line */
+                    }
+                }
+            }
+            catch {
+                /* no log file yet */
+            }
+            // Use the larger of "single-session" (loadSessionStats fallback)
+            // and the all-sessions sum so an empty single-session number
+            // doesn't override the meaningful project-wide total.
+            const surfaced = Math.max(total, stats.savedTokens);
+            if (surfaced > 0) {
+                const human = surfaced >= 1_000_000
+                    ? `${(surfaced / 1_000_000).toFixed(1)}M`
+                    : surfaced >= 1000
+                        ? `${Math.round(surfaced / 1000)}k`
+                        : `${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 */
+        }
         const output = {
             hookSpecificOutput: {
                 hookEventName: "SessionStart",
                 additionalContext: message,
                 watchPaths,
+                ...(sessionTitle ? { sessionTitle } : {}),
             },
         };
         return JSON.stringify(output);

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>;