@cruxy/cli 1.8.1 → 1.10.0

package/dist/session/log.js

@@ -1,28 +1,46 @@
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { APP_VERSION } from "../constants.js";
+import { formatBytes } from "../utils/disk.js";
 import { sessionFile } from "./paths.js";
+import { pruneSessions } from "./prune.js";
 import { SESSION_FILE_VERSION, } from "./types.js";
+/**
+ * How many pruned sessions is worth telling the user about unprompted.
+ *
+ * Retention on an existing install is a one-off cliff: every build so far had
+ * none, so the first prune after upgrading can remove months at once. That
+ * should not happen silently. Steady-state prunes remove one or two files and
+ * stay at `debug`, where they belong.
+ */
+const PRUNE_NOTICE_THRESHOLD = 10;
 export class SessionLog {
     file;
     logger;
     currentRunId;
     /** Set once a write fails: the log goes inert rather than warning per turn. */
     broken = false;
+    /**
+     * A NEW session's `meta` line, held until the session records something.
+     * Null on a reopen (the file already has its meta) and null again the moment
+     * it is flushed — see {@link write}.
+     */
+    pendingMeta = null;
     constructor(file, opts) {
         this.file = file;
         this.logger = opts.logger;
         this.currentRunId = opts.currentRunId;
     }
     /**
-     * Open (or create) a session log.
+     * Open a session log. WRITES NOTHING for a new session — see the note on the
+     * class about why the file no longer exists before the conversation does.
      *
-     * A NEW file gets its `meta` line. Reopening an existing one (a `--resume`)
-     * still does NOT get a second `meta` — that ruling is unchanged and is the
-     * reason this method has always branched: `meta` describes where and when the
-     * conversation began, and a second copy written from wherever it was resumed
-     * would make "the session's directory" ambiguous. Replay takes the first
-     * `meta`, so a duplicate could only ever mislead a later reader.
+     * A NEW session gets its `meta` line BUFFERED. Reopening an existing one (a
+     * `--resume`) still does NOT get a second `meta` — that ruling is unchanged
+     * and is the reason this method has always branched: `meta` describes where
+     * and when the conversation began, and a second copy written from wherever it
+     * was resumed would make "the session's directory" ambiguous. Replay takes
+     * the first `meta`, so a duplicate could only ever mislead a later reader.
      *
      * What a reopen gets instead is a `resumed` event (#172 item 2). It carries
      * the directory this run is in, which is the fact that used to vanish: a
@@ -31,16 +49,33 @@ export class SessionLog {
      * file forgot immediately. `meta` stays singular and authoritative; the
      * reopen is a separate kind, and no reader can confuse the two.
      *
-     * Returns `null` when a new log cannot be created at all — the caller then
-     * runs without persistence rather than failing, exactly as a corrupt usage
-     * store is survivable. A reopen still never returns null: the `resumed` write
-     * is now the first append, and a write problem there warns and goes inert
-     * exactly as any other failed append does. A session that cannot record its
-     * own reopen is not a session worth refusing to continue.
+     * The reopen write stays EAGER, and deliberately: a reopen is a fact about a
+     * conversation that already exists on disk, and `tree.test.ts` pins that it
+     * lifts a resumed session to the top of the picker with nothing said to it.
+     * Deferring it would quietly undo that.
+     *
+     * WHAT A FRESH OPEN NO LONGER TELLS YOU. It used to return `null` when the
+     * meta write failed, which is how the caller learned up front that
+     * persistence was dead. Nothing is written now, so there is nothing to fail:
+     * an unwritable home surfaces on the FIRST append instead, as one warning,
+     * and the session continues in memory. That is not a new tolerance — it is
+     * exactly how the reopen path has always behaved ("a session that cannot
+     * record its own reopen is not a session worth refusing to continue"), now
+     * applied to both branches rather than one.
+     *
+     * The `| null` in the signature is kept for the next thing to land here — a
+     * `sessions.enabled: false` that declines to record at all (#257) — rather
+     * than churning every call site twice.
      */
     static open(opts) {
+        // `sessions.enabled: false` — record nothing. The session runs in memory,
+        // which is the same degraded mode an unwritable home produces, reached on
+        // purpose. Every consumer already treats a missing recorder as normal.
+        if (opts.sessions?.enabled === false)
+            return null;
         const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
         const log = new SessionLog(file, opts);
+        log.pruneOnce(opts);
         if (hasContent(file)) {
             log.write({
                 kind: "resumed",
@@ -51,7 +86,10 @@ export class SessionLog {
             });
             return log;
         }
-        const ok = log.write({
+        // Buffered, not written. `startedAt` is stamped HERE rather than at flush:
+        // it means "when this conversation began", and the session began when it
+        // was opened, not when the user got around to saying something.
+        log.pendingMeta = {
             kind: "meta",
             version: SESSION_FILE_VERSION,
             sessionId: opts.sessionId,
@@ -61,8 +99,8 @@ export class SessionLog {
             cliVersion: APP_VERSION,
             ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
             ...(opts.model !== undefined ? { model: opts.model } : {}),
-        });
-        return ok ? log : null;
+        };
+        return log;
     }
     /** Messages appended to the history since the last event. */
     append(messages) {
@@ -99,8 +137,11 @@ export class SessionLog {
     }
     /**
      * One turn's token usage. Copied here rather than referenced, because the
-     * usage store keeps only its newest 50 runs while sessions are kept
-     * indefinitely — see the note on `UsageEventSchema`.
+     * usage store keeps only its newest 50 runs while a session keeps its own
+     * for as long as the session survives `sessions.retention` — see the note on
+     * `UsageEventSchema`. (That used to say "indefinitely", which was true until
+     * #257 gave sessions a bound; the two stores still expire independently, and
+     * the copy is still what makes a restored session's numbers whole.)
      */
     usage(inputTokens, outputTokens) {
         this.write({
@@ -130,18 +171,76 @@ export class SessionLog {
             count,
         });
     }
+    /**
+     * Enforce retention for this project, once, as this session opens.
+     *
+     * ORDERING: before the `resumed` write and before any meta flush, so the
+     * count cap is applied to the sessions that were there BEFORE this one and a
+     * fresh session never has to compete with itself for a slot. On a resume the
+     * file already exists and is explicitly excluded by id.
+     *
+     * Skipped entirely when the `file` seam is in use — see the note on
+     * {@link SessionLogOptions.sessions}.
+     */
+    pruneOnce(opts) {
+        if (!opts.sessions || opts.file !== undefined)
+            return;
+        let result;
+        try {
+            result = pruneSessions(opts.cwd, {
+                sessions: opts.sessions,
+                activeSessionId: opts.sessionId,
+            });
+        }
+        catch (err) {
+            // Retention is housekeeping. It does not get to fail a session.
+            this.logger?.debug(`session retention skipped: ${err.message}`);
+            return;
+        }
+        if (result.removed.length === 0)
+            return;
+        const line = `pruned ${result.removed.length} session${result.removed.length === 1 ? "" : "s"} ` +
+            `(${formatBytes(result.bytesFreed)}) past sessions.retention/maxAgeDays`;
+        if (result.removed.length >= PRUNE_NOTICE_THRESHOLD) {
+            this.logger?.info(`${line} — see \`cruxy sessions\``);
+        }
+        else {
+            this.logger?.debug(line);
+        }
+    }
     runId() {
         const id = this.currentRunId?.();
         return id === undefined ? {} : { runId: id };
     }
     /**
-     * Append one event as a single line. Returns whether it landed. The first
-     * failure warns and latches `broken`, so a persistent problem (a full disk)
-     * produces one diagnostic rather than one per turn.
+     * Record one event, flushing a buffered `meta` ahead of it.
+     *
+     * This is where a new session's file comes into existence: the first event to
+     * reach here brings the `meta` line with it, so the on-disk order is exactly
+     * what it always was and no reader can observe the difference.
+     *
+     * `pendingMeta` is cleared BEFORE the write is attempted. If the meta write
+     * fails, `broken` latches and every later event is refused — leaving the meta
+     * queued for a retry would let it land AFTER events it is supposed to
+     * precede, which is the one ordering the format depends on.
      */
     write(event) {
         if (this.broken)
             return false;
+        const meta = this.pendingMeta;
+        if (meta !== null) {
+            this.pendingMeta = null;
+            if (!this.writeLine(meta))
+                return false;
+        }
+        return this.writeLine(event);
+    }
+    /**
+     * Append one event as a single line. Returns whether it landed. The first
+     * failure warns and latches `broken`, so a persistent problem (a full disk)
+     * produces one diagnostic rather than one per turn.
+     */
+    writeLine(event) {
         try {
             mkdirSync(path.dirname(this.file), { recursive: true });
             // `mode` applies only when the file is created — 0600 from the first

package/dist/session/prune.js

@@ -0,0 +1,106 @@
+import { unlinkSync } from "node:fs";
+import path from "node:path";
+import { SESSION_RETENTION_FLOOR, } from "../config/index.js";
+import { sessionFilesByRecency } from "./list.js";
+import { SESSION_FILE_EXT } from "./paths.js";
+/** `<sessionId>.jsonl` → `<sessionId>`. */
+function idOf(file) {
+    return path.basename(file, SESSION_FILE_EXT);
+}
+/**
+ * Enforce `sessions.retention` and `sessions.maxAgeDays` on one project.
+ *
+ * Age is the primary bound and is measured on MTIME, never on
+ * `meta.startedAt`: a conversation begun forty days ago and resumed this
+ * morning is live, and an age check on when it BEGAN would delete it out from
+ * under the user. mtime is also the field the scan already carries, so the
+ * correct rule is the cheap one.
+ *
+ * The count cap is the backstop, applied by position in the same
+ * newest-first ordering. It exists because age alone does not protect a
+ * directory where someone runs forty sessions a day.
+ *
+ * Never throws. A file that cannot be unlinked is counted in `failed` and the
+ * sweep continues — retention failing is not a reason to take a session down,
+ * exactly as a failed session write is not.
+ */
+export function pruneSessions(cwd, opts) {
+    const result = {
+        removed: [],
+        kept: 0,
+        bytesFreed: 0,
+        failed: 0,
+    };
+    if (!opts.sessions.enabled)
+        return result;
+    // Defensive, mirroring `usage/store.ts`: the schema rejects anything below
+    // the floor, but this is also reachable with a hand-built config.
+    const retention = Math.max(SESSION_RETENTION_FLOOR, Math.floor(opts.sessions.retention));
+    const now = opts.now ?? Date.now();
+    const cutoff = now - opts.sessions.maxAgeDays * 24 * 60 * 60 * 1000;
+    // Newest first. Every file here ends in `.jsonl` and is a regular file — see
+    // the note on the scan about why `subagents/` depends on that.
+    const files = sessionFilesByRecency(cwd);
+    for (const [index, ref] of files.entries()) {
+        const sessionId = idOf(ref.file);
+        // WHY THE FILENAME IS TRUSTED HERE, when `listSessionRefs` refuses to.
+        // That refusal is about what may be OFFERED: a session resolvable by
+        // filename but unloadable for want of a meta line is a `--resume` that
+        // fails after the user picked it. This is the opposite question. Being
+        // conservative about what to DELETE and permissive about what to offer are
+        // opposite failure modes, and the cheap answer is the safe one on this
+        // side — at worst a filename that does not match the meta spares a file
+        // that could have gone. Do not "fix" this to `readMeta`; that puts a full
+        // read of every session back on the startup path.
+        if (sessionId === opts.activeSessionId) {
+            result.kept++;
+            continue;
+        }
+        const tooOld = ref.mtimeMs < cutoff;
+        const beyondCap = index >= retention;
+        if (!tooOld && !beyondCap) {
+            result.kept++;
+            continue;
+        }
+        try {
+            unlinkSync(ref.file);
+            result.removed.push({ ...ref, sessionId });
+            result.bytesFreed += ref.size;
+        }
+        catch {
+            result.failed++;
+            result.kept++;
+        }
+    }
+    sweepOrphanedJobLogs();
+    return result;
+}
+/**
+ * Drop retained job logs whose owning session has just been pruned.
+ *
+ * DELIBERATELY EMPTY, and reserved rather than forgotten. #172 item 1 will
+ * write background-job output to the `subagents/` subtree `paths.ts` reserves
+ * under this same project directory, and #257 exists because that issue asked
+ * "whether the retained-on-disk log is pruned with the session or independently"
+ * and found no answer. The answer is HERE, and it is: with the session, keyed on
+ * the session.
+ *
+ * That makes a job log content owned by its session in exactly the way a
+ * checkpoint's shadow objects are content owned by its manifest — so this is
+ * `CheckpointService.prune`'s second phase, the mark-and-sweep that runs after
+ * the doomed manifests are gone. Filling it in needs one thing the writer does
+ * not have yet: a job log has to record which session owns it, in its path or
+ * its first line.
+ *
+ * The hook is here so item 1 fills it rather than inventing a parallel
+ * retention policy alongside this one. Whatever lands must not `rm -r` this
+ * directory and must not assume every entry is a session's — `subagents/` is a
+ * sibling of the session files, not one of them.
+ *
+ * It takes nothing today because it does nothing; item 1 will want the `cwd`
+ * and the {@link PruneResult} whose `removed` names the sessions whose logs are
+ * now orphaned.
+ */
+function sweepOrphanedJobLogs() {
+    // #172 item 1.
+}

package/dist/session/resume.js

@@ -152,6 +152,11 @@ export function resolveSessionId(cwd, id) {
         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",
+            // #257: retention can now delete a session the user still remembers the
+            // id of, and a pruned session must not read as a bug. The checkpoint
+            // equivalent (`errors/constructors.ts`, CRUXY_E_CHECKPOINT_NOT_FOUND)
+            // says the same thing for the same reason.
+            "old sessions are pruned by retention — adjust `sessions.retention` / `sessions.maxAgeDays` in config to keep more",
         ]);
     }
     return summary;

package/dist/subagent/orchestrator.js

@@ -1,8 +1,8 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { runAgent } from "../agent/loop.js";
-import { classifyProviderError, CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
-import { UsageCollector } from "../usage/index.js";
+import { CruxyError, ErrorCode, messageOf, poolDenial, 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";
@@ -76,7 +76,30 @@ export class SubagentOrchestrator {
         if (childDepth < maxDepth) {
             registry.register(makeSpawnSubagentTool(this, childDepth));
         }
-        const budget = new Budget(resolveBudget(defaultBudget, spec.budget));
+        // Admission control for the SEQUENTIAL seam (cli#245). `spawnMany` asks for
+        // its whole batch and passes the verdict down; everything else — the
+        // `spawn_subagent` tool, a plan step, a nested child — arrives here having
+        // asked nobody, which is the hole cli#243 left behind. A refusal throws the
+        // same coded error the fan-out throws, and the spawn tool hands it to the
+        // model as a tool error it can act on (see `PROPAGATE` in `spawn-tool.ts`).
+        const admission = opts.admission ?? this.admitRuns(1, [spec]);
+        if (admission.kind === "refused") {
+            throw sessionBudgetExhausted(admission.reason);
+        }
+        if (admission.kind === "narrowed" && !opts.admission) {
+            deps.logger.warn(admission.reason);
+        }
+        // `admit` only ever NARROWS, and `Math.min` is what makes that true here: a
+        // batch verdict carries the heaviest child's ceiling, so applying it raw to
+        // a cheaper sibling would RAISE that child's cap on the strength of an
+        // admission check. `0` means the budget bounded nothing.
+        const resolved = resolveBudget(defaultBudget, spec.budget);
+        const budget = new Budget(admission.maxTokens > 0
+            ? {
+                ...resolved,
+                maxTokens: Math.min(resolved.maxTokens, admission.maxTokens),
+            }
+            : resolved);
         // Root scoping (C.33): a `spec.root` narrows the child's cwd + confinement to
         // that ONE root (its writes land there and nowhere else). Omitted → the full
         // session workspace, unchanged from C.14. An unknown name fails loud here
@@ -150,12 +173,19 @@ export class SubagentOrchestrator {
             // 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.
+            // STILL NOT WRITTEN TO THE USAGE STORE AS A RUN OF ITS OWN, and now for a
+            // different reason than when this was written (cli#244 closed the gap the
+            // old note described). The child's requests DO reach `/usage` — forwarded
+            // above into the spawning turn's collector, so they land as entries of the
+            // turn's record. What this record is for is the budget, and only the
+            // budget: it exists so the fold can happen the MOMENT the child finishes
+            // rather than at end of turn, because the next admission check inside the
+            // same turn has to see the spend.
+            //
+            // Which is exactly why the parent must NOT hand these same entries to the
+            // budget again when its turn closes — see the `origin` filter at
+            // `agent/session.ts`. Two folds of one child's tokens would halve the
+            // effective session cap on any turn that fans out.
             this.deps.budget?.record(usage.toRecord(randomUUID(), undefined, startedAt));
         }
     }
@@ -183,7 +213,16 @@ export class SubagentOrchestrator {
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
                 signal: opts.signal,
-                onRequestUsage: (req) => usage.record(req),
+                // Both, and in this order (cli#244). The child's OWN collector is what
+                // the budget fold below reads — it needs a per-child record — while the
+                // parent's sink is what puts this request in `/usage` at all. The
+                // explicit origin is load-bearing: the parent's collector defaults to
+                // `"turn"`, and a child's request inheriting that would be a lie about
+                // what the user did.
+                onRequestUsage: (req) => {
+                    usage.record(req);
+                    opts.onRequestUsage?.({ ...req, origin: "subagent" });
+                },
             });
         }
         catch (err) {
@@ -277,7 +316,7 @@ export class SubagentOrchestrator {
         // AFTER the scope check on purpose: an overlapping fan-out is malformed and
         // must be refused whatever the budget says, and narrowing a malformed batch
         // to two children would hide the overlap rather than report it.
-        const admitted = this.admitFanOut(specs);
+        const admitted = this.admitRuns(specs.length, specs);
         if (admitted.kind === "refused") {
             throw sessionBudgetExhausted(admitted.reason);
         }
@@ -317,6 +356,17 @@ export class SubagentOrchestrator {
                     results[i] = await this.spawn(spec, parentDepth, {
                         signal: controller.signal,
                         slot: `${i + 1}/${total}`,
+                        // The batch verdict, so the child does not ask a second time —
+                        // and so a cut token cap actually reaches the run it was cut
+                        // for. `admit` returns one for a single run it can only
+                        // partially afford, and until cli#245 `spawnMany` read the
+                        // count off that verdict and dropped the ceiling with it.
+                        admission: admitted,
+                        // Every child of the batch reports into the one turn that
+                        // spawned them, exactly as a sequential child does.
+                        ...(opts.onRequestUsage
+                            ? { onRequestUsage: opts.onRequestUsage }
+                            : {}),
                     });
                 }
                 catch (err) {
@@ -347,7 +397,13 @@ export class SubagentOrchestrator {
         }
     }
     /**
-     * Ask the session budget whether this batch fits (P10 track 3 / cli#212).
+     * Ask the session budget whether these runs fit (P10 track 3 / cli#212).
+     *
+     * ONE method for both seams (cli#245): a batch of N from `spawnMany`, and the
+     * single run `spawn` asks for when nobody admitted it. They differ only in
+     * `count` — the arithmetic, the tier resolution and the per-run ceiling are
+     * the same question, and a second copy for the singular case is how the two
+     * would come to disagree.
      *
      * The estimate is the batch's CEILING, not a guess at its actual draw:
      * `count × perChildTokens × multiplier`, where `perChildTokens` is the local
@@ -361,17 +417,17 @@ export class SubagentOrchestrator {
      * the pool, so it is weighed at the worst case rather than skipped — see
      * `UNRESOLVED_TIER`.
      */
-    admitFanOut(specs) {
+    admitRuns(count, specs) {
         const budget = this.deps.budget;
         if (!budget)
-            return { kind: "allow", count: specs.length, maxTokens: 0 };
+            return { kind: "allow", count, maxTokens: 0 };
         const { defaultBudget } = this.deps.config.subagent;
         // The heaviest child in the batch sets the per-run figure. The bound has to
         // hold for the batch as dispatched, and averaging would let one 64k child
         // hide behind four 4k ones.
         const perRunTokens = specs.reduce((max, spec) => Math.max(max, resolveBudget(defaultBudget, spec.budget).maxTokens), 0);
         return budget.admit({
-            count: specs.length,
+            count,
             perRunTokens,
             tier: this.fanOutTier(),
         });
@@ -489,22 +545,6 @@ 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.

package/dist/subagent/spawn-tool.js

@@ -91,7 +91,7 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
             "transcript is discarded. Use for independent subtasks whose details you don't " +
             'need in your own context (e.g. "find where X is configured and report the paths").',
         parameters,
-        async execute(input) {
+        async execute(input, ctx) {
             const budget = {
                 ...(input.maxIterations !== undefined
                     ? { maxIterations: input.maxIterations }
@@ -102,7 +102,12 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
             };
             let result;
             try {
-                result = await orchestrator.spawn({ task: input.task, tools: input.tools, budget }, depth);
+                result = await orchestrator.spawn({ task: input.task, tools: input.tools, budget }, depth, 
+                // The calling turn's usage collector (cli#244), the one thing on `ctx`
+                // that is per-turn rather than per-session. Absent outside a turn, in
+                // which case the child's spend still reaches the budget — it just has
+                // no record to join.
+                ctx.onRequestUsage ? { onRequestUsage: ctx.onRequestUsage } : {});
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3) —
@@ -186,10 +191,12 @@ export function makeSpawnSubagentsTool(orchestrator, depth) {
             "For children that WRITE, give each a distinct `root`; overlapping write scope is " +
             "refused. For a single subtask, use spawn_subagent instead.",
         parameters: batchParameters,
-        async execute(input) {
+        async execute(input, ctx) {
             let results;
             try {
-                results = await orchestrator.spawnMany(input.tasks.map(toSpec), depth);
+                results = await orchestrator.spawnMany(input.tasks.map(toSpec), depth, 
+                // Every child of the batch reports into the one turn that spawned it.
+                ctx.onRequestUsage ? { onRequestUsage: ctx.onRequestUsage } : {});
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3).

package/dist/tools/schema-depth.js

@@ -59,6 +59,24 @@ export function schemaDepth(node) {
  * does not raise it there — it only moves the failure from a red CI run to every
  * user's terminal. If a schema cannot fit, the schema changes.
  *
+ * THE MIRROR ONLY PROTECTS ONE DIRECTION. Raising this literal is caught by the
+ * paragraph above; the gateway TIGHTENING it is caught by nothing here. If
+ * `maxSchemaDepth` drops to 7, `apply_patch` and `spawn_subagents` — both at
+ * rendered depth 7, a margin accepted deliberately in #233 — are dead in the
+ * field for every user on every turn, and this repo's CI stays green, because
+ * the test written to prevent exactly that outage is asserting against a stale
+ * copy of the number. `mcp/bounds.ts` reads this same constant, so a drift takes
+ * the MCP guard with it.
+ *
+ * Asked on cruxy-ai/api#183 whether the bound could be SERVED rather than
+ * mirrored. Answer, in cruxy-ai/api#187 (merged 2026-08-19): half of it. A
+ * rejection is now self-describing — code `invalid_tool_schema` with `tool`,
+ * `bound` (`bytes` | `depth` | `nodes`) and `limit` as structured fields — but
+ * nothing reports the bound before a request is sent. So this stays a hand-copy,
+ * CI cannot catch a tightening, and the runtime error is the ONLY detector we
+ * have: a rejection whose `limit` disagrees with this constant means the
+ * constant is stale, not that one tool is bad. Fix it here, not at the tool.
+ *
  * The bound is EXCLUSIVE: a schema is safe at `MAX_SCHEMA_DEPTH - 1` and dies at
  * `MAX_SCHEMA_DEPTH`. Both consumers must spell that the same way — the CI gate
  * asserts `depth < MAX_SCHEMA_DEPTH`, the MCP bound trips on