bareloop 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",
@@ -23,8 +23,8 @@
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.35.0",
-    "bareguard": "^0.12.0",
+    "bare-agent": "^0.36.0",
+    "bareguard": "^0.13.0",
     "litectx": "^0.32.0"
   },
   "devDependencies": {

package/src/authorflow.js

@@ -75,11 +75,12 @@
 import { createRequire } from 'node:module';
 import { realpathSync } from 'node:fs';
 import { join, relative, isAbsolute } from 'node:path';
-import { seedRead as runSeedReadStages, makeSeedTrees, AGGREGATES, SIGNS, MAX_TERMS } from './kinds.js';
+import { seedRead as runSeedReadStages, makeSeedTrees, AGGREGATES, SIGNS, MAX_TERMS, MAX_JUDGED_PATHS } from './kinds.js';
+import { JUDGE_RULE_IDS } from './judged.js';
 import {
   KIND_CATALOGUE, MAX_STAGES, DIRECTIONS, BASELINES,
   GENRE_LANGUAGES, TYPES_GENRE_TEMPLATE, classGuards, genreEnv, genreOwnedEnvNames, genreInstruments,
-  validateDeclaration, envCapableKind, VERDICT_CLASSES, LIVE_CLASSES,
+  validateDeclaration, envCapableKind, classMenu, VERDICT_CLASSES, LIVE_CLASSES,
 } from './authoring.js';
 import { buildSeedListing, cleanEntry, SURVEY_CAUSES } from './authorscout.js';
 import { extractArtifact, priceOf, scrubRaw, tallyCalls, capStop } from './text.js';
@@ -163,29 +164,107 @@ 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 three sets. `questions: null` on a locked class is ABSENT, never `{}`:
- * an empty set would read as "this class needs no questions", which is a
- * different and false statement (F59's distinction, at the interview layer).
- * Nothing ever reads them — a locked class refuses at ADMISSION, before its
- * questions run — and the two readers below throw rather than hand back nothing.
+ * 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?',
+});
+
+/**
+ * THE SOFTGREEN SET (module 3, design record §4.6) — the green questions BYTE
+ * FOR BYTE, plus TWO.
+ *
+ * Same discipline as the hitl set, and for the same reason: a softgreen close is
+ * *mechanical stages first, the judged stage after* (§4.5), so a softgreen job
+ * needs every mechanical fact a green one does. No renumbering of the green set,
+ * no genre question, nothing reworded.
+ *
+ * The two additions are the only things the green set cannot supply, and neither
+ * is a flourish — they are the judged floor's two REQUIRED inputs:
+ *   - Q6 becomes the RUBRIC CARD (§4.3): the person's own pass/fail lines,
+ *     compiled into enumerated items, signed, and enumerated in the spec hash.
+ *     The documented ceiling rides with it — the judge catches violations of
+ *     STATED card items only, and the fix for a miss is a new card line and a
+ *     re-sign, never a smarter judge.
+ *   - Q7 becomes the frozen CALIBRATION SET (§4.4): the whole pipe must grade it
+ *     correctly before the close is signable.
+ * Both are asked in the person's own terms — an example they would pass and one
+ * they would fail, not a rubric they are asked to write — because compiling a lay
+ * answer into extractable items is the LLM's job (D5, proposed-and-signed) and
+ * asking the person to do it is the SWE tax this product refuses.
+ *
+ * What the two answers COMPILE INTO is module 4. This module carries them
+ * exactly as the hitl set carries its own last answer: they ride in `answers`,
+ * they reach the composer verbatim through the prompt's interview block, and
+ * nothing here derives anything from them.
+ */
+export const SOFTGREEN_QUESTIONS = Object.freeze({
+  ...GREEN_QUESTIONS,
+  6: 'When you judge the result yourself, what separates a pass from a fail? Name the few things you actually look for.',
+  7: 'Give one example you\'d pass and one you\'d fail, and say why.',
+});
+
+/**
+ * The three sets, all LIVE as of softgreen module 3. The locked shape stays
+ * spelled out in the readers below rather than deleted with the last locked
+ * class: `questions: null` is ABSENT, never `{}` — an empty set would read as
+ * "this class needs no questions", a different and false statement (F59's
+ * distinction, at the interview layer) — and a locked class refuses at ADMISSION,
+ * before its questions run, so the two readers throw rather than hand back
+ * nothing. A fourth class arrives locked, and the machinery is here for it.
  * @type {Record<string, {locked: boolean, questions: Record<string|number, string>|null, required: readonly number[]|null}>}
  */
 export const QUESTION_SETS = Object.freeze({
@@ -194,8 +273,16 @@ export const QUESTION_SETS = Object.freeze({
     questions: GREEN_QUESTIONS,
     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 }),
+  'soft-green': Object.freeze({
+    locked: false,
+    questions: SOFTGREEN_QUESTIONS,
+    required: Object.freeze(Object.keys(SOFTGREEN_QUESTIONS).map(Number).sort((a, b) => a - b)),
+  }),
+  hitl: Object.freeze({
+    locked: false,
+    questions: HITL_QUESTIONS,
+    required: Object.freeze(Object.keys(HITL_QUESTIONS).map(Number).sort((a, b) => a - b)),
+  }),
 });
 
 /**
@@ -213,8 +300,27 @@ export const CLASS_STATEMENTS = Object.freeze({
     + 'to decide it — no judgement, no score, and no person in the loop. Every stage you compose is a mechanical '
     + '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,
+  // softgreen module 3. Stated as an ORDER for the same reason hitl's is: the
+  // close is first-red-wins, so the cheap mechanical stages shield the one stage
+  // that spends money, and the judge is never the first filter. The last sentence
+  // is the documented ceiling (§4.3) said to the composer in its own terms — the
+  // judge only ever checks lines the card names, so an unstated expectation is
+  // not a stricter judge, it is a line nobody wrote.
+  'soft-green': 'The person declared this job SOFT-GREEN: part of what "done" means here needs JUDGEMENT — reading '
+    + 'the result and deciding whether it is any good — and no command can render it. 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. Then put ONE judged-floor stage AFTER them, carrying the few things the person said they '
+    + 'actually look for and the real files the work lands in. A judged stage decides only the lines its card names, '
+    + 'so name each thing they look for as its own line, and leave nothing to be inferred.',
+  // 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 +460,45 @@ 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 },
+  // SOFTGREEN's two. `rule` is an ENUM off the judge's own rulebook — where only a
+  // closed set can satisfy a field, the illegal value is made inexpressible rather
+  // than rejected after the fact (`check-passes(name)`, again) — and `text` is the
+  // only free string, carrying the signer's words so a red can be explained in them.
+  card: {
+    type: 'object',
+    description: 'the rubric, as enumerated items: one line per thing the person actually looks for, in the order '
+      + 'they look for them. The rule is SELECTED from the arbiter\'s own rulebook; the text is theirs.',
+    properties: {
+      items: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          properties: {
+            rule: { enum: [...JUDGE_RULE_IDS], description: 'which owned rule this line asserts' },
+            text: { type: 'string', minLength: 1, description: 'what this line means, in the person\'s own words' },
+          },
+          required: ['rule', 'text'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['items'],
+    additionalProperties: false,
+  },
+  paths: {
+    type: 'array',
+    minItems: 1,
+    maxItems: MAX_JUDGED_PATHS,
+    items: { type: 'string' },
+    description: 'the AUTHORITATIVE artifacts to judge, repository-relative, read off the listing. One paid call each.',
+  },
+  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?".',
+  },
 });
 
 /**
@@ -391,19 +536,27 @@ export function schemaCoverage(catalogue = KIND_CATALOGUE) {
  * and they arrive as validation reds through the revise loop — a schema that
  * tried to restate them would be a second validator.
  *
+ * `verdictType` narrows the branches to the kinds the picked class may express
+ * (softgreen module 3, `classMenu`): a green job cannot SPELL `judged-floor`,
+ * rather than spelling it and being told afterwards. COVERAGE is still computed
+ * over the WHOLE catalogue — the class filter must never make a parameter look
+ * orphaned and turn a menu narrowing into a catalogue-drift alarm.
+ *
  * THROWS on a catalogue it cannot cover: a malformed catalogue is a bareloop bug,
  * and failing loudly beats emitting a schema that quietly cannot say something
  * the validator will then demand.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function declarationSchema(catalogue = KIND_CATALOGUE) {
+export function declarationSchema(catalogue = KIND_CATALOGUE, { verdictType = null } = {}) {
   const cov = schemaCoverage(catalogue);
   if (!cov.ok) {
     throw new Error('[authorflow] the declaration schema does not cover the catalogue — '
       + `missing: ${cov.missing.join(', ') || 'none'}; orphaned: ${cov.orphan.join(', ') || 'none'}`);
   }
+  const menu = classMenu(verdictType, catalogue);
   const branches = Object.entries(catalogue)
-    .filter(([, spec]) => !spec.locked)
+    .filter(([kind, spec]) => !spec.locked && menu.includes(kind))
     .map(([kind, spec]) => {
       /** @type {Record<string, any>} */
       const properties = {};
@@ -451,13 +604,13 @@ export function declarationSchema(catalogue = KIND_CATALOGUE) {
  * The output channel. It records and acknowledges; it takes no action, which is
  * why handing it to a toolless authoring call does not reopen D3.
  * @param {{calls: any[]}} box
- * @param {{catalogue?: Record<string, any>}} [o]
+ * @param {{catalogue?: Record<string, any>, verdictType?: string|null}} [o]
  */
-export function declarationTool(box, { catalogue = KIND_CATALOGUE } = {}) {
+export function declarationTool(box, { catalogue = KIND_CATALOGUE, verdictType = null } = {}) {
   return {
     name: DECLARATION_TOOL_NAME,
     description: 'Deliver the finished close. Call this exactly once, with the whole declaration as its arguments.',
-    parameters: declarationSchema(catalogue),
+    parameters: declarationSchema(catalogue, { verdictType }),
     execute: async (/** @type {any} */ args) => { box.calls.push(args); return DECLARATION_ACK; },
   };
 }
@@ -468,10 +621,19 @@ export function declarationTool(box, { catalogue = KIND_CATALOGUE } = {}) {
  * The catalogue, as the authoring call sees it — rendered FROM the catalogue, so
  * the prompt and the validator judge one set of facts. `shape` and `asserts` are
  * M2's own strings.
+ *
+ * `verdictType` narrows it to the picked class's menu, exactly as it narrows the
+ * schema — the prompt and the tool must offer ONE set of kinds, or the composer
+ * reads about a kind it cannot call. A kind above the ceiling is omitted rather
+ * than rendered as unavailable: a LOCKED row says "this does not run in v1",
+ * which is a fact about the build; "not for your class" is a fact about a choice
+ * the person already made, and printing it invites the composer to argue with it.
  * @param {Record<string, any>} [catalogue]
+ * @param {{verdictType?: string|null}} [o]
  */
-export function catalogueBlock(catalogue = KIND_CATALOGUE) {
-  const rows = Object.entries(catalogue).map(([name, spec]) => (spec.locked
+export function catalogueBlock(catalogue = KIND_CATALOGUE, { verdictType = null } = {}) {
+  const menu = classMenu(verdictType, catalogue);
+  const rows = Object.entries(catalogue).filter(([name]) => menu.includes(name)).map(([name, spec]) => (spec.locked
     ? `- ${name}  — LOCKED. Not available in v1; it will not run.`
     : `- ${name}\n    ${spec.shape}\n    required: ${spec.required.join(', ')}`
       + `${spec.optional.length ? `   optional: ${spec.optional.join(', ')}` : ''}\n    asserts: ${spec.asserts}`));
@@ -659,7 +821,9 @@ measure anything.`;
     `THE INTERVIEW — the person's own words\n\n${interview}`,
     `THE FACTS OBJECT — from a read-only survey of the repository\n\n${JSON.stringify(facts, null, 2)}`
       + (listingBlock ? `\n\n${listingBlock}` : ''),
-    catalogueBlock(catalogue),
+    // CLASS-SCOPED (softgreen module 3): the composer for a green job is never
+    // shown a kind whose pick would red as `class-ceiling` after the call.
+    catalogueBlock(catalogue, { verdictType }),
     lawsBlock(),
     `THE GENRE TEMPLATE — fixed by the job's genre (${lang}), not yours to decide\n\n`
       + 'This job\'s genre carries a fixed close SHAPE. The following policy is law for your declaration. It names\n'
@@ -912,8 +1076,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.
  */
-/** @param {{ceilingUsd?: number|null}} [o] the OPERATOR's ceiling; `null`/absent is UNBOUNDED */
-export function makeCostBook({ ceilingUsd = null } = {}) {
+/**
+ * @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>[]} */
@@ -921,8 +1096,10 @@ export function makeCostBook({ ceilingUsd = null } = {}) {
   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
@@ -985,13 +1162,23 @@ function canonical(x) {
 
 /**
  * ONE structured ask, with the malformed-emission retry bounded on its OWN axis.
- * A reply that carries no declaration is an ARTIFACT-RED — name the axis, retry
+ * A reply that carries no artifact is an ARTIFACT-RED — name the axis, retry
  * under a cap, write nothing — and it never consumes a revision, because a
  * transport fault is not a defect in a close.
+ *
+ * THE CHANNEL IS A PARAMETER, and that is softgreen module 4's only change here:
+ * the rubric card and the calibration set are a SECOND schema-forced emission
+ * with the same failure modes, and a second ladder is a second place for the cap,
+ * the reject block and the re-ask to drift. The declaration channel below is the
+ * one this loop has always used, spelled out rather than inlined — nothing about
+ * the authoring path's behaviour moves.
  * @param {{messages: any[], generate: Function, mode: 'tool'|'text', retries: number,
- *   label: string, book: ReturnType<typeof makeCostBook>, catalogue: Record<string, any>}} o
+ *   label: string, book: ReturnType<typeof makeCostBook>,
+ *   channel: {name: string, instruction: string, textPath?: string, tool: (box: {calls: any[]}) => any}}} o
+ * @returns {Promise<{artifact: any, attempts: number, convo: any[], raw: string,
+ *   providerError: string|null, red: Red|null, budget: 'cap-halt'|'pricing-red'|null}>}
  */
-async function askDeclaration({ messages, generate, mode, retries, label, book, catalogue }) {
+export async function askStructured({ messages, generate, mode, retries, label, book, channel }) {
   /** @type {any[]} */
   const convo = [...messages];
   let attempts = 0;
@@ -1007,49 +1194,78 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
     // 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 };
+    if (halt) return { artifact: null, attempts, convo, raw: '', providerError: null, red: null, budget: halt };
 
     /** @type {{calls: any[]}} */
     const box = { calls: [] };
-    const tools = mode === 'tool' ? [declarationTool(box, { catalogue })] : [];
+    // the tool's schema is CLASS-SCOPED, like the prompt's catalogue block: the
+    // two must offer one set of kinds, or the composer reads about a kind it
+    // cannot call — or worse, calls one the ceiling will refuse after we paid.
+    const tools = mode === 'tool' ? [channel.tool(box)] : [];
     const r = await generate(convo, tools, {});
     attempts += 1;
     book.add(attempt === 0 ? label : `${label}#${attempt + 1}`, r, attempts);
     const raw = redactSecrets(String(r?.text ?? ''));
 
     if (r?.error) {
-      return { declaration: null, attempts, convo, raw, providerError: String(r.error), red: null, budget: null };
+      return { artifact: 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, budget: null };
+      if (box.calls.length === 1) return { artifact: box.calls[0], attempts, convo, raw, providerError: null, red: null, budget: null };
       red = {
         code: 'artifact-red',
-        path: DECLARATION_TOOL_NAME,
+        path: channel.name,
         detail: box.calls.length === 0
-          ? `the reply delivered no ${DECLARATION_TOOL_NAME} call — structure is enforced, prose is never parsed`
-          : `the reply delivered ${box.calls.length} ${DECLARATION_TOOL_NAME} calls; exactly one declaration is expected`,
+          ? `the reply delivered no ${channel.name} call — structure is enforced, prose is never parsed`
+          : `the reply delivered ${box.calls.length} ${channel.name} calls; exactly one is expected`,
         axis: box.calls.length === 0 ? 'no-declaration-tool-call' : 'multiple-declaration-tool-calls',
       };
     } else {
       // THE FALLBACK PATH — providers without tool mode only. The ONE shipped
       // parser, never a second one.
+      const at = channel.textPath ?? channel.name;
       const { code, red: extractRed } = extractArtifact(raw);
       if (code) {
-        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' }; }
+        try { return { artifact: JSON.parse(code), attempts, convo, raw, providerError: null, red: null, budget: null }; }
+        catch (e) { red = { code: 'artifact-red', path: at, detail: `the ${at} 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' };
+        red = { code: 'artifact-red', path: at, detail: `no artifact in the reply: ${extractRed}`, axis: 'no-artifact' };
       }
     }
 
     if (attempt < retries) {
       const block = renderRejectBlock({ kind: 'artifact', reds: [/** @type {Red} */ (red).detail] });
       convo.push({ role: 'assistant', content: raw.trim() || '(the reply carried no text)' });
-      convo.push({ role: 'user', content: `${block}\n\n${mode === 'tool' ? STRUCTURE_INSTRUCTION_TOOL : STRUCTURE_INSTRUCTION_TEXT}` });
+      convo.push({ role: 'user', content: `${block}\n\n${mode === 'tool' ? channel.instruction : STRUCTURE_INSTRUCTION_TEXT}` });
     }
   }
-  return { declaration: null, attempts, convo, raw: '', providerError: null, red, budget: null };
+  return { artifact: null, attempts, convo, raw: '', providerError: null, red, budget: null };
+}
+
+/** THE DECLARATION CHANNEL — the one this loop has always used. Its schema is
+ * CLASS-SCOPED, like the prompt's catalogue block: the two must offer one set of
+ * kinds, or the composer reads about a kind it cannot call.
+ * @param {{catalogue: Record<string, any>, verdictType: string}} o */
+const declarationChannel = ({ catalogue, verdictType }) => ({
+  name: DECLARATION_TOOL_NAME,
+  instruction: STRUCTURE_INSTRUCTION_TOOL,
+  textPath: 'declaration',
+  tool: (/** @type {{calls: any[]}} */ box) => declarationTool(box, { catalogue, verdictType }),
+});
+
+/** The declaration ask, over the shared ladder. `declaration` is `artifact`
+ * under this channel's own name — the flow below reads a declaration, not an
+ * anonymous artifact, and one word for two things is how a reader loses which.
+ * @param {{messages: any[], generate: Function, mode: 'tool'|'text', retries: number,
+ *   label: string, book: ReturnType<typeof makeCostBook>, catalogue: Record<string, any>,
+ *   verdictType: string}} o
+ */
+async function askDeclaration({ messages, generate, mode, retries, label, book, catalogue, verdictType }) {
+  const r = await askStructured({
+    messages, generate, mode, retries, label, book, channel: declarationChannel({ catalogue, verdictType }),
+  });
+  return { ...r, declaration: r.artifact };
 }
 
 /**
@@ -1085,6 +1301,8 @@ async function askDeclaration({ messages, generate, mode, retries, label, book,
  *   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
  */
@@ -1094,6 +1312,11 @@ export async function authorClose({
   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',
@@ -1118,7 +1341,7 @@ export async function authorClose({
   // 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 });
+  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.
@@ -1306,7 +1529,12 @@ export async function authorClose({
   try {
     for (let i = 0; i <= revisionCap; i += 1) {
       const label = i === 0 ? 'author' : `revise-${i}`;
-      const ask = await askDeclaration({ messages, generate, mode: structuredMode, retries: retryCap, label, book, catalogue });
+      // 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, verdictType });
       messages = ask.convo;
 
       // The cap tripped BEFORE this ask made any call at all, so there is no
@@ -1392,7 +1620,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;