@synaplink/orqlaude 0.8.0 → 0.9.3

package/dist/tools/dispatch.js

@@ -2,9 +2,11 @@ import { z } from "zod";
 import { findPlan, findTask } from "../lib/state.js";
 import { jsonlPathFor, snapshotSession } from "../lib/jsonl_tail.js";
 import { detectHallucination, extractToolUses } from "../lib/hallucination.js";
-import { spawnAgnetViaCli, findGitRoot, cleanupPlanWorktrees } from "../lib/spawn_cli.js";
+import { spawnAgnetViaCli, findGitRoot, cleanupPlanWorktrees, readChildExitRecord } from "../lib/spawn_cli.js";
 import { isProcessAlive } from "../lib/process_lib.js";
 import { resolveStateDir } from "../lib/state_dir.js";
+import { probeTelegramStatus } from "../lib/telegram_status.js";
+import { VERSION } from "../lib/version.js";
 import { promises as fs } from "node:fs";
 /**
  * Dispatch-phase tools: next_task, register_spawn, status, collect.
@@ -124,6 +126,7 @@ export function registerDispatch(server, store, audit) {
             task.commandLine = spawn.commandLine;
             task.stderrPath = spawn.stderrPath;
             task.stdoutPath = spawn.stdoutPath;
+            task.exitJsonPath = spawn.exitJsonPath;
             task.status = "running";
             task.startedAt = Date.now();
             return {
@@ -145,13 +148,50 @@ export function registerDispatch(server, store, audit) {
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }, ({ plan_id }) => ({ planId: plan_id })));
     // ---- cleanup_worktrees (companion to spawn_via_cli, v0.5.3+) -------------
-    server.tool("cleanup_worktrees", "Remove all orqlaude-managed worktrees for a plan (typically called after `collect`). Only touches paths under <project>/.orqlaude-worktrees/<plan_short>-*. Force-removes via `git worktree remove --force` then falls back to rm -rf if git refuses.", {
+    server.tool("cleanup_worktrees", "Remove all orqlaude-managed worktrees for a plan (typically called after `collect`). Only touches paths under <project>/.orqlaude-worktrees/<plan_short>-*. Force-removes via `git worktree remove --force` then falls back to rm -rf if git refuses. v0.9.0: also releases the spawn locks on every task whose worktree was removed - so the orchestrator can re-spawn against the same plan_id + task_id without create_plan churn.", {
         plan_id: z.string(),
         project_root: z.string().optional(),
     }, audit.wrap("cleanup_worktrees", async ({ plan_id, project_root }) => {
         const root = project_root ?? findGitRoot(process.cwd());
         const removed = await cleanupPlanWorktrees(root, plan_id);
-        return { content: [{ type: "text", text: JSON.stringify({ plan_id, removed_count: removed.length, removed }, null, 2) }] };
+        // v0.9.0: walk the plan's tasks and release any spawn lock whose
+        // worktreePath was just removed. This makes cleanup_worktrees the
+        // canonical "reset this plan, let me re-spawn fresh" entry point.
+        const released = await store.update((state) => {
+            const plan = findPlan(state, plan_id);
+            const releasedIds = [];
+            for (const t of plan.tasks) {
+                if (t.worktreePath && removed.includes(t.worktreePath)) {
+                    t.spawnedSessionId = undefined;
+                    t.pid = undefined;
+                    t.exitJsonPath = undefined;
+                    // Reset to pending so next_task / spawn_via_cli treat it fresh.
+                    // Preserve worktreePath/branch for audit but they'll be
+                    // overwritten on the next spawn.
+                    if (t.status === "running" || t.status === "dispatched" || t.status === "died_at_launch") {
+                        t.status = "pending";
+                    }
+                    releasedIds.push(t.id);
+                }
+            }
+            return releasedIds;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        plan_id,
+                        removed_count: removed.length,
+                        removed,
+                        released_task_ids: released,
+                        next_step: released.length > 0
+                            ? `Released ${released.length} spawn lock(s). You can call spawn_via_cli on the same task_ids to re-fire.`
+                            : undefined,
+                    }, null, 2),
+                },
+            ],
+        };
     }, ({ plan_id }) => ({ planId: plan_id })));
     // ---- register_spawn (MANUAL FALLBACK; rarely needed) ---------------------
     server.tool("register_spawn", "MANUAL FALLBACK ONLY. Normally the spawned agent self-registers on its first `checkin` call (the prompt next_task generates instructs it to). Only call this if a child fails to self-register within ~30s — symptom: status() shows the task as `dispatched` long after spawn_task succeeded.", {
@@ -185,7 +225,13 @@ export function registerDispatch(server, store, audit) {
                     note: "Not yet spawned (waiting for chip click + self-registration).",
                 };
             }
-            const snap = await snapshotSession(cwd, t.spawnedSessionId);
+            const snap = await snapshotSession(cwd, t.spawnedSessionId, t.stdoutPath);
+            // v0.9.0: fast-path terminal-state read. If the child wrote an
+            // exit record via the spawn_via_cli on('exit') handler, surface
+            // it - the orchestrator doesn't have to re-poll until isProcessAlive
+            // ticks over. Falls through to the regular PID/snapshot path if
+            // the file is missing (server restart after spawn, etc).
+            const exitRecord = t.exitJsonPath ? await readChildExitRecord(t.exitJsonPath) : null;
             const toolUses = await extractToolUses(jsonlPathFor(cwd, t.spawnedSessionId));
             const hallu = await detectHallucination(toolUses, cwd);
             const taskWarnings = [];
@@ -195,10 +241,39 @@ export function registerDispatch(server, store, audit) {
             // stops polling a corpse.
             let derivedStatus = snap.terminated ? "done" : t.status;
             let stderrExcerpt = null;
+            // v0.9.0: terminal-state precedence:
+            //   1. exit-record file (most authoritative; written by the
+            //      parent's on('exit') handler).
+            //   2. snap.terminated (result row in the event stream).
+            //   3. PID liveness + empty stream = died_at_launch.
+            if (exitRecord) {
+                derivedStatus = exitRecord.success ? "done" : "failed";
+                if (!exitRecord.success && t.stderrPath) {
+                    try {
+                        const buf = await fs.readFile(t.stderrPath, "utf8");
+                        stderrExcerpt = buf.slice(0, 1000);
+                    }
+                    catch {
+                        /* file missing */
+                    }
+                }
+                t.status = derivedStatus;
+                if (!t.finishedAt)
+                    t.finishedAt = exitRecord.terminated_at;
+            }
+            // died_at_launch is now defined as "PID dead AND no event was
+            // ever parsed from either stream source." Earlier versions
+            // checked `!snap.exists` which broke once we started creating
+            // the stdout log file at spawn time (the file exists but is
+            // empty when the child exits before writing). Use
+            // lastActivityAt + tokens-used == 0 as the canonical signal.
+            const producedNothing = !snap.lastActivityAt &&
+                snap.totalEffectiveTokens === 0 &&
+                !snap.lastAssistantText &&
+                !snap.lastToolUse;
             if (t.pid &&
                 !isProcessAlive(t.pid) &&
-                !snap.exists &&
-                !snap.lastActivityAt &&
+                producedNothing &&
                 (t.status === "running" || t.status === "dispatched")) {
                 derivedStatus = "died_at_launch";
                 if (t.stderrPath) {
@@ -210,7 +285,7 @@ export function registerDispatch(server, store, audit) {
                         /* file missing or unreadable */
                     }
                 }
-                taskWarnings.push(`Child PID ${t.pid} is dead and no JSONL was written. ` +
+                taskWarnings.push(`Child PID ${t.pid} is dead and no events were parsed from either the Desktop JSONL or the spawn_via_cli stdout log. ` +
                     `Inspect stderr at ${t.stderrPath ?? "(unknown)"} or re-run the command: ${t.commandLine ?? "(unknown)"}`);
                 // Persist the new status so subsequent calls don't redo this.
                 t.status = "died_at_launch";
@@ -218,9 +293,14 @@ export function registerDispatch(server, store, audit) {
             // Per-task soft budget warning: if the task has a budgetHintTokens
             // hint and we've blown past 70% of it, surface a yellow flag so the
             // orchestrator can intervene before the plan-wide hard cap fires.
-            if (t.budgetHintTokens && snap.totalEffectiveTokens > 0.7 * t.budgetHintTokens) {
-                const pct = Math.round((snap.totalEffectiveTokens / t.budgetHintTokens) * 100);
-                taskWarnings.push(`task at ${pct}% of hint (${snap.totalEffectiveTokens.toLocaleString()} / ${t.budgetHintTokens.toLocaleString()} tokens). Consider request_stop if it's stalling.`);
+            // v0.9.2: compare against billed (not total) to match the new
+            // default plan-level budget mode.
+            const taskBudgetRelevant = (plan0.budgetMode ?? "billed") === "billed"
+                ? snap.billedTokens
+                : snap.totalEffectiveTokens;
+            if (t.budgetHintTokens && taskBudgetRelevant > 0.7 * t.budgetHintTokens) {
+                const pct = Math.round((taskBudgetRelevant / t.budgetHintTokens) * 100);
+                taskWarnings.push(`task at ${pct}% of hint (${taskBudgetRelevant.toLocaleString()} / ${t.budgetHintTokens.toLocaleString()} tokens, mode=${plan0.budgetMode ?? "billed"}). Consider request_stop if it's stalling.`);
             }
             return {
                 task_id: t.id,
@@ -229,7 +309,12 @@ export function registerDispatch(server, store, audit) {
                 session_id: t.spawnedSessionId,
                 pid: t.pid ?? null,
                 pid_alive: t.pid ? isProcessAlive(t.pid) : null,
+                // v0.9.2: `tokens_used` retained as the back-compat field
+                // (= totalEffectiveTokens). Prefer `billed_tokens` for
+                // Plan-cost decisions.
                 tokens_used: snap.totalEffectiveTokens,
+                billed_tokens: snap.billedTokens,
+                cached_tokens: snap.cachedTokens,
                 budget_hint_tokens: t.budgetHintTokens ?? null,
                 cost_usd: snap.totalCostUsd,
                 last_event_type: snap.lastEventType,
@@ -243,10 +328,15 @@ export function registerDispatch(server, store, audit) {
                 stop_requested: t.stopRequested ?? null,
                 stderr_excerpt: stderrExcerpt,
                 stderr_path: t.stderrPath ?? null,
+                stdout_path: t.stdoutPath ?? null,
+                stream_source: snap.source,
+                exit_record: exitRecord,
                 command_line: t.commandLine ?? null,
+                // Internal hand-off for enforceBudget below.
+                __billed: snap.billedTokens,
+                __cached: snap.cachedTokens,
             };
         }));
-        const totalTokens = snapshots.reduce((sum, s) => sum + (s.tokens_used ?? 0), 0);
         const totalCost = snapshots.reduce((sum, s) => sum + (s.cost_usd ?? 0), 0);
         // v0.5.2: orphan detection — dispatched > 60s ago without
         // self-registering. Often means the orchestrator used a non-orqlaude
@@ -266,28 +356,21 @@ export function registerDispatch(server, store, audit) {
             remedy: "If you can identify its session id via mcp__ccd_session_mgmt__list_sessions, call register_spawn manually. Otherwise the task is invisible to orqlaude until a follow-up checkin arrives.",
         }));
         // ---- budget enforcement: kill on overbudget --------------------------
-        const overbudget = totalTokens > plan0.budgetCapTokens;
-        let autoCancelled = false;
-        if (overbudget && plan0.status !== "cancelled_overbudget" && plan0.status !== "cancelled") {
-            await store.update((state) => {
-                const plan = findPlan(state, plan_id);
-                plan.status = "cancelled_overbudget";
-                for (const t of plan.tasks) {
-                    if (t.spawnedSessionId && !t.stopRequested) {
-                        t.stopRequested = { reason: "fleet overbudget", requestedAt: Date.now(), kind: "hard" };
-                        plan.messages.push({
-                            id: cryptoRandomId(),
-                            toSessionId: t.spawnedSessionId,
-                            text: `STOP: fleet exceeded token budget (used ${Math.round(totalTokens / 1000)}k of ${Math.round(plan.budgetCapTokens / 1000)}k cap). Commit what you have and exit.`,
-                            queuedAt: Date.now(),
-                            delivered: false,
-                            kind: "stop",
-                        });
-                    }
-                }
-            });
-            autoCancelled = true;
+        // v0.9.2: shared helper, billed-vs-total aware. The helper picks
+        // billed (input + output, default) or total (all four buckets)
+        // based on `plan.budgetMode`.
+        const budget = await enforceBudget(store, plan_id, snapshots.map((s) => ({
+            billed: s.__billed ?? 0,
+            cached: s.__cached ?? 0,
+        })));
+        // Strip the internal hand-off keys so they don't leak into the
+        // public response.
+        for (const s of snapshots) {
+            delete s.__billed;
+            delete s.__cached;
         }
+        const totalTokens = budget.total_all; // for the legacy field
+        const autoCancelled = budget.auto_cancelled;
         // ---- aggregated hallucination warning -------------------------------
         const concerningAgents = snapshots
             .filter((s) => s.hallucination && s.hallucination.score >= 0.3)
@@ -310,10 +393,22 @@ export function registerDispatch(server, store, audit) {
                     text: JSON.stringify({
                         plan_id,
                         plan_status: autoCancelled ? "cancelled_overbudget" : plan0.status,
-                        budget_cap_tokens: plan0.budgetCapTokens,
+                        budget_cap_tokens: budget.budget_cap_tokens,
+                        // v0.9.2: legacy field; sum of all four token buckets.
+                        // For Plan-cost decisions read `tokens.billed` instead.
                         total_tokens_used: totalTokens,
-                        budget_remaining_tokens: Math.max(0, plan0.budgetCapTokens - totalTokens),
+                        budget_remaining_tokens: budget.budget_remaining_tokens,
                         total_cost_usd: totalCost,
+                        // v0.9.2: explicit token breakdown so orchestrators can
+                        // distinguish "cost-relevant" from "cache churn".
+                        tokens: {
+                            billed: budget.total_billed,
+                            cached: budget.total_cached,
+                            total: budget.total_all,
+                            budget_mode: budget.budget_mode,
+                            budget_relevant: budget.total_for_budget,
+                            budget_pct: budget.budget_pct,
+                        },
                         hallucination_alerts: concerningAgents,
                         orphan_alerts: orphans,
                         died_at_launch_alerts: deadAgents,
@@ -332,6 +427,156 @@ export function registerDispatch(server, store, audit) {
             ],
         };
     }, ({ plan_id }) => ({ planId: plan_id })));
+    // ---- wait_for_status_change (long-poll) ----------------------------------
+    // v0.9.0: replaces the orchestrator's polling-loop pattern. Blocks for up
+    // to `timeout_sec` (default 60s) until ANY task in the plan transitions
+    // state, finishes, opens a PR, dies at launch, or chews through a
+    // material slice of its token budget. Cheap internal poll (every 2s
+    // file-stat + tiny snapshot read), but holds the connection open so the
+    // primary Claude can sleep without waking up to call status() every 90s.
+    server.tool("wait_for_status_change", "Long-poll: blocks up to `timeout_sec` (default 60, max 600) and returns as soon as the fleet state changes (task transition, new PR url, exit-record, +1 KB token delta) - OR returns the unchanged state when the timeout elapses. Use this INSTEAD of ScheduleWakeup + status() polling: pass the `fingerprint` from the prior response as `since_fingerprint` and the call returns the moment something useful happens. v0.9.0+.", {
+        plan_id: z.string(),
+        since_fingerprint: z.string().optional().describe("The `fingerprint` field from the prior wait_for_status_change (or status) response. Omit on first call - the server returns immediately with the current snapshot + the fresh fingerprint to thread through subsequent calls."),
+        timeout_sec: z.number().int().positive().max(600).default(60).describe("Max seconds the call blocks before returning the unchanged state. Default 60. Cap 600 (10 min)."),
+    }, audit.wrap("wait_for_status_change", async ({ plan_id, since_fingerprint, timeout_sec }) => {
+        const cwd = process.cwd();
+        const POLL_INTERVAL_MS = 2_000;
+        const deadline = Date.now() + timeout_sec * 1000;
+        const buildSnapshot = async () => {
+            const plan = await store.read((state) => findPlan(state, plan_id));
+            const agents = await Promise.all(plan.tasks.map(async (t) => {
+                if (!t.spawnedSessionId) {
+                    return {
+                        task_id: t.id,
+                        title: t.title,
+                        status: t.status,
+                        tokens_used: 0,
+                        billed_tokens: 0,
+                        cached_tokens: 0,
+                        pr_url: t.prUrl ?? null,
+                        pid_alive: null,
+                        exit_record: null,
+                        terminated: false,
+                        stop_kind: t.stopRequested?.kind ?? null,
+                    };
+                }
+                const snap = await snapshotSession(cwd, t.spawnedSessionId, t.stdoutPath);
+                const exitRecord = t.exitJsonPath ? await readChildExitRecord(t.exitJsonPath) : null;
+                return {
+                    task_id: t.id,
+                    title: t.title,
+                    status: exitRecord ? (exitRecord.success ? "done" : "failed") : t.status,
+                    tokens_used: snap.totalEffectiveTokens,
+                    billed_tokens: snap.billedTokens,
+                    cached_tokens: snap.cachedTokens,
+                    pr_url: t.prUrl ?? null,
+                    pid_alive: t.pid ? isProcessAlive(t.pid) : null,
+                    exit_record: exitRecord,
+                    terminated: snap.terminated || !!exitRecord,
+                    stop_kind: t.stopRequested?.kind ?? null,
+                };
+            }));
+            // v0.9.2: enforce budget on every poll, not just from status().
+            // The plan-level kill needs to fire whether the orchestrator is
+            // calling status() or wait_for_status_change.
+            const budget = await enforceBudget(store, plan_id, agents.map((a) => ({ billed: a.billed_tokens, cached: a.cached_tokens })));
+            return {
+                plan_id,
+                plan_status: budget.auto_cancelled ? "cancelled_overbudget" : plan.status,
+                agents,
+                budget,
+            };
+        };
+        const computeFingerprint = (snap) => {
+            // v0.9.1: hash-safe encoding via JSON.stringify. The previous
+            // pipe-joined / colon-separated form was fragile if a task_id or
+            // pr_url ever contained a `|` or `:` (today both are sanitized
+            // UUIDs / GitHub URLs, but pinning the structure costs nothing).
+            // Also includes `stop_kind` so kill_task / request_stop transitions
+            // wake the long-poll without waiting for the child to actually
+            // terminate - useful when a soft-stop is in flight.
+            // v0.9.2: KB bucket runs off `billed_tokens` (input + output) so
+            // cache-read churn doesn't trip the fingerprint every 2s. The
+            // long-poll now fires only when something cost-relevant moves.
+            const parts = [snap.plan_status];
+            for (const a of snap.agents) {
+                const kb = Math.floor(a.billed_tokens / 1024);
+                parts.push([
+                    a.task_id,
+                    a.status,
+                    a.pr_url ?? null,
+                    kb,
+                    a.exit_record
+                        ? { code: a.exit_record.exit_code, sig: a.exit_record.signal }
+                        : null,
+                    a.terminated,
+                    a.pid_alive,
+                    a.stop_kind,
+                ]);
+            }
+            return JSON.stringify(parts);
+        };
+        // First read - if no fingerprint, return immediately with the
+        // current state (still useful as a fresh dispatch).
+        let snapshot = await buildSnapshot();
+        let fingerprint = computeFingerprint(snapshot);
+        if (!since_fingerprint || fingerprint !== since_fingerprint) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ...snapshot,
+                            fingerprint,
+                            changed: !!since_fingerprint,
+                            elapsed_sec: 0,
+                            timed_out: false,
+                            next_step: "Call wait_for_status_change again with this `fingerprint` as `since_fingerprint` to block until the next transition.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        // Poll loop until fingerprint changes or deadline hits.
+        const startedAt = Date.now();
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+            snapshot = await buildSnapshot();
+            fingerprint = computeFingerprint(snapshot);
+            if (fingerprint !== since_fingerprint) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...snapshot,
+                                fingerprint,
+                                changed: true,
+                                elapsed_sec: Math.round((Date.now() - startedAt) / 1000),
+                                timed_out: false,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        // Timeout - return unchanged state.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...snapshot,
+                        fingerprint,
+                        changed: false,
+                        elapsed_sec: Math.round((Date.now() - startedAt) / 1000),
+                        timed_out: true,
+                        next_step: "Nothing changed during the wait window. Call wait_for_status_change again with the same `since_fingerprint` to keep waiting, OR call status() for a deeper read.",
+                    }, null, 2),
+                },
+            ],
+        };
+    }, ({ plan_id }) => ({ planId: plan_id })));
     // ---- collect --------------------------------------------------------------
     server.tool("collect", "Final result aggregation: per-task summary, PR URLs, total tokens+cost, exit reasons. Call once all agents have terminated. The result includes a `ready_for_review` flag suggesting you call `review_prs` (when available) to spawn reviewers.", { plan_id: z.string() }, audit.wrap("collect", async ({ plan_id }) => {
         const plan = await store.update((state) => {
@@ -343,7 +588,9 @@ export function registerDispatch(server, store, audit) {
         });
         const cwd = process.cwd();
         const results = await Promise.all(plan.tasks.map(async (t) => {
-            const snap = t.spawnedSessionId ? await snapshotSession(cwd, t.spawnedSessionId) : null;
+            const snap = t.spawnedSessionId
+                ? await snapshotSession(cwd, t.spawnedSessionId, t.stdoutPath)
+                : null;
             return {
                 task_id: t.id,
                 title: t.title,
@@ -380,6 +627,121 @@ export function registerDispatch(server, store, audit) {
             ],
         };
     }, ({ plan_id }) => ({ planId: plan_id })));
+    // ---- fleet_summary (v0.9.0 dashboard, one-tool aggregation) --------------
+    // Single-call replacement for ping + status + list_plans + telegram probe.
+    // Use this at the START of a fresh session ("what's in flight?") and any
+    // time you want a wide view of every active plan without making 4 round
+    // trips. Returns:
+    //   - server health (version, cwd, state dir, telegram status)
+    //   - per-plan rollup (counts of pending/running/done/failed, PR list)
+    //   - cross-plan totals (active Agnets, total tokens spent today)
+    server.tool("fleet_summary", "Single-call dashboard for the entire orqlaude state. Returns server health + per-plan rollup + cross-plan totals. Use at session start to discover in-flight fleets; use mid-fleet for a wide view without ping + status + list_plans round-trips. v0.9.0+.", {}, audit.wrap("fleet_summary", async () => {
+        const cwd = process.cwd();
+        const stateDir = resolveStateDir().path;
+        const tg = await probeTelegramStatus(stateDir);
+        const { plans, orphanNotificationCount, orphanResponseCount } = await store.read((s) => ({
+            plans: Object.values(s.plans),
+            orphanNotificationCount: (s.orphanNotifications ?? []).length,
+            orphanResponseCount: (s.orphanResponseRequests ?? []).length,
+        }));
+        const planRollups = await Promise.all(plans.map(async (p) => {
+            // Fast per-task counts WITHOUT the full snapshotSession read.
+            const counts = { pending: 0, dispatched: 0, running: 0, done: 0, failed: 0, cancelled: 0, died_at_launch: 0 };
+            const prs = [];
+            // v0.9.1: parallelize the per-task snapshot reads. The first
+            // post-restart call is O(plans × tasks) IO; the inner Promise.all
+            // makes the per-plan inner loop concurrent. Cache makes
+            // subsequent calls cheap regardless.
+            for (const t of p.tasks) {
+                const status = t.status ?? "pending";
+                counts[status] = (counts[status] ?? 0) + 1;
+                if (t.prUrl)
+                    prs.push(t.prUrl);
+            }
+            const taskTokens = await Promise.all(p.tasks.map(async (t) => {
+                if (!t.spawnedSessionId)
+                    return { billed: 0, cached: 0, total: 0 };
+                const snap = await snapshotSession(cwd, t.spawnedSessionId, t.stdoutPath);
+                return {
+                    billed: snap.billedTokens,
+                    cached: snap.cachedTokens,
+                    total: snap.totalEffectiveTokens,
+                };
+            }));
+            const tokensBilled = taskTokens.reduce((s, v) => s + v.billed, 0);
+            const tokensCached = taskTokens.reduce((s, v) => s + v.cached, 0);
+            const tokensTotal = taskTokens.reduce((s, v) => s + v.total, 0);
+            // v0.9.2: budget_pct reflects the plan's chosen mode (billed
+            // default). Plan users see the cost-relevant pct, not the
+            // cache-inflated total.
+            const mode = p.budgetMode ?? "billed";
+            const tokensForBudget = mode === "billed" ? tokensBilled : tokensTotal;
+            const allDone = p.tasks.length > 0 && p.tasks.every((t) => t.status === "done" || t.status === "failed" || t.status === "cancelled");
+            return {
+                plan_id: p.id,
+                status: p.status,
+                created_at: p.createdAt,
+                root_task: p.rootTask.slice(0, 120),
+                task_count: p.tasks.length,
+                task_status_counts: counts,
+                tokens_used: tokensTotal, // legacy field (sum of all four buckets)
+                tokens: {
+                    billed: tokensBilled,
+                    cached: tokensCached,
+                    total: tokensTotal,
+                    budget_mode: mode,
+                    budget_relevant: tokensForBudget,
+                },
+                budget_cap_tokens: p.budgetCapTokens,
+                budget_pct: p.budgetCapTokens ? Math.round((tokensForBudget / p.budgetCapTokens) * 100) : 0,
+                prs,
+                all_terminal: allDone,
+                suggested_next: p.status === "draft"
+                    ? "request_approval + confirm"
+                    : counts.pending > 0
+                        ? "spawn_via_cli (per-task) or next_task"
+                        : counts.running + counts.dispatched > 0
+                            ? "wait_for_status_change"
+                            : allDone
+                                ? "collect + cleanup_worktrees"
+                                : "status",
+            };
+        }));
+        const activeAgnets = planRollups.reduce((sum, r) => sum + (r.task_status_counts.running ?? 0) + (r.task_status_counts.dispatched ?? 0), 0);
+        const grandTokens = planRollups.reduce((sum, r) => sum + r.tokens_used, 0);
+        const grandBilled = planRollups.reduce((sum, r) => sum + r.tokens.billed, 0);
+        const grandCached = planRollups.reduce((sum, r) => sum + r.tokens.cached, 0);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        server: { version: VERSION, cwd, state_dir: stateDir },
+                        telegram: tg,
+                        plans: planRollups.sort((a, b) => b.created_at - a.created_at),
+                        totals: {
+                            plan_count: plans.length,
+                            active_agnets: activeAgnets,
+                            grand_total_tokens: grandTokens, // legacy: sum of all buckets
+                            grand_billed_tokens: grandBilled, // v0.9.2: input + output only
+                            grand_cached_tokens: grandCached, // v0.9.2: cache reads + creations
+                        },
+                        orphan_queue: {
+                            notifications: orphanNotificationCount,
+                            response_requests: orphanResponseCount,
+                        },
+                        next_step: activeAgnets > 0
+                            ? `${activeAgnets} Agnet(s) actively running. Call wait_for_status_change(<plan_id>) to block until any transitions.`
+                            : planRollups.some((r) => r.status === "draft")
+                                ? "One or more plans are draft - confirm or cancel."
+                                : planRollups.some((r) => r.all_terminal && r.status !== "collected")
+                                    ? "All Agnets on at least one plan are terminal. Call collect + cleanup_worktrees."
+                                    : "Idle.",
+                    }, null, 2),
+                },
+            ],
+        };
+    }, () => ({})));
 }
 function buildSpawnPrompt(planId, taskId, userPrompt, branchHint) {
     const branchSection = branchHint ? `\n\nSuggested branch: \`${branchHint}\`.` : "";
@@ -431,6 +793,54 @@ task_id: ${taskId}
 ═══════════════════════════════════════════════════════════════
 `;
 }
+async function enforceBudget(store, plan_id, agents) {
+    const plan0 = await store.read((state) => findPlan(state, plan_id));
+    const totalBilled = agents.reduce((s, a) => s + a.billed, 0);
+    const totalCached = agents.reduce((s, a) => s + a.cached, 0);
+    const totalAll = totalBilled + totalCached;
+    const budgetMode = plan0.budgetMode ?? "billed";
+    const totalForBudget = budgetMode === "billed" ? totalBilled : totalAll;
+    const cap = plan0.budgetCapTokens;
+    const overbudget = totalForBudget > cap;
+    const alreadyCancelled = plan0.status === "cancelled_overbudget" || plan0.status === "cancelled";
+    let autoCancelled = false;
+    if (overbudget && !alreadyCancelled) {
+        await store.update((state) => {
+            const plan = findPlan(state, plan_id);
+            // Re-check inside the lock - another concurrent call may have raced us.
+            if (plan.status === "cancelled_overbudget" || plan.status === "cancelled")
+                return;
+            plan.status = "cancelled_overbudget";
+            for (const t of plan.tasks) {
+                if (t.spawnedSessionId && !t.stopRequested) {
+                    t.stopRequested = { reason: "fleet overbudget", requestedAt: Date.now(), kind: "hard" };
+                    plan.messages.push({
+                        id: cryptoRandomId(),
+                        toSessionId: t.spawnedSessionId,
+                        text: `STOP: fleet exceeded token budget (used ${Math.round(totalForBudget / 1000)}k of ` +
+                            `${Math.round(cap / 1000)}k cap, mode=${budgetMode}). Commit what you have and exit.`,
+                        queuedAt: Date.now(),
+                        delivered: false,
+                        kind: "stop",
+                    });
+                }
+            }
+        });
+        autoCancelled = true;
+    }
+    return {
+        total_billed: totalBilled,
+        total_cached: totalCached,
+        total_all: totalAll,
+        total_for_budget: totalForBudget,
+        budget_mode: budgetMode,
+        budget_cap_tokens: cap,
+        budget_remaining_tokens: Math.max(0, cap - totalForBudget),
+        budget_pct: cap > 0 ? Math.round((totalForBudget / cap) * 100) : 0,
+        overbudget,
+        auto_cancelled: autoCancelled,
+    };
+}
 function cryptoRandomId() {
     // small helper to avoid importing crypto in this top-of-file scope twice
     return Math.random().toString(36).slice(2) + Date.now().toString(36);