bareloop 0.21.0 → 0.22.0

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 };
+}

package/src/closetimeout.js

@@ -0,0 +1,165 @@
+// Close timeout — PRD item 27/M3, `docs/product/CLOSE-INTEGRITY-BUILD.md`.
+//
+// hamr's ruling (2026-09-06, verbatim): "both … autoset and can be override,
+// same like api pricing" — the guesstimate-plus-loud-sign-plus-customer-
+// override shape, never a hidden knob. Today `runClose`'s own default
+// (`src/ralph.js:221`, `timeoutMs = 120_000`) is a defaulted cap with no
+// operator-set floor — the same shape the wall's no-default rule already
+// forbids for `maxWallMs`. This module is the fix: measure the close's own
+// stages once at $0, before any provider call, and derive a per-stage ceiling
+// from what was actually measured, unless the signed spec names one itself.
+//
+// CONSTANTS BELOW ARE ARBITER CONSTANTS — hamr set them 2026-09-07, verbatim:
+// "floor = 120,000 ms; K = 5 ('2 and 5 are fine')." Never agent- or
+// adopter-settable; a build changing them is arbiter territory, not a tuning
+// knob a drafted spec or a runner script can reach for.
+
+import { runClose } from './ralph.js';
+
+/** hamr, 2026-09-07: the floor, verbatim. Also the value `runClose`'s own
+ * un-autoset default has always used — kept as its own named constant here
+ * (not re-exported from ralph.js) because the two are different CLAIMS: one is
+ * "what runClose does if nobody says otherwise", the other is "the arbiter's
+ * chosen floor for autoset" — they happen to be the same number today, and a
+ * future change to either must not silently move the other. */
+export const CLOSE_TIMEOUT_FLOOR_MS = 120_000;
+/** hamr, 2026-09-07, verbatim: "K = 5 ('2 and 5 are fine')." */
+export const CLOSE_TIMEOUT_K = 5;
+/** `runClose`'s own shipped default when nobody passes a timeout at all
+ * (`src/ralph.js:221`) — the ceiling the $0 timing PASS ITSELF runs each
+ * stage under is a multiple of this, never of the floor above (the two are
+ * the same number today; named separately on purpose, see the constant
+ * above). */
+export const LIBRARY_DEFAULT_CLOSE_TIMEOUT_MS = 120_000;
+/**
+ * The generous PROVISIONAL ceiling the timing preflight runs every stage
+ * under, so "a genuinely hung stage still ends" (build spec, M3 §2) rather
+ * than blocking the timing pass forever. Deliberately the library default × K
+ * (600s) — NOT the autoset/override ceiling this module computes, which is
+ * only known after the pass completes.
+ */
+export const TIMING_PREFLIGHT_CEILING_MS = LIBRARY_DEFAULT_CLOSE_TIMEOUT_MS * CLOSE_TIMEOUT_K;
+
+/**
+ * The $0 timing preflight (PRD item 27, M3 §2): run every close STAGE once,
+ * ignoring verdicts — first-red-wins stays for the real verdict precheck
+ * (`src/planrun.js`'s `check-preflight`); this is a separate, sequential pass
+ * (F131/F68: never two closes in flight against one tree) whose only purpose
+ * is TIMING. A declared-close stage (no `.cmd`, a kind executor) has nothing
+ * a command runner can spawn and is skipped — it contributes no reading, not
+ * a zero one (a silent zero would understate the real close's later cost).
+ *
+ * @param {any[]} stages a close stage chain (`runStages`'s own shape)
+ * @param {{cwd?: string, redact?: (s: string) => string, ceilingMs?: number}} [opts]
+ *   `ceilingMs` (test seam only — never wired to any spec/runner surface):
+ *   overrides `TIMING_PREFLIGHT_CEILING_MS` so a hang-detection test does not
+ *   have to wait 10 real minutes. Production callers never pass it.
+ * @returns {Promise<{
+ *   perStage: {name: string, ms: number, exitCode: number|null, timedOut: boolean}[],
+ *   slowestMs: number, slowestName: string|null, anyTimedOut: boolean,
+ * }>}
+ */
+export async function timeCloseStages(stages, { cwd, redact = (s) => s, ceilingMs = TIMING_PREFLIGHT_CEILING_MS } = {}) {
+  /** @type {{name: string, ms: number, exitCode: number|null, timedOut: boolean}[]} */
+  const perStage = [];
+  for (const st of Array.isArray(stages) ? stages : []) {
+    if (!st || typeof st !== 'object' || typeof st.cmd !== 'string') continue; // declared/kind stage — nothing to spawn
+    const start = Date.now();
+    // Sequential by construction (F68), same discipline as `runStages`: a
+    // stage's own timing pass is never in flight beside another close.
+    // eslint-disable-next-line no-await-in-loop
+    const r = await runClose(st.cmd.trim().split(/\s+/), redact, {
+      timeoutMs: ceilingMs, cwd, expect: st.expect, judged: st.judged, gapKeep: st.gapKeep,
+    });
+    const ms = Date.now() - start;
+    // `runClose` only reports `exitCode` on a NON-satisfied verdict (a
+    // satisfied close's exit code is implied by `expect`, never re-stated) —
+    // this timing pass records it either way, since "which exit code did
+    // this stage return" is a cheap, honest thing to keep for `close-timing`.
+    const exitCode = typeof r.exitCode === 'number' ? r.exitCode
+      : (r.verdict === 'satisfied' && typeof st.expect === 'number' ? st.expect : null);
+    perStage.push({
+      name: typeof st.name === 'string' ? st.name : st.cmd,
+      ms,
+      exitCode,
+      timedOut: r.verdict === 'timed-out',
+    });
+  }
+  let slowest = null;
+  for (const s of perStage) if (slowest === null || s.ms > slowest.ms) slowest = s;
+  return {
+    perStage,
+    slowestMs: slowest ? slowest.ms : 0,
+    slowestName: slowest ? slowest.name : null,
+    anyTimedOut: perStage.some((s) => s.timedOut),
+  };
+}
+
+/**
+ * The ceiling formula (PRD item 27, M3): `max(FLOOR, K × slowest measured
+ * stage)`, unless an explicit override is given — the override is the
+ * OPERATOR'S number (the rates-passthrough shape, F113: guesstimate + loud
+ * sign + customer override), so it may legally sit ABOVE or BELOW the
+ * autoset estimate; this is not tighten-only.
+ * @param {{slowestMs: number, overrideMs?: number|null}} args
+ * @returns {{ ceilingMs: number, source: 'estimated'|'override' }}
+ */
+export function computeCloseTimeoutCeiling({ slowestMs, overrideMs = null }) {
+  if (typeof overrideMs === 'number' && Number.isFinite(overrideMs)) {
+    return { ceilingMs: overrideMs, source: 'override' };
+  }
+  return { ceilingMs: Math.max(CLOSE_TIMEOUT_FLOOR_MS, CLOSE_TIMEOUT_K * slowestMs), source: 'estimated' };
+}
+
+/**
+ * ONE resolver for "what per-stage close timeout does this job get", shared
+ * by `src/planrun.js` (the in-run path) and `scripts/run-u.mjs` (which must
+ * know the answer BEFORE it spawns the outside watchdog — F67 — so the
+ * watchdog's own stale/grace windows are sized off the real ceiling rather
+ * than a hardcoded guess). Two callers computing this independently is
+ * exactly the class of drift this whole rung exists to close (F129's own
+ * lesson, one level up): this function is the only place the precedence is
+ * spelled out.
+ *
+ * Precedence: a signed spec override (`job.closeTimeoutMs`) wins outright,
+ * with NO timing pass run (the pass would waste real machine time and, on a
+ * deliberately slow/hung stage, block for up to `TIMING_PREFLIGHT_CEILING_MS`
+ * for no purpose). Absent that, every stage is timed once (F131's autoset
+ * design) and the ceiling is `max(FLOOR, K × slowest)`.
+ * @param {{job: any, stages: any[], cwd: string, redact?: (s: string) => string, ceilingMs?: number}} args
+ *   `ceilingMs` — see `timeCloseStages`; test seam only.
+ * @returns {Promise<{
+ *   closeTimeoutMs: number|null, source: 'estimated'|'override',
+ *   timing: Awaited<ReturnType<typeof timeCloseStages>>|null, timedOut: boolean,
+ * }>} `closeTimeoutMs: null, timedOut: true` means a stage never finished the
+ *   timing pass — the caller reds `close-timing-red` rather than trusting any
+ *   number here.
+ */
+export async function resolveCloseTimeoutMs({ job, stages, cwd, redact = (s) => s, ceilingMs }) {
+  const signedOverride = typeof job?.closeTimeoutMs === 'number' ? job.closeTimeoutMs : null;
+  if (signedOverride !== null) {
+    return { closeTimeoutMs: signedOverride, source: 'override', timing: null, timedOut: false };
+  }
+  const timing = await timeCloseStages(stages, { cwd, redact, ...(ceilingMs !== undefined ? { ceilingMs } : {}) });
+  if (timing.anyTimedOut) return { closeTimeoutMs: null, source: 'estimated', timing, timedOut: true };
+  const computed = computeCloseTimeoutCeiling({ slowestMs: timing.slowestMs });
+  return { closeTimeoutMs: computed.ceilingMs, source: computed.source, timing, timedOut: false };
+}
+
+/**
+ * The printed banner (build spec M3 §2's exact wording) — ONE spelling, so
+ * the run-u tail and the bundle CLI can never drift into two announcements of
+ * the same number. `source` accepts 'explicit' too: a caller-passed
+ * `closeTimeoutMs` runtime option (the pre-M3 shell/test knob, kept for
+ * backward compatibility and test control — never the signed spec field) is
+ * a real override but not a SIGNED one, so it earns its own honest word
+ * rather than being folded into 'signed override'.
+ * @param {{ceilingMs: number, source: 'estimated'|'override'|'explicit', slowestMs?: number, slowestName?: string|null}} args
+ * @returns {string}
+ */
+export function closeTimeoutBanner({ ceilingMs, source, slowestMs, slowestName }) {
+  const seconds = Math.round(ceilingMs / 1000);
+  if (source === 'override') return `close timeout: ${seconds}s per stage (signed override)`;
+  if (source === 'explicit') return `close timeout: ${seconds}s per stage (explicit runner override)`;
+  return `close timeout: ${seconds}s per stage (estimated from seed timing: slowest ${slowestName ?? '<none>'} ${slowestMs ?? 0}ms × ${CLOSE_TIMEOUT_K}, floor ${Math.round(CLOSE_TIMEOUT_FLOOR_MS / 1000)}s)`;
+}

package/src/index.js

@@ -262,6 +262,20 @@ export { PROMPT_REGISTERS, isPromptFile } from './promptregisters.js';
 export {
   exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
 } from './bundle.js';
+// Close integrity (PRD item 27 / M1, `docs/product/CLOSE-INTEGRITY-BUILD.md`)
+// — the ONE `close-absolute-path` detector shared by `exportBundle` (above)
+// and `runPlan`'s run-start precheck. `readCloseScripts` is the pure reader
+// M2's sha256 fingerprint will reuse.
+export { readCloseScripts, checkCloseAbsolutePaths, absolutePathLiteralsOf } from './close-integrity.js';
+// Close integrity M2 (PRD item 27, `docs/product/CLOSE-INTEGRITY-BUILD.md`) —
+// the close-BYTES half. `hashCloseScriptBytes`/`checkCloseByteSignature` are
+// the fingerprint the run-start precheck and `exportBundle` both compare
+// against; `checkStageByteSignature` is the narrower re-verify `runCloseStages`
+// (src/planrun.js) runs before every close run; `signCloseScripts` is the
+// pure minting helper `scripts/sign-close.mjs` wraps (never writes itself).
+export {
+  hashCloseScriptBytes, checkCloseByteSignature, checkStageByteSignature, signCloseScripts,
+} from './close-integrity.js';
 // Export M2 (`docs/product/EXPORT-BUILD.md`) — the CLI's one entry point,
 // exported as `cliMain` (never `main`, a name generic enough to collide with
 // an adopter's own). `bin/bareloop.mjs` is the only other caller; this export

package/src/job.js

@@ -14,8 +14,9 @@
 // judgment call. Minting policy is product doctrine, not job-authorable.
 
 import { createHash } from 'node:crypto';
-import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals, hasNestedQuantifier } from './validate.js';
+import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals, hasNestedQuantifier, closeScriptCandidateToken } from './validate.js';
 import { validateCloseDecl, DECLARED_CLOSE_CLASSES } from './declaredclose.js';
+import { CLOSE_TIMEOUT_FLOOR_MS } from './closetimeout.js';
 
 // The menus below ARE the close-authoring hierarchy (PRD §7) and ship frozen:
 // they are read at call time, so a mutable export would let adopter code
@@ -140,7 +141,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
 // `steps` stays in the field list ONLY so a retired spec reds by name
 // (`shape-retired`) instead of falling through to a generic unknown-field —
 // the operator gets told what happened, not just that something is wrong.
-const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
 /** the four-field plan shape's core (decision 5) — presence of any of these
  * declares the shape; `tools` (the ceiling) rides the shape but alone does not
  * declare it, so a legacy spec carrying it gets a pointed red, not a conflict */
@@ -148,7 +149,7 @@ const PLAN_CORE_FIELDS = ['goal', 'verdictType', 'close', 'closeDecl', 'checks']
 /** exact field set per close type — anything else is an unknown-field red
  * (freeform code, script bodies, and minting claims all land there) */
 const CLOSE_FIELDS = {
-  predicate: ['type', 'cmd', 'expect', 'judged', 'gapKeep'],
+  predicate: ['type', 'cmd', 'expect', 'judged', 'gapKeep', 'sha256'],
   gold: ['type', 'expected', 'compare'],
   rubric: ['type', 'criteria'],
   hitl: ['type', 'prompt'],
@@ -240,6 +241,21 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
       `integer milliseconds >= ${MIN_WALL_MS} (one close timeout). Enforcement is a between-round deadline, measured as maxWallMs + closeStages x closeTimeoutMs (design addendum 1: loop.stop() cannot cut an in-flight call; W5: every close stage runs under the full timeout), so a budget under one close cannot fund its own close and the advertised number would be more wrong than right`);
   }
 
+  // CLOSE TIMEOUT (PRD item 27/M3, hamr 2026-09-06: "both … autoset and can be
+  // override, same like api pricing"). OPTIONAL and WITH NO CEILING: absent
+  // means the runner autosets it from a $0 seed timing pass
+  // (`src/closetimeout.js`); present is the OPERATOR's own number and — like a
+  // rates-passthrough override (F113) — it may legally sit ABOVE the autoset
+  // estimate, so this is not tighten-only. The one bound that IS enforced is
+  // the floor every close timeout has always had (`CLOSE_TIMEOUT_FLOOR_MS`,
+  // hamr's arbiter constant, 2026-09-07): a value below it could never fund
+  // even a fast close, exactly the "advertised number more wrong than right"
+  // failure `maxWallMs` already guards above.
+  if (spec.closeTimeoutMs !== undefined
+      && !(typeof spec.closeTimeoutMs === 'number' && Number.isInteger(spec.closeTimeoutMs) && spec.closeTimeoutMs >= CLOSE_TIMEOUT_FLOOR_MS)) {
+    red('bounds', 'closeTimeoutMs', `integer milliseconds >= ${CLOSE_TIMEOUT_FLOOR_MS} (the arbiter's floor) — a signed override may sit above the autoset estimate, never below the floor every close timeout has always had`);
+  }
+
   // MODEL — the worker's provider model id (build-list #3, hamr's GO
   // 2026-08-30). OPTIONAL, exactly like budgetUsd/maxWallMs before it: absent
   // means today's behaviour (the runner's own default), present it is part
@@ -356,6 +372,34 @@ function predicateBody(o, at, red) {
   // refusal beats silent misparse (N2 design default)
   else if (/["']/.test(o.cmd)) red('invalid-value', `${at}.cmd`, 'quote characters are inexpressible: cmd runs as whitespace-split argv, no shell');
   else if (o.cmd !== o.cmd.trim()) red('invalid-value', `${at}.cmd`, 'leading/trailing whitespace — argv splits on whitespace and an empty argv[0] cannot spawn; honest refusal beats a silent misparse');
+  // Close-bytes signature (PRD item 27/M2, F129's general fix's own general
+  // fix — N4): the signature must cover the close SCRIPT'S CONTENT, not only
+  // its path (`cmd`). Demanded exactly where a byte-exact fingerprint can be
+  // minted against something: `cmd` names an addressable script by the
+  // SAME shape test `src/close-integrity.js`'s detectors use
+  // (`closeScriptCandidateToken`, src/validate.js — `node <path> …`, OR a
+  // bare directly-executable absolute path such as a `.sh` wrapper; widened
+  // 2026-09-06 after an orchestrator audit found the bare form silently
+  // invisible to both this demand and the byte/path detectors — a blind
+  // instrument). A cmd naming no such script (most test-fixture closes:
+  // `true`, `npx`, `pytest`, a relative bare executable — or a
+  // missing/malformed cmd, already reded above) carries no demand — a stage
+  // with nothing to hash gets no `missing-required` for a field that could
+  // never be minted honestly. `validateJob` stays pure (no fs): this checks
+  // the FIELD'S SHAPE only, never the bytes on disk (that is the runner's
+  // job, `checkCloseByteSignature`/`checkStageByteSignature`).
+  const isScriptCmd = closeScriptCandidateToken(o.cmd) !== null;
+  if (isScriptCmd) {
+    if (o.sha256 === undefined) {
+      red('missing-required', `${at}.sha256`, 'hex sha256 of the script file bytes `cmd` names — mint it with signCloseScripts (src/close-integrity.js) / scripts/sign-close.mjs, never hand-typed');
+    } else if (typeof o.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(o.sha256)) {
+      red('invalid-value', `${at}.sha256`, '64 lowercase hex chars — sha256 of the script file bytes, never the spec, never the path');
+    }
+  } else if (o.sha256 !== undefined && (typeof o.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(o.sha256))) {
+    // not demanded for a non-script cmd, but a PRESENT value is still
+    // shape-checked — a malformed string is a typo either way
+    red('invalid-value', `${at}.sha256`, '64 lowercase hex chars — sha256 of the script file bytes, never the spec, never the path');
+  }
   if (!Number.isInteger(o.expect)) red('invalid-value', `${at}.expect`, 'integer exit code');
   // The judgment-rendered signal (PRD v1.11, optional). Exit code alone
   // cannot separate "the suite ran and failed" from "the suite crashed at
@@ -492,7 +536,7 @@ export function checkMenu(close) {
 }
 
 /** the fields a close STAGE may carry — anything else is a smuggle channel */
-const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs', 'direction'];
+const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs', 'direction', 'sha256'];
 
 /**
  * Validate the staged close. Every stage is a predicate BODY under the same

package/src/plan.js

@@ -177,7 +177,11 @@ export { hasNestedQuantifier };
 export function stageClose(close) {
   if (Array.isArray(close)) return close;
   if (!isObj(close) || close.type !== 'predicate') return null;
-  return [{ name: 'close', cmd: close.cmd, expect: close.expect, judged: close.judged, gapKeep: close.gapKeep }];
+  // `sha256` (M2, PRD item 27) rides through exactly like every other
+  // predicate-body field — a single-object predicate close is byte-signable
+  // the same way a staged close's stages are, and `checkCloseByteSignature`
+  // reads this field off whatever `closeStagesOf` hands back.
+  return [{ name: 'close', cmd: close.cmd, expect: close.expect, judged: close.judged, gapKeep: close.gapKeep, sha256: close.sha256 }];
 }
 
 /**