bareloop 0.8.0 → 0.10.0

package/src/ralph.js

@@ -285,6 +285,21 @@ export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000,
   };
 }
 
+/**
+ * The staged gap's header — WHICH wall the close stopped at, in front of that
+ * wall's own output. A worker handed three stages' worth of output cannot tell
+ * which one it must satisfy, and `src/trend.js` parses this exact line to bucket
+ * a grade per stage (its `STAGE_HEADER`).
+ *
+ * Exported for the one reason `GAP_KEEP_TRIM_MARKER` is: a SECOND executor now
+ * renders staged gaps (`src/declaredclose.js`, the declared close), and two
+ * spellings of this line would be two instruments — the reader would silently
+ * stop bucketing whichever one drifted. Behaviour here is unchanged; this is the
+ * same template, named.
+ * @param {string} name @param {string} gap
+ */
+export const stageGap = (name, gap) => `close stage "${name}" failed:\n${gap}`;
+
 /**
  * Run a STAGED close (PRD v1.28) — an ordered list of named command stages, run
  * in order until one renders a verdict that is not `satisfied`. The return is
@@ -310,7 +325,7 @@ export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000,
  * @param {{timeoutMs?: number, cwd?: string}} [opts]
  * @returns {Promise<any>} runClose's verdict shape, plus `stage` and `stages`
  */
-export async function runStages(stages, redact = (s) => s, { timeoutMs, cwd } = {}) {
+export async function runStages(stages, redact = (s) => s, /** @type {{timeoutMs?: number, cwd?: string}} */ { timeoutMs, cwd } = {}) {
   const ran = [];
   let last;
   for (const st of stages) {
@@ -326,9 +341,9 @@ export async function runStages(stages, redact = (s) => s, { timeoutMs, cwd } =
         ...r,
         stage: st.name,
         stages: ran,
-        // The gap says WHICH wall, then the wall's own output. A worker handed
-        // three stages' worth of output cannot tell which one it must satisfy.
-        ...(r.gap ? { gap: `close stage "${st.name}" failed:\n${r.gap}` } : {}),
+        // The gap says WHICH wall, then the wall's own output (`stageGap`, the
+        // one spelling — the declared executor renders the same header).
+        ...(r.gap ? { gap: stageGap(st.name, r.gap) } : {}),
       };
     }
   }
@@ -575,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).',

package/src/reuse.js

@@ -48,7 +48,7 @@ import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { loadRegistry, saveBridge, appendGreen, appendRed, mintBridge, registryExists } from './bridges.js';
 import { renderListing, selectionPrompt } from './selection.js';
-import { stageClose } from './plan.js';
+import { closeStagesOf } from './plan.js';
 import { MIN_WALL_MS, jobSpecHash } from './job.js';
 import { isObj, isNonEmptyString } from './validate.js';
 import { readGrade } from './trend.js';
@@ -498,6 +498,30 @@ function readStepCheckpoint(seen) {
   };
 }
 
+/**
+ * The WORK BRANCH the dead leg created (PRD v1.57 §3), read off its own `work-branch`
+ * record — the one place the runner writes it down.
+ *
+ * It is read rather than re-derived, and that is the whole point. `workBranchName` is
+ * deterministic from the signed spec, so a restart computing it fresh would get the very
+ * name its predecessor already took and the collision walk would hand it
+ * `<name>-2` — a brand-new branch standing beside the work the resume exists to
+ * continue. The declared-fold precedent (`priorSpentUsd`, `priorReplans`): what the
+ * chain already did is DECLARED on the spine and inherited, never recomputed.
+ *
+ * The LAST record wins. A leg emits exactly one, but a window can reach back through an
+ * abandoned attempt of the same try, and the newest is the branch the work is actually
+ * sitting on.
+ * @param {any[]} seen the window's own events, in file order
+ * @returns {string|null} null on a spine older than the record, or a kill before 0c
+ */
+function readWorkBranch(seen) {
+  for (let i = seen.length - 1; i >= 0; i -= 1) {
+    if (seen[i].type === 'work-branch' && isNonEmptyString(seen[i].branch)) return String(seen[i].branch);
+  }
+  return null;
+}
+
 /**
  * The dead leg's CLOSE GRADES, in order — the trend baselines a resumed leg
  * inherits (PRD v1.46 §3, and hamr's approved #2: *a resumed run's trend judges the
@@ -641,7 +665,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 }`
  */
@@ -792,7 +816,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
@@ -842,6 +909,17 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
         // restart already re-graded that tree. Counting both would enter the same
         // reading twice and flatten a chain that moved.
         grades: readGradeSeed(open.seen),
+        // the WORK BRANCH this leg's uncommitted work is sitting on (v1.57 §3). Read
+        // from THIS window first and then from the newest abandoned window of the same
+        // try, on the checkpoint's own rule and for the checkpoint's own reason: the
+        // branch — like the plan — is a fact about the TREE, and the tree survives an
+        // attempt that died before recording anything of its own. Null is the honest
+        // answer for a leg killed before 0c (or a spine older than the record); the
+        // resume then takes the cold path and creates one, which is correct, because a
+        // leg that never branched has no work to strand.
+        branch: readWorkBranch(open.seen)
+          ?? abandoned.filter((w) => w.n === open.n).map((w) => readWorkBranch(w.seen)).filter(Boolean).at(-1)
+          ?? null,
         // the REPLAN ledger, folded like the money one line below and deliberately
         // NOT like the grades one line above. A grade seed feeds a READOUT and its
         // documented shortening chain can only under-claim a direction; this feeds a
@@ -928,7 +1006,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,
@@ -1170,8 +1255,14 @@ export async function runReuse(opts) {
    *   much of the try's allowance is gone; this says how much of its WORK is done, so the
    *   restart re-pays for neither the scout, the draft, nor a finished step. Null is the
    *   scout/draft death, where nothing paid is re-payable and the try simply restarts.
+   * @param {string|null} [branch] RESUME (v1.57 §3) — the WORK BRANCH that attempt's work
+   *   is sitting on (`readResume`'s `restart.branch`). The name is derived from the SIGNED
+   *   spec and is therefore the same on every leg, so a restart that recomputed it would
+   *   collide with its own predecessor and be handed a fresh `-2` beside the work it came
+   *   back for. Declared and inherited, exactly like the money and the replan ledger. Null
+   *   is the cold path, and also the leg killed before it ever branched.
    * @returns {Promise<any>} the try row */
-  const runTry = async (bridge, n, prior = NO_PRIOR, seed = null) => {
+  const runTry = async (bridge, n, prior = NO_PRIOR, seed = null, branch = null) => {
     const mode = bridge ? 'bridge' : 'cold';
     const name = bridge ? bridge.name : null;
     const resumed = prior.spentUsd > 0 || prior.wallMs > 0;
@@ -1231,6 +1322,10 @@ export async function runReuse(opts) {
         // a bound the operator signed, widened by a kill (PRD v1.12).
         ...(prior.replans > 0 ? { resumeReplans: { count: prior.replans, grantUsed: prior.replanGrantUsed } } : {}),
         ...(seed ? { resumeSeed: seed } : {}),
+        // …and WHERE its work is. Same omission class as the three folds above, with its
+        // own cost: a branch that never arrives is not a wrong number but a SECOND branch,
+        // and the leg would carry on beside the tree it was resumed to continue.
+        ...(branch ? { resumeBranch: branch } : {}),
         bridge,
       });
     } catch (e) {
@@ -1290,7 +1385,7 @@ export async function runReuse(opts) {
         name: name ?? job.job,
         goal: job.goal,
         specHash: trySpecHash,
-        closeStageNames: (stageClose(job.close) ?? []).map((/** @type {any} */ s) => s.name),
+        closeStageNames: (closeStagesOf(job) ?? []).map((/** @type {any} */ s) => s.name),
         toolsUsed: [...new Set((read.plan.steps ?? []).flatMap((/** @type {any} */ s) => s.tools ?? []))],
       };
       row.bridgeWrite = writeGreen(bridge, meta, { ...record, plan: read.plan });
@@ -1423,6 +1518,19 @@ export async function runReuse(opts) {
         decision: 'The plan flow cannot execute this job\'s close — it runs commands whose exit codes are truth. Nothing was judged, and no workflow can be graded by a close that will not run, so the next try and the cold leg would refuse identically for $0 apiece.',
         options: ['restate the close as a staged (or single predicate) close — a spec edit, whose new hash needs re-approval', 'wait for the verdict-classes rung'],
       },
+      'branch-red': {
+        // NOT re-filed, for `interpreter-red`'s reason plus one of its own: the runner
+        // already escalated it at the fault's own site, and the fault is the OPERATOR's
+        // state (a patient that is not a git checkout, a crowded branch namespace),
+        // never a library failing — the ledger excludes it for exactly that.
+        refile: false,
+        decision: 'The run could not create its own work branch, and no job runs on the branch it was handed (PRD v1.57 §3). That is a property of the PATIENT, not of any stored workflow: every further try and the cold leg would refuse identically, for $0 apiece.',
+        options: [
+          'make the patient a git checkout with at least one commit',
+          'free the work-branch name (delete or rename the stale branches this run collided with)',
+          'abandon the run',
+        ],
+      },
       'interpreter-red': {
         // NOT re-filed as an escalation. `interpreter-red` is one of the categories the
         // ledger CLASSIFIES — it aims a runtime-red at a library — and runJob already
@@ -1522,7 +1630,10 @@ export async function runReuse(opts) {
       // `gradesInherited` is a COUNT, and only when there is one to state: the seam
       // carries stage names and numbers, never a close byte — the spine is append-only,
       // so a gap that crosses here crosses for good.
-      restart: rs ? { n: rs.n, mode: rs.mode, bridge: rs.bridge ?? null, priorSpentUsd: prior.spentUsd, priorWallMs: prior.wallMs, priorSpendComplete: prior.spendComplete, remainingCapUsd, remainingWallMs, resumedAt: rs.seed ? { phase: rs.seed.phase, stepsDone: rs.seed.completedSteps.length, stepsPlanned: rs.seed.plan?.steps?.length ?? null } : null, ...(prior.grades.length ? { gradesInherited: prior.grades.length } : {}) } : null,
+      restart: rs ? { n: rs.n, mode: rs.mode, bridge: rs.bridge ?? null, priorSpentUsd: prior.spentUsd, priorWallMs: prior.wallMs, priorSpendComplete: prior.spendComplete, remainingCapUsd, remainingWallMs, resumedAt: rs.seed ? { phase: rs.seed.phase, stepsDone: rs.seed.completedSteps.length, stepsPlanned: rs.seed.plan?.steps?.length ?? null } : null, ...(prior.grades.length ? { gradesInherited: prior.grades.length } : {}),
+        // WHERE it comes back to (v1.57 §3), stated before anything is spent rather than
+        // discovered from the restarted leg's own `work-branch` record afterwards
+        ...(rs.branch ? { branch: rs.branch } : {}) } : null,
       nextTry: rs ? null : startN,
     });
 
@@ -1560,7 +1671,7 @@ export async function runReuse(opts) {
       if (rs.mode === 'cold') {
         // every bridge try was already spent before the cold leg started: the loop below
         // has nothing left to authorize, and the restart IS the cold attempt
-        coldRestart = { n: typeof rs.n === 'number' ? rs.n : tries.length + 1, prior, seed: rs.seed ?? null };
+        coldRestart = { n: typeof rs.n === 'number' ? rs.n : tries.length + 1, prior, seed: rs.seed ?? null, branch: rs.branch ?? null };
         startN = resolved.bridgeTries + 1;
       } else {
         const entry = loadRegistry(registryDir).bridges.find((/** @type {any} */ b) => b.name === rs.bridge);
@@ -1576,7 +1687,7 @@ export async function runReuse(opts) {
           });
         }
         tried.add(entry.name);
-        const stop = afterTry(await runTry(entry, rs.n, prior, rs.seed ?? null));
+        const stop = afterTry(await runTry(entry, rs.n, prior, rs.seed ?? null, rs.branch ?? null));
         if (stop) return stop;
         startN = rs.n + 1;
       }
@@ -1644,7 +1755,7 @@ export async function runReuse(opts) {
   // the verdict that attempt actually earned.
   const inheritedCold = coldRestart ? null : tries.find((t) => t.mode === 'cold' && t.inherited) ?? null;
   const cold = coldRestart
-    ? await runTry(null, coldRestart.n, coldRestart.prior, coldRestart.seed)
+    ? await runTry(null, coldRestart.n, coldRestart.prior, coldRestart.seed, coldRestart.branch)
     : inheritedCold ?? await runTry(null, tries.length + 1);
   const coldStop = afterTry(cold);
   if (coldStop) return coldStop;

package/src/root.js

@@ -30,6 +30,7 @@
 // UNRELIABLE red-set for comparison. Imported (never re-spelled) so the detector
 // keys off the exact string the shell emits — a magic string here would drift.
 import { GAP_KEEP_TRIM_MARKER } from './ralph.js';
+import { GAP_TRIM_MARKER } from './kinds.js';
 
 /**
  * Strip a trailing duration stamp from a kept-failure line. Real `node --test`
@@ -107,7 +108,13 @@ export function createRoot({ gapKeep, redact = (s) => s, writesInformative = tru
    */
   const keptSet = (gap, pattern) => {
     const re = pattern ? new RegExp(pattern, 'm') : keepRe;
-    if (!re || gap.includes(GAP_KEEP_TRIM_MARKER)) return null;
+    // BOTH trim announcements, because there are now two gap renderers: ralph's
+    // keep-block cap on a command close, and the kind executor's per-stage line
+    // cap on a DECLARED one. A trim the detector cannot see is worse than a
+    // missing detector — it makes the strong "reds unchanged" claim off a window
+    // that silently dropped failures (finding 5), which is the direction that
+    // manufactures a fixation reading out of an instrument that went blind.
+    if (!re || gap.includes(GAP_KEEP_TRIM_MARKER) || gap.includes(GAP_TRIM_MARKER)) return null;
     const lines = [...new Set(gap.split('\n').filter((l) => re.test(l)).map(normalizeRedLine))].sort();
     return lines.length ? lines : null;
   };

package/src/run.js

@@ -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'));
@@ -125,6 +126,13 @@ async function primitiveSmoke(workdir) {
  *   RUN's ("unlimited replanning launders thrash as adaptation"). It also rides onto this
  *   run's `job-start` as `priorReplans`, the declared-fold precedent `priorSpentUsd`
  *   already sets, so a resume OF a resume folds once. Absent is the cold path.
+ * @param {string|null} [opts.resumeBranch] RESUME — the WORK BRANCH the killed attempt
+ *   created and recorded on its own spine (`readResume`'s `restart.branch`). The branch
+ *   name is DERIVED from the signed spec and is therefore identical on every leg, so
+ *   without this the restart would collide with its own predecessor's branch and the
+ *   collision walk would mint a `-2` beside the work the resume exists to continue. The
+ *   fold's precedent exactly: the chain's state is DECLARED, never re-derived. Forwarded
+ *   verbatim to the plan flow; absent is the cold path.
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -134,10 +142,10 @@ async function primitiveSmoke(workdir) {
  *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
- *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' | 'provider-red' |
+ *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `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 }) {
+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 }) {
   // 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
@@ -275,7 +283,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,
+      workdir, provider, nativeProvider, providerFor, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch,
       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/text.js

@@ -4,6 +4,11 @@
 // are two instruments (F2/F21, the adaptlearn instrument caveat). It replaced
 // N0's stripFences when the fence-robust upgrade landed at N2. priceOf is the
 // ONE spelling of the honest-null cost read for the same reason (F6).
+// `scrubRaw` is the third: the ONE way a model's raw output becomes a persisted
+// record, for the same reason again — a second writer that forgets the scrub is
+// a leak on the very trail the scrub exists to protect.
+
+import { redactSecrets } from './validate.js';
 
 // A fence counts as the artifact's WRAPPER only when it opens within this many
 // lines of the response — the chatty-preamble shape ("Here's the fix:\n```…").
@@ -64,3 +69,197 @@ export function priceOf(r) {
     unpricedRounds: r?.metrics?.unpricedRounds ?? 0,
   };
 }
+
+/**
+ * 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
+// copy of what the model actually said: the red named the position, the process
+// exited, and the only artifact that could have decided whether the malformation
+// is recurring (and therefore whether the scout must move to a structure-forced
+// tool call) went with it. A raw that is not written down is a diagnosis nobody
+// can make twice.
+//
+// Everything a persisted raw needs is HERE rather than at each writer, and the
+// reason is the `scrubRed` reason one layer up: the scrub, the bound and the
+// announcement are properties of PERSISTING A RAW, not of any one caller
+// remembering them. A future writer that reaches for a raw reaches for this.
+
+/**
+ * The ceiling on ONE persisted raw. Sized to the survey's own prompt-ingredient
+ * cap (`AUTHOR_SCOUT_BLOB_MAX`, 8000) rather than picked: the largest raw this
+ * repository produces is a survey, the archive's real surveys ran 5991-8056
+ * bytes, and a record that cannot hold one whole specimen cannot answer the
+ * question it exists for. The two constants are deliberately independent
+ * numbers — one bounds a PROMPT, this one bounds a RECORD.
+ */
+export const RAW_PERSIST_MAX = 8000;
+
+/**
+ * The announced-trim marker for a persisted raw. A NEW spelling rather than a
+ * reuse of `GAP_TRIM_MARKER` ('gap trimmed:'), and that is a decision, not
+ * decoration: `src/root.js` READS `GAP_TRIM_MARKER` to mean *this gap was cut,
+ * so Layer R must not compare it*, so a second producer of those bytes in a
+ * different population is exactly the F90 hazard — a reader must know every
+ * producer of its marker. Nothing reads this one yet; it exists so the trim
+ * announces itself (F28) and so a future reader has an unambiguous key.
+ */
+export const RAW_TRIM_MARKER = 'raw trimmed:';
+
+/**
+ * ONE raw model emission, ready to persist.
+ *
+ * Three things happen here and NONE of them is optional at a call site:
+ *   - the text goes through the ONE redactor (`redactSecrets`, over the ONE
+ *     `SECRET_PATTERNS` inventory). A raw is the single most likely record in
+ *     this system to carry a live credential: it is whatever a model read out
+ *     of a repository, verbatim, and it lands in a file that outlives the run;
+ *   - it is BOUNDED, and the bound ANNOUNCES itself with the full size (F28 —
+ *     a bound eats detail, never evidence). The cut is decoded rather than
+ *     sliced so a multi-byte character is never split in half;
+ *   - it carries its own address: which call produced it (`label`, the same
+ *     spelling the cost book meters under) and which attempt (`attempt`), plus
+ *     the typed failure that describes it when there is one.
+ *
+ * `cause`/`reason` are `null` when the emission was fine — an ABSENT failure is
+ * absent, never an empty string that reads like a diagnosis nobody wrote.
+ * @param {{label: string, attempt: number, text: unknown, cause?: string|null,
+ *   reason?: string|null, cap?: number}} o
+ * @returns {{label: string, attempt: number, bytes: number, trimmed: boolean,
+ *   text: string, cause: string|null, reason: string|null}}
+ */
+export function scrubRaw({ label, attempt, text, cause = null, reason = null, cap = RAW_PERSIST_MAX }) {
+  const scrubbed = redactSecrets(String(text ?? ''));
+  const buf = Buffer.from(scrubbed, 'utf8');
+  const trimmed = buf.length > cap;
+  // walk the cut BACK off any continuation byte (0b10xxxxxx): a byte-wise slice
+  // through a multi-byte character renders as a replacement char, and a record
+  // that garbles the evidence is a worse instrument than one that keeps a byte
+  // less of it
+  let end = cap;
+  while (trimmed && end > 0 && (buf[end] & 0xC0) === 0x80) end -= 1;
+  const kept = trimmed ? buf.subarray(0, end).toString('utf8') : scrubbed;
+  // the two diagnosis fields are rendered by `stampRaw` below, never here: the
+  // writer that stamps them LATER must go through the same one place, or the
+  // scrub becomes a property of when you knew the verdict
+  return stampRaw({
+    label,
+    attempt,
+    // the FULL size, always — the number a trim is measured against
+    bytes: buf.length,
+    trimmed,
+    // WITHHELD is measured off `end`, not off `cap`: the multi-byte walk-back above
+    // can cut up to three bytes short of the cap, and announcing `length - cap` would
+    // under-report the withheld bytes by exactly that much. An announced bound that
+    // states a number it did not withhold is the announcement failing at its one job.
+    text: trimmed
+      ? `${kept}\n[${RAW_TRIM_MARKER} ${buf.length - end} of ${buf.length} bytes withheld — the cap is ${cap} per raw]`
+      : kept,
+    cause: null,
+    reason: null,
+  }, { cause, reason });
+}
+
+/**
+ * Stamp a persisted raw with the verdict that DESCRIBES it — through the same
+ * boundary the raw's own text rode.
+ *
+ * It exists because the verdict is not known when the raw is created: a writer
+ * records the emission the moment the call returns (so a metered call can never
+ * be missing its output), and only classifies it afterwards. The obvious
+ * shape — assigning `cause`/`reason` onto the stored object at that later
+ * point — writes an UNSCRUBBED string into a record that is already past the
+ * one redactor, and `reason` is the worst field to do it to: it quotes the
+ * transport's own error prose, which nobody in this repo wrote and nobody
+ * bounds. So the stamp is a function, not an assignment, and `scrubRaw` renders
+ * its own two fields through it: ONE place decides how a diagnosis becomes
+ * persistable, exactly as ONE place decides it for the text.
+ *
+ * `cause` is enumerated (`SURVEY_CAUSES`) and passes through untouched; a mask
+ * over a closed set would only hide a bug in the set.
+ * @template {{cause: string|null, reason: string|null}} T
+ * @param {T} raw @param {{cause?: string|null, reason?: string|null}} o @returns {T}
+ */
+export function stampRaw(raw, { cause = null, reason = null }) {
+  raw.cause = cause ?? null;
+  raw.reason = reason === null || reason === undefined ? null : redactSecrets(reason);
+  return raw;
+}

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. '