mandrel 2.35.0 → 2.37.0

package/.agents/docs/agentrc-reference.json

@@ -340,7 +340,9 @@
         "maxResumes": 3,
         "attachWindowMs": 1200000
       },
-      "autoMerge": "trust-ci"
+      "autoMerge": "trust-ci",
+      "blockOnAdvisoryFailure": true,
+      "advisoryAllowlist": []
     },
     "routing": {
       "roleScopedAgents": true,

package/.agents/docs/configuration.md

@@ -320,6 +320,8 @@ Everything `/deliver` and `single-story-close` consume: execution timeouts, work
 | `ci.watch.maxResumes` | No | `integer` | `3` | How many times the watcher may resume after a transient stall. 0 disables resuming. |
 | `ci.watch.attachWindowMs` | No | `integer` | `1200000` | Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started). |
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | `"trust-ci"` | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
+| `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
+| `ci.advisoryAllowlist` | No | `array<string>` | `[]` | Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks. |
 | `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
 | `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
 | `routing.freshCriticSampleRate` | No | `number` | `0.2` | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
@@ -681,6 +683,31 @@ Claude Code web environment-variables UI for web sessions.
 | `NOTIFICATION_WEBHOOK_URL` | No        | POST target for in-band Notifier events (Make.com / Slack / Discord). Unset disables the webhook channel; `log` and `epic-comment` channels still fire. |
 | `WEBHOOK_SECRET`           | No        | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads.                                 |
 | `MANDREL_ALLOW_TEST_WEBHOOKS` | No     | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
+| `MANDREL_POOL_CONCURRENCY` | No | Upper bound on the width of every `runOnPool` worker pool in the process (the MI and CRAP scan pools). Precedence is: a caller's explicit `concurrency` → this variable → a clamp of 4 under `node:test` → `os.availableParallelism()`. Set it on a constrained or shared runner where one pool per core oversubscribes the host; a non-numeric value is ignored rather than collapsing the pool. |
+| `MANDREL_AGENTRC_VALIDATOR` | No | Set to `dynamic` to compile the `.agentrc.json` AJV validator at runtime instead of loading the committed precompiled one (see below). Costs ~35 ms per process; the escape hatch exists for a hand-edited schema or a host where the generated module will not load. |
+
+### The `.agentrc` validator is precompiled
+
+`getAgentrcValidator()` returns AJV's **standalone emit** for
+`AGENTRC_SCHEMA`, committed at
+[`.agents/scripts/lib/generated/agentrc-validator.js`](../scripts/lib/generated/agentrc-validator.js).
+Compiling that schema costs ~35 ms, and 36 of the framework's entry scripts
+resolve configuration, so the compile was being paid over and over to
+re-derive a function from a literal that is already in the repository.
+
+The artifact is generated — never hand-edited — by
+[`check-generated-validator.js`](../scripts/check-generated-validator.js):
+
+```bash
+npm run validator:gen     # rewrite it after a deliberate schema change
+npm run validator:check   # fail when it is stale (also run by `npm run lint`)
+```
+
+`npm run lint` runs the `--check` mode, so a schema edit that skips
+regeneration is refused rather than shipping a validator that accepts the
+wrong config. Validation behaviour is unchanged in either mode: the generated
+code is AJV's own, emitted with the same `allErrors: true` option the dynamic
+path uses, and returns the same verdict and the same `errors` array.
 
 ### Test-mode webhook isolation
 

package/.agents/rules/testing-standards.md

@@ -79,6 +79,13 @@ of the pyramid.
 - **Location.** `tests/features/**/*.feature` with step definitions in
   `tests/steps/**` (or the project's equivalent). The companion skill is
   [`stack/qa/playwright-bdd`](../skills/stack/qa/playwright-bdd/SKILL.md).
+- **Run tier.** This tier MUST NOT ride inside the default suite. It is slow
+  by construction — real installs, real browsers, real stacks — and the
+  default suite is what a pre-push hook and every local iteration pay for.
+  Give it its own runner tier and its own CI job, so its cost is charged to
+  the surface whose signal it is. In this repository that is `tests/e2e/**`,
+  the `e2e` tier (`npm run test:e2e`), and the per-PR `e2e` job; the coverage
+  run still measures those files, so nothing leaves the measured surface.
 
 ## Assertion Placement Rule {#assertion-placement}
 
@@ -236,3 +243,52 @@ Hypothesis keeps a failure DB, proptest writes `proptest-regressions/` — pin o
 commit whichever the stack provides. Once shrinking surfaces a minimal
 counterexample, **add it as an example-based regression test** alongside the
 property: the property guards the domain, the pinned example guards the bug.
+
+## The suite's child-process budget
+
+`npm test` forks one process per test file, and the spawns those leaves make
+dominate the suite's system time. Two instruments and one rule keep that
+budget visible and honest (Story #5121).
+
+### Measure it with `npm run test:census`
+
+```bash
+npm run test:census            # writes temp/census.json
+```
+
+`tests/fixtures/spawn-census.cjs` is a `--require` preload that counts every
+`child_process` call per binary, aggregates across all ~700 processes, and
+reports `nodeInSuite` (node children spawned *by test files*, excluding the
+runner's own fan-out), `git`, `gh`, `npm`, and any standalone
+`git config user.*` spawns. Read the numbers from the census rather than
+re-deriving them; two audits hand-rolled this measurement and lost it both
+times with the gitignored temp tree.
+
+The script interpolates `$PWD` deliberately. A **relative** `--require` path is
+inherited by children that run with a different `cwd`, where it fails to
+resolve and kills the child before it runs a line — measured as 15 spurious
+failures in one file.
+
+### Build a fixture repo once, then copy it
+
+A multi-commit fixture repo rebuilt in `beforeEach` is the costly shape. Build
+it once in `before()` and hand each test an `fs` copy via
+`copyGitRepo(pristine)` from `tests/fixtures/git-fixture.js`: each test still
+gets a private directory it may freely mutate, for **no subprocess at all**.
+One file went from 92 `git` spawns to 27 this way.
+
+`copyGitRepo` is safe only for a locally-`git init`ed repo, whose
+`.git/config` holds no absolute paths. Do **not** copy a **clone** (its
+`remote.origin.url` is absolute, so the copy would fetch from the original) or a
+linked worktree (its `gitdir:` / `commondir` pointers would dangle).
+
+### Never trade coverage for a spawn count
+
+Most of the suite's remaining `git` spawns are integration tests exercising
+real git against git-manipulating production code — the spawn **is** the
+subject under test, and so is a CLI's exit code in an exit-code contract test.
+Those are not fixture waste and must not be converted to in-process calls or
+mocks to make a number smaller. Hoist shared setup; leave the assertions alone.
+A spawn census also records argv, not what the binary resolved to: a
+`gh pr view 4890` line may well be a fake `gh` the test put on `PATH`, so
+verify resolution before calling a spawn a network call.

package/.agents/schemas/agentrc.schema.json

@@ -1913,6 +1913,17 @@
               "enum": ["trust-ci", "strict"],
               "description": "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
               "default": "trust-ci"
+            },
+            "blockOnAdvisoryFailure": {
+              "type": "boolean",
+              "description": "Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.",
+              "default": true
+            },
+            "advisoryAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.",
+              "default": []
             }
           },
           "additionalProperties": false

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -29,7 +29,8 @@
         "branch-protection-human-required",
         "arm-failure",
         "api-race-other",
-        "predicate-refused"
+        "predicate-refused",
+        "advisory-gate-red"
       ]
     },
     "reason": { "type": "string", "minLength": 1 },

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -125,6 +125,7 @@
             "arm-failure",
             "api-race-other",
             "predicate-refused",
+            "advisory-gate-red",
             "merged-flip-failed"
           ]
         },

package/.agents/scripts/boot-sweep.js

@@ -45,6 +45,7 @@ import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
+import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
 import { sweepTempRetention } from './lib/temp-retention.js';
 
@@ -141,8 +142,13 @@ export async function runBootSweep({
       excludeGlobs.push(current);
     }
 
+    // Story #5112 — one critical section, one lock. `single-story-init.js`
+    // reaps the same merged `story-*` branches through the same engine; when
+    // the two surfaces held differently named lockfiles they could run
+    // concurrently, each deleting branches the other had already planned.
+    // Both now resolve the path through `resolveSweepLockPath`.
     const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
-    const lockPath = path.resolve(root, tempRoot, 'boot-sweep.lock');
+    const lockPath = resolveSweepLockPath({ cwd: root, tempRoot });
     const lockTimeoutMs =
       config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
 

package/.agents/scripts/check-context-budget.js

@@ -481,6 +481,179 @@ export function renderReachable(tierMap, baseline) {
  * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
  *   1 = a gated tier grew beyond tolerance
  */
+/**
+ * Write a fresh budget, preserving the recorded tolerance so `--update` never
+ * silently widens the gate it is refreshing.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function writeUpdatedBaseline({ tierMap, resolvedBaselinePath, json, stdout }) {
+  const existing = loadBaseline(resolvedBaselinePath);
+  const tolerance = Number.isFinite(existing?.toleranceBytes)
+    ? existing.toleranceBytes
+    : DEFAULT_TOLERANCE_BYTES;
+  const envelope = buildBaseline(tierMap, tolerance);
+  fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
+  fs.writeFileSync(
+    resolvedBaselinePath,
+    `${JSON.stringify(envelope, null, 2)}\n`,
+  );
+  if (!json) {
+    stdout.write(
+      `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
+    );
+  } else {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * An absent budget is a no-op, not a failure: a consumer that has never
+ * recorded one has nothing to regress against.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function reportMissingBaseline({
+  tierMap,
+  resolvedBaselinePath,
+  json,
+  stdout,
+  stderr,
+}) {
+  if (json) {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+    );
+  } else {
+    stderr.write(
+      `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * Score the tree against the recorded budget. Pure — every verdict the two
+ * renderers below present is decided here, so they cannot disagree about what
+ * failed or drift apart in which fields they surface.
+ *
+ * @param {{ tierMap: object, baseline: object }} params
+ * @returns {{ diff: object, ceiling: number, bootOverflow: object[], bootDrift: object[], permissiveDrift: object[], exitCode: 0 | 1 }}
+ */
+function evaluateBudget({ tierMap, baseline }) {
+  const diff = diffBudget(tierMap, baseline);
+  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const bootOverflow = agentBootOverflow(tierMap, ceiling);
+  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
+  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
+  const exitCode =
+    budgetFailureCount(diff) > 0 ||
+    bootOverflow.length > 0 ||
+    permissiveDrift.length > 0
+      ? 1
+      : 0;
+  return { diff, ceiling, bootOverflow, bootDrift, permissiveDrift, exitCode };
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderJsonReport({
+  tierMap,
+  baseline,
+  resolvedBaselinePath,
+  report,
+  stdout,
+}) {
+  const { diff, ceiling, bootOverflow, bootDrift, exitCode } = report;
+  const envelope = {
+    kind: 'context-budget-report',
+    baselinePath: resolvedBaselinePath,
+    toleranceBytes: Number.isFinite(baseline.toleranceBytes)
+      ? baseline.toleranceBytes
+      : 0,
+    current: Object.fromEntries(
+      GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
+    ),
+    grown: diff.grown,
+    shrunk: diff.shrunk,
+    absent: diff.absent,
+    skipped: diff.skipped,
+    agentBootCeilingBytes: ceiling,
+    agentBootOverflow: bootOverflow,
+    agentBootDrift: bootDrift,
+    workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
+    exitCode,
+  };
+  stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+
+/**
+ * Each failing condition gets its own remediation line: they are fixed
+ * differently (trim a role def vs refresh the budget), so a single generic
+ * message would leave the author guessing which applies.
+ *
+ * @param {object} params
+ * @returns {void}
+ */
+function renderFailureDiagnostics({ report, stderr }) {
+  const { diff, ceiling, bootOverflow, permissiveDrift } = report;
+  if (permissiveDrift.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
+    );
+  }
+  if (bootOverflow.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
+    );
+  }
+  if (diff.grown.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+    );
+  }
+  if (diff.shrunk.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+  if (diff.absent.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderTextReport({ tierMap, baseline, report, stdout, stderr }) {
+  const { diff, bootOverflow, bootDrift, exitCode } = report;
+  stdout.write(`\n--- context-budget preview ---\n`);
+  stdout.write(`${renderDiff(diff)}\n`);
+  const reachable = renderReachable(tierMap, baseline);
+  if (reachable) stdout.write(`${reachable}\n`);
+  for (const o of bootOverflow) {
+    stdout.write(
+      `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
+    );
+  }
+  for (const line of renderBootDrift(bootDrift)) {
+    stdout.write(`${line}\n`);
+  }
+  if (exitCode === 1) renderFailureDiagnostics({ report, stderr });
+}
+
 export async function runCli({
   argv = process.argv.slice(2),
   cwd = process.cwd(),
@@ -498,120 +671,39 @@ export async function runCli({
   const tierMap = resolveDocTiers(resolvedConfig, { root });
 
   if (update) {
-    const existing = loadBaseline(resolvedBaselinePath);
-    const tolerance = Number.isFinite(existing?.toleranceBytes)
-      ? existing.toleranceBytes
-      : DEFAULT_TOLERANCE_BYTES;
-    const envelope = buildBaseline(tierMap, tolerance);
-    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
-    fs.writeFileSync(
+    return writeUpdatedBaseline({
+      tierMap,
       resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    if (!json) {
-      stdout.write(
-        `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
-      );
-    } else {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
-      );
-    }
-    return 0;
+      json,
+      stdout,
+    });
   }
 
   const baseline = loadBaseline(resolvedBaselinePath);
   if (!baseline) {
-    if (json) {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
-      );
-    } else {
-      stderr.write(
-        `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
-      );
-    }
-    return 0;
+    return reportMissingBaseline({
+      tierMap,
+      resolvedBaselinePath,
+      json,
+      stdout,
+      stderr,
+    });
   }
 
-  const diff = diffBudget(tierMap, baseline);
-  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
-    ? baseline.agentBoot.ceilingBytes
-    : AGENT_BOOT_CEILING_BYTES;
-  const bootOverflow = agentBootOverflow(tierMap, ceiling);
-  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
-  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
-  const exitCode =
-    budgetFailureCount(diff) > 0 ||
-    bootOverflow.length > 0 ||
-    permissiveDrift.length > 0
-      ? 1
-      : 0;
-
+  const report = evaluateBudget({ tierMap, baseline });
   if (json) {
-    const envelope = {
-      kind: 'context-budget-report',
-      baselinePath: resolvedBaselinePath,
-      toleranceBytes: Number.isFinite(baseline.toleranceBytes)
-        ? baseline.toleranceBytes
-        : 0,
-      current: Object.fromEntries(
-        GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
-      ),
-      grown: diff.grown,
-      shrunk: diff.shrunk,
-      absent: diff.absent,
-      skipped: diff.skipped,
-      agentBootCeilingBytes: ceiling,
-      agentBootOverflow: bootOverflow,
-      agentBootDrift: bootDrift,
-      workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
-      exitCode,
-    };
-    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    renderJsonReport({
+      tierMap,
+      baseline,
+      resolvedBaselinePath,
+      report,
+      stdout,
+    });
   } else {
-    stdout.write(`\n--- context-budget preview ---\n`);
-    stdout.write(`${renderDiff(diff)}\n`);
-    const reachable = renderReachable(tierMap, baseline);
-    if (reachable) stdout.write(`${reachable}\n`);
-    for (const o of bootOverflow) {
-      stdout.write(
-        `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
-      );
-    }
-    for (const line of renderBootDrift(bootDrift)) {
-      stdout.write(`${line}\n`);
-    }
-    if (exitCode === 1) {
-      if (permissiveDrift.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
-        );
-      }
-      if (bootOverflow.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
-        );
-      }
-      if (diff.grown.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
-        );
-      }
-      if (diff.shrunk.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-      if (diff.absent.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-    }
+    renderTextReport({ tierMap, baseline, report, stdout, stderr });
   }
 
-  return exitCode;
+  return report.exitCode;
 }
 
 async function main() {