bareloop 0.9.0 → 0.11.0

package/src/ralph.js

@@ -590,6 +590,11 @@ export async function ralph({ middle, close, judge, capRuns, ladder, emit, redac
       const DECISIONS = {
         'cap-halt': [`Budget gate tripped mid-run (${e && e.message}). Continue with a higher cap, change approach, or stop?`,
           ['raise the cap and rerun', 'change the middle/harness', 'abandon the task']],
+        // No site in this tree mints `gate-red` any more: a BA-11 denial streak is
+        // a bounded attempt now (planrun's two `ask`s), not a terminal, because the
+        // fence HOLDING is governance working, not a fault. The entry stays because
+        // this catch is a dumb passthrough — it files whatever category the thrower
+        // names, so an unlisted one would read out with the generic text.
         'gate-red': ['The gate denied an action mid-run — the harness asked for something outside its scope.',
           ['widen the write scope deliberately', 'change the middle/harness', 'abandon the task']],
         'provider-red': ['The provider path failed mid-run (transport, not logic) — no verdict exists and the spend for the failed call is unknown (F6).',
@@ -624,6 +629,15 @@ export async function ralph({ middle, close, judge, capRuns, ladder, emit, redac
         // interpreter" would aim a human at the one component that did nothing wrong.
         'step-stalled': ['The model stopped producing rounds and reissuing the call did not recover it — a stall, not a fault.',
           ['let the planner re-allocate what is left (replan)', 'retry the run', 'check provider status', 'abandon the task']],
+        // N4 — the close is WAITING ON A PERSON. Nothing failed and nothing is
+        // discarded: every mechanical stage passes and the one stage left is a
+        // question no worker can answer, so the loop stopped rather than buying
+        // an attempt that could not change the answer. The caller renders the
+        // real decision-ready package (`hitl-pause`, with the evidence); this
+        // entry exists so the passthrough never narrates a paused run as a
+        // broken middle.
+        'hitl-pause': ['The close reached its human stage — the run is paused, decision-ready, and the clock is stopped.',
+          ['accept', 'rerun (your words become the gap the worker converts)', 'pause (the checkpoint keeps, and it resumes)']],
       };
       // Object.hasOwn, not bare lookup: a category named after an
       // Object.prototype member ("toString") would return the inherited

package/src/reuse.js

@@ -1,5 +1,5 @@
 // Layer 3 — the D7 ENVELOPE and the REUSE RUNNER (design record
-// docs/plans/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
+// docs/02-features/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
 //
 // hamr's sentence is the whole specification of this file, verbatim:
 //
@@ -52,6 +52,12 @@ import { closeStagesOf } from './plan.js';
 import { MIN_WALL_MS, jobSpecHash } from './job.js';
 import { isObj, isNonEmptyString } from './validate.js';
 import { readGrade } from './trend.js';
+
+/** the paused-run TERMINAL and its spine record share one name (`runPlan` returns
+ * it and `runJob` writes it onto `job-end`), spelled once in `declaredclose.js`
+ * beside the close-verdict word it translates, so the emitters, the checkpoint
+ * list, and the TTL gate below cannot drift from each other */
+import { HITL_PAUSE, HUMAN_CHECKPOINTS } from './declaredclose.js';
 import { extractArtifact, priceOf } from './text.js';
 import { runJob as shippedRunJob } from './run.js';
 
@@ -84,6 +90,34 @@ const { Loop } = require('bare-agent');
  */
 export const REUSE_GRADED_RED = Object.freeze(['escalated']);
 
+/**
+ * WHICH TERMINALS ARE A CHECKPOINT — the list a runner hands `readResume` as
+ * `resumableOutcomes`, minted HERE rather than in whichever script happens to
+ * launch a run.
+ *
+ * `readResume` deliberately takes it as a parameter and defaults to empty, and
+ * that stays true: the reuse loop's own semantics depend on the empty default.
+ * What did not exist was a canonical ANSWER, so `scripts/run-u.mjs` kept its own
+ * copy — and the exported bundle (PRD v1.44 §2: a thin runner with bareloop as a
+ * dependency) would have had to keep a third. The same reasoning that put the
+ * pause TTL in the library (OPEN-2, hamr, 2026-08-13) puts this here.
+ *
+ * Every entry is a stop that left WORK ON DISK and an allowance unspent — money,
+ * time, a self-healed stall, and now a person who has not answered yet. A verdict
+ * already rendered is never on this list: `green`/`escalated` are graded rows, and
+ * re-buying one would pay twice for an answer already in hand. (The signer's own
+ * `hitl-cancel` terminal used to be the other example; the door was deleted on
+ * 2026-08-17 — a person who does not want to carry on pauses, and the checkpoint
+ * they keep is retired by the TTL rather than by a terminal.)
+ *
+ * The human half is SPLICED IN from `declaredclose.js` rather than spelled again,
+ * because the try loop below reads the two halves differently and a second copy is
+ * how they would come to disagree about which member is which: the first three are
+ * allowances the loop's remaining tries are meant to spend against, and the human
+ * ones are the stop no further try can change (see `hardStop`).
+ */
+export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', ...HUMAN_CHECKPOINTS]);
+
 /**
  * v1's definition of "the same KIND of recipe" — and it is the LOAD GATE's own: the
  * close-stage names, in the same order (`bridges.loadGate` rule 2). One predicate,
@@ -418,13 +452,24 @@ function readTry(events) {
   };
 }
 
-/** the three-way verdict read of a runJob outcome, in ONE place: a green, the one
- * GRADED red that demotes (D6), or a casualty that keeps its own name. Both the live
- * try loop and the resume reader classify through this — two spellings of "what kind
- * of answer was that" is how a casualty ends up demoting a recipe.
- * @param {string} outcome @returns {'green'|'red'|'casualty'} */
+/** the verdict read of a runJob outcome, in ONE place: a green, the one GRADED red
+ * that demotes (D6), a CHECKPOINT waiting on a person, or a casualty that keeps its
+ * own name. Both the live try loop and the resume reader classify through this — two
+ * spellings of "what kind of answer was that" is how a casualty ends up demoting a
+ * recipe.
+ *
+ * `checkpoint` is its own name rather than a fourth flavour of casualty (2026-08-17).
+ * A casualty is a run that DIED — a transport fault, a governance cut, a broken close
+ * — and a reader that sees one is being told the attempt is over. A human checkpoint
+ * is the opposite fact in every respect: nothing failed, nothing is discarded, the
+ * work and the money are exactly where they were, and the allowance still unspent is
+ * a person's answer. It behaves like neither a red nor a casualty everywhere it
+ * matters already (`hardStop` ends the loop on it, the box is left untouched), so the
+ * ROW saying "casualty" was the one place the machinery still mis-described itself.
+ * @param {string} outcome @returns {'green'|'red'|'checkpoint'|'casualty'} */
 function verdictClassOf(outcome) {
   if (outcome === 'green' || outcome === 'already-green') return 'green';
+  if (HUMAN_CHECKPOINTS.includes(outcome)) return 'checkpoint';
   return REUSE_GRADED_RED.includes(outcome) ? 'red' : 'casualty';
 }
 
@@ -665,7 +710,7 @@ function readGradeSeed(seen) {
  *   which is later and better evidence than the last event). Defaults to the last
  *   event's own timestamp — the last sign of life there is.
  * @returns {any} `{ started, approvalHash, specHash, patient, job, bridgeTries,
- *   perTryBudgetUsd, perTryWallMs, ended, endOutcome, greened, completed, tried,
+ *   perTryBudgetUsd, perTryWallMs, ended, endOutcome, wallDerivedHalt, greened, completed, tried,
  *   selectionCostUsd, selectionComplete, strayRounds, r1Missing, restart, deathAtKnown,
  *   spentUsd, spendComplete, carrySpentUsd, carrySpendComplete }`
  */
@@ -816,7 +861,50 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
    * CHECKPOINT and re-entering it is the ruling, not a second payment for an answer
    * already in hand. Empty by default, which is what keeps the reuse loop's own
    * graded-row semantics exactly where they were. */
-  const haltedResumable = open?.jobEnd ? resumableHalt.has(String(open.jobEnd.outcome)) : false;
+  const recordedOutcome = open?.jobEnd ? String(open.jobEnd.outcome) : null;
+  /** D4a — the MISLABELLED wall stop, derived from the run's own primary records.
+   *
+   * `step-red` is a verdict-shaped terminal and stays non-resumable: a red is an
+   * answer. But on u-msmt91t3 the runner minted one 9.9 seconds AFTER its own
+   * `wall-bounded` record — a governance stop wearing a capability label, because the
+   * step-variance terminal did not re-read the clock (fixed at the source, src/planrun.js).
+   * Spines already written under the defect are not re-runnable and cannot be edited (a
+   * spine is append-only forever), so the READER derives the truth the file already
+   * holds: a run whose own record says the wall was crossed BEFORE it ended is a wall
+   * stop, and W-2's ruling applies — it keeps the grades it minted and pauses.
+   *
+   * Three constraints, each of them load-bearing:
+   *   * a DERIVATION, never an override. The evidence is the run's own `wall-bounded`
+   *     event, emitted by the runner at the round seam; no caller can assert this.
+   *   * `step-red` ONLY, and only when `wall-halt` is itself resumable for this caller.
+   *     Every other outcome — green, escalated, provider-red, a step-red with no wall
+   *     record — is untouched, so "a red is an answer" survives intact.
+   *   * it touches NO close verdict. `step-red` here is a GOVERNANCE stop label; the
+   *     grades the close rendered are exactly what they were, and the resume seeds
+   *     from them.
+   * @param {any[]} seen @param {any} jobEnd */
+  const wallCrossedBefore = (seen, jobEnd) => {
+    // strictly BEFORE the terminal: a record written after the run ended could not have
+    // been what stopped it. `indexOf` on the window's own array is the ordering there is
+    // (the reader never re-sorts), and a jobEnd somehow absent from it reads nothing.
+    const end = seen.indexOf(jobEnd);
+    if (end < 0) return false;
+    for (let i = 0; i < end; i += 1) {
+      const e = seen[i];
+      if (!isObj(e) || e.type !== 'wall-bounded' || e.bounded !== true) continue;
+      // the clock's OWN two spellings of "the deadline passed", both off `clock.report`.
+      // Never a re-derivation from timestamps: a second arithmetic for one question is
+      // how two instruments come to disagree.
+      if (e.remainingMs === 0) return true;
+      if (typeof e.elapsedMs === 'number' && typeof e.requestedMs === 'number' && e.elapsedMs >= e.requestedMs) return true;
+    }
+    return false;
+  };
+  const wallDerivedHalt = recordedOutcome === 'step-red'
+    && resumableHalt.has('wall-halt')
+    && wallCrossedBefore(open.seen, open.jobEnd);
+  const haltedResumable = recordedOutcome !== null
+    && (resumableHalt.has(recordedOutcome) || wallDerivedHalt);
   if (open) {
     if (open.jobEnd && !haltedResumable) {
       // GRADED: runJob returned and the close had its say. Not a restart — the row is
@@ -963,7 +1051,14 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
     perTryBudgetUsd: head?.perTryBudgetUsd ?? directHead?.budgetUsd ?? null,
     perTryWallMs: head?.perTryWallMs ?? null,
     ended: end !== null || (directEnd !== null && !haltedResumable),
+    // the RECORDED terminal, always — the derivation below never rewrites what the run
+    // said about itself, it only says how this reader read it
     endOutcome: end?.outcome ?? directEnd?.outcome ?? null,
+    /** D4a — true when a recorded `step-red` was re-read as a wall-halt off this run's
+     * OWN `wall-bounded` record. Surfaced rather than silent: an operator resuming a
+     * run whose spine says `step-red` must be told which record turned it into a
+     * checkpoint, or the gate looks like it simply stopped refusing. */
+    wallDerivedHalt,
     greened: completed.some((t) => t.verdictClass === 'green'),
     completed,
     tried,
@@ -973,6 +1068,81 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
   };
 }
 
+/**
+ * THE PAUSE TTL (2026-08-12 §2): a hitl checkpoint is kept for 60 days.
+ *
+ * OPEN-2, RULED (hamr, in-turn, 2026-08-13): **the TTL lives in the LIBRARY**, so
+ * the exported bundle (a headless runner with bareloop as a dependency, PRD v1.44
+ * §2) inherits it instead of every runner re-implementing it. A script-only TTL
+ * would vanish on export — the one place the rule is most needed and least
+ * likely to be re-typed.
+ */
+export const PAUSE_TTL_MS = 60 * 24 * 60 * 60_000;
+
+/**
+ * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it
+ * asks the other question a 60-day-old checkpoint raises. The tree gate asks
+ * *is this still the tree the run left?*; this asks *is this still a decision
+ * anyone is waiting on?*
+ *
+ * THREE things it deliberately does NOT do:
+ *
+ *  - it does not widen any other resume rule. The 2026-08-12 ruling is about a
+ *    person deciding, so `applies: false` on every other terminal: a cap-halt
+ *    checkpoint is a different stop under a different allowance, and quietly
+ *    ageing it out would be a governance change nobody ruled.
+ *  - it does not treat an unreadable stamp as young (F6). A checkpoint that
+ *    cannot say WHEN it paused has an unknown age, and unknown is refused rather
+ *    than rounded down to fresh — the direction that fails safe.
+ *  - it does not skip silently. An expired checkpoint comes back as a refusal
+ *    that NAMES the age and the TTL, because the operator's next move (start
+ *    fresh) depends on knowing which of the two it hit.
+ *
+ * The clock is injected for the same reason `runPlan`'s is: a rule measured in
+ * months cannot otherwise be tested at all.
+ *
+ * @param {any[]} events the paused run's own spine, parsed, in file order
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, applies: boolean, ageMs: number|null, ttlMs: number, pausedAt: string|null, detail: string|null}}
+ */
+export function checkpointAgeGate(events, { now = Date.now, ttlMs = PAUSE_TTL_MS } = {}) {
+  const list = Array.isArray(events) ? events.filter(isObj) : [];
+  const end = list.filter((e) => e.type === 'job-end').at(-1) ?? null;
+  const base = { applies: false, ageMs: null, ttlMs, pausedAt: null, detail: null };
+  if (end?.outcome !== HITL_PAUSE) return { ...base, ok: true };
+
+  // the PAUSE RECORD's own timestamp, and its terminal's as the fallback: the
+  // pause is what the human is answering, so its stamp is when the waiting began
+  const pause = list.filter((e) => e.type === HITL_PAUSE).at(-1) ?? end;
+  const pausedAt = typeof pause.ts === 'string' ? pause.ts : null;
+  const atMs = pausedAt === null ? NaN : Date.parse(pausedAt);
+  if (!Number.isFinite(atMs)) {
+    return {
+      ...base,
+      ok: false,
+      applies: true,
+      detail: 'this checkpoint does not record when it paused, so its age is unknown — and an unknown age is not a '
+        + `young one (F6). The TTL is ${Math.round(ttlMs / 86_400_000)} days; start a fresh run rather than resuming a `
+        + 'checkpoint nothing can date.',
+    };
+  }
+  const ageMs = Math.max(0, now() - atMs);
+  const days = (/** @type {number} */ ms) => Math.floor(ms / 86_400_000);
+  if (ageMs > ttlMs) {
+    return {
+      ...base,
+      ok: false,
+      applies: true,
+      ageMs,
+      pausedAt,
+      detail: `this run paused ${days(ageMs)} days ago and the pause TTL is ${days(ttlMs)} days — the tree, the `
+        + 'toolchain and the job itself have had two months to move, so the evidence the signer would be answering '
+        + 'about is no longer the evidence the run produced. Start a fresh run.',
+    };
+  }
+  return { ...base, ok: true, applies: true, ageMs, pausedAt };
+}
+
 /**
  * The PATIENT gate for a resume, which is deliberately NOT the fresh-launch one.
  *
@@ -1325,7 +1495,30 @@ export async function runReuse(opts) {
       costUsd: read.spentUsd, spendComplete: read.spendComplete, wallMs, rounds,
       ...(trySpecHash ? { specHash: trySpecHash } : {}),
     };
-    if (verdictClass === 'green' && read.plan === null) {
+    if (outcome === 'already-green') {
+      // A GREEN THAT PREDATES THE RUN mints nothing, and the guard keys on the
+      // TERMINAL rather than on the absence of a plan. `already-green` means the
+      // close was satisfied at the precheck — before this leg wrote a byte — so
+      // whatever plan is on the spine did not produce it, and minting a version
+      // from one would be learning credit for work that did not happen.
+      //
+      // It used to be covered by accident: a cold already-green never drafts, so
+      // `read.plan` was null and the branch below caught it. N4 broke that
+      // accident — a hitl try that PAUSED and came back with the signer's
+      // `accept` lands `already-green` with its predecessor's `plan-accepted`
+      // sitting in the same try window. A rule with no wired detector is prose.
+      bridgeWrites.push({
+        name,
+        action: 'none',
+        file: null,
+        reds: [{
+          code: 'green-predates-run',
+          path: 'outcome',
+          detail: 'the close was already satisfied before this run did anything (already-green) — nothing here earned '
+            + 'a version, and a plan on the spine did not produce this green',
+        }],
+      });
+    } else if (verdictClass === 'green' && read.plan === null) {
       // a green with no plan on the spine cannot mint a version — the artifact that
       // inherits is the one that RAN, and there is nothing here to inherit. Reported,
       // never faked with a placeholder.
@@ -1339,6 +1532,26 @@ export async function runReuse(opts) {
         toolsUsed: [...new Set((read.plan.steps ?? []).flatMap((/** @type {any} */ s) => s.tools ?? []))],
       };
       row.bridgeWrite = writeGreen(bridge, meta, { ...record, plan: read.plan });
+    } else if (HUMAN_CHECKPOINTS.includes(outcome)) {
+      // A PAUSE IS NOT A RESULT, so the box gets nothing — not a casualty row, not a red,
+      // and the workflow is left exactly as it was. The recipe has not been judged: the
+      // close is not FINISHED rendering its verdict, and the answer that would finish it
+      // is a person's. Filing it as history would put a row on the entry that reads as a
+      // run this workflow failed to carry, and the signer's `accept` moments later would
+      // leave that row standing as evidence against a workflow that in fact greened.
+      // Recorded as an explicit no-write for the already-green branch's reason: a reader
+      // never has to branch on absence.
+      bridgeWrites.push({
+        name,
+        action: 'none',
+        file: null,
+        reds: [{
+          code: 'run-paused-for-decision',
+          path: 'outcome',
+          detail: `the run is waiting on a person (${outcome}) — nothing has been judged yet, so there is no result to `
+            + 'file against this workflow. The row is written by whatever the resumed run finally earns.',
+        }],
+      });
     } else if (bridge) {
       // R1: the recipe is NOT edited by a red. `outcome` rides in verbatim — a casualty
       // keeps its own name, and only the literal 'red' demotes (D6).
@@ -1445,6 +1658,31 @@ export async function runReuse(opts) {
    * @param {any} row @returns {any|null} the terminal, or null to carry on
    */
   const hardStop = (row) => {
+    // THE HUMAN HALF, read before the table and off the LIBRARY's own list: a run
+    // waiting on a person is not one of the stops below, which are properties of the
+    // run that would reproduce for $0. This one is the opposite — a try that did real
+    // work and reached the one stage a machine cannot render. Buying the next try (and
+    // then the cold leg) would spend the envelope re-asking a question already put to
+    // someone who has not replied yet, and the second attempt could not be graded any
+    // sooner than the first. The allowance still unspent is a person, so the loop stops
+    // and hands the run back; the checkpoint on disk is untouched and resumable, which
+    // is the runner script's half (N4 §1.6, PAUSE_TTL_MS).
+    if (HUMAN_CHECKPOINTS.includes(row.runOutcome)) {
+      return done(row.runOutcome, {
+        category: row.runOutcome,
+        decision: 'The run reached a stage only a person can render, and it is waiting on that answer. Every further '
+          + 'try and the cold leg would run the same job to the same question, so the loop stops here rather than '
+          + 'buying attempts nobody can grade yet. Nothing is lost: the run kept everything it did, and it resumes '
+          + 'from this checkpoint once the decision is in.',
+        options: [
+          'read the evidence package the pause recorded, then answer it and resume this run',
+          'leave it: an unanswered checkpoint expires on its own once the pause TTL is up',
+        ],
+      // NOT re-filed, for `interpreter-red`'s reason: the pause already escalated from
+      // its own site inside the run, under this same name and with the evidence package
+      // attached. A second copy here would count one person's pending decision twice.
+      }, false);
+    }
     const decisions = {
       'unapproved-spec': {
         decision: `No approval record matches the per-try spec (hash ${trySpecHash}). Tightening the caps with an envelope makes a NEW spec version, and a new version is signed, not inherited — nothing was run.`,

package/src/root.js

@@ -1,5 +1,5 @@
 // Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
-// docs/plans/2026-07-19-layer-r-design.md). One state that survives attempts
+// docs/02-features/2026-07-19-layer-r-design.md). One state that survives attempts
 // inside ONE run so a never-green run stops repeating itself (F21). Role is
 // CONTINUITY ONLY — F39 measured that hand-delivered state buys no conversion;
 // the semantic converter is Layer 2's job, not this module's.

package/src/run.js

@@ -3,7 +3,7 @@
 // smoke, the ONE budget ledger (cap-not-estimate; unpriced is never free, F6),
 // and the decision-ready stops. It composes the plan flow below it and
 // interprets nothing itself.
-// Design record: docs/plans/2026-07-12-n2-headless-loop-design.md.
+// Design record: docs/02-features/2026-07-12-n2-headless-loop-design.md.
 //
 // The legacy operator-authored `steps[]` path was DELETED 2026-07-26 (PRD
 // v1.32): the drafting call, config-v1, the per-step interpret loops and the
@@ -15,6 +15,7 @@ import { join } from 'node:path';
 import { LiteCtx } from 'litectx';
 import { validateJob, jobSpecHash, checkApproval } from './job.js';
 import { runPlan } from './planrun.js';
+import { SMOKE_STORE } from './kinds.js';
 
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 
@@ -29,7 +30,7 @@ import { runPlan } from './planrun.js';
  */
 async function primitiveSmoke(workdir) {
   try {
-    const lc = new LiteCtx({ root: join(workdir, '.smoke') });
+    const lc = new LiteCtx({ root: join(workdir, SMOKE_STORE) });
     await lc.remember('smoke-known-answer', 'bareloop primitive smoke: the answer is 42', { kind: 'fact' });
     const hits = await lc.recall('bareloop primitive smoke known answer', { kind: 'fact', n: 5, body: true });
     const ok = hits.some((h) => String(h.body ?? '').includes('the answer is 42'));
@@ -139,12 +140,18 @@ async function primitiveSmoke(workdir) {
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
+ *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
+ *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
+ *   done?" is the rubber-stamp the class exists to prevent, 2026-08-12 §4).
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null }) {
   // 0. the ledger's counters, declared FIRST so that every job-end — including
   // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
   // not a zero: a consumer reads `undefined` and either crashes or launders it
@@ -282,7 +289,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch,
+      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact

package/src/selection.js

@@ -1,5 +1,5 @@
 // Layer 3 — D3's DISPLAY half: the workflow LISTING, and the prompt that asks for a
-// pick (design record docs/plans/2026-08-01-layer-3-reuse-design.md, D3).
+// pick (design record docs/02-features/2026-08-01-layer-3-reuse-design.md, D3).
 //
 // hamr's ruling, verbatim: *"i think there should be a listing for workflows names that
 // user can choose or auto-choose, or do we want llm to always decide (we still need to

package/src/text.js

@@ -70,6 +70,85 @@ export function priceOf(r) {
   };
 }
 
+/**
+ * The F6 tally over a list of PRICED CALLS — `priceOf`'s per-call read, summed.
+ *
+ * `knownUsd` carries the priced half explicitly and `costUsd` is the honest
+ * total: null the moment anything went unpriced, never the priced half wearing a
+ * complete coat. An EMPTY list is a complete $0 and not an unknown — nothing
+ * spent is a number somebody can act on.
+ * @param {{costUsd: number|null, unpricedRounds?: number}[]|null|undefined} entries
+ * @returns {{costUsd: number|null, knownUsd: number, spendComplete: boolean,
+ *   nullCostCalls: number, unpricedRounds: number}}
+ */
+export function tallyCalls(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  const known = list.reduce((a, e) => a + (typeof e.costUsd === 'number' ? e.costUsd : 0), 0);
+  const nullCostCalls = list.filter((e) => e.costUsd === null).length;
+  const unpricedRounds = list.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,
+  };
+}
+
+/**
+ * THE ONE MONEY-CEILING PREDICATE, for the same reason `priceOf` above is one:
+ * the authoring pipeline meters two populations of paid call in two different
+ * accumulators (the survey's `calls[]`, the declaration loop's cost book), and
+ * two hand-spelled answers to "am I over the ceiling?" is two instruments.
+ *
+ * It is asked BETWEEN metered calls and never inside one. A cap that binds
+ * mid-call kills the row before it can be graded — F45 measured that as 3 of 7
+ * launches lost and $5.82 unreadable.
+ *
+ * Three answers, and the order between the last two is load-bearing:
+ *   - NO CEILING → null, always. An absent cap is UNBOUNDED, and unbounded is a
+ *     visible operator choice, never a defaulted number nobody set (the
+ *     `maxWallMs` precedent). There is nothing to enforce, so unpriced spend
+ *     here is merely reported.
+ *   - KNOWN SPEND AT OR OVER THE CEILING → `cap-halt`, even when the total is
+ *     unknown. The breach is CERTAIN on the priced half alone — whatever the
+ *     unpriced remainder turns out to be, it can only be larger — so naming this
+ *     `pricing-red` would send the operator to fix a meter when the fact is that
+ *     the money is gone. At-or-over rather than over: the next call is the one
+ *     that breaches, and it is the one being decided.
+ *   - SPEND THAT CANNOT BE KNOWN → `pricing-red`. `?? 0` launders unknown into
+ *     $0 (F6) and a ceiling enforced against a laundered floor is not enforced
+ *     at all. If the spend cannot be seen the cap cannot govern it, and that is
+ *     its own stop rather than a silent pass.
+ *
+ * A MALFORMED ceiling is the one input it refuses rather than answers: `null` and
+ * an absent field mean UNBOUNDED, and they are the ONLY way to get there. Anything
+ * else that is not a finite number (`'2.50'`, `NaN`, `Infinity`) reading as
+ * unbounded would be F6's laundering in its ceiling form — a caller who set a cap
+ * getting a paid pipeline with nothing enforcing it, which is the exact collapse
+ * the ceiling exists to prevent, wearing the caller's own typo (PRD v1.62). The
+ * CLI's `parseCeiling` guards the FLAG; this guards the LIBRARY, and `authorClose`
+ * / `runAuthorScout` / `authorCloseForJob` are documented adopter seams. It THROWS
+ * rather than clamping, unlike the attempt caps beside it, because those axes have
+ * a safe direction to clamp toward and this one does not: every candidate default
+ * is either a number nobody set or the unbounded run the caller just declined.
+ * @param {{ceilingUsd: number|null|undefined, knownUsd: number, spendComplete: boolean}} o
+ * @returns {'cap-halt'|'pricing-red'|null}
+ * @throws {Error} when the ceiling is neither absent nor a finite number
+ */
+export function capStop({ ceilingUsd, knownUsd, spendComplete }) {
+  if (ceilingUsd === null || ceilingUsd === undefined) return null;
+  if (typeof ceilingUsd !== 'number' || !Number.isFinite(ceilingUsd)) {
+    throw new Error(`capStop: a money ceiling must be a finite number of dollars or null — got ${typeof ceilingUsd} `
+      + `${String(ceilingUsd)}. A malformed ceiling is an ERROR, never a silent fall back to UNBOUNDED: omit it, or `
+      + 'pass an explicit null, to run unbounded — that is a stated operator choice and never a typo arrived at');
+  }
+  if (knownUsd >= ceilingUsd) return 'cap-halt';
+  if (!spendComplete) return 'pricing-red';
+  return null;
+}
+
 // ── THE RAW MODEL OUTPUT, AS A PERSISTED RECORD ─────────────────────────────
 //
 // Run mslhn707 died on a survey that broke JSON at position 1339 and left NO

package/src/tools.js

@@ -31,6 +31,7 @@ import { extractArtifact, priceOf } from './text.js';
 // caller can forget to pass, and this leak has to be inexpressible, not optional.
 // Same ONE inventory the spine channel and the close output ride through.
 import { redactSecrets } from './validate.js';
+import { GATE_AUDIT_FILE, ARBITER_BOOK_STORES } from './kinds.js';
 
 /** @typedef {{body?: string|null, text?: string|null}} RecallHit litectx recall hit — body present only with `{body: true}` */
 
@@ -45,6 +46,16 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
 // cheap, wrong attempt the rational move — which is exactly what the loop wants.
 export const PERSONA_TOOLS = 'You are a senior engineer working in a repository through file tools. '
   + 'ALWAYS use absolute paths — relative paths resolve against the process, not the repository, and will be denied. '
+  // F98's residual: the fence ALREADY denies these (planrun's Gate deny list), and the
+  // spine is written outside the patient entirely — but nothing ever SAID so, and a
+  // denial is a wall while a stated law is a map. The way a worker learned the rule was
+  // by spending rounds of a bounded attempt probing bookkeeping files, and the rounds a
+  // probe costs are rounds the fix does not get. Registered here, beside the other fence
+  // fact a worker cannot infer, so it renders for every worker on every grant.
+  // the names are SPELLED FROM the one home (`ARBITER_BOOK_STORES`) so the stated
+  // law can never drift from the fence that enforces it
+  + `The repository root also holds the arbiter's own books — ${GATE_AUDIT_FILE}, ${ARBITER_BOOK_STORES.join(', ')}, and this run's spine. `
+  + 'They are ALWAYS denied and record how you are being judged, never anything about the task: never read them, and never try to route around the denial. '
   + 'You are ONE attempt inside an automated loop: when you finish, a test suite runs and, if it still fails, you are called again with its output. '
   + 'So do not try to be certain before acting. Read only what you need to form your best hypothesis, make the change with the write tool, and stop. '
   + 'A wrong cheap attempt is corrected by the next round; exhaustive reading is not — every file you read is re-sent on every later round and the run has a hard budget it can exhaust before you ever write. '