bareloop 0.21.0 → 0.22.0

package/src/planrun.js

@@ -43,6 +43,8 @@ import {
 } from './kinds.js';
 import { workBranchName, prepareWorkBranch } from './workbranch.js';
 import { TRANSPORT_MAX_ATTEMPTS, isTransportFailure } from './transport.js';
+import { checkCloseAbsolutePaths, checkCloseByteSignature, checkStageByteSignature, checkCloseDirRequired } from './close-integrity.js';
+import { resolveCloseTimeoutMs, closeTimeoutBanner, TIMING_PREFLIGHT_CEILING_MS } from './closetimeout.js';
 
 const require = createRequire(import.meta.url);
 const { Loop, Retry, wireGate, HaltError } = require('bare-agent');
@@ -640,7 +642,14 @@ ${scoutBlob || '(no scout notes)'}`;
  *   ladder (src/ladder.js). Arbiter territory exactly as the count it replaced was —
  *   the runner sets it, the plan cannot express it, and no step may tighten or raise
  *   it.
- * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory)
+ * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory).
+ *   OPTIONAL as of PRD item 27/M3: absent, this run autosets it from a $0 seed
+ *   timing pass (or the spec's own signed `closeTimeoutMs` override) — an
+ *   explicit value here still wins outright (backward compatibility/test
+ *   control only, F133: `scripts/run-u.mjs`/`src/cli.js` never pass this).
+ * @param {string|null} [opts.closeDir] the close's own books directory (PRD
+ *   item 27/M3 Part B), forwarded to every close invocation as
+ *   `BARELOOP_CLOSE_DIR`
  * @param {number} [opts.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
  * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md):
  *        `false` on a FRESH run (no `resumeSeed`) skips the survey entirely — `scoutBlob`
@@ -811,12 +820,18 @@ ${scoutBlob || '(no scout notes)'}`;
  *   precisely the state the person rejected), and the words reach the PLANNER as new
  *   authoring. It is never a `humanRuling` — that answers a close's human STAGE, and
  *   a green-class job has none. Empty words are refused at the same seam every door is.
+ * @param {boolean} [opts.resumable=true] PRD item 27(c)/F130 — does THIS runner
+ *   support `--resume`? Forwarded verbatim from `runJob`; `run-u.mjs` leaves it at
+ *   the default (byte-identical to before this param existed), the bundle CLI
+ *   passes `false` so the three `--resume`-naming readouts below (`MONEY_OPTIONS`,
+ *   the resume-plan-red option, the fix-loop terminal) say "resume is `run-u`-only
+ *   in v1" instead of naming a flag that would fail if typed.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -916,6 +931,159 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     return 'close-unsupported';
   }
 
+  // ── close-absolute-path (PRD item 27(c), F129's general fix): the SAME
+  // detector `src/bundle.js` already applies at export time, now applied for
+  // EVERY job at run start, before the close-first precheck and before any
+  // provider call. A close script whose CONTENT bakes in an absolute path
+  // that exists on disk judges the wrong tree by construction (F129) — the
+  // spec's own `cmd` field naming the script is the address and stays legal;
+  // only the script's bytes are judged. `readCloseScripts`/
+  // `checkCloseAbsolutePaths` live in `src/close-integrity.js` so this and
+  // `exportBundle` never drift into two spellings of the same rule.
+  {
+    const integrity = checkCloseAbsolutePaths(job, workdir);
+    if (!integrity.ok) {
+      const detail = integrity.reds.map((r) => `${r.stage}: "${r.literal}"`).join('; ');
+      emit('escalation', {
+        category: 'close-absolute-path', decisionReady: true,
+        decision: 'A close script bakes in an absolute path that exists on disk — it would judge the wrong tree by construction (F129), so nothing was run and nothing was spent.',
+        options: ['fix the close script to read the cwd it is given, never a baked-in path', 'abandon the task'],
+        detail,
+      });
+      return 'close-absolute-path';
+    }
+  }
+
+  // ── close-tampered (PRD item 27/M2, N4's own general fix): the job's
+  // signature covers a close STAGE's byte-exact CONTENT (`close[].sha256`),
+  // not only the `cmd` path naming it — `jobSpecHash` already covers this
+  // field with no hash-function change (it sits inside the signed spec), so
+  // the only thing left to verify is that the SCRIPT ON DISK still is what
+  // was signed. Same seam as `close-absolute-path` immediately above (run
+  // start, $0, before the close-first precheck and before any provider
+  // call) and the same detector module — `checkCloseByteSignature` reuses
+  // `readCloseScripts`, so this and the runtime re-verify inside
+  // `runCloseStages` below can never drift into two spellings of "which
+  // bytes were signed".
+  {
+    const sig = checkCloseByteSignature(job, workdir);
+    if (!sig.ok) {
+      const detail = sig.reds.map((r) => `${r.stage}: expected ${r.expected.slice(0, 12)}… got ${r.actual ? `${r.actual.slice(0, 12)}…` : '<unreadable>'}`).join('; ');
+      emit('escalation', {
+        category: 'close-tampered', decisionReady: true,
+        decision: "A close script's bytes no longer match its signed sha256 — it would run something other than what was approved, so nothing was run and nothing was spent.",
+        options: ['restore the close script to its signed bytes', 're-sign the close if the change is intentional (a new spec hash needs re-approval)', 'abandon the task'],
+        detail,
+      });
+      return 'close-tampered';
+    }
+  }
+
+  // ── close-dir-required (PRD item 27/M3 Part B): a close script that reads
+  // its own books directory (`BARELOOP_CLOSE_DIR`) and gets none would run
+  // silently against `undefined` — refuse at the same $0 seam as the two
+  // checks immediately above, before any tokens spend.
+  {
+    const dirCheck = checkCloseDirRequired(job, workdir, closeDir);
+    if (!dirCheck.ok) {
+      const detail = dirCheck.reds.map((r) => `${r.stage}: ${r.path}`).join('; ');
+      emit('escalation', {
+        category: 'close-dir-required', decisionReady: true,
+        decision: 'A close script reads BARELOOP_CLOSE_DIR (its own books directory, deliberately outside the patient tree) but the runner was given none — nothing was run and nothing was spent.',
+        options: ['run this job through a runner that sets closeDir (run-u.mjs, or the bundle CLI)', 'abandon the task'],
+        detail,
+      });
+      return 'close-dir-required';
+    }
+  }
+
+  // ── close timeout: autoset + signed override (PRD item 27/M3). hamr,
+  // 2026-09-06: "both … autoset and can be override, same like api pricing".
+  // Constants (`CLOSE_TIMEOUT_FLOOR_MS`, `CLOSE_TIMEOUT_K`) are hamr's own
+  // arbiter constants (2026-09-07) — never agent- or adopter-settable.
+  //
+  // Precedence, all $0, before any provider call:
+  //   1. an EXPLICIT `closeTimeoutMs` runtime option (the pre-M3 shell/test
+  //      knob) wins outright — kept for backward compatibility and for tests
+  //      that force a specific close-timeout scenario; it is never the signed
+  //      spec field and prints its own honest word rather than "signed
+  //      override". F133 (run mtqwmb9l): this used to also be how
+  //      `scripts/run-u.mjs` fed its OWN pre-resolved ceiling through, which
+  //      printed the number correctly here but under the wrong word
+  //      ("explicit runner override") beside run-u's own already-correct
+  //      "estimated"/"signed override" line — two banners for one number,
+  //      the second one lying about its source. Fixed by making this the
+  //      ONLY caller of `closeTimeoutMs` an operator/runner is meant to use:
+  //      `run-u.mjs` no longer resolves-and-passes it at all (see its own
+  //      comment); this tier is test/back-compat-only again.
+  //   2. the SIGNED spec field `job.closeTimeoutMs` — the operator's own
+  //      number, which may legally sit above OR below the autoset estimate
+  //      (F113's rates-passthrough shape).
+  //   3. AUTOSET — a $0 timing pass runs every stage once (ignoring verdicts;
+  //      first-red-wins stays for the real precheck below), under the
+  //      generous provisional ceiling `TIMING_PREFLIGHT_CEILING_MS` so a
+  //      genuinely hung stage still ends. `max(FLOOR, K × slowest)` becomes
+  //      the ceiling every close run in this call uses, and a stage that
+  //      timed out DURING THE TIMING PASS is `close-timing-red` — the close
+  //      cannot run on this machine, and the provider was never called.
+  //
+  // The pass is SKIPPED whenever an override already exists (case 1 or 2):
+  // running every stage a second time just to throw the reading away would
+  // waste real machine time before any provider call, and — measured risk —
+  // a close stage a test or an operator deliberately made slow/hanging would
+  // then block for up to 10 minutes for no purpose. "Guesstimate only when no
+  // rate is given" is the same doctrine F113 already applies to pricing.
+  {
+    const explicitOverride = typeof closeTimeoutMs === 'number' && Number.isFinite(closeTimeoutMs) ? closeTimeoutMs : null;
+    if (explicitOverride !== null) {
+      // A caller-passed runtime option wins outright and skips the timing
+      // pass entirely — this is the pre-M3 shell/test knob (backward
+      // compatibility only, F133: no production runner passes this anymore —
+      // `scripts/run-u.mjs` and `src/cli.js` both leave this call site
+      // nothing to autoset from but the autoset/signed-override tiers below).
+      closeTimeoutMs = explicitOverride;
+      emit('close-timing', { perStage: [], slowestMs: null, slowestName: null, ceilingMs: closeTimeoutMs, source: 'explicit' });
+      console.log(closeTimeoutBanner({ ceilingMs: closeTimeoutMs, source: 'explicit' }));
+    } else {
+      const resolved = await resolveCloseTimeoutMs({ job, stages: stagedClose, cwd: workdir, redact: scrub });
+      if (resolved.timedOut) {
+        // `timedOut` is only ever true alongside a real `timing` reading
+        // (`resolveCloseTimeoutMs` never sets one without the other) — the
+        // cast states that correlation for the checker, which cannot infer
+        // it across the two independent optional fields on its own.
+        const timing = /** @type {NonNullable<typeof resolved.timing>} */ (resolved.timing);
+        const detail = timing.perStage.filter((s) => s.timedOut).map((s) => s.name).join(', ');
+        emit('close-timing', { perStage: timing.perStage, slowestMs: timing.slowestMs, slowestName: timing.slowestName, ceilingMs: null, source: 'estimated' });
+        emit('escalation', {
+          category: 'close-timing-red', decisionReady: true,
+          decision: `A close stage did not finish within the timing preflight's own ceiling (${TIMING_PREFLIGHT_CEILING_MS}ms) — the close cannot run on this machine in a boundable time, so nothing was run and nothing was spent.`,
+          options: ['investigate why the stage hangs (infra/network/resource issue)', 'sign an explicit closeTimeoutMs override once the real duration is known', 'abandon the task'],
+          detail,
+        });
+        return 'close-timing-red';
+      }
+      closeTimeoutMs = /** @type {number} */ (resolved.closeTimeoutMs);
+      emit('close-timing', { ...(resolved.timing ?? { perStage: [], slowestMs: null, slowestName: null, anyTimedOut: false }), ceilingMs: closeTimeoutMs, source: resolved.source });
+      console.log(closeTimeoutBanner({ ceilingMs: closeTimeoutMs, source: resolved.source, slowestMs: resolved.timing?.slowestMs, slowestName: resolved.timing?.slowestName }));
+    }
+  }
+
+  // ── the wall must be able to fund at least one close under the EFFECTIVE
+  // ceiling just computed (PRD item 27/M3): `job.maxWallMs`'s own static
+  // floor (`MIN_WALL_MS`, src/job.js) assumed the library's un-autoset
+  // default — with autoset, the real per-stage ceiling is only known here, at
+  // run start, so the honest shape is a run-start check, never a silent
+  // clamp (a budget under one close cannot fund its own close, verbatim the
+  // reasoning `maxWallMs`'s own validator red already states).
+  if (typeof job.maxWallMs === 'number' && job.maxWallMs < closeTimeoutMs) {
+    emit('escalation', {
+      category: 'wall-under-close-timeout', decisionReady: true,
+      decision: `maxWallMs (${job.maxWallMs}ms) is under the effective close timeout (${closeTimeoutMs}ms) — a budget under one close cannot fund its own close, so nothing was run and nothing was spent.`,
+      options: ['raise maxWallMs to at least the printed close timeout and rerun (a spec edit, so the new hash needs re-approval)', 'sign a lower closeTimeoutMs override if the measured duration allows it (same re-approval)', 'abandon the task'],
+    });
+    return 'wall-under-close-timeout';
+  }
+
   // ── THE SIGNER'S ANSWER (N4 §1.4), read before anything costs anything.
   //
   // Three gates, and each refuses rather than guesses. A decision that is not one
@@ -1300,6 +1468,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     'revise the goal/spec so the work fits the time (same re-approval)',
     'abandon the task',
   ];
+  /** PRD item 27(c)/F130 — the honest escalation tail. `run-u.mjs` supports
+   * `--resume`; the exported bundle CLI does not (v1) and would print a flag
+   * that fails if typed. `resumable` (default `true`, `run-u`'s existing
+   * lines unchanged) picks which sentence names the resume lever. */
+  const resumeToCapNote = resumable
+    ? 'top up budgetUsd and rerun with --resume (resume-to-cap; a spec edit, so the new hash needs re-approval)'
+    : 'resume is `run-u`-only in v1 — top up budgetUsd and re-fire the bundle from the start (a spec edit, so the new hash needs re-approval)';
   /** MONEY's levers (PRD v1.46 §2), the same three shapes the wall's are, because a
    * money cut is the same KIND of stop: the run is out of an operator-owned
    * allowance, not out of capability, and the last verdict rendered stands. hamr's
@@ -1310,12 +1485,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * hash, so raising it is a new spec version somebody signs — the library only ever
    * names the lever, and never adjusts a budget itself (the permanent hard line). */
   const MONEY_OPTIONS = [
-    'top up budgetUsd and rerun with --resume (resume-to-cap; a spec edit, so the new hash needs re-approval)',
+    resumeToCapNote,
     'revise the goal/spec so the work fits the budget (same re-approval)',
     'abandon the task',
   ];
 
-  const closeOpts = { timeoutMs: closeTimeoutMs, cwd: workdir };
+  const closeOpts = { timeoutMs: closeTimeoutMs, cwd: workdir, closeDir };
   /** D8 — the DECLARED close's seed, filled in below before anything runs.
    * `null` for a command close, which has no baseline to measure against. */
   /** @type {{seedRef: string}|null} */
@@ -1329,7 +1504,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * The command path is byte-identical to what it was: same call, same options.
    * @param {any[]} stages
    */
-  const runCloseStages = (stages) => (declared
+  const runCloseStagesInner = (stages) => (declared
     ? runDeclaredStages(stages, scrub, {
       ...closeOpts,
       seedRef: /** @type {any} */ (declaredCtx).seedRef,
@@ -1359,6 +1534,34 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       }),
     })
     : runStages(stages, scrub, closeOpts));
+  /**
+   * PRD item 27/M2 — the re-verify that runs before EVERY close run, precheck
+   * included: `runCloseStagesInner` is the ONE seam every close execution in
+   * this runner goes through (the precheck's `judgeClose`, the preflight
+   * loop, the check-passes seam, and the close-fix loop via its own `judge`
+   * seam), so wrapping it here covers all of them without threading a
+   * verify call through each call site separately — the same reasoning
+   * `checkCloseAbsolutePaths`'s run-start placement already relies on (W4:
+   * "the staging itself lives in ONE place").
+   *
+   * A mismatch never reaches the executor: it returns a `close-tampered`
+   * verdict in the SAME shape `runClose`/`runStages` render (`{verdict,
+   * stage, detail}`), so every downstream reader that already keys off
+   * `Object.hasOwn(CLOSE_FAULTS, v.verdict)` (the precheck, the preflight
+   * loop, the post-fix read, and ralph's own judge-fault routing) treats it
+   * exactly like `crashed`/`timed-out`/`killed` — a forbidden-zone outcome,
+   * never retried, never fed back as a gap.
+   * @param {any[]} stages
+   */
+  const runCloseStages = async (stages) => {
+    const sig = checkStageByteSignature(stages, workdir);
+    if (!sig.ok) {
+      const r = sig.reds[0];
+      const detail = sig.reds.map((rr) => `${rr.stage}: expected ${rr.expected.slice(0, 12)}… got ${rr.actual ? `${rr.actual.slice(0, 12)}…` : '<unreadable>'}`).join('; ');
+      return { verdict: 'close-tampered', stage: r?.stage, detail };
+    }
+    return runCloseStagesInner(stages);
+  };
   /** @type {string|undefined} the stage that rendered the LAST close verdict (Layer R's red-set source) */
   let closeStage;
   /** @type {any} the LAST close verdict itself (W-2). A wall stop KEEPS the grade
@@ -3462,7 +3665,9 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
             : `${rep.strikes}/${rep.limit} strikes — the fix loop stopped making progress against the close's own numbers (${t.reading}). Continue, change approach, or stop?`,
           options: [
             'revise the goal/spec so the work is reachable (a spec edit, so the new hash needs re-approval)',
-            'top up budgetUsd and rerun with --resume, if the trend above says it was still converging',
+            resumable
+              ? 'top up budgetUsd and rerun with --resume, if the trend above says it was still converging'
+              : 'resume is `run-u`-only in v1 — top up budgetUsd and re-fire the bundle from the start, if the trend above says it was still converging',
             'abandon the task',
           ],
         };
@@ -3576,7 +3781,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // is not passed — it survives only inside the governor, as the bound for the
       // case the trend instrument is blind.
       middle, judge: async () => judgeClose(), ladder: fixGovernor, emit: emitL, redact: scrub,
-      closeTimeoutMs, cwd: workdir, workerWrites: w.workerWrites,
+      closeTimeoutMs, cwd: workdir, workerWrites: w.workerWrites, closeDir,
     });
   } catch (e) {
     planExecuted();

package/src/ralph.js

@@ -208,17 +208,24 @@ export const CLOSE_ENV_DENY = Object.freeze({
  *
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
  * @param {(s: string) => string} [redact] source scrubber; identity by default
- * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string }} [opts]
+ * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string, closeDir?: string|null }} [opts]
  *   close wall-clock cap (operator-set via the runner, never the config's — the
  *   agent must not author its arbiter's clock), the directory the close runs in
  *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
  *   success, the judgment-rendered signal, and the kept-failures pattern. All
  *   five are arbiter territory: the drafted workflow config cannot express any.
+ *   `closeDir` (PRD item 27/M3 Part B) is the close's OWN books directory —
+ *   pristine copies, calibration thresholds, logs — deliberately outside the
+ *   patient tree (the worker must never read the arbiter's books). Handed to
+ *   the child as `BARELOOP_CLOSE_DIR` (`CLOSE_DIR_ENV_VAR`,
+ *   src/close-integrity.js); a close script that needs one and gets none
+ *   instrument-stops itself, by the script's own contract — this seam only
+ *   ever THREADS the value, it never invents one.
  * @returns {Promise<{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
  *   gap?: string, exitCode?: number, signal?: string, detail?: string,
  *   judgedCount?: number|null, unaudited?: boolean}>}
  */
-export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, expect = 0, judged, gapKeep } = {}) {
+export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, expect = 0, judged, gapKeep, closeDir = null } = {}) {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT; // a `node --test` close inherits this from a test runner and silently no-ops — a fake green
   // …and the operator's credentials go with it (CLOSE_ENV_DENY above). A COPY is
@@ -229,6 +236,13 @@ export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000,
       || CLOSE_ENV_DENY.prefixes.some((p) => name.startsWith(p))
       || CLOSE_ENV_DENY.shape.test(name)) delete env[name];
   }
+  // PRD item 27/M3 Part B — a `BARELOOP_` name, deliberately not matched by
+  // any CLOSE_ENV_DENY rule above (checked: no name/prefix/suffix entry there
+  // touches it), set AFTER the strip loop so it can never be stripped by a
+  // future denylist edit either. Only set when the runner actually has one —
+  // an empty/absent `closeDir` leaves the child's env exactly as it was
+  // before this rung, so a script that never reads the variable is unaffected.
+  if (typeof closeDir === 'string' && closeDir.length > 0) env.BARELOOP_CLOSE_DIR = closeDir;
   const r = await spawnClose(close[0], close.slice(1), { env, cwd, timeoutMs });
 
   // ── forbidden zone, before any exit code is believed ──────────────────────
@@ -322,17 +336,17 @@ export const stageGap = (name, gap) => `close stage "${name}" failed:\n${gap}`;
  *
  * @param {any[]} stages the stage list (already validated by validateJob)
  * @param {(s: string) => string} [redact] scrub, applied at capture on EVERY stage
- * @param {{timeoutMs?: number, cwd?: string}} [opts]
+ * @param {{timeoutMs?: number, cwd?: string, closeDir?: string|null}} [opts]
  * @returns {Promise<any>} runClose's verdict shape, plus `stage` and `stages`
  */
-export async function runStages(stages, redact = (s) => s, /** @type {{timeoutMs?: number, cwd?: string}} */ { timeoutMs, cwd } = {}) {
+export async function runStages(stages, redact = (s) => s, /** @type {{timeoutMs?: number, cwd?: string, closeDir?: string|null}} */ { timeoutMs, cwd, closeDir } = {}) {
   const ran = [];
   let last;
   for (const st of stages) {
     // Sequential by construction (F68): stages run one at a time under a single
     // await, so nothing here ever has two closes in flight against one tree.
     const r = await runClose(st.cmd.trim().split(/\s+/), redact, {
-      timeoutMs, cwd, expect: st.expect, judged: st.judged, gapKeep: st.gapKeep,
+      timeoutMs, cwd, expect: st.expect, judged: st.judged, gapKeep: st.gapKeep, closeDir,
     });
     ran.push({ name: st.name, verdict: r.verdict, ...(r.exitCode !== undefined ? { exitCode: r.exitCode } : {}) });
     last = r;
@@ -443,6 +457,21 @@ export const CLOSE_FAULTS = Object.freeze({
     decision: 'The close exited without judging anything — it crashed rather than failed. Its exit code is NOT a verdict, in either direction.',
     options: ['fix what makes the close crash at startup', 'fix the close argv', 'lower the declared judgment floor if the suite legitimately shrank', 'abandon the task'],
   },
+  // PRD item 27/M2 (`docs/product/CLOSE-INTEGRITY-BUILD.md`) — a close
+  // script's bytes no longer match what was signed. Distinct from every row
+  // above: those are read off HOW THE CHILD PROCESS TERMINATED, and this one
+  // is decided BEFORE the process is even spawned (`runCloseStages`,
+  // `src/planrun.js`, re-verifies before every close run and short-circuits
+  // to this verdict on a mismatch, the same forbidden-zone shape as a
+  // crash). Never `close-red` (a judged "no" from a working close) and never
+  // `close-crashed` (an instrument fault the close itself hit) — this is a
+  // THIRD thing: the close that ran would not have been the one the operator
+  // approved.
+  'close-tampered': {
+    category: 'close-tampered',
+    decision: "A close script's bytes no longer match its signed sha256 — it would run something other than what was approved, so no verdict from it can be trusted.",
+    options: ['restore the close script to its signed bytes', 're-sign the close if the change is intentional (a new spec hash needs re-approval)', 'abandon the task'],
+  },
 });
 
 /**
@@ -529,9 +558,13 @@ export const CLOSE_FAULTS = Object.freeze({
  *   it to the gate audit's allow-decision writes. Injected like `redact` so the shell
  *   stays stdlib-only and dumb; consulted ONLY at a crashed verdict. With no seam, or
  *   with zero writes, a crash stays what it always was: an instrument stop.
+ * @param {string|null} [opts.closeDir] the close's own books directory
+ *   (PRD item 27/M3 Part B), forwarded to the raw `close` path's `runClose`
+ *   call unchanged; a caller supplying `judge` instead already closed over
+ *   its own `closeDir` and this param does nothing for it.
  * @returns {Promise<'green'|'escalated'>}
  */
-export async function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
+export async function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites, closeDir }) {
   // PARAM GUARD (the BA-4 class — a caller's malformed argument, which is the one
   // thing this shell throws for; a WORKER's bad reach comes back as a refusal
   // RESULT instead, and that rule is about feedback, not about the API contract).
@@ -660,7 +693,7 @@ export async function ralph({ middle, close, judge, capRuns, ladder, emit, redac
     emit('middle-done', { iteration });
     const v = judge
       ? await judge()
-      : await runClose(/** @type {string[]} */ (close), redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
+      : await runClose(/** @type {string[]} */ (close), redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep, closeDir });
     // Worker-crash attribution (F32, measured in F31: 4 of 7 battery rows). A crash is
     // still not a verdict (F17) — but a crash that FOLLOWS worker writes, on a run whose
     // precheck proved the close judged at baseline (run.js escalates a crash-at-precheck

package/src/reuse.js

@@ -1353,6 +1353,7 @@ export function resumeTreeGate({ head, seed, dirty }) {
  * @param {number} [opts.capRuns] forwarded
  * @param {number} [opts.strikeLimit] forwarded (a plan step's strike ceiling)
  * @param {number} [opts.closeTimeoutMs] forwarded
+ * @param {string} [opts.closeDir] forwarded (PRD item 27/M3 Part B)
  * @param {boolean} [opts.layerRoot] forwarded
  * @param {boolean|'cap'|'diff'} [opts.readShim] the read shim's ARM (A0/A1/A2/A3), forwarded verbatim
  * @param {any} [opts.resume] RESUME (module C) — a `readResume` reading of the KILLED
@@ -1371,7 +1372,7 @@ export async function runReuse(opts) {
   const {
     job, approvals, registryDir, patient, workdir, provider, selectionProvider,
     emit, ask, pinned = null, shortlist = null, forceCold = false,
-    providerFor, nativeProvider, capRuns, strikeLimit, closeTimeoutMs, layerRoot, readShim,
+    providerFor, nativeProvider, capRuns, strikeLimit, closeTimeoutMs, closeDir, layerRoot, readShim,
     runJob = shippedRunJob, now = () => Date.now(),
   } = opts;
   const runid = opts.runid ?? Date.now().toString(36);
@@ -1538,6 +1539,7 @@ export async function runReuse(opts) {
         ...(capRuns !== undefined ? { capRuns } : {}),
         ...(strikeLimit !== undefined ? { strikeLimit } : {}),
         ...(closeTimeoutMs !== undefined ? { closeTimeoutMs } : {}),
+        ...(closeDir !== undefined ? { closeDir } : {}),
         ...(layerRoot !== undefined ? { layerRoot } : {}),
         ...(readShim !== undefined ? { readShim } : {}),
         // the fold, and whether the fold is EXACT. `priorSpendComplete` used to stop at

package/src/reviewdoor.js

@@ -38,6 +38,7 @@ import { isDeclaredClose, runDeclaredStages, HITL_DECISION_RED } from './declare
 import { runStages } from './ralph.js';
 import { redactSecrets } from './validate.js';
 import { applyDoorDecision, PAUSE_TTL_MS } from './reuse.js';
+import { checkStageByteSignature } from './close-integrity.js';
 
 /** the door's own record, off the run's spine — the LAST one, because a run that
  * ends at a door writes exactly one and a reader that guesses which is which is a
@@ -92,6 +93,7 @@ const red = (code, detail, path = 'decision') => [{ code, path, detail }];
  * @param {string} opts.decision one of the three doors
  * @param {string|null} [opts.text] the rerun's words — the gap, and refused when empty
  * @param {number} [opts.closeTimeoutMs] the per-stage bound for the accept's re-run
+ * @param {string|null} [opts.closeDir] the close's own books directory (PRD item 27/M3 Part B), forwarded to the accept's re-run
  * @param {string|null} [opts.registryDir] the workflow registry, when the runner keeps one
  * @param {string|null} [opts.name] the workflow this run wrote its row against
  * @param {string|null} [opts.runid] the RUN's id, exactly as the bridge row records it
@@ -104,7 +106,7 @@ const red = (code, detail, path = 'decision') => [{ code, path, detail }];
  *   options: string[], ttlMs: number, note: string|null}>}
  */
 export async function answerReviewDoor({
-  job, workdir, events, decision, text = null, closeTimeoutMs,
+  job, workdir, events, decision, text = null, closeTimeoutMs, closeDir = null,
   registryDir = null, name = null, runid = null, at = null,
   now = Date.now, ttlMs = PAUSE_TTL_MS, emit = null,
 }) {
@@ -149,7 +151,7 @@ export async function answerReviewDoor({
   // this is the only branch that runs anything, and it runs the close's own
   // mechanical stages — never a second, weaker spelling of "is it still green".
   if (out.decision === 'accept') {
-    const proof = await proveMechanically({ job, workdir, events, closeTimeoutMs });
+    const proof = await proveMechanically({ job, workdir, events, closeTimeoutMs, closeDir });
     out.mechanical = proof.reading;
     if (!proof.ok) {
       out.reds = red('door-accept-red', proof.detail, proof.reading.stage ? `stage.${proof.reading.stage}` : 'close');
@@ -200,16 +202,24 @@ export async function answerReviewDoor({
 
 /**
  * The accept's re-proof: the close's MECHANICAL stages, run against the tree as it
- * stands now, through the SAME executors the run itself was judged by.
+ * stands now, through the SAME executors the run itself was judged by — the
+ * scripts' own bytes are verified against their signed sha256 FIRST (F135).
  *
  * The declared path measures against the run's OWN seed (`close-decl.seedRef` off
  * the spine), never a fresh one: re-basing the baseline onto today's HEAD would
  * compare the tree to itself and turn "nothing has changed since the run" into a
  * green for a `files-changed` stage that means the opposite. A run whose seed is
  * not on its spine is refused rather than guessed at.
- * @param {{job: any, workdir: string, events: any[], closeTimeoutMs?: number}} o
+ *
+ * F135 — the script BYTES are verified (`checkStageByteSignature`, PRD item 27/M2)
+ * BEFORE any stage runs, exactly the re-verify every other close execution in this
+ * runner already goes through (`runCloseStages`, `src/planrun.js`). Without it, a
+ * close script swapped on disk after the run ended but before the signer's accept
+ * would be re-run unchecked — a mismatch here never reaches the executor, and
+ * reads the same `close-tampered` shape the run-start/mid-run checks already use.
+ * @param {{job: any, workdir: string, events: any[], closeTimeoutMs?: number, closeDir?: string|null}} o
  */
-async function proveMechanically({ job, workdir, events, closeTimeoutMs }) {
+async function proveMechanically({ job, workdir, events, closeTimeoutMs, closeDir = null }) {
   const stages = mechanicalStages(closeStagesOf(job) ?? []);
   if (!stages.length) {
     // Honest, and named: a close with no mechanical stage has nothing a machine
@@ -217,6 +227,16 @@ async function proveMechanically({ job, workdir, events, closeTimeoutMs }) {
     // dressed as a re-run.
     return { ok: true, detail: '', reading: { ran: 0, verdict: null, stage: null, stages: [], note: 'this close has no mechanical stage — there is nothing a machine can re-prove, so the accept rests on the person' } };
   }
+  const sig = checkStageByteSignature(stages, workdir);
+  if (!sig.ok) {
+    const r = sig.reds[0];
+    const detail = sig.reds.map((rr) => `${rr.stage}: expected ${rr.expected.slice(0, 12)}… got ${rr.actual ? `${rr.actual.slice(0, 12)}…` : '<unreadable>'}`).join('; ');
+    return {
+      ok: false,
+      reading: { ran: 0, verdict: 'close-tampered', stage: r?.stage ?? null, stages: [] },
+      detail: `the close script's bytes no longer match its signed sha256 (close-tampered) — the accept is refused rather than re-run against a script nobody vouched for. ${detail}`,
+    };
+  }
   /** @type {any} */
   let v;
   if (isDeclaredClose(job)) {
@@ -226,7 +246,7 @@ async function proveMechanically({ job, workdir, events, closeTimeoutMs }) {
     }
     v = await runDeclaredStages(stages, redactSecrets, { timeoutMs: closeTimeoutMs, cwd: workdir, seedRef });
   } else {
-    v = await runStages(stages, redactSecrets, { timeoutMs: closeTimeoutMs, cwd: workdir });
+    v = await runStages(stages, redactSecrets, { timeoutMs: closeTimeoutMs, cwd: workdir, closeDir });
   }
   const reading = {
     ran: stages.length,

package/src/run.js

@@ -106,7 +106,22 @@ async function primitiveSmoke(workdir) {
  *   CLOSE-FIX loop (a plan STEP runs under the strike ladder instead)
  * @param {number} [opts.strikeLimit] shell-owned strike ceiling for a plan step's ladder
  * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
- * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory).
+ *   OPTIONAL as of PRD item 27/M3: absent, the plan flow autosets it from a $0
+ *   seed timing pass (or reads the spec's own signed `closeTimeoutMs`
+ *   override) — a caller passing an explicit value here still wins outright
+ *   (backward compatibility / test control), but production callers
+ *   (`src/cli.js`, `scripts/run-u.mjs`) pass nothing (F133, run mtqwmb9l: a
+ *   runner that resolves this itself for its own purposes — e.g. `run-u.mjs`
+ *   sizing its outside watchdog, F67 — must never feed the number back in
+ *   here too, or this call's own autoset/override banner prints a SECOND,
+ *   mislabelled "explicit runner override" line on top of the runner's own
+ *   correctly-labelled one).
+ * @param {string|null} [opts.closeDir] the close's own books directory (PRD item
+ *   27/M3 Part B) — pristine copies, calibration thresholds, logs — outside
+ *   the patient tree. Forwarded to every close invocation as
+ *   `BARELOOP_CLOSE_DIR`; a close script that needs one and gets none
+ *   instrument-stops itself (`checkCloseDirRequired`, src/close-integrity.js).
  * @param {unknown} [opts.bridge] Layer 3 — a bridge-v1 entry to reuse as the drafter's
  *   STARTING DRAFT (design record 2026-08-01, D4), forwarded to the plan flow. Omitted is
  *   the cold path and is byte-identical to a pre-Layer-3 run. WHICH entry (the listing, an
@@ -202,13 +217,19 @@ async function primitiveSmoke(workdir) {
  * @param {{text: string, fromRunid?: string|null, receivedAt?: string|null}|null} [opts.doorRerun]
  *   MODULE 8 — this leg IS the fresh engagement a signer commissioned at a previous
  *   run's review door, carrying their words. Forwarded verbatim.
+ * @param {boolean} [opts.resumable=true] PRD item 27(c)/F130 — does THIS runner
+ *   support `--resume` at all? `run-u.mjs` does (the default, `true`, byte-identical
+ *   to before this param existed); the exported bundle CLI does not (F130) and
+ *   passes `false` so the escalation tail's option strings say "resume is
+ *   `run-u`-only in v1" instead of naming a flag that would fail if typed. Forwarded
+ *   verbatim to the plan flow, which owns the three `--resume`-naming readouts.
  * @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' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -415,7 +436,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, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
       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