bareloop 0.9.0 → 0.11.0

package/src/authoring.js

@@ -94,9 +94,11 @@ import { isObj, isNonEmptyString, hasNestedQuantifier, globToPrefix } from './va
 
 /** the whole menu, in ascending order of what it takes to render the verdict */
 export const VERDICT_CLASSES = Object.freeze(['green', 'soft-green', 'hitl']);
-/** declared-but-locked: selecting one is COUNTED demand, never an admission */
-export const LOCKED_CLASSES = Object.freeze(['soft-green', 'hitl']);
-/** the classes v1 actually builds — exactly one */
+/** declared-but-locked: selecting one is COUNTED demand, never an admission.
+ * `hitl` LEFT this list at N4 slice 1 (see `src/job.js`'s twin) — the class is
+ * built, and its battery is below. `soft-green` waits for the judged floor. */
+export const LOCKED_CLASSES = Object.freeze(['soft-green']);
+/** the classes v1 actually builds */
 export const LIVE_CLASSES = Object.freeze(VERDICT_CLASSES.filter((c) => !LOCKED_CLASSES.includes(c)));
 
 /** the hierarchy as a comparable number. `green` is the FLOOR: a mechanical
@@ -237,11 +239,22 @@ export const KIND_CATALOGUE = Object.freeze({
     shape: 'LOCKED — not available in v1',
     asserts: 'a judged score must clear a floor. Declaring it is recorded as demand; it will not run.',
   }),
+  // LIVE at N4 slice 1, and the ONLY kind that does not measure anything: it
+  // does not RUN, it PAUSES the run and hands the tree to a person (ruling 1).
+  // `ask` is the whole parameter surface — no cmd, no timeoutMs, no env — so a
+  // human stage cannot spawn, cannot be env-capable, and cannot be given a
+  // second job. `offer` is never one of its fields either: ruling 5's law is a
+  // LAW, checked by the validator, not a knob the composer sets.
   'human-confirms': Object.freeze({
     verdictClass: 'hitl',
-    required: Object.freeze([]), optional: Object.freeze([]), pathParams: Object.freeze([]), locked: true,
-    shape: 'LOCKED — not available in v1',
-    asserts: 'a person renders the verdict. Declaring it is recorded as demand; it will not run.',
+    required: Object.freeze(['ask']),
+    optional: Object.freeze([]),
+    pathParams: Object.freeze([]),
+    shape: 'ask: string',
+    asserts: 'a PERSON renders this verdict, at the end of the run, and nothing about it is measured. Write `ask` as '
+      + 'the plain question they answer while looking at the finished result. It is always the LAST stage, it is '
+      + 'never offered to the agent as an in-run check, and every part of the job a command can decide belongs in a '
+      + 'mechanical stage before it.',
   }),
 });
 
@@ -417,6 +430,86 @@ export const TYPES_GENRE = Object.freeze({
       /** no import-resolution hazard on this runner — an EMPTY list, declared,
        * never an absent field that would read as "not looked into" (F59) */
       env: Object.freeze([]),
+      instruments: Object.freeze([
+        Object.freeze({
+          id: 'tsc-error-line',
+          what: 'one type error, as the TypeScript checker prints it',
+          lineMatch: 'error TS\\d+',
+          capture: null,
+          // REAL, from the captured `npm run typecheck -- --strict` of the pulselog
+          // patient (2026-08-09): 67 error lines, every one in this shape.
+          example: 'src/backup.js(21,19): error TS7006: Parameter \'now\' implicitly has an \'any\' type.',
+          why: 'tsc prints a DIFFERENT shape on a terminal (`src/backup.js:21:19 - error TS7006:`) than through a '
+            + 'pipe, and a close only ever reads the piped one. Run msmbpjk6 composed the terminal shape: it matched '
+            + '0 of 67 real error lines while the tool exited 2, so the stage read a crashed instrument. This pattern '
+            + 'is anchored on the CODE, not on the path spelling, so it reads both shapes and cannot lose that flip.',
+        }),
+        // ── node --test, the SAME pipe-vs-terminal trap, MEASURED ──────────────
+        //
+        // PROVENANCE, two independent halves.
+        //
+        // (1) REAL CAPTURED OUTPUT. The mailproof job-#2 battery's own spines carry
+        // whole `npm test` → `node --test` captures inside their `close-precheck`
+        // gap: `bareloop-patients/mailproof-job2-bareloop/battery-P1-mrm7gk25.jsonl`
+        // (`# tests 317` / `# pass 312` / `# fail 5`, five `not ok` lines) and
+        // `battery-P2-mrm7gk25.jsonl` (`# pass 316` / `# fail 1`). Nothing there was
+        // written to match a pattern — it is what the runner printed down the close's
+        // pipe, months before this table existed.
+        //
+        // (2) A SHIPPED, LIVE-FIRED SPELLING. `jobs/pulselog-author-types.json`
+        // already grades `^# pass (\d+)$` and `^# fail (\d+)$` (stages `tests-kept`
+        // and `test-suite-zero-failures`), and run msoc6t8v graded green through it.
+        // The table is not minting a new ruler; it is HANDING OVER the one the tree
+        // already grades with, the way the tsc term does.
+        //
+        // WHY IT IS THE TSC TRAP AGAIN, measured on this machine (node v22.22.2,
+        // one test file, identical args, 2026-08-13): through a PIPE the runner
+        // prints TAP — `TAP version 13`, `# pass 1`, `not ok 2 - b`; on a real pty it
+        // prints the spec reporter — `ℹ pass 1`, no `#`, no TAP at all. A close only
+        // ever reads the piped half, and a pattern composed against the pretty half
+        // matches nothing while the suite runs fine. Exactly what cost run msmbpjk6
+        // its authoring pass on tsc, waiting behind a second tool.
+        Object.freeze({
+          id: 'node-test-total-count',
+          what: 'how many tests the runner EXECUTED, off the TAP summary',
+          lineMatch: '^# tests (\\d+)$',
+          capture: 1,
+          example: '# tests 317',
+          why: 'the EXECUTED count is the honest denominator: a passed-count floor is satisfiable by a suite that '
+            + 'stopped running, so a stage asking "is the suite still whole?" counts this, not passes. Anchored '
+            + 'both ends because the runner prefixes ordinary chatter with the same `# ` (`# Subtest: <name>`), and '
+            + 'an unanchored `# tests` would count test NAMES.',
+        }),
+        Object.freeze({
+          id: 'node-test-pass-count',
+          what: 'how many tests passed, off the TAP summary',
+          lineMatch: '^# pass (\\d+)$',
+          capture: 1,
+          example: '# pass 316',
+          why: 'the spelling `jobs/pulselog-author-types.json` already grades with, green through run msoc6t8v. '
+            + 'The runner prints this line on a green run too, so a zero here is a REPORTED zero.',
+        }),
+        Object.freeze({
+          id: 'node-test-fail-count',
+          what: 'how many tests failed, off the TAP summary',
+          lineMatch: '^# fail (\\d+)$',
+          capture: 1,
+          example: '# fail 1',
+          why: 'this runner prints every counter on every run — a fully green suite still prints `# fail 0` '
+            + '(measured), so reading the figure cannot confuse "no failures" with "never reported". Its pytest '
+            + 'counterpart has no such guarantee, which is why python has no fail-COUNT term.',
+        }),
+        Object.freeze({
+          id: 'node-test-failed-line',
+          what: 'one failing test, as the TAP reporter names it',
+          lineMatch: '^not ok \\d+ ',
+          capture: null,
+          example: 'not ok 7 - edit-renotify: a non-participant edit, and edits on a pending event, ping no one',
+          why: 'one line per failing test, so it TALLIES and no match is a genuine counted zero. The trailing '
+            + 'space and the `^` both carry weight: every passing test prints `ok 7 - …`, and without the anchor '
+            + 'each of those would count as a failure.',
+        }),
+      ]),
     }),
     python: Object.freeze({
       suppressions: Object.freeze([
@@ -437,6 +530,58 @@ export const TYPES_GENRE = Object.freeze({
             + 'found by probe). It moves no seed number, so no seed-verdict read can see its absence.',
         }),
       ]),
+      instruments: Object.freeze([
+        Object.freeze({
+          id: 'mypy-error-line',
+          what: 'one type error, as mypy prints it',
+          lineMatch: ' error: ',
+          capture: null,
+          // REAL, from a live aurora run's own spine
+          // (bareloop-patients/aurora-u-bareloop/u-ms2c0ls7.jsonl).
+          example: 'packages/spawner/src/aurora_spawner/timeout_policy.py:89: error: Statement is unreachable  [unreachable]',
+          why: 'the operator\'s own hand-written close reads mypy this way (scripts/u-spawner-close.mjs:133), minted '
+            + 'by paid live runs. It is anchored on the SEVERITY word, not on the path spelling, so a relative or '
+            + 'absolute path, a package prefix or a config-driven root all read the same.',
+        }),
+        // ── pytest, from the aurora battery's own captured runs ────────────────
+        //
+        // PROVENANCE: six `close-precheck` gaps in
+        // `bareloop-patients/aurora-soar-bareloop/battery-A{1..4}-*.jsonl` carry the
+        // whole captured pytest run of the aurora patient (pytest 9.1.1, python
+        // 3.14.6, the patient's own `pytest.ini` addopts, which include `-ra`) —
+        // 2,690-odd tests, the `short test summary info` section and the final counts
+        // line. Real, uncrafted, paid for.
+        //
+        // WHAT IS NOT ANCHORED, and why. Every archived counts line arrives padded
+        // with `=` on both sides, and the padding WIDTH is terminal-derived: the
+        // archived long line gets exactly one `=` per side, a short local run gets
+        // twenty-five (measured, pytest 9.0.2, 2026-08-13). Under `-q` the padding is
+        // absent entirely. So the term anchors on the WORD and its number, never on
+        // the decoration — the same discipline as anchoring tsc on the code rather
+        // than the path.
+        Object.freeze({
+          id: 'pytest-pass-count',
+          what: 'how many tests passed, off pytest\'s final counts line',
+          lineMatch: '(\\d+) passed',
+          capture: 1,
+          example: '= 1 failed, 2690 passed, 3 skipped, 18 deselected, 1775 warnings in 326.12s (0:05:26) =',
+          why: 'the ONE segment of this line pytest prints whether the run was green or red, so it is the only '
+            + 'count on it that can be read as a figure without risking "never reported". The other segments '
+            + '(failed, skipped, deselected) are omitted when their count is zero — a green run prints just '
+            + '`1 passed in 0.04s` (measured) — so a term reading THOSE would go silent exactly when the news is '
+            + 'good, and a silent figure term is a broken instrument, not a zero.',
+        }),
+        Object.freeze({
+          id: 'pytest-failed-line',
+          what: 'one failing test, as pytest\'s short summary names it',
+          lineMatch: '^FAILED ',
+          capture: null,
+          example: 'FAILED packages/soar/tests/test_agent_registry_deprecation.py::TestAgentRegistryDeprecation::test_registry_and_discovery_equivalent_results',
+          why: 'this is how you count pytest FAILURES: exactly one line per failing test (measured under both `-ra` '
+            + 'and `-q`), so it TALLIES and no match at all is a legitimate counted zero rather than an unreported '
+            + 'number. It needs pytest\'s short summary section, which the patient\'s own config must not suppress.',
+        }),
+      ]),
     }),
   }),
 });
@@ -481,30 +626,40 @@ function language(lang) {
  * than hand back nothing if anything ever does.
  * @type {Record<string, {locked: boolean, guards: readonly any[]|null}>}
  */
-export const CLASS_BATTERIES = Object.freeze({
-  green: Object.freeze({
-    locked: false,
-    guards: Object.freeze([
-      Object.freeze({
-        name: 'changed-from-seed',
-        kind: 'files-changed',
-        params: Object.freeze({ requireNonEmpty: true }),
-        compose: Object.freeze([]),
-        fill: Object.freeze(['allowPrefixes']),
-      }),
-      Object.freeze({
-        name: 'no-suppressions',
-        kind: 'pattern-absent-in-diff',
-        // NO scope: the scan covers every changed file of these extensions. A
-        // narrowing here is the round-3 arm A defect and is a red, not a taste.
-        params: Object.freeze({}),
-        compose: Object.freeze(['patterns', 'extensions']),
-        fill: Object.freeze([]),
-      }),
-    ]),
+/** THE MECHANICAL BATTERY — the two guards a machine can always render, named
+ * once because TWO classes carry exactly them (OPEN-1's ruling below). It is
+ * shared by reference and never mutated: `classGuards` deep-copies before it
+ * hands anything back, so one battery cannot be weakened through another class. */
+const MECHANICAL_GUARDS = Object.freeze([
+  Object.freeze({
+    name: 'changed-from-seed',
+    kind: 'files-changed',
+    params: Object.freeze({ requireNonEmpty: true }),
+    compose: Object.freeze([]),
+    fill: Object.freeze(['allowPrefixes']),
+  }),
+  Object.freeze({
+    name: 'no-suppressions',
+    kind: 'pattern-absent-in-diff',
+    // NO scope: the scan covers every changed file of these extensions. A
+    // narrowing here is the round-3 arm A defect and is a red, not a taste.
+    params: Object.freeze({}),
+    compose: Object.freeze(['patterns', 'extensions']),
+    fill: Object.freeze([]),
   }),
+]);
+
+export const CLASS_BATTERIES = Object.freeze({
+  green: Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
   'soft-green': Object.freeze({ locked: true, guards: null }),
-  hitl: Object.freeze({ locked: true, guards: null }),
+  // OPEN-1, RULED (hamr, in-turn, 2026-08-13): **hitl inherits the green
+  // mechanical guards and adds nothing a human stage cannot see.** D5 makes the
+  // battery mandatory, shown-and-fixed and un-removable, and PRD v1.57 §2 keys it
+  // to the CLASS; the mechanical-first composition law makes every hitl close
+  // mostly mechanical anyway, so the green battery is the right FLOOR. A guard a
+  // person cannot verify by looking would be a guard nobody checks — the one
+  // thing D5 exists to make unsayable.
+  hitl: Object.freeze({ locked: false, guards: MECHANICAL_GUARDS }),
 });
 
 /**
@@ -599,6 +754,64 @@ export function genreOwnedEnvNames(lang) {
   return language(lang).env.map((/** @type {any} */ e) => e.name);
 }
 
+/**
+ * HOW THE GENRE'S OWN TOOLS PRINT — genre property, like the suppression battery
+ * and like `MYPYPATH`, and for the same reason: it is a FACT ABOUT AN INSTRUMENT
+ * WE ALREADY OWN, not a composition choice. Seven hand-written closes read tsc
+ * with the identical `/error TS\d+/` (`scripts/u-pulselog-close.mjs:122`,
+ * `u-bareguard-close.mjs:123`, `u-bareagent-close.mjs:123`,
+ * `u-baremobile-close.mjs:122`, `u-litectx-close.mjs:140`, `types-close.mjs:190`,
+ * `types-check.mjs:60`) and one reads mypy with `' error: '`
+ * (`u-spawner-close.mjs:133`) — the same provenance the SUPPRESSIONS table has:
+ * operator knowledge minted by paying for live runs.
+ *
+ * WHY IT BECAME GENRE DATA (run msmbpjk6, 2026-08-09, $0.43). Left to the model,
+ * the parser for a known tool is a DRAFT-TIME LOTTERY on a fact nobody needed to
+ * guess: that run composed tsc's TTY-only pretty shape
+ * (`^\S+\.js:\d+:\d+ - error TS\d+:`), which matched 0 of the 67 real error lines
+ * the piped run actually printed, while the tool exited 2. The gates held — the
+ * stage read as a crashed instrument and signing was refused, correctly — but the
+ * refusal cost a whole authoring run to learn something the tree already knew. An
+ * earlier run (mslwbkz7) happened to roll the right shape. A coin-flip on an
+ * owned fact is not a capability question.
+ *
+ * WHAT THIS IS NOT: it does not close the parser. A stage counting something we
+ * have NOT measured still writes its own pattern, and that remains a real gap —
+ * named, not smoothed. This table is where a measured instrument fact lands, one
+ * at a time, with its provenance.
+ *
+ * THE TEST-COUNT FACTS (2026-08-13) landed under exactly that rule, and closed
+ * two of the three gaps the paragraph above used to name by hand: the executed
+ * count and the failure line, for both runners, are now measured facts rather
+ * than draft-time lotteries. Provenance rides on each entry.
+ *
+ * WHAT STAYED OUT, deliberately, because no evidence covers it:
+ *  - a pytest FAIL-COUNT figure. A green pytest run omits the segment entirely
+ *    (`1 passed in 0.04s`), so a figure term over it reports "never reported" on
+ *    precisely the runs that went well. Failures are counted with the `^FAILED `
+ *    tally instead, where no match IS zero.
+ *  - a pytest EXECUTED count. `collected N items` is printed under `-ra` and NOT
+ *    under `-q` (measured both ways), so no single spelling survives the modes a
+ *    patient may configure; a stage needing it still composes its own and says so.
+ *
+ * Returns a fresh copy per call, for the reason `classGuards` does: a frozen
+ * constant handed to a caller that edits it is one shared table away from a
+ * silently changed ruler.
+ * @param {string} lang
+ * @returns {{id: string, what: string, lineMatch: string, capture: number|null, example: string, why: string}[]}
+ */
+export function genreInstruments(lang) {
+  const instruments = language(lang).instruments ?? [];
+  // F59's shape at a table that feeds a RULER: an empty list would read as "this
+  // language's tools need no stated format", which is exactly the sentence that
+  // put the pretty-format regex into a signed-close candidate.
+  if (!instruments.length) {
+    throw new Error(`no known-instrument formats for language "${lang}" — a language the genre admits states how its `
+      + 'own checker prints, or the model is back to guessing a fact we already own');
+  }
+  return instruments.map((/** @type {any} */ i) => ({ ...i }));
+}
+
 /**
  * GROUNDING for a RECORDED genre environment — the provenance half of the
  * owned-env rule, and the reason the by-value comparison is worth anything.
@@ -735,7 +948,12 @@ function scopeOfJob(declaration, idx, guards) {
  * stage — applied to the one population that decides whether the law fires at
  * all.
  */
-const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed']);
+const AT_MOST_ONCE_KINDS = Object.freeze(['files-changed', 'human-confirms']);
+
+/** the kinds NO ONE runs as an in-run ruler — ruling 5's law, as data. A
+ * declaration that offers one is a red rather than a normalization: the signer
+ * must not read one thing and have the runner store another. */
+export const NEVER_OFFERED_KINDS = Object.freeze(['human-confirms', 'judged-floor']);
 
 /** @param {any} v */
 const strArray = (v) => Array.isArray(v) && v.length > 0 && v.every(isNonEmptyString);
@@ -938,13 +1156,43 @@ export function validateDeclaration(declaration, opts = {}) {
     if (AT_MOST_ONCE_KINDS.includes(s.kind)) {
       const owner = kindOwners.get(s.kind);
       if (owner !== undefined) {
-        red('duplicate-kind', `${at}.kind`, `stage "${label}" is a second ${s.kind} stage — "${owner}" already declares `
-          + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
-          + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
-          + 'second answer to what this job\'s scope IS', { kind: s.kind, stage: label, twin: owner });
+        red('duplicate-kind', `${at}.kind`, s.kind === 'human-confirms'
+          ? `stage "${label}" is a second ${s.kind} stage — "${owner}" already asks the person. One signer, one judge `
+            + '(ruling 4), asked ONCE at the end: a second door is a second verdict, and the run has no way to say '
+            + 'which of them was the one it stopped for'
+          : `stage "${label}" is a second ${s.kind} stage — "${owner}" already declares `
+            + 'which files this job may change. Stages are ANDed, so two of them mean the intersection of two prefix sets, '
+            + 'which is itself a prefix set and already says the same thing in one stage; what a second one does add is a '
+            + 'second answer to what this job\'s scope IS', { kind: s.kind, stage: label, twin: owner });
       } else kindOwners.set(s.kind, label);
     }
 
+    // ── RULING 5, AS LAW: judged and human stages are `offer: false`, and the
+    // law is checked rather than applied. `checkMenu` filters `offer !== false`,
+    // so a declaration that says nothing is silent about a rule the runner
+    // enforces anyway (`declaredStages` stamps it) — that part is the arbiter's
+    // own bookkeeping. What must never happen is a declaration that says
+    // something ELSE: `offer: true` on a human stage is the composer asking to
+    // use a person as an in-run ruler, and a silent normalization would leave
+    // the signer reading one thing while the runner stored another.
+    if (NEVER_OFFERED_KINDS.includes(s.kind) && Object.hasOwn(s, 'offer') && s.offer !== false) {
+      red('human-stage-offered', `${at}.offer`, `stage "${label}" is a ${s.kind} stage and offers itself as an in-run `
+        + 'check. A person (or a paid judge) is never an in-run ruler (ruling 5): the agent may never use one to '
+        + 'decide a step, and this is refused rather than quietly rewritten to offer: false',
+      { kind: s.kind, stage: label });
+    }
+    // ── THE COMPOSITION LAW's ordering half (2026-08-07: *mechanical first,
+    // judge minimal, human LAST*), enforced where it is cheap. First-red-wins
+    // means anything after the human stage never runs — so a human stage in the
+    // middle silently deletes the mechanical stages behind it AND empties the
+    // evidence package ruling 2 requires the person to be shown.
+    if (s.kind === 'human-confirms' && i !== stages.length - 1) {
+      red('human-stage-not-last', `${at}.kind`, `stage "${label}" asks a person and is not the LAST stage. The close `
+        + 'is first-red-wins, so every stage after this one would never run: the person would be shown an incomplete '
+        + 'evidence package and the mechanical stages behind them would be silently deleted (the composition law: '
+        + 'mechanical first, human last)', { kind: s.kind, stage: label, at: i, last: stages.length - 1 });
+    }
+
     const p = s.params;
     if (!isObj(p)) { red('missing-field', `${at}.params`, `an object carrying: ${spec.required.join(', ')}`); return; }
     for (const k of spec.required) {
@@ -1148,6 +1396,15 @@ function checkKind({ kind, params: p, at, red, scoped, label, populations, envOw
       if (!strArray(p.allowPrefixes)) red('invalid-value', `${at}.params.allowPrefixes`, 'a non-empty array of path prefixes');
       if (p.requireNonEmpty !== true) red('invalid-value', `${at}.params.requireNonEmpty`, 'literally true');
       break;
+    case 'human-confirms':
+      // the whole surface: the question the signer answers. It is shown to a
+      // person verbatim, so an empty one is a bare "approve?" — ruling 2's
+      // named failure mode, refused here rather than rendered.
+      if (!isNonEmptyString(p.ask)) {
+        red('invalid-value', `${at}.params.ask`, 'the plain question the signer answers while looking at the finished '
+          + 'result — a human stage with nothing to ask is the bare "approve?" ruling 2 forbids');
+      }
+      break;
     default:
       red('unknown-kind', `${at}.kind`, `"${kind}" is in the catalogue but has no checker`, { kind });
   }

package/src/authorjob.js

@@ -96,7 +96,7 @@ import {
   GENRE_LANGUAGES, LOCKED_KINDS, TYPES_GENRE, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES,
 } from './authoring.js';
 import { QUESTION_SETS, questionsFor, requiredAnswersFor, authorClose } from './authorflow.js';
-import { runAuthorScout, buildSeedListing } from './authorscout.js';
+import { runAuthorScout, buildSeedListing, SCOUT_ATTEMPTS } from './authorscout.js';
 import {
   DECLARED_GAP_PREFIX, DECLARED_GENRES, guardNames, isDeclaredClose, validateCloseDecl,
 } from './declaredclose.js';
@@ -365,7 +365,9 @@ function composerRefusal(reds) {
  * @param {{answers: Record<string|number, any>, repoPath?: string|null, lang: string,
  *   verdictType?: string|null,
  *   questions?: Record<string|number, string>|null, generate?: Function, provider?: any,
- *   seedRef?: string|null, scout?: any, listing?: any,
+ *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null,
+ *   onPhase?: (phase: string, data?: any) => void,
+ *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
  *   authorFn?: Function, authorOpts?: object}} o
  * @returns {Promise<{ok: boolean, refusal: Refusal|null, verdictType: string|null,
@@ -375,6 +377,14 @@ function composerRefusal(reds) {
 export async function authorCloseForJob({
   answers, repoPath = null, lang, verdictType = null, questions = null,
   generate, provider = null, seedRef = null, scout = null, listing = null,
+  ceilingUsd = null,
+  // THE PROGRESS SEAMS. This composition is the pipeline's long silence — a real
+  // survey, a real declaration ladder, and a real toolchain per close stage — and
+  // it emitted nothing until it returned, so an operator watching a live run
+  // could not tell work from a hang. The library REPORTS and the shell PRINTS
+  // (`runJob`'s `emit` → `runPlan`, the same shape): nothing here reads either
+  // callback back, and no decision in this file or below it depends on one.
+  onPhase = () => {}, onCall = () => {},
   seedFn = seedAtHead, scoutFn = runAuthorScout, listingFn = buildSeedListing,
   authorFn = authorClose, authorOpts = {},
 }) {
@@ -424,6 +434,10 @@ export async function authorCloseForJob({
   // D8 — the seed, READ rather than typed.
   let seed = seedRef;
   if (!isNonEmptyString(seed)) {
+    // Announced only on the path that actually READS one: a caller who handed a
+    // seedRef in never paid for a git call, and a phase line for work nobody did
+    // is the blind-instrument class, one line wide.
+    onPhase('seed', {});
     const s = await seedFn(workdir);
     if (s.stop !== null) {
       // same git-stderr channel as `prepareSigning`'s, scrubbed at the same
@@ -437,15 +451,53 @@ export async function authorCloseForJob({
   // D11 — the scout LOOKS, the author WRITES, neither acts. An ABSENT survey is
   // never "no special facts are needed" (F59), and `authorClose` refuses on it at
   // $0, so nothing here has to second-guess the classification.
-  const survey = scout ?? await scoutFn({ workdir, provider });
-  const seeds = listing ?? await listingFn({
-    workdir, seedRef: seed, sourcePaths: survey?.facts?.sourcePaths, testPaths: survey?.facts?.testPaths,
-  });
+  // ONE CEILING, BOTH PAID SEAMS. The survey and the declaration loop are two
+  // populations of paid call with two accumulators, and the operator set ONE
+  // number: handing it to both is what makes the advertised ceiling and the
+  // enforced ceiling the same ceiling (the standing hard line, in its money
+  // form). `null` travels EXPLICITLY rather than being left off — unbounded is a
+  // stated operator choice, and an absent field read as falsy is the same state
+  // arrived at by accident.
+  /** @type {any} */
+  let survey = scout;
+  // `== null` and not `!survey`: this is the `??` these two lines replaced, kept
+  // exactly — a caller-supplied survey is used whatever it is, and only an
+  // ABSENT one is paid for.
+  if (survey == null) {
+    // The scout is the pipeline's FIRST paid stage and its longest single
+    // silence: up to three ladder attempts, each a real toolable survey over a
+    // real tree. `attempts` is the ceiling the scout enforces on itself, so the
+    // reader knows how many the line could repeat for.
+    onPhase('scout', { attempts: SCOUT_ATTEMPTS });
+    survey = await scoutFn({ workdir, provider, ceilingUsd, onCall });
+    // …and the survey's own VERDICT, said the moment it lands. `state` is what
+    // every downstream refusal keys on (F59: absent is never "no facts needed"),
+    // and the fact count is the one number that says whether the ladder came
+    // back with anything to author from.
+    onPhase('scout-done', { state: survey?.state ?? null, facts: Object.keys(survey?.facts ?? {}).length });
+  }
+  /** @type {any} */
+  let seeds = listing;
+  if (seeds == null) {
+    onPhase('listing', {});
+    seeds = await listingFn({
+      workdir, seedRef: seed, sourcePaths: survey?.facts?.sourcePaths, testPaths: survey?.facts?.testPaths,
+    });
+    // the count is only knowable AFTER, so it rides the done line rather than
+    // being guessed onto the start one
+    onPhase('listing-done', { files: seeds?.files?.length ?? null, stop: seeds?.stop ?? null });
+  }
 
+  // The declaration ladder. The REVISION CAP is deliberately not quoted here:
+  // the tighten-only clamp lives in `authorClose` (and `authorOpts` may lower
+  // it), so a number spelled at this call site could disagree with the one the
+  // loop obeys — `author-call` carries the enforced cap instead, from where it
+  // is computed.
+  onPhase('author', {});
   const authored = await authorFn({
     workdir, seedRef: seed, lang, verdictType: picked,
     answers: interview.answers, questions: questions ?? questionsFor(picked),
-    scout: survey, listing: seeds, generate, ...authorOpts,
+    scout: survey, listing: seeds, generate, ceilingUsd, onPhase, onCall, ...authorOpts,
   });
 
   if (!authored.ok) {