bareloop 0.9.0 → 0.11.0

package/src/authorflow.js

@@ -78,11 +78,11 @@ import { join, relative, isAbsolute } from 'node:path';
 import { seedRead as runSeedReadStages, makeSeedTrees, AGGREGATES, SIGNS, MAX_TERMS } from './kinds.js';
 import {
   KIND_CATALOGUE, MAX_STAGES, DIRECTIONS, BASELINES,
-  GENRE_LANGUAGES, TYPES_GENRE_TEMPLATE, classGuards, genreEnv, genreOwnedEnvNames,
+  GENRE_LANGUAGES, TYPES_GENRE_TEMPLATE, classGuards, genreEnv, genreOwnedEnvNames, genreInstruments,
   validateDeclaration, envCapableKind, VERDICT_CLASSES, LIVE_CLASSES,
 } from './authoring.js';
-import { buildSeedListing, cleanEntry } from './authorscout.js';
-import { extractArtifact, priceOf, scrubRaw } from './text.js';
+import { buildSeedListing, cleanEntry, SURVEY_CAUSES } from './authorscout.js';
+import { extractArtifact, priceOf, scrubRaw, tallyCalls, capStop } from './text.js';
 import { redactSecrets } from './validate.js';
 
 const require = createRequire(import.meta.url);
@@ -163,21 +163,63 @@ export const STRUCTURE_INSTRUCTION_TEXT = 'Your reply could not be read as one J
  * cannot emit anything else (D2/D3), so a genre it has never seen is a
  * composition problem, not a catalogue problem.
  *
- * The GREEN set is questions 1–6 of the frozen TYPES set (prereg §5) BYTE FOR
- * BYTE. What is gone is the seventh slot — D13's genre CONFIRM ("this looks like
- * a type-fixing job, correct?") — superseded in full: the interview never asks
- * about a genre again. The refusal it carried did not disappear; it MOVED to the
- * composer, on the same counted `request-red` path (see `authorCloseForJob`).
- * The remaining six are already genre-neutral, which is why generalising them
- * required deleting a slot rather than rewording one.
+ * The GREEN set descends from questions 1–6 of the frozen TYPES set (prereg §5).
+ * TWO slots have been deleted since, both because the interview was ASKING FOR
+ * SOMETHING IT ALREADY HAD or already knew:
+ *
+ *   - D13's genre CONFIRM ("this looks like a type-fixing job, correct?") —
+ *     superseded in full: the interview never asks about a genre again, and the
+ *     refusal it carried MOVED to the composer, on the same counted
+ *     `request-red` path (see `authorCloseForJob`);
+ *   - "Is there a code repo I can look at? Where?" — DROPPED on hamr's ruling
+ *     after he drove the terminal interview himself (2026-08-15, verbatim: *"drop
+ *     Q6"*). The repository is a MANDATORY, STRUCTURED input already —
+ *     `runInterview`'s own `repoPath`, which the runner takes from `--patient` and
+ *     refuses to start without. Asking a person to re-type in prose a path the
+ *     machine is holding in a variable is the SWE tax this product refuses, and
+ *     it invites a second, drifting answer for the same fact (hamr's own answer
+ *     on the live run was *"Yes — the patient itself."*). Nothing downstream lost
+ *     anything: the scout reads `repoPath`, never the answer.
+ *
+ * Question 2 was WIDENED in the same ruling: it now asks for the read-or-draw-from
+ * files as well as the ones that change. The two halves belong in one answer
+ * because they are one decision for the person answering — what the work touches,
+ * and what it touches only to look at.
+ *
+ * The five that remain are genre-neutral, which is why every generalisation so far
+ * has deleted a slot rather than reworded one. They are NUMBERED CONTIGUOUSLY from
+ * 1: the number a person sees is the key their answer is filed under, and a gap
+ * would be a hole in a form nobody can explain.
  */
 export const GREEN_QUESTIONS = Object.freeze({
   1: 'What do you want done?',
-  2: 'Which files or folders should change?',
+  2: 'Which files or folders should change? And which files should the work read or draw from (they stay untouched)?',
   3: 'Is there anything that must not change?',
   4: 'How do you check today whether it\'s working?',
   5: 'What would make you say this came back worse than before?',
-  6: 'Is there a code repo I can look at? Where?',
+});
+
+/**
+ * THE HITL SET (N4 slice 1) — the green questions BYTE FOR BYTE, plus one.
+ *
+ * The five are unchanged deliberately rather than economically: the
+ * mechanical-first composition law (2026-08-07) says every hitl close is
+ * *deterministic stages first, judge minimal, human last*, so a hitl job needs
+ * exactly the same mechanical facts a green one does — what changes, what must
+ * not, how it is checked today, what "worse" looks like. Rewording them would
+ * fork one interview into two that drift.
+ *
+ * The last one is the only thing the green set cannot supply, and it is not a
+ * flourish: `human-confirms` requires an `ask` — the question the signer answers
+ * at the end of the run — and nothing else in the interview names it. Without it
+ * the composer would have to invent what a person is deciding, which is the one
+ * thing a human stage must never have done for it. It is the SPREAD's next number
+ * rather than a fixed one, so a green-side deletion renumbers it instead of
+ * leaving a gap (it was 7 while the green set held six, and is 6 now it holds five).
+ */
+export const HITL_QUESTIONS = Object.freeze({
+  ...GREEN_QUESTIONS,
+  6: 'When you look at the finished result yourself, what are you deciding?',
 });
 
 /**
@@ -195,7 +237,11 @@ export const QUESTION_SETS = Object.freeze({
     required: Object.freeze(Object.keys(GREEN_QUESTIONS).map(Number).sort((a, b) => a - b)),
   }),
   'soft-green': Object.freeze({ locked: true, questions: null, required: null }),
-  hitl: Object.freeze({ locked: true, questions: null, required: null }),
+  hitl: Object.freeze({
+    locked: false,
+    questions: HITL_QUESTIONS,
+    required: Object.freeze(Object.keys(HITL_QUESTIONS).map(Number).sort((a, b) => a - b)),
+  }),
 });
 
 /**
@@ -214,7 +260,15 @@ export const CLASS_STATEMENTS = Object.freeze({
     + 'measurement of this repository. If part of what they asked for cannot be measured that way, leave it out and '
     + 'say so in your notes rather than approximating it with a stage that means something else.',
   'soft-green': null,
-  hitl: null,
+  // N4 slice 1. The mechanical-first composition law is stated as an ORDER
+  // because first-red-wins makes the order the mechanism: the cheap stages shield
+  // the expensive one, and the person is never the first filter.
+  hitl: 'The person declared this job HITL: a PERSON renders the final verdict, because their judgement is what '
+    + '"done" means here. Compose the mechanical part first — everything about this repository a command can decide '
+    + 'is still a mechanical stage, exactly as it would be for a green job — and put ONE human-confirms stage LAST, '
+    + 'carrying the question they answer when they look at the result. Never make the person the first filter: a '
+    + 'stage a command can render is never handed to them, and they are asked only once, at the end, about the part '
+    + 'no command can hold.',
 });
 
 /** @param {string} verdictType @returns {{locked: boolean, questions: any, required: any}} */
@@ -354,6 +408,12 @@ export const PARAM_SCHEMAS = Object.freeze({
   extensions: { type: 'array', minItems: 1, items: { type: 'string' } },
   allowPrefixes: { type: 'array', minItems: 1, items: { type: 'string' } },
   requireNonEmpty: { const: true },
+  ask: {
+    type: 'string',
+    minLength: 1,
+    description: 'the plain question the person answers while looking at the finished result. They see it verbatim, '
+      + 'so write what they are DECIDING — never a bare "approve?".',
+  },
 });
 
 /**
@@ -496,6 +556,60 @@ THE PARSER reads ONE number out of a command's output, as signed arithmetic over
               not actually happen.`;
 }
 
+/**
+ * HOW THE GENRE'S OWN TOOLS PRINT — rendered FROM `genreInstruments`, so the
+ * pattern the author is handed and the pattern the tree already grades with are
+ * one string.
+ *
+ * This block is the fix for run msmbpjk6: a parser for a tool WE OWN THE FACTS
+ * ABOUT was left to the model to compose, and it composed tsc's terminal-only
+ * shape against piped output — 0 matches on 67 real error lines. The delivery is
+ * deliberately the MANDATORY-GUARD delivery, not advice: the pattern arrives
+ * spelled out, marked genre property, with the real captured line beside it, in
+ * the same register as the guard battery that arrives already parameterised.
+ *
+ * It states the MECHANISM (pipe, not a terminal) rather than only the answer,
+ * because the same trap is waiting behind every tool that pretty-prints for a
+ * human, and only some of them are in the table yet. That prediction has since
+ * been paid off by measurement: `node --test` prints TAP down a pipe and the
+ * spec reporter on a terminal, the identical flip, on a second tool.
+ *
+ * Each row also carries its `capture`, because a count term and a tally term are
+ * read by DIFFERENT aggregates and the wrong pairing is a silent misreading, not
+ * an error — `first` over a line the tool omits on a good run reports a broken
+ * instrument. The block states that mapping once rather than per row.
+ * @param {string} lang
+ */
+export function instrumentsBlock(lang) {
+  const rows = genreInstruments(lang).map((i) => `- ${i.id} — ${i.what}\n`
+    + `    lineMatch: ${i.lineMatch}\n`
+    + `    capture: ${i.capture === null ? 'null' : i.capture}\n`
+    + `    a REAL captured line: ${i.example}\n`
+    + `    why this spelling: ${i.why}`);
+  return `KNOWN INSTRUMENTS — how this genre's own tools PRINT, fixed by the genre, not yours to decide
+
+A close captures output through a PIPE, never a terminal. Tools that pretty-print for a human
+print something else entirely down a pipe, and the piped shape is the only one a close ever reads.
+The patterns below are MEASURED against real captured output of this genre's tools.
+
+Where a stage of yours counts one of these, use its lineMatch EXACTLY as written — a pattern you
+compose yourself for one of these tools is a pattern for output that never arrives, and a term that
+matches nothing does not report a small number, it reports a broken instrument.
+
+Each row states its own capture, and that choice decides the aggregate:
+  capture: null   the term TALLIES one per matching line. Use aggregate "sum" — over no matching
+                  lines that is a legitimate counted zero.
+  capture: <n>    the term reads the FIGURE the tool printed, out of that group. Use aggregate
+                  "first" — and note that no match at all then means the tool never reported the
+                  number, which is a broken instrument, never a zero. A count is listed this way
+                  only where the tool prints the line even when the number is zero.
+
+${rows.join('\n\n')}
+
+This covers only the tools listed. For anything else, you still compose the pattern yourself from
+the facts object — and say in your notes when you had to.`;
+}
+
 /** The three laws. Stated to the author; enforced, where checkable, by M2. */
 export function lawsBlock() {
   return `THE LAWS YOUR DECLARATION MUST OBEY
@@ -611,6 +725,11 @@ measure anything.`;
       + 'This job\'s genre carries a fixed close SHAPE. The following policy is law for your declaration. It names\n'
       + 'no command, no path, no environment value and no pattern for this repository — finding those is your work,\n'
       + `from the facts object and the interview:\n\n${TYPES_GENRE_TEMPLATE}`,
+    // The template deliberately names no regex for this repository — but the
+    // shape a KNOWN tool prints is not "for this repository", it is a fact about
+    // an instrument the genre already owns and already grades with. It sits here,
+    // immediately after the policy that mandates the typecheck stage.
+    instrumentsBlock(lang),
     'MANDATORY GUARDS — already placed and already parameterised\n\n'
       + 'This kind of job carries stages the person did not ask for. They are fixed by the job\'s genre and they are\n'
       + 'already in your declaration, with their pattern battery and extensions already filled in — those are genre\n'
@@ -853,7 +972,19 @@ export function resolveSourcePrefixes({ workdir, sourcePaths, seedFiles }) {
  * run could not be read afterwards. A cost entry with no raw beside it is that
  * run again.
  */
-export function makeCostBook() {
+/**
+ * @param {{ceilingUsd?: number|null,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void}} [o]
+ *   `ceilingUsd` is the OPERATOR's ceiling; `null`/absent is UNBOUNDED.
+ *   `onCall` is a REPORTING seam fired as each metered call lands — the shell's
+ *   only chance to know what has been spent while the run is still alive. It is
+ *   never consulted and never governs: `capStop` below is still the one
+ *   predicate, still asked between calls, and still reads the same `entries`.
+ *   `absorb` deliberately does NOT fire it: those calls were metered (and
+ *   reported) by whoever made them, and reporting them twice would double the
+ *   scout's spend in every reader downstream.
+ */
+export function makeCostBook({ ceilingUsd = null, onCall = () => {} } = {}) {
   /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
   const entries = [];
   /** @type {ReturnType<typeof scrubRaw>[]} */
@@ -861,8 +992,10 @@ export function makeCostBook() {
   return {
     /** @param {string} label @param {any} r a bare-agent run result @param {number} [attempt] */
     add(label, r, attempt = 1) {
-      entries.push({ label, ...priceOf(r) });
+      const call = { label, ...priceOf(r) };
+      entries.push(call);
       raws.push(scrubRaw({ label, attempt, text: r?.text, reason: r?.error ? String(r.error) : null }));
+      onCall({ ...call });
       return entries.at(-1);
     },
     /** @param {{label: string, costUsd: number|null, unpricedRounds: number}[]} calls
@@ -872,19 +1005,19 @@ export function makeCostBook() {
      * `report().calls`, because both are readings of one list */
     raws() { return raws.map((w) => ({ ...w })); },
     report() {
-      const known = entries.reduce((a, e) => a + (typeof e.costUsd === 'number' ? e.costUsd : 0), 0);
-      const nullCostCalls = entries.filter((e) => e.costUsd === null).length;
-      const unpricedRounds = entries.reduce((a, e) => a + (e.unpricedRounds || 0), 0);
-      const spendComplete = nullCostCalls === 0 && unpricedRounds === 0;
-      return {
-        costUsd: spendComplete ? Number(known.toFixed(6)) : null,
-        knownUsd: Number(known.toFixed(6)),
-        spendComplete,
-        nullCostCalls,
-        unpricedRounds,
-        calls: entries.map((e) => ({ ...e })),
-      };
+      return { ...tallyCalls(entries), calls: entries.map((e) => ({ ...e })) };
     },
+    /**
+     * THE CEILING'S OWN READING, asked between metered calls. The book is the one
+     * place this pipeline's spend accumulates, so it is the one place that can
+     * answer honestly — and it answers through the shared predicate rather than a
+     * second hand-spelled comparison (`src/text.js`, beside `priceOf`).
+     * @returns {'cap-halt'|'pricing-red'|null}
+     */
+    capStop() { return capStop({ ceilingUsd, ...tallyCalls(entries) }); },
+    /** what was set, stated — `null` is "nobody set one", which is UNBOUNDED and
+     * a visible operator choice, never a defaulted number */
+    ceilingUsd,
   };
 }
 
@@ -939,6 +1072,16 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
   let red = null;
 
   for (let attempt = 0; attempt <= retries; attempt += 1) {
+    // THE CEILING, immediately before the paid call and nowhere else. Sited HERE
+    // rather than in the revise loop because this is where every declaration call
+    // is actually made: the author call, each revise, AND each malformed-emission
+    // retry. The retry axis is the one that matters most — it fires exactly when
+    // the model is malforming, which is the worst moment for a paid loop to be
+    // unbounded. `attempts` is returned as-is so the caller can tell a cap that
+    // tripped before this ask began (0) from one that cut a retry ladder short.
+    const halt = book.capStop();
+    if (halt) return { declaration: null, attempts, convo, raw: '', providerError: null, red: null, budget: halt };
+
     /** @type {{calls: any[]}} */
     const box = { calls: [] };
     const tools = mode === 'tool' ? [declarationTool(box, { catalogue })] : [];
@@ -948,11 +1091,11 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
     const raw = redactSecrets(String(r?.text ?? ''));
 
     if (r?.error) {
-      return { declaration: null, attempts, convo, raw, providerError: String(r.error), red: null };
+      return { declaration: null, attempts, convo, raw, providerError: String(r.error), red: null, budget: null };
     }
 
     if (mode === 'tool') {
-      if (box.calls.length === 1) return { declaration: box.calls[0], attempts, convo, raw, providerError: null, red: null };
+      if (box.calls.length === 1) return { declaration: box.calls[0], attempts, convo, raw, providerError: null, red: null, budget: null };
       red = {
         code: 'artifact-red',
         path: DECLARATION_TOOL_NAME,
@@ -966,7 +1109,7 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
       // parser, never a second one.
       const { code, red: extractRed } = extractArtifact(raw);
       if (code) {
-        try { return { declaration: JSON.parse(code), attempts, convo, raw, providerError: null, red: null }; }
+        try { return { declaration: JSON.parse(code), attempts, convo, raw, providerError: null, red: null, budget: null }; }
         catch (e) { red = { code: 'artifact-red', path: 'declaration', detail: `the declaration did not parse as JSON: ${String(/** @type {any} */ (e)?.message ?? e)}`, axis: 'unparseable-json' }; }
       } else {
         red = { code: 'artifact-red', path: 'declaration', detail: `no artifact in the reply: ${extractRed}`, axis: 'no-artifact' };
@@ -979,7 +1122,7 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
       convo.push({ role: 'user', content: `${block}\n\n${mode === 'tool' ? STRUCTURE_INSTRUCTION_TOOL : STRUCTURE_INSTRUCTION_TEXT}` });
     }
   }
-  return { declaration: null, attempts, convo, raw: '', providerError: null, red };
+  return { declaration: null, attempts, convo, raw: '', providerError: null, red, budget: null };
 }
 
 /**
@@ -1010,9 +1153,13 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
  *
  * @param {{workdir: string, seedRef: string, lang: string, verdictType: string,
  *   answers: Record<string|number, string>, questions?: Record<string|number, string>,
- *   scout: {state: string, facts: any, reason?: string|null, calls?: any[], raws?: any[]},
+ *   scout: {state: string, facts: any, reason?: string|null, cause?: string|null, calls?: any[], raws?: any[],
+ *     budgetStop?: 'cap-halt'|'pricing-red'|null},
  *   listing?: {stop: string|null, files: string[]|null, block: string|null, meta: any}|null,
  *   generate: Function, seedReadFn?: Function, closeCtx?: any,
+ *   ceilingUsd?: number|null,
+ *   onPhase?: (phase: string, data?: any) => void,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   maxRevisions?: number, structureRetries?: number,
  *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>}} o
  */
@@ -1021,6 +1168,12 @@ export async function authorClose({
   answers, questions = GREEN_QUESTIONS,
   scout, listing = null,
   generate, seedReadFn = runSeedReadStages, closeCtx = {},
+  ceilingUsd = null,
+  // The two REPORTING seams, defaulted to nothing so every existing caller is
+  // byte-identical. Neither is consulted: the revise ladder, the ceiling and the
+  // seed read all run exactly as they did — the shell is merely told, while the
+  // run is still alive, which of the up-to-15 silent minutes it is inside.
+  onPhase = () => {}, onCall = () => {},
   maxRevisions = MAX_REVISIONS,
   structureRetries = MAX_STRUCTURE_RETRIES,
   structuredMode = 'tool',
@@ -1039,7 +1192,13 @@ export async function authorClose({
   // ceiling. Floor 0, exactly as above: `askDeclaration` loops `attempt <= retries`,
   // so 0 is still ONE attempt with no retry — a legal tighter ask, not an absent one.
   const retryCap = Math.max(0, Math.min(Math.trunc(Number(structureRetries)) || 0, MAX_STRUCTURE_RETRIES));
-  const book = makeCostBook();
+  // THE OPERATOR'S CEILING — NO DEFAULT, and none is invented here. `null` means
+  // nobody set one, which is UNBOUNDED: a defaulted cap is a silent second
+  // ceiling, and the run path already paid for that lesson twice (`maxWallMs` has
+  // no default for exactly this reason, and `shellCapUsd` left off judged against
+  // a number nobody chose). An unbounded authoring run is legal; it is just never
+  // an accident, which is why the driver PRINTS it.
+  const book = makeCostBook({ ceilingUsd, onCall });
   // The scout's calls AND its raws, together. The raws matter most on the path
   // that spends nothing more: run mslhn707 refused at the $0 preflight below,
   // and the survey text that would have said WHY died with the process.
@@ -1057,6 +1216,40 @@ export async function authorClose({
   // special facts are needed". This one lands in a SIGNED artefact.
   if (scout?.state !== 'PRESENT' || !scout.facts || typeof scout.facts !== 'object'
       || Object.keys(scout.facts).length === 0) {
+    // A SURVEY THE CEILING STOPPED IS NOT A SURVEY THAT FAILED. The scout carries
+    // its own governance stop, and when it is set that is the honest name for why
+    // the facts are missing — the same rule W-2 settled for the clock (a time-stop
+    // is NAMED a time-stop). `scout-absent` sends the operator to the scout; a
+    // cap-halt sends them to the number they set, which is the one that moves.
+    if (scout?.budgetStop) {
+      // A CONCURRENT CAUSE IS CONCEDED, NEVER DENIED. The ceiling can refuse the
+      // reserved recovery round for a call that ALSO died on transport, and both
+      // are then true at once. "not on anything it read" would deny the very
+      // error the same sentence goes on to quote, and this red carries
+      // `path: budgetUsd` — so the operator is steered to raise a ceiling into a
+      // dead socket, which is the one lever that cannot repair it. The stop
+      // itself does not move: the ceiling did bind, and naming the second cause
+      // is attribution, not routing.
+      //
+      // The transport death is not the only second cause. The ceiling also
+      // refuses the recovery round behind a SHORT/EMPTY reply, and the retry
+      // behind an EMPTY/UNPARSEABLE one — every cause except NOT_FUNDED means a
+      // real call produced the reason being quoted, so "not on anything it
+      // read" is honest ONLY when no call was ever made.
+      const alsoDied = scout?.cause === SURVEY_CAUSES.CALL_FAILED;
+      const alsoIncomplete = !alsoDied && scout?.cause != null && scout.cause !== SURVEY_CAUSES.NOT_FUNDED;
+      return refuse([{
+        code: scout.budgetStop,
+        path: 'budgetUsd',
+        detail: alsoDied
+          ? 'the authoring ceiling bound here AND the survey call itself failed — both are true, and raising the '
+            + `ceiling will not repair the second: ${redactSecrets(String(scout.reason ?? ''))}`
+          : alsoIncomplete
+            ? 'the authoring ceiling bound here AND the survey came back incomplete — both are true: the ceiling '
+              + `refused the round that could have repaired it: ${redactSecrets(String(scout.reason ?? ''))}`
+            : `the survey stopped on the authoring ceiling, not on anything it read: ${redactSecrets(String(scout.reason ?? ''))}`,
+      }], scout.budgetStop);
+    }
     return refuse([{
       code: 'scout-absent',
       path: 'scout',
@@ -1158,12 +1351,60 @@ export async function authorClose({
   /** @type {{stage: string, name: string}[]} */
   let droppedEnv = [];
 
+  /**
+   * THE GOVERNANCE STOP'S OWN RED. It names the CAP and the SPEND, because the
+   * operator's next move is a NUMBER — resume-to-cap is the shipped lever (the
+   * stop IS the checkpoint), and a stop that reports neither side of the
+   * comparison cannot be acted on. It is a governance stop, never an error: the
+   * partial artifacts stay exactly where they are, nothing retries, and nothing
+   * about the close itself is being judged here.
+   * @param {'cap-halt'|'pricing-red'} code
+   * @returns {Red}
+   */
+  const capRed = (code) => {
+    const c = book.report();
+    const spent = `$${c.knownUsd.toFixed(6)} across ${c.calls.length} metered call(s)`;
+    return code === 'pricing-red'
+      ? {
+        code,
+        path: 'budgetUsd',
+        detail: `the authoring ceiling cannot be enforced: ${c.nullCostCalls} unpriced call(s) and ${c.unpricedRounds} `
+          + `unpriced round(s) make the total unknown, against a $${ceilingUsd} ceiling (${spent} is the KNOWN half). `
+          + 'Unpriced is never free (F6) — a cap that cannot see the spend cannot govern it, so the run stops rather '
+          + 'than spending against a floor that reads as exact.',
+      }
+      : {
+        code,
+        path: 'budgetUsd',
+        detail: `the authoring ceiling is spent: ${spent} against a $${ceilingUsd} ceiling. The next call was never `
+          + 'made — the cap binds BETWEEN calls, so nothing was cut off mid-flight and everything paid for is on '
+          + 'disk. The stop IS the checkpoint: raise the ceiling and re-run, or read what is here and stop.',
+      };
+  };
+
   const seedTrees = makeSeedTrees();
   try {
     for (let i = 0; i <= revisionCap; i += 1) {
       const label = i === 0 ? 'author' : `revise-${i}`;
+      // WHICH call, and how many the ladder may make. `of` is the ENFORCED cap
+      // (`revisionCap`, already clamped tighten-only) rather than the constant —
+      // a readout quoting a number the loop does not obey is a second
+      // instrument, and this file's own history is what that costs.
+      onPhase('author-call', { call: label, i, of: revisionCap });
       const ask = await askDeclaration({ messages, generate, mode: structuredMode, retries: retryCap, label, book, catalogue });
       messages = ask.convo;
+
+      // The cap tripped BEFORE this ask made any call at all, so there is no
+      // iteration to record: an iteration row for a call that never happened is
+      // the blind-instrument class one field wide (`ralph` already pays for the
+      // sibling of this — a governance stop narrated for a loop it never
+      // entered). A ladder cut SHORT is the other case and falls through: those
+      // calls did happen, so the row stays and the stop is read after it.
+      if (ask.budget && ask.attempts === 0) {
+        fatal = [capRed(ask.budget)];
+        stop = ask.budget;
+        break;
+      }
       /** @type {any} */
       const iter = {
         call: label, attempts: ask.attempts, declaration: ask.declaration ?? null,
@@ -1172,6 +1413,17 @@ export async function authorClose({
       };
       iterations.push(iter);
 
+      // A retry ladder cut short by the cap. The money stop OUTRANKS the artifact
+      // red that was in flight: the artifact red says the model malformed, the cap
+      // says we stopped paying to find out — and only the second one is why the
+      // loop ended. Reporting the first would send the operator to the model when
+      // the fact is the wallet.
+      if (ask.budget) {
+        fatal = [capRed(ask.budget)];
+        stop = ask.budget;
+        break;
+      }
+
       if (ask.providerError) {
         // a transport failure is a casualty, never evidence about the model — and
         // the transport's own prose (a proxy URL, an auth echo) is scrubbed on the
@@ -1225,7 +1477,20 @@ export async function authorClose({
         // `gapKeep` defaults to EMPTY rather than being left undefined: M1
         // prefixes every gap line with it verbatim, so an unset one prints the
         // word "undefined" on every failure line the model is asked to read
-        const rows = await seedReadFn(injected.declaration, { gapKeep: '', ...closeCtx, workdir, seedRef, seedTrees });
+        // THE LONG ONE. Every stage of the declaration spawns a real toolchain
+        // against the patient, so this single await is where a run spends
+        // minutes saying nothing — the per-stage line below is the whole point,
+        // and the block boundary is what makes it readable.
+        const stageCount = injected.declaration?.stages?.length ?? null;
+        onPhase('seed-read', { call: label, stages: stageCount });
+        // `onStage` sits AFTER the `closeCtx` spread beside `workdir`/`seedRef`:
+        // it is the runner's own reporting channel, not a knob a caller's close
+        // context may quietly redirect.
+        const rows = await seedReadFn(injected.declaration, {
+          gapKeep: '', ...closeCtx, workdir, seedRef, seedTrees,
+          onStage: (/** @type {any} */ row) => onPhase('stage', { call: label, ...row }),
+        });
+        onPhase('seed-read-done', { call: label, stages: stageCount });
         iter.seedRead = rows;
         accepted = injected.declaration;
         acceptedSeedRead = rows;