bareloop 0.21.0 → 0.22.0

package/src/validate.js

@@ -73,6 +73,65 @@ export function isNonEmptyString(v) {
   return typeof v === 'string' && v.length > 0;
 }
 
+/**
+ * PRD item 27/M2 close-bytes signature, orchestrator-flagged gap
+ * (2026-09-06): a close stage's `cmd` can name an addressable script TWO
+ * ways — `node <path> …` (M1's original scope) or a BARE directly-executable
+ * absolute path (a `.sh` wrapper, e.g. `jobs/aurora-testgen-cold.json`'s
+ * close, which `readCloseScripts` used to skip entirely, leaving both
+ * `close-absolute-path` and the sha256 signature blind to it — a "blind
+ * instrument" the audit named directly). This list is the shared, STATIC
+ * (no fs) shape test both `src/job.js` (which only needs to know WHETHER a
+ * stage names an addressable script, to decide whether `sha256` is
+ * demanded) and `src/close-integrity.js` (which resolves the token against
+ * a real cwd and reads it off disk) key off — one spelling, so the demand
+ * and the detector can never drift apart about which stages are in scope.
+ * A leading-interpreter cmd (`sh`/`bash`/`python`/`python3`/`npx` besides
+ * `node`) is included for the same reason `node` is: a close author may use
+ * any of them, and a scope that only recognized `node` would just move the
+ * blind spot rather than close it.
+ * @type {readonly string[]}
+ */
+export const CLOSE_SCRIPT_INTERPRETERS = Object.freeze(['node', 'sh', 'bash', 'python', 'python3', 'npx']);
+
+/**
+ * The candidate script path TOKEN a close stage's `cmd` names, by SHAPE
+ * alone — no fs, no cwd resolution, so this is safe for `validateJob` (pure)
+ * to call directly. Two recognized forms, first match wins:
+ *   - an INTERPRETER cmd: the token is the first argv[1..] element that is
+ *     PATH-SHAPED (not a `-`-prefixed flag, and either contains `/` or ends
+ *     in one of `.mjs .cjs .js .ts .sh .py`) — never just argv[1] outright.
+ *     `node --enable-source-maps ./close/x.mjs stage` names `./close/x.mjs`,
+ *     not `--enable-source-maps`; `python -m pytest` and `npx tsc --noEmit`
+ *     name NOTHING (`-m`/`--noEmit` are flags, `pytest`/`tsc` are bare
+ *     command names with no path shape) — fixed 2026-09-06 (orchestrator
+ *     audit) after the earlier bare-argv[1] version demanded a sha256 for a
+ *     token that named no file, making such a spec unsignable forever (the
+ *     sign helper reads nothing, the validator reds permanently);
+ *   - a bare cmd whose argv[0] ITSELF is an absolute path (no interpreter
+ *     prefix — a `.sh`/other directly-executable close script) → the token
+ *     is argv[0].
+ * Anything else — a relative bare executable (`true`, `pytest`), an
+ * interpreter with no path-shaped argument (`python -m pytest`, `npx tsc
+ * --noEmit`), a non-string/empty cmd — names no addressable file under this
+ * scheme and returns null; those stages carry no sha256 demand and are
+ * invisible to the byte/path detectors, exactly as they always were (most
+ * test-fixture closes use exactly this shape on purpose, to exercise
+ * runtime behaviour with no real script file at all).
+ * @param {unknown} cmd
+ * @returns {string|null}
+ */
+export function closeScriptCandidateToken(cmd) {
+  if (typeof cmd !== 'string') return null;
+  const parts = cmd.trim().split(/\s+/);
+  if (!parts[0]) return null;
+  if (CLOSE_SCRIPT_INTERPRETERS.includes(parts[0])) {
+    const pathShaped = (/** @type {string} */ tok) => !tok.startsWith('-') && (tok.includes('/') || /\.(?:mjs|cjs|js|ts|sh|py)$/.test(tok));
+    return parts.slice(1).find(pathShaped) ?? null;
+  }
+  return parts[0].startsWith('/') ? parts[0] : null;
+}
+
 // Secrets never enter the tree/spine/configs (hard line) — BOTH config
 // documents get the same sweep: the agent-authored workflow config is the
 // riskier entry point (machine-written), the operator's job spec the other.

package/types/close-integrity.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 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: string): string;
+/**
+ * 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: string): string[];
+/**
+ * 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: any, cwd: string): {
+    stage: string;
+    path: string;
+    bytes: string | null;
+    sha256: string | null;
+}[];
+/**
+ * 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: any, cwd: string): {
+    ok: true;
+} | {
+    ok: false;
+    reds: {
+        stage: string;
+        path: string;
+        literal: string;
+    }[];
+};
+/**
+ * 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: any, cwd: string): {
+    ok: true;
+} | {
+    ok: false;
+    reds: ByteRed[];
+};
+/**
+ * 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: any, cwd: string, closeDir: string | null | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    reds: {
+        stage: string;
+        path: string;
+    }[];
+};
+/**
+ * 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: any[], cwd: string): {
+    ok: true;
+} | {
+    ok: false;
+    reds: ByteRed[];
+};
+/**
+ * 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: any, cwd: string): {
+    ok: boolean;
+    spec: any;
+    changes: {
+        stage: string;
+        path: string;
+        old: string | null;
+        new: string;
+    }[];
+    missing: {
+        stage: string;
+        path: string;
+    }[];
+};
+/**
+ * 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: string[];
+/** 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";
+export type ByteRed = {
+    stage: string;
+    path: string;
+    expected: string;
+    actual: string | null;
+};

package/types/closetimeout.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 function timeCloseStages(stages: any[], { cwd, redact, ceilingMs }?: {
+    cwd?: string;
+    redact?: (s: string) => string;
+    ceilingMs?: number;
+}): Promise<{
+    perStage: {
+        name: string;
+        ms: number;
+        exitCode: number | null;
+        timedOut: boolean;
+    }[];
+    slowestMs: number;
+    slowestName: string | null;
+    anyTimedOut: boolean;
+}>;
+/**
+ * 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 }: {
+    slowestMs: number;
+    overrideMs?: number | null;
+}): {
+    ceilingMs: number;
+    source: "estimated" | "override";
+};
+/**
+ * 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 function resolveCloseTimeoutMs({ job, stages, cwd, redact, ceilingMs }: {
+    job: any;
+    stages: any[];
+    cwd: string;
+    redact?: (s: string) => string;
+    ceilingMs?: number;
+}): Promise<{
+    closeTimeoutMs: number | null;
+    source: "estimated" | "override";
+    timing: Awaited<ReturnType<typeof timeCloseStages>> | null;
+    timedOut: boolean;
+}>;
+/**
+ * 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 }: {
+    ceilingMs: number;
+    source: "estimated" | "override" | "explicit";
+    slowestMs?: number;
+    slowestName?: string | null;
+}): string;
+/** 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: 120000;
+/** 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: 120000;
+/**
+ * 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: number;

package/types/index.d.ts

@@ -28,3 +28,4 @@ export { replayRun, formatReplay } from "./replay.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";
 export { PROMPT_REGISTERS, isPromptFile } from "./promptregisters.js";
 export { exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps } from "./bundle.js";
+export { readCloseScripts, checkCloseAbsolutePaths, absolutePathLiteralsOf, hashCloseScriptBytes, checkCloseByteSignature, checkStageByteSignature, signCloseScripts } from "./close-integrity.js";

package/types/planrun.d.ts

@@ -221,7 +221,14 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   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`
@@ -392,12 +399,18 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   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 function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -414,6 +427,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     capRuns?: number | undefined;
     strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
+    closeDir?: string | null | undefined;
     maxStepRounds?: number | undefined;
     scout?: boolean | undefined;
     scoutRounds?: number | undefined;
@@ -449,6 +463,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         fromRunid?: string | null;
         receivedAt?: string | null;
     } | null | undefined;
+    resumable?: boolean | undefined;
 }): Promise<string>;
 /**
  * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a

package/types/ralph.d.ts

@@ -54,17 +54,24 @@
  *
  * @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 function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
+export function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep, closeDir }?: {
     timeoutMs?: number;
     cwd?: string;
     expect?: number;
@@ -73,6 +80,7 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
         min: number;
     };
     gapKeep?: string;
+    closeDir?: string | null;
 }): Promise<{
     verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
     gap?: string;
@@ -104,12 +112,13 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
  *
  * @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 function runStages(stages: any[], redact?: (s: string) => string, { timeoutMs, cwd }?: {
+export function runStages(stages: any[], redact?: (s: string) => string, { timeoutMs, cwd, closeDir }?: {
     timeoutMs?: number;
     cwd?: string;
+    closeDir?: string | null;
 }): Promise<any>;
 /**
  * Bound an over-long close stream to a head sample + elided middle + tail. When
@@ -210,9 +219,13 @@ export function boundGap(s: string, keepPattern?: string): string;
  *   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 function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
+export function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites, closeDir }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close?: string[] | undefined;
     judge?: (() => Promise<{
@@ -237,6 +250,7 @@ export function ralph({ middle, close, judge, capRuns, ladder, emit, redact, clo
     } | undefined;
     gapKeep?: string | undefined;
     workerWrites?: (() => string[]) | undefined;
+    closeDir?: string | null | undefined;
 }): Promise<"green" | "escalated">;
 /**
  * What the close child must NOT be able to read (operator ruling, 2026-07-31:

package/types/reuse.d.ts

@@ -377,6 +377,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
@@ -411,6 +412,7 @@ export function runReuse(opts: {
     capRuns?: number | undefined;
     strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
+    closeDir?: string | undefined;
     layerRoot?: boolean | undefined;
     readShim?: boolean | "cap" | "diff" | undefined;
     resume?: any;

package/types/reviewdoor.d.ts

@@ -40,6 +40,7 @@ export function doorAgeGate(door: any, { now, ttlMs }?: {
  * @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
@@ -51,13 +52,14 @@ export function doorAgeGate(door: any, { now, ttlMs }?: {
  *   doorRecorded: boolean, reds: any[], mechanical: any, door: any, text: string|null,
  *   options: string[], ttlMs: number, note: string|null}>}
  */
-export function answerReviewDoor({ job, workdir, events, decision, text, closeTimeoutMs, registryDir, name, runid, at, now, ttlMs, emit, }: {
+export function answerReviewDoor({ job, workdir, events, decision, text, closeTimeoutMs, closeDir, registryDir, name, runid, at, now, ttlMs, emit, }: {
     job: any;
     workdir: string;
     events: any[];
     decision: string;
     text?: string | null | undefined;
     closeTimeoutMs?: number | undefined;
+    closeDir?: string | null | undefined;
     registryDir?: string | null | undefined;
     name?: string | null | undefined;
     runid?: string | null | undefined;

package/types/run.d.ts

@@ -45,7 +45,22 @@
  *   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
@@ -141,13 +156,19 @@
  * @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 function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -164,6 +185,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     strikeLimit?: number | undefined;
     shellCapUsd?: number | undefined;
     closeTimeoutMs?: number | undefined;
+    closeDir?: string | null | undefined;
     bridge?: unknown;
     priorSpentUsd?: number | undefined;
     priorSpendComplete?: boolean | undefined;
@@ -196,6 +218,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         fromRunid?: string | null;
         receivedAt?: string | null;
     } | null | undefined;
+    resumable?: boolean | undefined;
 }): Promise<string>;
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 /**