bareloop 0.21.0 → 0.23.0

package/src/bundle.js

@@ -27,6 +27,7 @@ import { jobSpecHash } from './job.js';
 import { loadRegistry } from './bridges.js';
 import { closeStagesOf } from './plan.js';
 import { shapeForkName } from './reuse.js';
+import { absolutePathLiteralsOf, hashCloseScriptBytes } from './close-integrity.js';
 // The live export list IS `src/index.js`'s own `Object.keys` — never a second,
 // hand-kept copy that can drift from the real surface a close script can
 // legally import. This module is itself exported from `index.js` (a cycle by
@@ -128,50 +129,10 @@ function isRelative(spec) {
   return spec.startsWith('./') || spec.startsWith('../');
 }
 
-// Every quoted string literal (single/double/backtick). Backtick literals
-// carrying `${…}` interpolation are filtered out below — they are not a
-// fixed literal, so they cannot be "a path baked into the script" at all.
-const STRING_LITERAL_RE = /'([^'\\]*(?:\\.[^'\\]*)*)'|"([^"\\]*(?:\\.[^"\\]*)*)"|`([^`\\]*(?:\\.[^`\\]*)*)`/g;
-
-// A close script is entitled to name a real system path (`/usr/bin/env`,
-// `/etc/hosts`, …) without that being the F8/F129 hazard — only a path this
-// bundle would actually relocate (a patient checkout, a scratch dir) is.
-const SYSTEM_PATH_PREFIXES = ['/usr/', '/bin/', '/sbin/', '/lib/', '/lib64/', '/dev/', '/etc/', '/proc/', '/sys/', '/opt/'];
-
-/**
- * F8/F129 — a close judges the cwd the runner gives it, never a path baked
- * into the script itself (`src/ralph.js`'s `cwd` is load-bearing precisely
- * because every close script in this repo's OWN test suite named an
- * absolute path, so cwd never mattered there — see F8). This scans every
- * quoted string literal in a close script's source for an absolute POSIX
- * path (`/…`) that EXISTS on the exporting machine right now and is not
- * under an allow-listed system prefix.
- *
- * Deliberately monotone and simple, not clever, with named limits: a
- * nonexistent absolute-looking string is treated as a NAME, not a path —
- * `existsSync` is the only oracle this has for "load-bearing", so it is not
- * flagged; a path built by string concatenation (never one whole literal)
- * is invisible to this scan; and a literal that only exists inside a `//` or
- * `/* *\/` comment is naturally excluded because a comment carries no quote
- * characters of its own around the path text.
- * @param {string} source close script text
- * @returns {string[]} the offending literal path values, in source order
- */
-function absolutePathLiteralsOf(source) {
-  /** @type {string[]} */
-  const hits = [];
-  for (const m of source.matchAll(STRING_LITERAL_RE)) {
-    const isBacktick = m[3] !== undefined;
-    const value = m[1] ?? m[2] ?? m[3];
-    if (value === undefined) continue;
-    if (isBacktick && value.includes('${')) continue; // interpolated, not a fixed literal
-    if (!value.startsWith('/')) continue;
-    if (SYSTEM_PATH_PREFIXES.some((p) => value.startsWith(p))) continue;
-    if (!existsSync(value)) continue; // a nonexistent path is a name, not a hazard
-    hits.push(value);
-  }
-  return hits;
-}
+// F8/F129 — `absolutePathLiteralsOf` (a close judges the cwd the runner
+// gives it, never a path baked into the script itself) now lives in
+// `src/close-integrity.js`, shared with the run-start precheck that applies
+// the SAME rule to every job, not only exports. Never a second spelling.
 
 /**
  * Every import in a close script this bundle has an opinion about: a
@@ -378,6 +339,20 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
     for (const lit of absolutePathLiteralsOf(source)) {
       red('close-absolute-path', at, `${basename(scriptPath)}: bakes in the absolute path "${lit}" — a close judges the cwd the runner gives it, never a path baked into the script (F8/F129)`);
     }
+    // PRD item 27/M2 — the spec's OWN sha256 (if it carries one) must agree
+    // with the bytes actually being packed into the bundle: the two
+    // signatures (this one, and `bundleHash`'s manifest hash over the
+    // rewritten script) cover the same bytes by two different paths, and N4
+    // is exactly the hazard of letting a spec's signature drift from what it
+    // names. A spec with no sha256 at all is a SEPARATE red (`validateJob`'s
+    // `missing-required`, upstream of export) — this only fires when a value
+    // is present and wrong.
+    if (isNonEmptyString(stage.sha256)) {
+      const actual = hashCloseScriptBytes(source);
+      if (actual !== stage.sha256) {
+        red('close-sha-mismatch', at, `${basename(scriptPath)}: signed sha256 ${stage.sha256.slice(0, 12)}… does not match the script bytes being packed (${actual.slice(0, 12)}…) — re-sign before exporting`);
+      }
+    }
   });
 
   if (reds.length > 0) return fail();
@@ -391,10 +366,19 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
 
   /** @type {Record<string, string>} */
   const files = {};
+  // F132 — keyed by scriptPath (not name) so the spec-rewrite pass below can
+  // look up each relocated stage's REWRITTEN-bytes hash without re-hashing.
+  // Both `sha256` here and `hashCloseScriptBytes` (src/close-integrity.js)
+  // hash the same way (sha256 of the UTF-8 script text) — this is not a
+  // second formula, just this module's own existing helper reused.
+  /** @type {Map<string, string>} scriptPath -> sha256 of the RELOCATED bytes */
+  const relocatedSha = new Map();
   for (const [scriptPath, name] of byPath) {
     const rewritten = rewriteSrcImports(scripts[scriptPath]);
     writeFileSync(join(closeDir, name), rewritten);
-    files[`close/${name}`] = sha256(rewritten);
+    const hash = sha256(rewritten);
+    files[`close/${name}`] = hash;
+    relocatedSha.set(scriptPath, hash);
   }
 
   const specOut = { ...spec, close: spec.close.map((/** @type {any} */ stage) => {
@@ -404,7 +388,17 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
     if (!parsed.ok) throw new Error(`unreachable: ${stage.cmd} was validated as a relocatable close cmd`);
     const name = byPath.get(parsed.scriptPath);
     const cmd = ['node', `${BUNDLE_TOKEN}/close/${name}`, ...parsed.rest].join(' ');
-    return { ...stage, cmd };
+    // F132 (run mtqwmb9l/mtqwydl4): the bundle's manifest hash covers the
+    // RELOCATED bytes (the import rewrite above), but the spec's own
+    // `close[].sha256` was left carrying the SOURCE spec's signature — two
+    // signatures over two different byte strings, so `checkCloseByteSignature`
+    // at run start correctly read the bundle as tampered even though nothing
+    // was. Re-sign here, over the bytes actually being packed, so the two
+    // signatures agree by construction. Only a stage that already carried a
+    // signature gets one written back — a stage export never fabricates a
+    // signature that was never there (M2 leaves that to the validator).
+    const sha256Out = typeof stage.sha256 === 'string' ? (relocatedSha.get(parsed.scriptPath) ?? stage.sha256) : stage.sha256;
+    return { ...stage, cmd, sha256: sha256Out };
   }) };
   const specText = `${JSON.stringify(specOut, null, 2)}\n`;
   writeFileSync(join(outDir, 'spec.json'), specText);

package/src/calibrate.js

@@ -63,6 +63,7 @@ import {
 } from './judged.js';
 import { JUDGE_ATTEMPTS } from './kinds.js';
 import { tallyCalls } from './text.js';
+import { PROVIDER_TIMEOUT_MS } from './clock.js';
 
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
 
@@ -330,6 +331,15 @@ async function pipeOnce({ artifactText, card, judgeLoop, attempts, meter, id, ki
       card,
       loopFactory: /** @type {any} */ (judgeLoop),
       attempt,
+      // F152/PRD 30.4 — this module's own header already names the hazard ("a
+      // dead socket") as one of its three CASUALTY readings, but with no bound
+      // at all a truly silent judge endpoint never reaches that reading — it
+      // hangs the authoring process forever instead (measured). The gate runs
+      // at draft/sign time, which has no wall clock to derive a bound from (the
+      // authoring pipeline's only ceiling is money, `ceilingUsd`/`capStop`), so
+      // this reuses the same idle-timeout default the run path falls back to
+      // when ITS OWN wall is unbounded (`PROVIDER_TIMEOUT_MS`, src/clock.js).
+      callBounds: { timeoutMs: PROVIDER_TIMEOUT_MS },
       onCost: (c) => meter({
         id, kind, attempt, label: CALIBRATION_LABEL, model: JUDGE_MODEL,
         costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,

package/src/cli.js

@@ -19,7 +19,6 @@
 // run, never the unresolved bundleHash. `history.jsonl` records both hashes
 // side by side (POC fact 2) so the pairing can never drift silently.
 
-import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { hostname } from 'node:os';
 import { execFileSync } from 'node:child_process';
@@ -34,15 +33,13 @@ import {
   exportBundle, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
   runJob, makeSpine, loadRegistry, listingRow, jobSpecHash, resolveWorkerModel, JUDGE_MODEL,
 } from './index.js';
+import { resolveProvider, buildRunnerProviders } from './providers.js';
 
-const require = createRequire(import.meta.url);
-
-// The runner's own tier menu, the same spelling `scripts/run-u.mjs` uses (not
-// exported from `src/` — the tier->model mapping is runner territory, not the
-// library's). A `bareloop run` has no `--model` flag (not in the frozen
-// spec), so `flagModel` is always undefined and only the spec's own `model`
-// (if signed) or this default is ever in play.
-const DEFAULT_TIER_MODELS = { sonnet: 'claude-sonnet-5', haiku: 'claude-haiku-4-5-20251001' };
+// The tier->model tables live in `src/providers.js` now (PRD item 28's
+// factory) — one seam instead of a copy hardcoded in each runner. A
+// `bareloop run` has no `--model` flag (not in the frozen spec), so
+// `flagModel` is always undefined below and only the spec's own `model`
+// (if signed) or the resolved provider's default tier is ever in play.
 
 /** @param {unknown} v @returns {v is Record<string, any>} */
 const isObj = (v) => typeof v === 'object' && v !== null;
@@ -58,20 +55,38 @@ const isObj = (v) => typeof v === 'object' && v !== null;
  * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
  */
 function buildProviders(apiKey, spec) {
-  const { AnthropicProvider } = require('bare-agent/providers');
+  // `bareloop run`'s frozen key contract (module header above) is
+  // ANTHROPIC_API_KEY only — this `apiKey` is always that key. A bundle
+  // whose spec names a provider that reads a DIFFERENT env key therefore
+  // has no seam into this flow yet, and the one thing this must never do is
+  // construct that provider with the Anthropic key: the run would fail at
+  // the first call with a vendor 401, which reads as a credential problem
+  // rather than as the unbuilt seam it actually is. So it REFUSES here, at
+  // $0, naming the key it would have needed. Widening the contract (a
+  // signed per-provider key story) is PRD item 28 part (2)/(3), the
+  // arbiter's, not this factory rewire's — the runner that actually fires
+  // openai-api jobs today is `scripts/run-u.mjs`, which IS key-aware.
+  const providerName = isObj(spec) && typeof spec.provider === 'string' ? spec.provider : 'anthropic-api';
+  const entry = resolveProvider(providerName);
+  if (entry.envKey !== 'ANTHROPIC_API_KEY') {
+    throw new Error(
+      `bareloop run: this bundle's spec names provider "${providerName}", which reads `
+      + `${entry.envKey}. The bundle runner's key contract is ANTHROPIC_API_KEY only, so it `
+      + 'refuses rather than calling that provider with the wrong key (PRD item 28 part 2 — '
+      + 'a signed per-provider key story is not built). Run this job through scripts/run-u.mjs.',
+    );
+  }
   const modelResolution = resolveWorkerModel({
     specModel: isObj(spec) && typeof spec.model === 'string' ? spec.model : undefined,
     flagModel: undefined,
-    defaultModel: DEFAULT_TIER_MODELS.sonnet,
+    defaultModel: entry.tiers.sonnet,
   });
   const MODEL = modelResolution.model;
-  const provider = new AnthropicProvider({ apiKey, model: MODEL });
-  const TIER_MODELS = modelResolution.source === 'spec' ? { ...DEFAULT_TIER_MODELS, sonnet: MODEL } : DEFAULT_TIER_MODELS;
-  /** @type {Record<string, any>} */
-  const tierCache = {};
-  const providerFor = (/** @type {string} */ tier) => (tierCache[tier] ??= (TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] === MODEL ? provider : new AnthropicProvider({ apiKey, model: TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] })));
-  const judgeProvider = new AnthropicProvider({ apiKey, model: JUDGE_MODEL });
-  return { provider, providerFor, judgeProvider };
+  const tierModels = modelResolution.source === 'spec' ? { ...entry.tiers, sonnet: MODEL } : entry.tiers;
+  const baseUrl = isObj(spec) && typeof spec.baseUrl === 'string' ? spec.baseUrl : undefined;
+  return buildRunnerProviders({
+    providerName, apiKey, model: MODEL, tierModels, baseUrl, judgeApiKey: apiKey, judgeModel: JUDGE_MODEL,
+  });
 }
 
 /** @param {string[]} args @returns {{ positional: string[], flags: Record<string, string|true> }} */
@@ -230,7 +245,13 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       out(`bundleHash: ${bundle.manifest.bundleHash}`);
       return 0;
     }
-    ({ provider, providerFor, judgeProvider } = buildProviders(apiKey, bundle.spec));
+    try {
+      ({ provider, providerFor, judgeProvider } = buildProviders(apiKey, bundle.spec));
+    } catch (e) {
+      // a refusal from the key contract above: name it and spend nothing
+      err(String(/** @type {any} */ (e)?.message ?? e));
+      return 1;
+    }
   }
 
   // 4. blessing.
@@ -300,6 +321,14 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
   mkdirSync(runsDir, { recursive: true });
   const spineFile = join(runsDir, 'spine.jsonl');
   const emit = makeSpine(spineFile);
+  // PRD item 27/M3 Part B — the close's own books directory, inside the run's
+  // own directory so the bundle stays one self-contained unit (hamr,
+  // 2026-09-07: "export holds as one unit of itself"). `runJob` autosets the
+  // close timeout itself (no `closeTimeoutMs` passed — the bundle CLI has
+  // always run on the library default/autoset path, never run-u's operator
+  // knob).
+  const closeDir = join(runsDir, 'close');
+  mkdirSync(closeDir, { recursive: true });
 
   let outcome;
   try {
@@ -310,9 +339,13 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       providerFor,
       judgeProvider,
       emit,
+      closeDir,
       shellCapUsd: runSpec.budgetUsd,
       readShim: 'cap',
       scout: true,
+      // F130/PRD item 27(c) — the bundle CLI has no `--resume` (v1); the
+      // honest tail says so instead of naming a flag that does not exist.
+      resumable: false,
     });
   } catch (e) {
     err(`runJob crashed: ${/** @type {Error} */ (e).message}`);

package/src/close-integrity.js

@@ -0,0 +1,325 @@
+// Close integrity — PRD item 27 / M1(b), `docs/product/CLOSE-INTEGRITY-BUILD.md`.
+//
+// ONE detector for "does a close script bake in an absolute path", shared by
+// `src/bundle.js` (export-time, mechanical) and the run-start precheck below
+// (every job, not only bundles). Two spellings of the same rule is exactly
+// how F129 shipped an export-only guard while every non-exported job stayed
+// exposed — this module exists so that never happens again.
+//
+// `readCloseScripts` is the reader M2's sha256 fingerprint reuses: pure,
+// never throws on a missing file (reports it absent so a caller can red
+// distinctly from a tampered one). Scope (widened 2026-09-06, orchestrator
+// audit): an INTERPRETER cmd (`node <path> …`, `sh <path> …`, …) OR a bare
+// directly-executable ABSOLUTE path (a `.sh` wrapper with no interpreter
+// prefix, e.g. `jobs/aurora-testgen-cold.json`'s close) — see
+// `closeScriptCandidateToken` (src/validate.js) for the exact shape test.
+// A relative bare executable (`true`, `pytest`) is still out of scope: it
+// names no file at all, so there is nothing to read or sign.
+//
+// M2 (PRD item 27, `docs/product/CLOSE-INTEGRITY-BUILD.md`) adds the
+// close-BYTES half beside the close-PATH half already here: `close[].sha256`
+// is a hex sha256 of the same script bytes `readCloseScripts` already reads,
+// so the fingerprint (`checkCloseByteSignature`/`checkStageByteSignature`)
+// and the minting helper (`signCloseScripts`) both live in this one module —
+// two spellings of "which bytes does this stage sign" is exactly the class
+// of drift F129 shipped once already (see the module header above).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+import { isObj, closeScriptCandidateToken } from './validate.js';
+import { closeStagesOf } from './plan.js';
+
+/**
+ * Resolve a close stage's `cmd` to the addressable script's ABSOLUTE path on
+ * disk — the shape test itself (`closeScriptCandidateToken`, src/validate.js)
+ * is shared with `src/job.js`'s sha256 demand; this just resolves the
+ * resulting token against `cwd` when it is relative. Returns null for
+ * anything the shared shape test rejects (a relative bare executable, an
+ * interpreter with no argument, a non-string/empty cmd).
+ * @param {unknown} cmd
+ * @param {string} cwd
+ * @returns {string|null} absolute script path, or null if out of scope
+ */
+function closeScriptPathOf(cmd, cwd) {
+  const token = closeScriptCandidateToken(cmd);
+  if (token === null) return null;
+  return isAbsolute(token) ? token : resolve(cwd, token);
+}
+
+/**
+ * Hex sha256 of a close script's TEXT, exactly the way `src/bundle.js`'s own
+ * `sha256(source)` hashes a close script's source before bundling (a JS
+ * source file is always valid UTF-8, so hashing the decoded string and
+ * hashing the raw file bytes agree) — ONE formula, so a signature minted here
+ * and a mismatch read at export time can never disagree about what "the
+ * bytes" means.
+ * @param {string} text
+ * @returns {string} sha256 hex
+ */
+export function hashCloseScriptBytes(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/**
+ * A close script is entitled to name a real system path (`/usr/bin/env`,
+ * `/etc/hosts`, …) without that being the F8/F129 hazard — only a path a
+ * runner would actually relocate (a patient checkout, a scratch dir) is.
+ * @type {string[]}
+ */
+export const SYSTEM_PATH_PREFIXES = ['/usr/', '/bin/', '/sbin/', '/lib/', '/lib64/', '/dev/', '/etc/', '/proc/', '/sys/', '/opt/'];
+
+// Every quoted string literal (single/double/backtick). Backtick literals
+// carrying `${…}` interpolation are filtered out below — they are not a
+// fixed literal, so they cannot be "a path baked into the script" at all.
+const STRING_LITERAL_RE = /'([^'\\]*(?:\\.[^'\\]*)*)'|"([^"\\]*(?:\\.[^"\\]*)*)"|`([^`\\]*(?:\\.[^`\\]*)*)`/g;
+
+/**
+ * F8/F129 — a close judges the cwd the runner gives it, never a path baked
+ * into the script itself. This scans every quoted string literal in a close
+ * script's source for an absolute POSIX path (`/…`) that EXISTS on this
+ * machine right now and is not under an allow-listed system prefix.
+ *
+ * Deliberately monotone and simple, not clever, with named limits: a
+ * nonexistent absolute-looking string is treated as a NAME, not a path —
+ * `existsSync` is the only oracle this has for "load-bearing", so it is not
+ * flagged; a path built by string concatenation (never one whole literal)
+ * is invisible to this scan; and a literal that only exists inside a `//` or
+ * `/* *\/` comment is naturally excluded because a comment carries no quote
+ * characters of its own around the path text.
+ * @param {string} source close script text
+ * @returns {string[]} the offending literal path values, in source order
+ */
+export function absolutePathLiteralsOf(source) {
+  /** @type {string[]} */
+  const hits = [];
+  for (const m of source.matchAll(STRING_LITERAL_RE)) {
+    const isBacktick = m[3] !== undefined;
+    const value = m[1] ?? m[2] ?? m[3];
+    if (value === undefined) continue;
+    if (isBacktick && value.includes('${')) continue; // interpolated, not a fixed literal
+    if (!value.startsWith('/')) continue;
+    if (SYSTEM_PATH_PREFIXES.some((p) => value.startsWith(p))) continue;
+    if (!existsSync(value)) continue; // a nonexistent path is a name, not a hazard
+    hits.push(value);
+  }
+  return hits;
+}
+
+/**
+ * Resolve every `close[].cmd` (or `closeDecl`'s equivalent, via
+ * `closeStagesOf`) that names an addressable script (`closeScriptCandidateToken`'s
+ * scope: an interpreter cmd or a bare absolute executable) to its absolute
+ * path and bytes off disk. The spec's OWN `cmd` path is the address and is never
+ * itself judged — only the named script's CONTENT is read here. A relative
+ * path resolves against `cwd` (the caller passes the run's own workdir or
+ * the spec file's directory, matching how each caller already resolves
+ * paths elsewhere). Never throws: a missing/unreadable script reports
+ * `bytes: null` so a caller can red it distinctly from a tampered one.
+ * `sha256` (M2, additive): the stage's OWN signed field, verbatim, or `null`
+ * when the stage carries none — the field this rung's checker compares
+ * against `hashCloseScriptBytes(bytes)`. M1's callers read `.stage`/`.path`/
+ * `.bytes` only, so this addition is behaviour-preserving for them.
+ * @param {any} spec resolved job spec (or anything `closeStagesOf` accepts)
+ * @param {string} cwd
+ * @returns {{stage: string, path: string, bytes: string|null, sha256: string|null}[]}
+ */
+export function readCloseScripts(spec, cwd) {
+  const stages = closeStagesOf(spec) ?? [];
+  /** @type {{stage: string, path: string, bytes: string|null, sha256: string|null}[]} */
+  const out = [];
+  for (const stage of stages) {
+    if (!isObj(stage) || typeof stage.cmd !== 'string') continue;
+    const scriptPath = closeScriptPathOf(stage.cmd, cwd);
+    if (!scriptPath) continue;
+    /** @type {string|null} */
+    let bytes = null;
+    try { bytes = readFileSync(scriptPath, 'utf8'); } catch { bytes = null; }
+    out.push({
+      stage: typeof stage.name === 'string' ? stage.name : scriptPath,
+      path: scriptPath,
+      bytes,
+      sha256: typeof stage.sha256 === 'string' ? stage.sha256 : null,
+    });
+  }
+  return out;
+}
+
+/**
+ * The $0 run-start integrity check (PRD item 27(c)): red `close-absolute-path`
+ * for EVERY job whose close script bakes in an absolute path literal that
+ * exists on disk — the same rule `src/bundle.js`'s `exportBundle` already
+ * applies at export time, now applied before the close-first precheck and
+ * before any provider call, for every run, not only exported bundles. A
+ * script this reads couldn't read (missing/unreadable) is not reported here
+ * — that is `broken-close`'s job once the close actually tries to run it.
+ * @param {any} spec resolved job spec
+ * @param {string} cwd
+ * @returns {{ ok: true } | { ok: false, reds: {stage: string, path: string, literal: string}[] }}
+ */
+export function checkCloseAbsolutePaths(spec, cwd) {
+  const scripts = readCloseScripts(spec, cwd);
+  /** @type {{stage: string, path: string, literal: string}[]} */
+  const reds = [];
+  for (const s of scripts) {
+    if (s.bytes == null) continue;
+    for (const literal of absolutePathLiteralsOf(s.bytes)) {
+      reds.push({ stage: s.stage, path: s.path, literal });
+    }
+  }
+  return reds.length > 0 ? { ok: false, reds } : { ok: true };
+}
+
+/** @typedef {{stage: string, path: string, expected: string, actual: string|null}} ByteRed */
+
+/**
+ * The core comparison, shared by the two checkers below: a `readCloseScripts`
+ * row signs nothing (`sha256: null`, e.g. a `.sh`-cmd stage or a declared
+ * kind) reads as `ok` — M2's validator is what demands the field on the
+ * stages that must carry it; this runtime check only ever compares a
+ * signature that exists.
+ * @param {{stage: string, path: string, bytes: string|null, sha256: string|null}[]} scripts
+ * @returns {{ ok: true } | { ok: false, reds: ByteRed[] }}
+ */
+function compareSignatures(scripts) {
+  /** @type {ByteRed[]} */
+  const reds = [];
+  for (const s of scripts) {
+    if (s.sha256 == null) continue;
+    const actual = s.bytes == null ? null : hashCloseScriptBytes(s.bytes);
+    if (actual !== s.sha256) reds.push({ stage: s.stage, path: s.path, expected: s.sha256, actual });
+  }
+  return reds.length > 0 ? { ok: false, reds } : { ok: true };
+}
+
+/**
+ * M2's run-start integrity check (PRD item 27, `close-tampered`): every
+ * signed `close[].sha256` must match the script's bytes off disk, RIGHT NOW —
+ * checked before the close-first precheck and before any provider call,
+ * exactly where `checkCloseAbsolutePaths` already runs (the two are always
+ * called together at that seam). A script this cannot read reads `actual:
+ * null` — distinct from a byte mismatch, but still a red: an unreadable
+ * signed script is exactly as untrustworthy as a tampered one, and silently
+ * treating "gone" as "fine" would be the M1 F129 hazard in a new coat.
+ * @param {any} spec resolved job spec
+ * @param {string} cwd
+ * @returns {{ ok: true } | { ok: false, reds: ByteRed[] }}
+ */
+export function checkCloseByteSignature(spec, cwd) {
+  return compareSignatures(readCloseScripts(spec, cwd));
+}
+
+/** the exact env var name a close script reads for its own books directory
+ * (Part B, PRD item 27/M3) — named once so the detector below and the runner
+ * that sets it (`src/ralph.js`'s `runClose`) can never drift into two
+ * spellings of the same contract. */
+export const CLOSE_DIR_ENV_VAR = 'BARELOOP_CLOSE_DIR';
+
+/**
+ * PRD item 27/M3, Part B — "the library `runJob` takes `closeDir` and refuses
+ * at $0 if a spec's close needs it and none is given." A close script's
+ * NEED is read the same way its bytes already are (`readCloseScripts`): a
+ * script whose source mentions `BARELOOP_CLOSE_DIR` reads that variable at
+ * run time, so a run with no `closeDir` handed to it would run that script
+ * against `undefined` — silently, since `env.BARELOOP_CLOSE_DIR` would just
+ * be absent from the child's environment rather than throwing. Refusing here,
+ * at the same $0 run-start seam as the absolute-path/byte-signature checks,
+ * turns that silent gap into a named red before any tokens spend, rather than
+ * leaving it to whatever the script's own author remembered to check for.
+ *
+ * A script that never mentions the variable carries no demand — most
+ * predicate-only fixture closes (`true`, `pytest`) have no books of their own
+ * to keep, and requiring a `closeDir` for them would be a needless refusal.
+ * @param {any} spec resolved job spec
+ * @param {string} cwd
+ * @param {string|null|undefined} closeDir the value the runner is about to hand
+ *   the close as `BARELOOP_CLOSE_DIR` (or none)
+ * @returns {{ ok: true } | { ok: false, reds: {stage: string, path: string}[] }}
+ */
+export function checkCloseDirRequired(spec, cwd, closeDir) {
+  if (typeof closeDir === 'string' && closeDir.length > 0) return { ok: true };
+  const scripts = readCloseScripts(spec, cwd);
+  /** @type {{stage: string, path: string}[]} */
+  const reds = [];
+  for (const s of scripts) {
+    if (s.bytes != null && s.bytes.includes(CLOSE_DIR_ENV_VAR)) reds.push({ stage: s.stage, path: s.path });
+  }
+  return reds.length > 0 ? { ok: false, reds } : { ok: true };
+}
+
+/**
+ * The re-verify that runs before EVERY close run, precheck included (PRD
+ * item 27, M2 §2) — scoped to the STAGES about to actually run rather than
+ * the whole spec, because that is the true blast radius of "was this close
+ * script's content tampered with since it was signed" for this particular
+ * invocation. Same comparison, same red shape, as `checkCloseByteSignature`;
+ * kept as a separate export because its caller (`runCloseStages` in
+ * `src/planrun.js`) already holds a stage array, not a spec.
+ * @param {any[]} stages a close stage chain (the shape `runStages` takes)
+ * @param {string} cwd
+ * @returns {{ ok: true } | { ok: false, reds: ByteRed[] }}
+ */
+export function checkStageByteSignature(stages, cwd) {
+  const scripts = [];
+  for (const stage of Array.isArray(stages) ? stages : []) {
+    if (!isObj(stage) || typeof stage.cmd !== 'string') continue;
+    const scriptPath = closeScriptPathOf(stage.cmd, cwd);
+    if (!scriptPath) continue;
+    /** @type {string|null} */
+    let bytes = null;
+    try { bytes = readFileSync(scriptPath, 'utf8'); } catch { bytes = null; }
+    scripts.push({
+      stage: typeof stage.name === 'string' ? stage.name : scriptPath,
+      path: scriptPath,
+      bytes,
+      sha256: typeof stage.sha256 === 'string' ? stage.sha256 : null,
+    });
+  }
+  return compareSignatures(scripts);
+}
+
+/**
+ * M2's minting helper (PRD item 27 §3) — fills `close[].sha256` from disk for
+ * every addressable-script stage in `spec.close` (`closeScriptCandidateToken`'s
+ * scope: an interpreter cmd or a bare absolute executable, e.g. a `.sh`
+ * wrapper). Pure: never writes anything itself (the CLI wrapper,
+ * `scripts/sign-close.mjs`, gates on `--write`) and never throws on a
+ * missing/unreadable script — it names the miss in `missing` and leaves
+ * that stage's `sha256` untouched, so a caller can refuse to sign (and
+ * refuse to report a hash it never computed) a spec it could not fully
+ * hash. A stage outside this rung's scope (a relative bare executable, a
+ * declared-kind stage) passes through unchanged and is never listed as
+ * missing — it was never addressable to begin with (same scope
+ * `readCloseScripts`/`checkCloseAbsolutePaths` already draw).
+ *
+ * Only ever operates on `spec.close` (the command-close array) — a
+ * `closeDecl` spec has no script path to sign and `signCloseScripts` reports
+ * `ok:false` for one rather than silently doing nothing to it.
+ * @param {any} spec resolved job spec (parsed `jobs/<x>.json`)
+ * @param {string} cwd base for resolving a RELATIVE script path (jobs in this
+ *   repo only ever use absolute `cmd` paths; relative resolution is here for
+ *   parity with `readCloseScripts` and any future relative-path spec)
+ * @returns {{ ok: boolean, spec: any, changes: {stage: string, path: string, old: string|null, new: string}[], missing: {stage: string, path: string}[] }}
+ */
+export function signCloseScripts(spec, cwd) {
+  if (!isObj(spec) || !Array.isArray(spec.close)) {
+    return { ok: false, spec, changes: [], missing: [] };
+  }
+  /** @type {{stage: string, path: string, old: string|null, new: string}[]} */
+  const changes = [];
+  /** @type {{stage: string, path: string}[]} */
+  const missing = [];
+  const newClose = spec.close.map((/** @type {any} */ stage) => {
+    if (!isObj(stage)) return stage;
+    const scriptPath = closeScriptPathOf(stage.cmd, cwd);
+    if (!scriptPath) return stage; // out of this rung's scope — never touched, never reported missing
+    /** @type {string|null} */
+    let bytes = null;
+    try { bytes = readFileSync(scriptPath, 'utf8'); } catch { bytes = null; }
+    if (bytes == null) { missing.push({ stage: stage.name, path: scriptPath }); return stage; }
+    const hash = hashCloseScriptBytes(bytes);
+    changes.push({ stage: stage.name, path: scriptPath, old: typeof stage.sha256 === 'string' ? stage.sha256 : null, new: hash });
+    return { ...stage, sha256: hash };
+  });
+  return { ok: missing.length === 0, spec: { ...spec, close: newClose }, changes, missing };
+}