@cruxy/cli 1.7.1 → 1.8.1

package/dist/session/replay.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { modeFromFlags } from "../agent/mode.js";
 import { redactMessages } from "./redact.js";
-import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
+import { KNOWN_EVENT_KINDS, SessionEventSchema, SessionMetaSchema, } from "./types.js";
 /**
  * Replay: fold an append-only event log back into the state a session needs to
  * resume (P2).
@@ -11,8 +11,7 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
  * the array the model last saw, including the synthetic compaction summaries.
  * Nothing is re-derived or re-summarised on the way back in.
  *
- * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED and counted,
- * never fatal:
+ * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED, never fatal:
  *  - a torn final line from a crash mid-append would otherwise cost the whole
  *    conversation (this is the failure temp-then-rename buys off at write time;
  *    an append-only log buys it off here instead);
@@ -20,8 +19,25 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
  *    heard of is skipped rather than rejected, which together with the
  *    `.passthrough()` schemas is what keeps two CLI versions able to share one
  *    home directory.
- * `SessionState.skipped` carries the count so a caller can say so out loud
- * rather than presenting a partial history as complete.
+ *
+ * THE TWO ARE COUNTED APART (#172 item 2), because they are not the same fact
+ * and the caller says something different about each. A damaged line means
+ * content was LOST — "the restored history may be incomplete" is warranted. An
+ * unknown kind means content is not visible HERE while the file is perfectly
+ * intact.
+ *
+ * Conflating them was survivable only while unknown kinds were rare. The
+ * `resumed` event is written on EVERY reopen, so an older build sharing a home
+ * directory would have announced possible history loss on every single resume —
+ * a forward-compatibility mechanism producing a corruption warning as routine
+ * output. `SessionState.skipped` now counts only damage;
+ * `SessionState.unknownEvents` counts the rest.
+ *
+ * This fixes readers from this build forward. An ALREADY-SHIPPED cruxy has the
+ * old reader and will still say "unreadable lines" when it meets a `resumed`
+ * event; nothing here can reach it. That is the cost of the split landing with
+ * the event rather than before it, and it is bounded — it misreports, it does
+ * not lose anything.
  */
 /**
  * The one cast in this module, isolated and explained.
@@ -36,20 +52,37 @@ import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
 function asMessages(validated) {
     return validated;
 }
-/** Parse one line, or `null` when it is unusable (torn, or an unknown kind). */
+/**
+ * Classify one line.
+ *
+ * The distinction that matters is inside the failure case. A line that is valid
+ * JSON, is an object, and names a `kind` this build has never heard of is a
+ * NEWER cruxy's event — the file is intact and the forward-compatibility rule is
+ * working as designed. Anything else that fails is damage.
+ *
+ * A known kind with a payload that does not validate counts as DAMAGE, not as
+ * unknown: this build understands that kind, so failing to parse it means the
+ * line is wrong rather than merely new.
+ */
 function parseLine(line) {
     const trimmed = line.trim();
     if (trimmed === "")
-        return null;
+        return { outcome: "blank" };
     let raw;
     try {
         raw = JSON.parse(trimmed);
     }
     catch {
-        return null;
+        return { outcome: "damaged" }; // torn mid-write
     }
     const parsed = SessionEventSchema.safeParse(raw);
-    return parsed.success ? parsed.data : null;
+    if (parsed.success)
+        return { outcome: "event", event: parsed.data };
+    const kind = raw?.kind;
+    if (typeof kind === "string" && !KNOWN_EVENT_KINDS.has(kind)) {
+        return { outcome: "unknown" };
+    }
+    return { outcome: "damaged" };
 }
 /**
  * Fold events into {@link SessionState}. Exported separately from file reading
@@ -60,7 +93,7 @@ function parseLine(line) {
  * which directory the history refers to, and resuming a conversation whose
  * origin is unknown is precisely what ruling 4 forbids.
  */
-export function foldEvents(events, skipped = 0) {
+export function foldEvents(events, counts = {}) {
     const metaEvent = events.find((e) => e.kind === "meta");
     if (!metaEvent) {
         throw new Error("session log has no readable meta line");
@@ -76,6 +109,7 @@ export function foldEvents(events, skipped = 0) {
     let planMode = false;
     let mode = null;
     let redactions = 0;
+    const resumes = [];
     const usage = { input_tokens: 0, output_tokens: 0 };
     for (const event of events) {
         switch (event.kind) {
@@ -116,6 +150,12 @@ export function foldEvents(events, skipped = 0) {
                 messages = redactMessages(messages).messages;
                 redactions++;
                 break;
+            case "resumed":
+                // Recorded, never folded into anything the model sees. A reopen is a
+                // fact ABOUT the conversation, not a turn in it — the whole reason it
+                // could be added without touching `meta` or the message array.
+                resumes.push({ at: event.at, cwd: event.cwd });
+                break;
             case "meta":
                 break;
         }
@@ -128,7 +168,9 @@ export function foldEvents(events, skipped = 0) {
         // Auto-approve reads false there, which is right: it was not a thing that
         // could be on, so nothing is being inferred.
         mode: mode ?? modeFromFlags(planMode, false),
-        skipped,
+        skipped: counts.skipped ?? 0,
+        unknownEvents: counts.unknownEvents ?? 0,
+        resumes,
         redactions,
     };
 }
@@ -137,21 +179,29 @@ export function readEvents(file) {
     const raw = readFileSync(file, "utf8");
     const events = [];
     let skipped = 0;
+    let unknownEvents = 0;
     for (const line of raw.split("\n")) {
-        if (line.trim() === "")
-            continue;
-        const event = parseLine(line);
-        if (event)
-            events.push(event);
-        else
-            skipped++;
+        const parsed = parseLine(line);
+        switch (parsed.outcome) {
+            case "event":
+                events.push(parsed.event);
+                break;
+            case "unknown":
+                unknownEvents++;
+                break;
+            case "damaged":
+                skipped++;
+                break;
+            case "blank":
+                break;
+        }
     }
-    return { events, skipped };
+    return { events, skipped, unknownEvents };
 }
 /** Read a session file and fold it into resumable state. */
 export function replaySession(file) {
-    const { events, skipped } = readEvents(file);
-    return foldEvents(events, skipped);
+    const { events, skipped, unknownEvents } = readEvents(file);
+    return foldEvents(events, { skipped, unknownEvents });
 }
 /**
  * Read ONLY the meta line — enough to list a session without folding its whole

package/dist/session/resume.js

@@ -1,6 +1,6 @@
 import { selectList } from "../components/index.js";
 import { usageError } from "../errors/index.js";
-import { findSession, isAmbiguous, listSessions } from "./list.js";
+import { listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
 import { replaySession } from "./replay.js";
 /** How many sessions the bare-`--resume` picker offers. */
 export const PICKER_LIMIT = 10;
@@ -47,6 +47,28 @@ export function cwdMismatchWarning(state, cwd) {
     return (`this session was recorded in ${state.meta.cwd}, but you are in ${cwd} — ` +
         `its history refers to files and paths from the original directory`);
 }
+/**
+ * Directories this session has run in BEFORE, other than the one we are
+ * resuming into now (#172 item 2). Returns a warning to print, or null.
+ *
+ * Distinct from {@link cwdMismatchWarning}, which compares where the
+ * conversation BEGAN against where it is being resumed. This compares where it
+ * has since RUN. The two disagree in exactly the case that motivated the
+ * `resumed` event: begin in `/a`, resume in `/b`, then resume in `/a` again —
+ * `meta.cwd` matches, so the mismatch check is silent, and yet the history now
+ * contains a whole stretch of work done against a different tree.
+ *
+ * Nothing could say this before, because nothing recorded it. Sessions written
+ * before the event simply have no `resumes` and are silent here — absence is
+ * "not recorded", never "did not happen".
+ */
+export function priorDirectoriesWarning(state, cwd) {
+    const others = [...new Set(state.resumes.map((r) => r.cwd))].filter((dir) => dir !== cwd && dir !== state.meta.cwd);
+    if (others.length === 0)
+        return null;
+    return (`this session has also run in ${others.join(", ")} — ` +
+        `part of its history refers to files and paths from ${others.length === 1 ? "that directory" : "those directories"}`);
+}
 /**
  * Load one session and collect its warnings. Throws a usage error when the
  * file cannot be replayed at all (no meta line) — an unreadable session is
@@ -67,10 +89,23 @@ export function loadResume(session, cwd) {
     const mismatch = cwdMismatchWarning(state, cwd);
     if (mismatch)
         warnings.push(mismatch);
+    const elsewhere = priorDirectoriesWarning(state, cwd);
+    if (elsewhere)
+        warnings.push(elsewhere);
     if (state.skipped > 0) {
         warnings.push(`${state.skipped} unreadable line${state.skipped === 1 ? "" : "s"} in the session log were skipped — ` +
             `the restored history may be incomplete`);
     }
+    if (state.unknownEvents > 0) {
+        // Deliberately NOT the sentence above. The file is intact; this build is
+        // simply older than whatever wrote those lines, and saying "unreadable"
+        // about a healthy log would send the user looking for damage that is not
+        // there. What IS true is that some of what the session recorded cannot be
+        // shown here.
+        warnings.push(`${state.unknownEvents} event${state.unknownEvents === 1 ? "" : "s"} in this session ` +
+            `${state.unknownEvents === 1 ? "was" : "were"} written by a newer cruxy and ${state.unknownEvents === 1 ? "is" : "are"} not shown — ` +
+            `the conversation itself is complete; upgrade to see the rest`);
+    }
     if (state.redactions > 0) {
         // Said on resume because the alternative is a user finding `[redacted …]`
         // in a transcript and not knowing whether cruxy did it or the model wrote
@@ -82,27 +117,54 @@ export function loadResume(session, cwd) {
     return { session, state, warnings };
 }
 /**
- * Resolve `--resume <id>`. Fails loud on an unknown or ambiguous id rather than
- * silently starting a new session — the user named something specific.
+ * VALIDATE `--resume <id>` — which session does this name? — without loading it.
+ *
+ * Split from the loading half for two reasons, one of them ordering:
+ *
+ *  1. `executeRun` has to answer "is this a real id?" BEFORE the non-TTY guard,
+ *     so `cruxy --resume no-such-id < /dev/null` complains about the id rather
+ *     than about the terminal. It must not have to pay a full `replaySession`
+ *     to find that out — a VALID id in that same position is still going to be
+ *     told it needs a terminal, and reading a whole conversation only to throw
+ *     it away is exactly the cost this split avoids.
+ *  2. Both questions — ambiguous? which one? — are now asked of ONE index. This
+ *     used to build the full listing up to three times (`isAmbiguous`, then
+ *     `findSession`, then a third time to name the collisions), each one a
+ *     complete read and parse of every session file in the project.
+ *
+ * Fails loud on an unknown or ambiguous id rather than silently starting a new
+ * session — the user named something specific.
+ *
+ * The one file that matched IS summarized, so the caller still gets the title
+ * and turn count the resume line prints. That is one read, not N.
  */
-export function resumeById(cwd, id) {
-    if (isAmbiguous(cwd, id)) {
-        const matches = listSessions(cwd)
-            .filter((s) => s.sessionId.startsWith(id))
-            .map((s) => shortId(s.sessionId));
+export function resolveSessionId(cwd, id) {
+    const matches = matchSessionRefs(listSessionRefs(cwd), id);
+    if (matches.length > 1) {
+        const names = matches.map((m) => shortId(m.sessionId)).join(", ");
         throw usageError(`\`${id}\` matches more than one session`, [
-            `did you mean one of: ${matches.join(", ")}?`,
+            `did you mean one of: ${names}?`,
             "run `cruxy --resume` to pick from a list",
         ]);
     }
-    const found = findSession(cwd, id);
-    if (!found) {
+    const summary = matches.length === 1 ? summarizeSession(matches[0].file) : null;
+    if (!summary) {
         throw usageError(`no session \`${id}\` in this project`, [
             "run `cruxy --resume` to pick from recent sessions",
             "sessions are per-directory; check you are in the right one",
         ]);
     }
-    return loadResume(found, cwd);
+    return summary;
+}
+/**
+ * Resolve `--resume <id>` all the way to restorable state: validate, then load.
+ *
+ * `executeRun` calls the two halves separately, so validation can precede the
+ * non-TTY guard; this composition is what everything else (and the tests) use
+ * where there is no ordering constraint to respect.
+ */
+export function resumeById(cwd, id) {
+    return loadResume(resolveSessionId(cwd, id), cwd);
 }
 /**
  * Bare `--resume`: pick from the most recent sessions, or start a new one.

package/dist/session/types.js

@@ -248,6 +248,41 @@ export const RedactEventSchema = z
     count: z.number().int().nonnegative().default(0),
 })
     .passthrough();
+/**
+ * A session was REOPENED (#172 item 2) — `--resume` found this log and
+ * continued it.
+ *
+ * `meta` is written once and never again, on purpose: it records where and when
+ * the conversation BEGAN, and a second copy written from wherever it was
+ * resumed would make "the session's directory" ambiguous. That ruling stands.
+ * Its consequence was that a resume left no trace at all — a session started in
+ * one directory and continued in another looked, from the file, as though it
+ * had only ever run in the first.
+ *
+ * This event closes that without touching `meta`'s authority. `meta.cwd` is
+ * still where the conversation began; `resumed.cwd` is somewhere it has since
+ * run. A reader can tell the two apart because they are different kinds.
+ *
+ * SCOPE, stated because the obvious next step is deliberately NOT taken here:
+ * this makes a cross-directory resume AUDITABLE, not DISCOVERABLE. The file
+ * still lives under `projectKey(meta.cwd)`, and `listSessions` for the other
+ * directory does one `readdir` of its own project dir and will never see it.
+ * Surfacing it there needs a pointer written into the second directory, or a
+ * scan across every project — a separate decision with a real cost, not a
+ * side effect of recording the fact.
+ */
+export const ResumedEventSchema = z
+    .object({
+    kind: z.literal("resumed"),
+    at: z.string(),
+    /** The primary root the session was resumed INTO. */
+    cwd: z.string(),
+    /** Roots declared on the resuming run — multi-root can differ per run. */
+    roots: z.array(RootRefSchema).default([]),
+    /** The build that reopened it; a session can outlive several. */
+    cliVersion: z.string().optional(),
+})
+    .passthrough();
 /** Every event, discriminated on `kind`. */
 export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionMetaSchema,
@@ -258,4 +293,14 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionModeEventSchema,
     UsageEventSchema,
     RedactEventSchema,
+    ResumedEventSchema,
 ]);
+/**
+ * Every `kind` this build understands, derived from the union itself so the two
+ * cannot drift.
+ *
+ * This exists so the reader can tell "a line I do not understand" from "a line
+ * that is damaged" — see `replay.ts`. Those are different facts about a file and
+ * they used to be counted as one.
+ */
+export const KNOWN_EVENT_KINDS = new Set(SessionEventSchema.options.map((option) => option.shape.kind.value));

package/dist/subagent/orchestrator.js

@@ -1,6 +1,8 @@
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { runAgent } from "../agent/loop.js";
-import { CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { classifyProviderError, CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { UsageCollector } from "../usage/index.js";
 import { UNRESOLVED_TIER, } from "../budget/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { Workspace } from "../workspace/index.js";
@@ -52,10 +54,12 @@ export class SubagentOrchestrator {
      * withheld at the cap, so this throw is the fail-loud backstop.
      *
      * Never rejects on a *child* failure — provider or tool crashes come back as
-     * `status: "failed"` for the parent to reason over. The two exceptions that
-     * do propagate: the depth cap (above) and `CRUXY_E_APPROVAL_REQUIRED`
+     * `status: "failed"` for the parent to reason over. The three exceptions that
+     * do propagate: the depth cap (above), `CRUXY_E_APPROVAL_REQUIRED`
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
-     * not a way to swallow it).
+     * not a way to swallow it), and `CRUXY_E_BUDGET_EXHAUSTED` (the weighted pool
+     * refused this child — see the catch block for why that one is not a partial
+     * result).
      */
     async spawn(spec, parentDepth, opts = {}) {
         const { deps } = this;
@@ -110,6 +114,57 @@ export class SubagentOrchestrator {
         // parent's messages are never in scope here, and this array dies with the
         // spawn — only the structured result below leaves this function.
         const messages = [{ role: "user", content: spec.task }];
+        // Per-request usage for THIS child, collected exactly as the parent's turn
+        // collects its own (`agent/session.ts`) — the loop reports one entry per
+        // completed request, with the tier that served it. Two things need it and
+        // neither can be got from `AgentResult.usage`: the weighted-pool arithmetic
+        // is per-tier, and a run that THREW has no `AgentResult` at all while still
+        // having spent whatever it spent before it died.
+        const usage = new UsageCollector();
+        const startedAt = new Date().toISOString();
+        try {
+            return await this.runChild({
+                spec,
+                opts,
+                messages,
+                registry,
+                budget,
+                ctx,
+                artifacts,
+                label,
+                noun,
+                tag,
+                usage,
+            });
+        }
+        finally {
+            // CHILD SPEND IS SESSION SPEND (cli#212). `budget.record` had exactly one
+            // call site — the parent's own turn — so a fan-out drew on the pool and
+            // left the numerator where it found it. The next admission check then
+            // divided by an allowance that had already been spent, which made the
+            // bound weakest at the moment it mattered most: the second fan-out of a
+            // session that had just dispatched three children.
+            //
+            // In the `finally` because the tokens are spent on every path out of here,
+            // including the two that throw. A child that died mid-run, or that a
+            // sibling's pool denial cancelled, still drew whatever it drew before it
+            // stopped, and the record is what it reported.
+            //
+            // NOT ALSO WRITTEN TO THE USAGE STORE. Child requests have never appeared
+            // in `/usage` and this does not change that — `/budget` now counts them
+            // and `/usage` still does not, so the two figures can differ by a
+            // fan-out's worth. That gap is real and pre-dates this; closing it means
+            // persisting child runs, which is a change to what is on disk and belongs
+            // in its own right rather than smuggled in behind an admission fix.
+            this.deps.budget?.record(usage.toRecord(randomUUID(), undefined, startedAt));
+        }
+    }
+    /** One child's run, from dispatch to structured result. Split out only so the
+     * usage fold above can be a `finally` over every path this can leave by. */
+    async runChild(args) {
+        const { deps } = this;
+        const { spec, opts, messages, registry, budget, ctx, artifacts } = args;
+        const { label, noun, tag, usage } = args;
         let run;
         try {
             run = await runAgent({
@@ -128,6 +183,7 @@ export class SubagentOrchestrator {
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
                 signal: opts.signal,
+                onRequestUsage: (req) => usage.record(req),
             });
         }
         catch (err) {
@@ -136,6 +192,26 @@ export class SubagentOrchestrator {
                 deps.renderer?.setPhase(null);
                 throw err;
             }
+            // THE WEIGHTED POOL REFUSED THIS CHILD (429 `budget_exhausted`), and that
+            // is not a per-child outcome (cli#212). The pool is one denominator shared
+            // by every sibling, every other surface on the account, and the parent's
+            // own next request: nothing that is about to run can succeed, so folding
+            // this into a `failed` result would let each sibling walk into its own
+            // refusal — N denials for one fact, each after its tokens were spent.
+            //
+            // Rethrown as the TYPED error rather than the raw one so `code`,
+            // `window`, `resetAt` and `miraAvailable` survive to the boundary. The
+            // last of those is the only step that unblocks the user now rather than
+            // telling them when to come back, and flattening it into a message string
+            // is exactly how it used to be lost.
+            const denial = poolDenial(err);
+            if (denial) {
+                if (deps.renderer) {
+                    deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} stopped — ${denial.title}`);
+                }
+                deps.renderer?.setPhase(null);
+                throw denial;
+            }
             if (deps.renderer) {
                 deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} failed: ${label}`);
             }
@@ -146,13 +222,20 @@ export class SubagentOrchestrator {
                 ...artifactsField(artifacts),
                 error: `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`,
                 iterations: 0,
-                usage: { input_tokens: 0, output_tokens: 0 },
+                // WHAT IT ACTUALLY SPENT, which is not zero and was reported as zero
+                // until now. A child that failed on its third request had two requests'
+                // tokens deducted from a pool the parent then went on to fan out
+                // against; a fabricated 0 put that spend nowhere. When NOTHING reported
+                // usage — the request died before the provider said anything — the
+                // field is absent, which the parent reads as unknown. Zero is reserved
+                // for a child that genuinely drew nothing.
+                ...usageField(usage),
             };
         }
         deps.renderer?.setPhase(null);
         const result = this.toResult(run, artifacts, label, noun);
         deps.logger.debug(`${noun} ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
-            `${result.usage.input_tokens}/${result.usage.output_tokens} — ${label}`);
+            `${describeUsage(result.usage)} — ${label}`);
         return result;
     }
     /**
@@ -168,11 +251,18 @@ export class SubagentOrchestrator {
      *
      * Cancellation: children share one {@link AbortController}. A child returning a
      * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
-     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
-     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
-     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
-     * fan-out leaves no orphan. All children are awaited to settle before a fatal
-     * throw propagates — never a detached, still-running sibling.
+     * on. But a *fatal* throw from any child (non-interactive default-deny, or a
+     * weighted-pool denial) or an abort on `opts.signal` (Ctrl-C) aborts the
+     * controller: every sibling stops at its next turn boundary and its in-flight
+     * shell child is kill-tree'd, so the fan-out leaves no orphan. All children are
+     * awaited to settle before a fatal throw propagates — never a detached,
+     * still-running sibling.
+     *
+     * THE POOL DENIAL IS THE ONE WORTH NAMING (cli#212). `budget_exhausted` is a
+     * statement about a denominator every sibling shares, so the first 429 is the
+     * whole batch's answer: without the abort, each remaining child walks into its
+     * own refusal and the parent gets N reports of one fact — each one arriving
+     * after that child had already spent what it spent getting there.
      */
     async spawnMany(specs, parentDepth, opts = {}) {
         const { maxDepth } = this.deps.config.subagent;
@@ -230,8 +320,11 @@ export class SubagentOrchestrator {
                     });
                 }
                 catch (err) {
-                    // A fatal throw (non-interactive default-deny) cancels the whole
-                    // fan-out — no sibling is left running — then propagates.
+                    // A fatal throw (non-interactive default-deny, or a weighted-pool
+                    // denial) cancels the whole fan-out — no sibling is left running —
+                    // then propagates. The abort is what makes the FIRST 429 the
+                    // batch's answer: siblings stop at their next turn boundary rather
+                    // than each spending its way into the same refusal.
                     controller.abort();
                     throw err;
                 }
@@ -396,6 +489,57 @@ function taskLabel(task) {
 function isWriter(spec) {
     return (spec.tools ?? []).some((t) => SUBAGENT_WRITE_TOOLS.has(t));
 }
+/**
+ * The typed pool denial behind an error, or `null` if it is not one.
+ *
+ * Two shapes reach here and both are the same fact: the raw SDK
+ * `BudgetExhaustedError` from this child's own request, and — when a child that
+ * itself spawned re-throws — the `CruxyError` a nested `spawn` already
+ * converted. Mapping goes through `classifyProviderError` so there is still ONE
+ * place that knows which SDK class means what.
+ */
+function poolDenial(err) {
+    if (CruxyError.is(err)) {
+        return err.code === ErrorCode.BudgetExhausted ? err : null;
+    }
+    const typed = classifyProviderError(err);
+    return typed?.code === ErrorCode.BudgetExhausted ? typed : null;
+}
+/**
+ * The tokens a child is KNOWN to have spent, or `undefined` when no request
+ * reported any.
+ *
+ * The loop fires `onRequestUsage` only for a request that COMPLETED, and when
+ * it does the provider's counts arrive as a pair or not at all — so an entry
+ * carries both figures or neither, and summing the ones that have them is a
+ * real measurement rather than a partial one. No entry at all is the genuinely
+ * unknown case: the request died before the provider reported anything, which
+ * does NOT mean the gateway metered nothing for it.
+ */
+function usageField(collected) {
+    const entries = collected.toRecord("", undefined, "").entries;
+    const total = sumReported(entries);
+    return total ? { usage: total } : {};
+}
+function sumReported(entries) {
+    let input = 0;
+    let output = 0;
+    let reported = false;
+    for (const e of entries) {
+        if (e.inputTokens === undefined && e.outputTokens === undefined)
+            continue;
+        input += e.inputTokens ?? 0;
+        output += e.outputTokens ?? 0;
+        reported = true;
+    }
+    return reported ? { input_tokens: input, output_tokens: output } : undefined;
+}
+/** `in/out`, or the word for an absent figure — never a stand-in `0/0`. */
+function describeUsage(usage) {
+    return usage
+        ? `${usage.input_tokens}/${usage.output_tokens}`
+        : "unknown (nothing reported)";
+}
 /** The honest result for a child cancelled before it could produce anything —
  * used when a fatal sibling / Ctrl-C fired before this slot even dispatched. */
 function cancelledResult() {

package/dist/subagent/spawn-tool.js

@@ -8,6 +8,26 @@ import { SPAWN_SUBAGENT_TOOL_NAME, SPAWN_SUBAGENTS_TOOL_NAME, } from "./registry
  * on structurally encodes how much deeper nesting may go: at the configured
  * cap the tool simply isn't registered.
  */
+/**
+ * Errors a spawn tool must NOT convert into a tool result.
+ *
+ * A tool error is an invitation to the model to try again differently, so this
+ * set is exactly the errors for which trying again differently is not a thing
+ * the model can do:
+ *
+ *  - `APPROVAL_REQUIRED` — non-interactive default-deny (U.3). There is no
+ *    variation of the call that would be approved; the boundary reports it.
+ *  - `BUDGET_EXHAUSTED` — the weighted pool refused (cli#212). Retrying, in any
+ *    shape, is a request to a gate that will refuse again, and the parent's own
+ *    next request would hit the same 429 regardless. Propagating it means the
+ *    user reads what the gateway actually said — which window, when it recovers,
+ *    and whether mira is still open — instead of the model narrating a tool
+ *    failure and reaching for another spawn.
+ */
+const PROPAGATE = new Set([
+    ErrorCode.ApprovalRequired,
+    ErrorCode.BudgetExhausted,
+]);
 const parameters = z.object({
     task: z
         .string()
@@ -42,10 +62,12 @@ function resultPayload(result) {
         ...(result.artifacts ? { artifacts: result.artifacts } : {}),
         ...(result.error ? { error: result.error } : {}),
         iterations: result.iterations,
-        tokens: {
-            input: result.usage.input_tokens,
-            output: result.usage.output_tokens,
-        },
+        // `"unknown"` rather than an omitted field or a `0/0` pair: the parent model
+        // reasons about what a child cost, and a missing key reads as nothing spent
+        // to anything skimming the payload. See `SubagentResult.usage`.
+        tokens: result.usage
+            ? { input: result.usage.input_tokens, output: result.usage.output_tokens }
+            : "unknown",
     };
 }
 /** The compact wire shape fed back to the parent model. */
@@ -84,10 +106,10 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3) —
-                // same behavior as every other gated tool.
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                // same behavior as every other gated tool. So does a weighted-pool
+                // denial (cli#212): see `PROPAGATE`.
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Depth-exceed and scope violations are the model's to correct: feed
                 // the coded, actionable message back as a tool error.
                 return { ok: false, error: toolErrorMessage(err) };
@@ -171,9 +193,8 @@ export function makeSpawnSubagentsTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3).
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Scope overlap / depth-exceed are the model's to correct — coded error.
                 return { ok: false, error: toolErrorMessage(err) };
             }

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./registry.js";
+export * from "./schema-depth.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
 export * from "./search-codebase.js";