bareloop 0.7.0 → 0.9.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) } : {}),
       };
     }
   }
@@ -359,10 +374,17 @@ export const GAP_KEEP_TRIM_MARKER = 'more elided by the';
  * `keepPattern` is set (F28), lines of the WHOLE stream matching it are also
  * carried in a clearly-delimited block between head and tail — capped — so the
  * failing-test names buried in the middle still reach the worker.
+ * Exported for the ONE reason `GAP_KEEP_TRIM_MARKER` above is: a second consumer
+ * that needs a gap bounded must reuse THIS envelope, not spell its own. A private
+ * copy would be a second truncation scheme, and the two would drift on exactly the
+ * property that matters — whether the red lines survive, and whether the trim
+ * announces itself (F28: silent truncation is the disease this function cures).
+ * The close path is unchanged: `runClose` still calls it with the stage's own
+ * `gapKeep`, byte-identically.
  * @param {string} s the (redacted) close output
  * @param {string} [keepPattern] regex source; matching lines survive the elision
  */
-function boundGap(s, keepPattern) {
+export function boundGap(s, keepPattern) {
   if (s.length <= GAP_HEAD + GAP_TAIL + 100) return s;
   const head = s.slice(0, GAP_HEAD);
   const tail = s.slice(-GAP_TAIL);

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
@@ -594,7 +618,11 @@ function readGradeSeed(seen) {
  * **The declared fold, not a re-derivation.** A restarted try's own `try-start`
  * carries the fold it inherited (`priorSpentUsd`/`priorWallMs`), so a resume OF a
  * resume adds only its own new rounds. Re-deriving from the whole file would bill an
- * abandoned attempt twice.
+ * abandoned attempt twice. The REPLAN ledger (`priorReplans`/`priorReplanGrantUsed`)
+ * folds on this same mechanism and deliberately not on `readGradeSeed`'s: a grade seed
+ * feeds a readout, so its documented one-leg-per-resume shortening can only under-claim
+ * a direction, while an under-claimed CEILING is a refilled allowance and every kill
+ * would buy one (PRD v1.12 — the replan bound is the RUN's).
  *
  * **KNOWN LIMIT, stated rather than discovered later.** A call that was killed BEFORE it
  * returned left no event at all — no `worker-round`, no `selection-result` — so money it
@@ -688,6 +716,19 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
     // declaration existed, or a try nobody resumed — both are honestly zero.
     declaredRounds: !('priorRounds' in ev) ? 0
       : (typeof ev.priorRounds === 'number' && Number.isFinite(ev.priorRounds) && ev.priorRounds >= 0 ? ev.priorRounds : null),
+    // the REPLAN ledger this attempt was already carrying, on the same declared-fold
+    // mechanism and with the same `> 0` belt as the money. It has to fold this way
+    // rather than the grade seed's way: `readGradeSeed`'s chain shortens by one leg
+    // per resume, which under-claims — harmless for a readout, and for a CEILING an
+    // under-claim IS a refilled allowance, one per kill (PRD v1.12).
+    declaredReplans: typeof ev.priorReplans === 'number' && Number.isFinite(ev.priorReplans) && ev.priorReplans > 0 ? Math.floor(ev.priorReplans) : 0,
+    // the F85-C latch rides BESIDE the count, never derived from it: a chain can have
+    // spent the ordinary ceiling with the arbiter's one extra still unearned, and
+    // deriving one from the other would collapse those two states into one
+    declaredGrantUsed: ev.priorReplanGrantUsed === true,
+    // this window's OWN replans, counted from the records the runner emits — the same
+    // `replan` event a human reads, so the ledger and the log cannot disagree
+    windowReplans: 0, windowGrantUsed: false,
     roundsUsd: 0, roundsComplete: true, r1Written: false, jobEnd: null,
     /** @type {any[]} the window's own events, so the SAME `readTry` the live loop uses
      * reads a graded-but-unrecorded try — never a second reader spelling it differently */
@@ -745,6 +786,16 @@ export function readResume(events, { deathAt = null, direct = false, resumableOu
       open.jobEnd = ev;
     } else if (ev.type === 'bridge-write') {
       open.r1Written = true;
+    } else if (ev.type === 'replan') {
+      // ONE record per replan the runner drafts, so counting them IS the leg's ledger
+      // — never re-derived from `plan-accepted` (a resumed leg emits one of those for a
+      // plan it RELOADED, which would read as a redraft nobody paid for).
+      open.windowReplans += 1;
+      // the arbiter stamps `granted` only on the extra it granted past the ordinary
+      // ceiling, and stamps nothing on the ordinary one — so PRESENCE is the whole
+      // signal, and reading it by presence keeps this reader honest about a reading it
+      // does not itself make (never re-deciding whether the trend deserved it).
+      if (ev.granted !== undefined) open.windowGrantUsed = true;
     } else if (ev.type === 'try-end') {
       completed.push({ ...ev, seq: undefined, ts: undefined, inherited: true });
       if (open.bridge) tried.push(open.bridge);
@@ -815,6 +866,30 @@ 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
+        // BOUND, where under-claiming is a refilled allowance and every kill would buy
+        // one (PRD v1.12: unlimited replanning launders thrash as adaptation). So it
+        // reads the declared fold plus THIS window's own records — the same arithmetic
+        // as `priorSpentUsd`, which is what makes a resume of a resume inherit leg 1.
+        //
+        // The abandoned windows are not read, for the money's exact reason: the
+        // restart DECLARED what it inherited, so counting the window it abandoned
+        // would charge the chain twice for one leg's replans.
+        replans: open.declaredReplans + open.windowReplans,
+        replanGrantUsed: open.declaredGrantUsed || open.windowGrantUsed,
         priorSpentUsd: open.declaredSpentUsd + open.roundsUsd,
         // F83 — was that fold EXACT? Three sources, because `runJob` decides the same
         // question from more than this window can see (src/run.js: `!unpriced &&
@@ -1017,7 +1092,7 @@ export async function runReuse(opts) {
   const runid = opts.runid ?? Date.now().toString(36);
   const resume = isObj(opts.resume) ? /** @type {any} */ (opts.resume) : null;
   /** a try that inherits nothing: the ordinary, non-resumed attempt */
-  const NO_PRIOR = { spentUsd: 0, wallMs: 0, spendComplete: true, rounds: /** @type {number|null} */ (0), grades: /** @type {any[]} */ ([]) };
+  const NO_PRIOR = { spentUsd: 0, wallMs: 0, spendComplete: true, rounds: /** @type {number|null} */ (0), grades: /** @type {any[]} */ ([]), replans: 0, replanGrantUsed: false };
 
   /** @type {any[]} */
   const tries = [];
@@ -1113,7 +1188,7 @@ export async function runReuse(opts) {
 
   /** the shared per-try execution: run the job, read the spine, write the box (R1).
    * @param {any|null} bridge @param {number} n
-   * @param {{spentUsd: number, wallMs: number, spendComplete: boolean, rounds: number|null, grades: any[]}} [prior]
+   * @param {{spentUsd: number, wallMs: number, spendComplete: boolean, rounds: number|null, grades: any[], replans: number, replanGrantUsed: boolean}} [prior]
    *   RESUME — what a KILLED attempt of this same try already consumed, and what it
    *   already measured. Money and wall are FOLDED into the attempt (`runJob`'s own ledger
    *   and clock start partly spent) rather than shrinking the caps, so the signed per-try
@@ -1121,14 +1196,23 @@ export async function runReuse(opts) {
    *   way but on the ROW alone (nothing enforces a round bound here), and `null` — an
    *   attempt whose turns could not be counted — is reported, never folded. `grades` are
    *   the close readings that leg recorded, handed on as the run trend's BASELINES: they
-   *   feed the HALT READOUT alone and spend none of this attempt's bounds.
+   *   feed the HALT READOUT alone and spend none of this attempt's bounds. `replans` /
+   *   `replanGrantUsed` are the opposite kind of inheritance and sit here for that
+   *   contrast: they SPEND a bound (the plan flow's replan ceiling), because that ceiling
+   *   is the RUN's by doctrine and a fresh one per kill is the creep v1.12 forbids.
    * @param {any} [seed] RESUME (v2) — WHERE that attempt was killed (`readResume`'s
    *   `restart.seed`): the plan it accepted and the steps it finished. The fold says how
    *   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;
@@ -1142,6 +1226,15 @@ export async function runReuse(opts) {
       // means "a spine older than this field", and a reader that cannot tell that from a
       // predecessor's honest unknown would launder the unknown into a zero (F6).
       ...(resumed ? { priorSpentUsd: prior.spentUsd, priorWallMs: prior.wallMs, priorSpendComplete: prior.spendComplete, priorRounds: prior.rounds, resumedFrom: resume?.fromRunid ?? runid } : {}),
+      // the REPLAN ledger, declared on the same record and for the same reason as the
+      // money: the next reader adds only its own window's `replan` records to this
+      // number, so a chain of resumes folds once instead of restarting the ceiling at
+      // whichever leg it happens to be reading (PRD v1.12 — the bound is the RUN's).
+      // Declared independently of `resumed`, which is a MONEY/WALL test: a leg can
+      // replan without buying a round the fold would notice, and gating the ledger on
+      // the wallet would drop it exactly there. Only when there is one to state — a
+      // decorative zero is indistinguishable from a leg nobody folded.
+      ...(prior.replans > 0 ? { priorReplans: prior.replans, priorReplanGrantUsed: prior.replanGrantUsed } : {}),
       // WHERE it picks up, on the row's own record: a try that restarts at step 3 of 4 is
       // a materially different attempt from one that restarts at its beginning, and a
       // reader must not have to infer which happened from the absence of a scout.
@@ -1173,7 +1266,16 @@ export async function runReuse(opts) {
         // restarted leg would report `flat` on a run that was converging. Only when there
         // ARE grades: an empty array is the cold path, and the cold path stays identical.
         ...(prior.grades.length ? { resumeGrades: prior.grades } : {}),
+        // and the replan LEDGER. Same omission class as the two above, with a sharper
+        // cost: a grade seam that never arrives makes a readout say `flat`, while a
+        // ceiling that never arrives is spent by the dead leg and fresh in this one —
+        // 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) {
@@ -1233,7 +1335,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 });
@@ -1366,6 +1468,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
@@ -1446,6 +1561,12 @@ export async function runReuse(opts) {
         // this run make progress" and "is this loop out of ideas" are two questions,
         // and one instrument answering both is how they come to disagree.
         grades: Array.isArray(rs.grades) ? rs.grades : [],
+        // the replan LEDGER the chain has spent — belted like the money and NOT like
+        // the grades, because this one seeds a BOUND: a garbage or negative figure
+        // that read through as a widening is the ceiling being refilled by a corrupt
+        // spine (PRD v1.12). The latch rides beside the count, never derived from it.
+        replans: typeof rs.replans === 'number' && Number.isFinite(rs.replans) && rs.replans > 0 ? Math.floor(rs.replans) : 0,
+        replanGrantUsed: rs.replanGrantUsed === true,
       }
       : NO_PRIOR;
     const remainingCapUsd = envelope.perTryBudgetUsd - prior.spentUsd;
@@ -1459,7 +1580,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,
     });
 
@@ -1497,7 +1621,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);
@@ -1513,7 +1637,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;
       }
@@ -1581,7 +1705,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

@@ -116,6 +116,22 @@ async function primitiveSmoke(workdir) {
  *   chain, not just the leg: without them a leg that re-grades an unchanged tree reports
  *   `flat` — "revise the goal" — on a run that was converging when the money ran out.
  *   Counts and stage names only; no close bytes cross this seam. Absent is the cold path.
+ * @param {{count?: number, grantUsed?: boolean}|null} [opts.resumeReplans] RESUME — the
+ *   replan LEDGER the chain has already spent (`readResume`'s `restart.replans` /
+ *   `restart.replanGrantUsed`), forwarded to the plan flow, which seeds its ceiling with
+ *   it. Its sibling above feeds a READOUT; this one feeds a BOUND, and that is the whole
+ *   difference: `replanned`/`varianceGrantUsed` are locals in `runPlan`, so without this
+ *   every kill hands the next leg a fresh allowance of an allowance PRD v1.12 makes the
+ *   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
@@ -125,10 +141,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 = [] }) {
+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
@@ -204,6 +220,16 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     // it inherited, and it is the only field that can carry it forward.
     ...(spentUsd > 0 || priorFloor ? { priorSpentUsd: spentUsd, priorSpendComplete: !priorFloor } : {}),
     ...(typeof priorWallMs === 'number' && Number.isFinite(priorWallMs) && priorWallMs > 0 ? { priorWallMs } : {}),
+    // the REPLAN ledger, on the same declaration and for the same reason — a chain of
+    // resumes must fold once. This is the DIRECT-spine half of it: `readResume`'s
+    // `direct` mode opens its one implicit window on `job-start` and reads the fold off
+    // these very fields, so a U-path run resumed twice inherits leg 1's replans rather
+    // than restarting the ceiling at leg 2's window (PRD v1.12). Emitted only when there
+    // is one — a decorative `0` is indistinguishable from a run nobody folded, and the
+    // grant latch travels beside the count rather than being derived from it.
+    ...(typeof resumeReplans?.count === 'number' && Number.isFinite(resumeReplans.count) && resumeReplans.count > 0
+      ? { priorReplans: Math.floor(resumeReplans.count), priorReplanGrantUsed: resumeReplans.grantUsed === true }
+      : {}),
   });
 
   // 2. known-answer smoke before tokens (A3: silent degradation throws nothing)
@@ -256,7 +282,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,
+      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,118 @@ export function priceOf(r) {
     unpricedRounds: r?.metrics?.unpricedRounds ?? 0,
   };
 }
+
+// ── 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;
+}