bareloop 0.9.0 → 0.10.0

package/bareloop.context.md

@@ -294,6 +294,14 @@ N−1 are enforced only at the close, at the end of the run. That is a COST shap
 hole — the close still refuses a tree that fails any stage, and nothing green is minted mid-run
 — but a stage first tested at the tail is a stage the run pays full price to discover.
 
+**The ceiling of 2 is RULED, not provisional (2026-08-13, PRD v1.63 §3).** One check per write
+step is the contract: a step passing its own in-run check is never a verdict, only the close is
+truth, and widening the ceiling so a step's own gate could approximate the close would move
+judgement into the part the agent authors. Plan around one check; do not plan for a second one
+arriving. It is raised only on a demonstrated starvation case (a real run where a step provably
+cannot express its progress gate within one check and stalls for it), never for wording comfort,
+and the change is the operator's — arbiter territory.
+
 Red vocabulary (both validators): `parse-error`, `unknown-field`, `missing-required`,
 `invalid-value`, `bounds`, `duplicate-id`, `close-type`, `close-hierarchy`,
 `secret-literal`, `scope-escape`,
@@ -480,10 +488,10 @@ a step, or test it without a provider.
 | step | call | what it is |
 |---|---|---|
 | interview | `runInterview({ verdictType, answers, repoPath })` → `{ ok, answers, verdictType, refusal, reds }` | PURE — no model, no repo, no clock. THREE frozen question sets keyed by verdict class (`QUESTION_SETS`; `questionsFor(cls)` / `requiredAnswersFor(cls)`), and the interview asks NOTHING about a genre. The green set is six questions, answers keyed by number; the soft-green and hitl sets are named but LOCKED (`questions: null`, absent rather than empty) and their selection refuses before they run. `verdictType` and `repoPath` are STRUCTURED input, never parsed out of prose. Answers are scrubbed at INGEST |
-| survey | `runAuthorScout({ workdir, provider, attempts? })` → `{ state, facts, reason, meta, raw, raws, calls }` | a bounded READ-ONLY LLM survey. Read-only by MENU CONSTRUCTION (`AUTHOR_SCOUT_VERBS` = the full menu minus write-class and store-class verbs), 8 rounds, F59's reserved toolless final round. **`state: 'ABSENT'` means the scout did not complete — never "no special facts are needed"**, and a parsed `{}` is one of its five ABSENT routes. Up to `SCOUT_ATTEMPTS` (**3**, hardcoded — PRD v1.58) attempts: `attempts` is TIGHTEN-ONLY and CLAMPS rather than throws (floor **1**, because a scout that never ran is an ABSENT nobody can act on), the direction every cap in this system runs in. **A retry fires on the typed MALFORMED class alone** (`SCOUT_RETRY_CAUSES` = `empty` \| `unparseable`); what is excluded is excluded for a reason — `call-failed` covers transport and `truncated:max_tokens`, both provider-red with NO redraft; `short` is F59's cut-off population and already has its own instrument INSIDE the attempt; `non-object` and `empty-object` are valid JSON with wrong or vacuous content, which is a SEMANTIC failure, and F38/F39 measured what re-asking one buys (the same distribution, sampled twice) — that is the self-healing line, and it is not crossed here. The re-ask is TOOLLESS over the conversation the survey already produced (the repository was already read; only the emission was unreadable) and names the mechanical parse error and nothing else. **There is no JSON repair behind it and there never will be** — a repairer decides what the model MEANT and writes it down as though the model had said it, in the one artefact whose whole job is to be honest about what a repository contains. `meta.attempts` / `meta.attemptsAllowed` record what was paid for; every attempt is metered under its own label (`author-scout`, `author-scout#2`, …) and leaves its raw behind |
+| survey | `runAuthorScout({ workdir, provider, attempts?, ceilingUsd? })` → `{ state, facts, reason, meta, raw, raws, calls, budgetStop }` | a bounded READ-ONLY LLM survey. Read-only by MENU CONSTRUCTION (`AUTHOR_SCOUT_VERBS` = the full menu minus write-class and store-class verbs), 8 rounds, F59's reserved toolless final round. **`state: 'ABSENT'` means the scout did not complete — never "no special facts are needed"**, and a parsed `{}` is one of its five ABSENT routes. Up to `SCOUT_ATTEMPTS` (**3**, hardcoded — PRD v1.58) attempts: `attempts` is TIGHTEN-ONLY and CLAMPS rather than throws (floor **1**, because a scout that never ran is an ABSENT nobody can act on), the direction every cap in this system runs in. **A retry fires on the typed MALFORMED class alone** (`SCOUT_RETRY_CAUSES` = `empty` \| `unparseable`); what is excluded is excluded for a reason — `call-failed` covers transport and `truncated:max_tokens`, both provider-red with NO redraft; `short` is F59's cut-off population and already has its own instrument INSIDE the attempt; `non-object` and `empty-object` are valid JSON with wrong or vacuous content, which is a SEMANTIC failure, and F38/F39 measured what re-asking one buys (the same distribution, sampled twice) — that is the self-healing line, and it is not crossed here. The re-ask is TOOLLESS over the conversation the survey already produced (the repository was already read; only the emission was unreadable) and names the mechanical parse error and nothing else. **There is no JSON repair behind it and there never will be** — a repairer decides what the model MEANT and writes it down as though the model had said it, in the one artefact whose whole job is to be honest about what a repository contains. `meta.attempts` / `meta.attemptsAllowed` record what was paid for; every attempt is metered under its own label (`author-scout`, `author-scout#2`, …) and leaves its raw behind. **`ceilingUsd` is the operator's money ceiling** (PRD v1.62) — checked BETWEEN attempts and before F59's reserved round, so no paid call escapes it; `null`/absent is UNBOUNDED, and a non-null non-finite value THROWS (the shared `capStop` seam — see `authorClose` below). When it ends the ladder, `budgetStop` names which stop (`cap-halt` \| `pricing-red`) and a survey that was never asked for carries the typed cause `not-funded` — deliberately OUTSIDE `SCOUT_RETRY_CAUSES`, because a retry is precisely what the cap forbade |
 | listing | `buildSeedListing({ workdir, seedRef, sourcePaths, testPaths })` | mechanical, `$0`, no model. `files` is the WHOLE tree (what the validator judges paths against); `block` is scoped to the survey's own paths and capped in ANNOUNCED tiers (what the prompt carries). Handing the validator the scoped half would make a job scoped to `src/` read as whole-tree and silently disarm the one-population law |
-| authoring | `authorClose({ workdir, seedRef, lang, verdictType, answers, scout, listing, generate })` | the grounded loop: author → validate → run EVERY stage at the seed → feed the MEASURED results back → revise, bounded at `MAX_REVISIONS` (2) — a passed `maxRevisions` is TIGHTEN-ONLY, so a caller may LOWER that ceiling and never buy more revise rounds than the constant (floor **0**: one authoring call with no revise round is a legal ask, and unlimited revising would launder thrash as adaptation) — early-stop on an unchanged declaration. The declaration is emitted through a SCHEMA-FORCED TOOL CALL (`declare_close`), never parsed out of prose; the feedback is EXECUTION OUTPUT only — no model ever reviews another model's close. The return carries **`raws`**: what every model call actually SAID, the scout's attempts absorbed together with the declaration's, in the cost book's own order and under the same labels it meters. Each is `{ label, attempt, bytes, trimmed, text, cause, reason }` through the ONE persist helper (`scrubRaw` — redacted over the ONE `SECRET_PATTERNS` inventory, since a raw is the record most likely in this system to carry a live credential; bounded at `RAW_PERSIST_MAX` (8000) with the trim ANNOUNCING its own full size, and the cut walked back off a continuation byte so a multi-byte character is never split). `raws` is present on EVERY path **including the `$0` preflight refusals** — the path that spends nothing more is exactly the one whose evidence used to vanish with the process. `iterations` records what each turn MEANT (declaration, validation, seed read); `raws` records what it SAID, and a malformation is only ever visible in the second |
-| everything above, composed | `authorCloseForJob({ verdictType, answers, repoPath, lang, generate, ... })` → `{ ok, closeDecl, verdictType, refusal, cost, ... }` | refuses at the cheapest gate that can refuse: an interview refusal costs **zero**. THE GENRE REFUSAL LIVES HERE (not in the interview): a language the catalogue owns no data for, and a LOCKED KIND the model reached for, both come back as counted `request-red` demand |
+| authoring | `authorClose({ workdir, seedRef, lang, verdictType, answers, scout, listing, generate, ceilingUsd? })` | the grounded loop: author → validate → run EVERY stage at the seed → feed the MEASURED results back → revise, bounded at `MAX_REVISIONS` (2) — a passed `maxRevisions` is TIGHTEN-ONLY, so a caller may LOWER that ceiling and never buy more revise rounds than the constant (floor **0**: one authoring call with no revise round is a legal ask, and unlimited revising would launder thrash as adaptation) — early-stop on an unchanged declaration. The declaration is emitted through a SCHEMA-FORCED TOOL CALL (`declare_close`), never parsed out of prose; the feedback is EXECUTION OUTPUT only — no model ever reviews another model's close. The return carries **`raws`**: what every model call actually SAID, the scout's attempts absorbed together with the declaration's, in the cost book's own order and under the same labels it meters. Each is `{ label, attempt, bytes, trimmed, text, cause, reason }` through the ONE persist helper (`scrubRaw` — redacted over the ONE `SECRET_PATTERNS` inventory, since a raw is the record most likely in this system to carry a live credential; bounded at `RAW_PERSIST_MAX` (8000) with the trim ANNOUNCING its own full size, and the cut walked back off a continuation byte so a multi-byte character is never split). `raws` is present on EVERY path **including the `$0` preflight refusals** — the path that spends nothing more is exactly the one whose evidence used to vanish with the process. `iterations` records what each turn MEANT (declaration, validation, seed read); `raws` records what it SAID, and a malformation is only ever visible in the second. **`ceilingUsd` is the same operator ceiling the survey took** — the scout's spend is ABSORBED into this loop's cost book before its first call is weighed, so spend already incurred folds in and re-entering cannot silently widen it. It is checked immediately before EVERY paid call (the author call, each revise, and each malformed-emission retry). **A MALFORMED ceiling is an ERROR, not a silent unbounded run** (v1.64 §3): the seam every ceiling read goes through (`capStop`, `src/text.js`) THROWS on a non-null non-finite value — `'2.50'`, `NaN`, `Infinity`, `true`, `{}` — before the first paid call, and the throw propagates uncaught rather than being caught into an ABSENT survey, because a caught one would hand you the very silent-unbounded run it exists to prevent. `null`/omitted is the STATED operator choice for unbounded; `0` and negatives are finite, legal, and cap-halt immediately. The advertised ceiling and the enforced ceiling can therefore never be different numbers. A `cap-halt` here can arrive with `ok:true` — a close that was already validated and measured survives the money stop, exactly as a late provider casualty does |
+| everything above, composed | `authorCloseForJob({ verdictType, answers, repoPath, lang, generate, ceilingUsd?, ... })` → `{ ok, closeDecl, verdictType, refusal, cost, ... }` | refuses at the cheapest gate that can refuse: an interview refusal costs **zero**. THE GENRE REFUSAL LIVES HERE (not in the interview): a language the catalogue owns no data for, and a LOCKED KIND the model reached for, both come back as counted `request-red` demand. **`ceilingUsd` is ONE number handed to BOTH paid seams** (the survey's and the declaration loop's) — the advertised ceiling and the enforced ceiling are the same ceiling. It travels as an EXPLICIT `null` when unset, because unbounded is a stated choice and an absent field read as falsy is that state reached by accident — and anything that is neither a finite number nor `null` throws at the seam rather than becoming that state by typo |
 | assembly | `assembleSpec(specDraft, { closeDecl, verdictType })` | folds the authored half into the OPERATOR's half. Budgets, the fence, cadence, escalation and the provider are never authored by anything here. The GOAL is passed through, not generated. **A draft that ALREADY carries the authored half is REFUSED — it THROWS, never merges and never overwrites.** `AUTHORED_SPEC_FIELDS` (`close`, `closeDecl`, `verdictType`) names the fields this fold WRITES, as data, so the refusal and the fold cannot disagree about which half of the spec is which; the rule is `job.js`'s one step earlier (two closes are two arbiters, and picking one silently is how a signed artefact stops meaning what the signer read). `scripts/run-author.mjs` asks the same question at **$0 BEFORE the scout**, so the answer never arrives after the model has been paid |
 | the three gates | `prepareSigning({ spec, workdir, seedRef? })` → `{ ok, specHash, gates, work, guards, refusal }` | D9, and it NEVER signs |
 
@@ -510,6 +518,26 @@ declaring one is a counted `locked-kind` red rather than an unknown-kind typo; `
 tool mode a locked kind is INEXPRESSIBLE — the schema carries one branch per live kind — so
 that demand arrives through the interview layer instead (`refuseLockedKind(kind)`).
 
+**A red `count-not-worse` gap carries the LINES it counted, not only how many (F98).** Each
+term's **KEPT** matched lines nest under that term's own breakdown row — the row that already
+prints its `contributes +n`/`-n`, so a line's arithmetic role travels with it. Kept means the
+lines that survived the scope filter and were actually read by the aggregate (a `first` term
+echoes only the line that produced its value), which is to say the ones the count is made of.
+A scope-DROPPED line is never among them (it was never counted, so naming it would aim the
+worker outside its own population, F84's one-population law), duplicates collapse within a
+term (a line feeding two terms plays two roles and appears under each), and the value is
+still computed from the parsed values and never from this list.
+They ride the **existing** gap channel and invent none: the declared stage's `gapKeep` prefix
+on every line (Layer R's `redKeep` is DERIVED from that prefix), the same `GAP_LINE_CAP`, and
+the same announced trim on overflow — so a consumer parsing the gap sees more lines under the
+same shape, never a new one. `parseValue` returns them as `matched` alongside `value`,
+per-term, index-aligned with the breakdown. The
+licence is the one `pattern-absent-in-diff` already runs under: the instrument NAMED these
+lines, and echoing what it named is not the barred move of naming a culprit it never
+reported. **Nothing here can flip a signed spec hash** — the verdict logic, the baselines,
+the counting, the `closeDecl` schema and `detail` are untouched; only what the executor TELLS
+the worker changed.
+
 **The three gates, and the signature (D9).** Nothing LLM-judges a close.
 1. `validateCloseDecl(closeDecl, { verdictType, ... })` — schema, kinds, params, the F84
    one-population law, F49's static nested-quantifier reject, the D5 guard equality, the
@@ -524,12 +552,44 @@ that demand arrives through the interview layer instead (`refuseLockedKind(kind)
    **A close with no WORK stage red at seed is refused decision-ready** — it grades nothing,
    and an instrument that scans nothing reads clean exactly like one that measures correctly.
 
+**KNOWN LIMIT: gate 1 does not check a parser's FORMAT, and never will (F94, ruled WON'T-BUILD
+2026-08-13, PRD v1.63 §1).** A declaration can name the right stage, over the right population,
+with the right aggregate, and carry a `lineMatch` for a shape the tool never prints. Detecting
+that at draft time needs stage → tool attribution, and `npm run typecheck` defeats it
+mechanically: the declared command names npm, what prints is `tsc`, and the mapping lives in a
+`package.json` the validator does not read. A detector that resolved some spellings and passed
+the rest would read as coverage while being blind exactly where patients differ. **Gates 2 and 3
+are the instrument for this class, and they work** — a term matching nothing over a non-empty
+population reads unknown-not-zero (F6/F45/F93), so the seed-verdict read refuses it at $0 before
+a signature, which is how the real case was caught. Formats are checked by RUNNING the tool,
+never by reading a string. The complementary defence is upstream of the gate: for the tools the
+genre owns facts about, `genreInstruments` hands the author the measured pattern (with its real
+captured line) instead of asking, so fewer declarations reach gate 1 carrying an invented format
+at all. Reopens only if a wrong-format parser ever reaches a SIGNED close.
+
 Then the human signs `specHash`, unchanged: the approvals array and the human's word are
 the arbiter relocating to the user, not disappearing. **Re-authoring is a spec edit (D6)** —
 a different declaration is different bytes, a different resolved hash, and a new signature.
 The guards are stored ENUMERATED and every short-form parser is expanded, so no
 omittable-with-a-default field can change what runs without changing what was signed.
 
+**A signing surface must show the GOAL and the judged stages as one reading (F87).** The
+goal has to state everything the close will judge, and **nothing derives one from the other
+or checks them against each other** — the only derivation runs close-stages → check menu, one
+hop, one direction. So the sole defence against an unstated stage is that the person signing
+reads both halves at once, and any surface you build around `prepareSigning` inherits that
+obligation. Both reference runners now do it: `scripts/run-u.mjs --approve` names every close
+stage (name + kind) under the goal — for **BOTH spec forms**, through `closeStagesOf`, since
+gating that block on `closeDecl` reached exactly one of the eleven shipped specs and left the
+other ten (command `close[]`) showing the goal with no stages under it, which is the same
+half-reading in the guard against it (F100); a command stage prints `[command]` and NOT the
+catalogue kind name it does not carry — and `scripts/run-author.mjs` prints the goal above the
+declaration via `declarationLines(spec)` in `scripts/author-readout.mjs`, rendered from the
+**RESOLVED** spec — the bytes that get hashed, never the draft and never the authored half
+alone. An absent goal renders as absent rather than as a bare label. This is a READING, not a
+validator: nothing compares the goal to the declaration, because deriving one from the other
+is exactly what F87 forbids.
+
 **Refusals are COUNTED (D13).** `refusalEvents(refusal)` returns the spine events: a
 `job-red` carrying `{ code: 'request-red', verb, lib: 'bareloop' }` — the `lib` stamped at
 the EMIT SITE, so `classifyIncidents` files it against bareloop's own catalogue and its
@@ -661,9 +721,37 @@ three times on one call — each stall silently abandons the hung call and reiss
 laundered into `provider-red`, and carries `spendComplete:false` (an abandoned call may
 already have been billed). **The reissue is wall-aware:** past the run's deadline the fuse does
 not self-heal — self-heal is what a run does with time left — and it gives up as `wall-halt`,
-not `step-stalled`, since a replan has nothing left to re-allocate. Every one of them is a
+not `step-stalled`, since a replan has nothing left to re-allocate. **A `step-stalled` run is
+a CHECKPOINT, not a verdict** (hamr's ruling, 2026-08-13 — PRD v1.64 §1): it is resumable on
+the reference runner alongside the two governance halts, the work on disk stands, and its
+`spendComplete:false` carries forward as a floor. Every one of them is a
 decision-ready escalation with a terminal `job-end`: the spine never dangles.
 
+**`gate-red` is not in that list, and the plan flow no longer mints it (F98).** A fence
+DENIAL STREAK — bare-agent's BA-11 deny-spin guard returning `denied:*` after consecutive
+refusals — is a **BOUNDED ATTEMPT, never a terminal**, on BOTH worker surfaces: the attempt
+ends, `attempt-bounded` is emitted with the `reason`, the close judges the partial work, the
+gap feeds forward, the caps are unchanged and the loop continues.
+**The NEXT attempt is told which bound fired** (v1.64 §2): the bound carries
+`{iteration, cause, reason}`, and where the cause is `denied` the note says the GATE cut the
+attempt and quotes what the gate recorded, verbatim — instead of the round-cutoff sentence,
+which was false on cause and on count and aimed the worker at its read budget when the thing
+that stopped it was the fence. **Nothing is invented**: bare-agent returns `denied:<tool>`
+and nothing else — no path, no streak count — so neither is claimed. Every other cause keeps
+the round-bound wording byte for byte. The reason is scrubbed ONCE at capture through the one
+`SECRET_PATTERNS` inventory and shared by prompt and spine, and trimmed under the repo's one
+`GAP_TRIM_MARKER` (F90.2). It is the same lane
+`max_turns` and `loop.stop()` take, for the same reason — the attempt ran, produced audited
+work, and was cut short by a governance bound doing its job. **The fence holding is the
+system working, which is the opposite of a fault**; routing it as an instrument stop killed a
+converging run with $1.77 and 21.6 wall-minutes still on it. Nothing about the gate changed:
+the same actions are denied, the same audit rows are written, a genuine scope escape produces
+exactly what it did before — it now costs one bounded attempt instead of the whole run. The
+category survives only as a passthrough (`ralph`'s decision table still answers to it if a
+caller's own middle throws it, and `EXCLUDED_ESCALATIONS` still lists it so a future emission
+is filed as governance rather than re-read as a capability gap), but no site in this library
+raises it.
+
 **Every `job-end` carries the money, on every path**: `{ outcome, spentUsd, spendComplete }`
 (plus `step`/`cause`/`detail` where the outcome has them). `spentUsd` is the accumulated sum
 of PRICED rounds ONLY — never an estimate from token counts or averages (cap-not-estimate) —
@@ -1000,7 +1088,9 @@ learning credit and runs no on-green retention. A close that cannot RUN is a `br
 escalation before any provider call. So the resume story is: a `cap-halt` or `wall-halt`
 stop IS the checkpoint (the workdir + the close), the human raises `budgetUsd` or
 `maxWallMs` (a new spec hash — re-sign), and the rerun picks up where the budget died,
-paying zero provider calls for anything already green.
+paying zero provider calls for anything already green. (Those two are the *allowance* stops,
+the ones with a lever to raise. They are not the whole resumable set — `step-stalled` is also
+a checkpoint, with nothing to re-sign; see `resumableOutcomes` under the resume reader.)
 
 **Unpriced is never free (F6/F12):** the ledger meters **per ROUND** (`worker-round`, at
 bare-agent's `onLlmResult` seam) — money is counted as it is spent, never at the end of an
@@ -1022,7 +1112,14 @@ the loop contract (F16 — it is ONE attempt inside `while close-red and under-c
 re-run with the close's verdict; without this a model one-shots and can eat the budget in
 reads before ever writing). It is NOT allowed to read the run's own machinery (F14): the gate
 audit, the smoke store and the litectx store are denied — the agent neither authors the
-arbiter nor reads its books. N2 bounds (honest): `gold`/`rubric` closes refuse
+arbiter nor reads its books. **That denial is now REGISTERED in the persona, not left to be
+discovered (F98):** `PERSONA_TOOLS` names `gate-audit.jsonl`, `.smoke`, `.litectx` and the
+run's spine as always-denied, records of how the worker is being judged and never anything
+about its task, beside the absolute-path law it is the twin of — both are fence facts a worker
+cannot infer. It renders for EVERY worker on every grant (a worker granted only `write` gets
+no component strategy paragraph at all and must still be told). The fence is unchanged; what
+changed is that the rule is stated instead of learned one refusal at a time, which cost a real
+run the rounds of a bounded attempt. N2 bounds (honest): `gold`/`rubric` closes refuse
 `close-unsupported` (execution lands at N4).
 
 ### The reuse registry (Layer 3) — `src/bridges.js`, `src/selection.js`
@@ -1242,11 +1339,33 @@ semantics are byte-unchanged (PRD v1.46 §3):
   is `$0`: a leg whose every round came back unpriced folds nothing countable and is still not
   exact, so the declaration is emitted to carry that unknown forward rather than letting it read
   as an exact zero (F6).
-- **`resumableOutcomes: ['cap-halt', 'wall-halt']`** reclassifies a landed `job-end` whose
-  outcome is a GOVERNANCE HALT as a restart rather than a completed row. "A landed job-end is
-  complete" is true of a VERDICT; a halt means an operator-owned allowance ran out with the
-  work on disk and the plan on the spine. A green or any red stays non-resumable under every
-  setting — a verdict already rendered is never re-bought.
+- **`resumableOutcomes: [...]`** reclassifies a landed `job-end` whose outcome is a
+  CHECKPOINT rather than a verdict as a restart rather than a completed row. "A landed
+  job-end is complete" is true of a VERDICT; a checkpoint means the work is on disk and the
+  plan is on the spine with nothing decided against them. **The set is the CALLER's**, and
+  the reference runner's is `['cap-halt', 'wall-halt', 'step-stalled']` (`run-u`'s
+  `RESUMABLE_HALTS`). The first two are governance halts — an operator-owned allowance ran
+  out. `step-stalled` joined them 2026-08-13 on hamr's ruling (PRD v1.64 §1): it is the one
+  terminal whose OWN escalation already offers *"retry the run"*, nothing about the work on
+  disk is wrong, and the shape that named the fix is a stall that trips with time left and
+  then rides out past the wall — losing a checkpoint a `wall-halt` would have kept. Its NAME
+  deliberately stays `step-stalled` because `runJob` keys the **F44 spend FLOOR** on that
+  outcome; renaming it would report unknown spend as exact. The floor travels: a stalled
+  leg's `spendComplete:false` reaches the preview as `≥$x` and the resumed leg as
+  `priorSpendComplete: false`, so the next terminal stays a floor rather than healing an
+  unknown by inheriting it. A green or any red stays non-resumable under every setting — a
+  verdict already rendered is never re-bought.
+  **One exception, and it is a DERIVATION rather than a widening (D4a, F96).** A recorded
+  `step-red` is re-read as a wall-halt — and becomes resumable — when the run's OWN spine
+  carries a `wall-bounded {bounded: true}` record STRICTLY BEFORE its terminal, and only when
+  `'wall-halt'` is itself in `resumableOutcomes`. It fires on the run's own primary evidence,
+  which no caller can assert; a `step-red` with no wall record in front of it is untouched, so
+  "a red is an answer" survives intact. It touches no close verdict — the grades stand and the
+  resume seeds from them. The readout surfaces `wallDerivedHalt` so an operator resuming a spine
+  that SAYS `step-red` is told which record turned it into a checkpoint. **This is a PERMANENT
+  safety net, not a migration shim (ruled 2026-08-13, PRD v1.63 §2):** the defect that minted
+  the shape is fixed at source, but spines are append-only forever, so the population it protects
+  can never shrink — and on a healthy spine it is a branch that is never taken.
 
 `restart.branch` is the WORK BRANCH the dead leg was working on, READ off its `work-branch`
 record and never re-derived: the name is deterministic from the signed spec, so a restart that
@@ -1328,6 +1447,12 @@ and is re-signed.
   fold — a garbage, non-finite or negative `count` reads as `0` rather than widening the ceiling.
   Null/omitted is the cold path. The disarm control is pinned: a resumed leg with an UNSPENT
   ceiling still replans, so the bound is bounded, not switched off.
+  **NEVER-REFILL is now the RULING, not just the behaviour (2026-08-13, PRD v1.63 §4).** A resume
+  inherits the spent replan ledger, entire; a refill would let every kill buy an allowance, which
+  is unlimited replanning through the side door, and unlimited replanning launders thrash as
+  adaptation. The consequence for an adopter is a real one and is deliberate: a resume whose
+  ledger is already spent re-enters its plan with no channel to replace it. That is not funded —
+  it is SHOWN, by the resume banner, before you sign.
 - **Under the REMAINDER, never a fresh allotment.** The killed attempt's spend and wall
   FOLD IN (`runJob`'s `priorSpentUsd`/`priorSpendComplete`/`priorWallMs`, `createClock`'s
   `priorElapsedMs`), so
@@ -1405,7 +1530,9 @@ seeding an upstream ask. Deliberate exclusions
 counted as unmapped, never dropped): `cap-halt`/`wall-halt` (budget stories, money and
 time), `step-stalled` (the stall fuse firing is our governance, not an observed provider
 failure), `step-variance` (a planning story), `gate-red`/`smoke-red` (governance working
-as intended / already counted), `hitl-close`/`close-unsupported`/`close-unauthorable` (by design — and the last one
+as intended / already counted — and `gate-red` is no longer minted anywhere in this library,
+kept listed because this set is EXECUTABLE: dropping a name would not delete the category, it
+would re-file any future emission of it as a counted capability gap), `hitl-close`/`close-unsupported`/`close-unauthorable` (by design — and the last one
 is excluded for a SECOND reason: its demand is already counted once as the `request-red`
 the same refusal emits, so counting the escalation too would double every refusal),
 `close-timeout`/`close-killed`/`close-crashed` (the arbiter's own named terminals, F17);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.9.0",
+  "version": "0.10.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",

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);
@@ -496,6 +496,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 +665,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 +912,8 @@ 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}} [o] the OPERATOR's ceiling; `null`/absent is UNBOUNDED */
+export function makeCostBook({ ceilingUsd = null } = {}) {
   /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
   const entries = [];
   /** @type {ReturnType<typeof scrubRaw>[]} */
@@ -872,19 +932,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 +999,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 +1018,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 +1036,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 +1049,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 +1080,11 @@ 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,
  *   maxRevisions?: number, structureRetries?: number,
  *   structuredMode?: 'tool'|'text', catalogue?: Record<string, any>}} o
  */
@@ -1021,6 +1093,7 @@ export async function authorClose({
   answers, questions = GREEN_QUESTIONS,
   scout, listing = null,
   generate, seedReadFn = runSeedReadStages, closeCtx = {},
+  ceilingUsd = null,
   maxRevisions = MAX_REVISIONS,
   structureRetries = MAX_STRUCTURE_RETRIES,
   structuredMode = 'tool',
@@ -1039,7 +1112,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 });
   // 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 +1136,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 +1271,55 @@ 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}`;
       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 +1328,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