bareloop 0.20.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/bundle.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Recompute the bundle hash from what is ACTUALLY on disk right now (never
+ * trusts the stored manifest). Throws only if `dir` itself does not exist —
+ * every other absence (a missing spec.json, an empty close/) folds into the
+ * hash as an omitted file, which is exactly what makes a swapped/deleted
+ * script change the hash.
+ * @param {string} dir bundle directory
+ * @returns {string} sha256 hex
+ */
+export function bundleHash(dir: string): string;
+/**
+ * EXPORT — mints a bundle directory from a signed job spec (`docs/product/
+ * EXPORT-BUILD.md`, "The bundle"). Every check below runs BEFORE anything
+ * touches disk (typed reds, nothing written): a partially-written bundle
+ * would be worse than no bundle, since `readBundle`'s tamper check has
+ * nothing trustworthy to compare against yet.
+ *
+ * Refusals, each a distinct red code:
+ *  - `no-bridge-at-hash` — neither of the job's two possible bridge names —
+ *    `spec.job` itself, or its SHAPE FORK `shapeForkName(spec.job,
+ *    closeStagesOf(spec))` (the name `writeGreenRow`/`writeRunGreenRow` in
+ *    `src/reuse.js` mint whenever a run's close-stage set differs from the
+ *    base bridge's `closeStageNames` — same derivation, imported rather than
+ *    re-spelled, so the two names cannot drift) — carries a recorded specHash
+ *    (bridge-level or on some version) equal to `jobSpecHash(spec)`: nothing
+ *    has ever greened THIS exact spec, so there is nothing proven to ship.
+ *    Every candidate bridge that DOES exist (base and/or fork) still ships
+ *    into `bridges/` — the spec says "the job's WHOLE registry history
+ *    (greens and reds)", not just the one that matched.
+ *  - `close-cmd-unrelocatable` — a `close[].cmd` is not `node <abs .mjs> …`.
+ *  - `close-script-missing` — a cmd names a script `closeScripts` does not
+ *    carry the source for.
+ *  - `close-script-collision` — two different script paths share a basename;
+ *    copying both into one flat `close/` directory would silently clobber one.
+ *  - `close-import-unexported` — a close script imports a name from
+ *    bareloop's own src that `src/index.js` does not export.
+ *  - `close-import-unparsed` — a close script's import is a shape this
+ *    module cannot verify at all (default import, `* as ns`, mixed
+ *    default+named/namespace, a bare side-effect import, or a dynamic
+ *    `import()`), or is a relative import that does not point into
+ *    `src/` (a sibling file `close/` never ships, so it would be missing
+ *    from the bundle). Fails safe rather than silently accepting what it
+ *    cannot read.
+ *  - `close-absolute-path` — a close script's source bakes in a string
+ *    literal that is an absolute POSIX path which exists on the exporting
+ *    machine and is outside the system-prefix allow-list (see
+ *    `absolutePathLiteralsOf`): a close judges the cwd the runner gives it,
+ *    never a path baked into the script — F8/F129, the live defect this
+ *    guard would have refused at export time before any run.
+ *  - `outdir-not-empty` — `outDir` exists and already holds files.
+ *  - `registry-unreadable` — `registryDir` itself could not be read
+ *    (bubbled from `loadRegistry`).
+ * @param {{ spec: any, closeScripts: Record<string, string>, registryDir: string, outDir: string, bareloopVersion: string }} o
+ * @returns {{ ok: boolean, reds: Red[], dir: string|null, bundleHash: string|null, manifest: any|null }}
+ */
+export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloopVersion }: {
+    spec: any;
+    closeScripts: Record<string, string>;
+    registryDir: string;
+    outDir: string;
+    bareloopVersion: string;
+}): {
+    ok: boolean;
+    reds: Red[];
+    dir: string | null;
+    bundleHash: string | null;
+    manifest: any | null;
+};
+/**
+ * READ a bundle directory back: the manifest/spec, tamper-checked against
+ * what is actually on disk, plus the record-only bridges/blessing/history a
+ * runner needs beside them. Never throws — every failure is a typed red.
+ *
+ * `bundle-tampered` (N4) is a RED, never a warning, and runs whenever both a
+ * manifest and a spec could be read at all — a swapped close script must be
+ * caught here, before any caller reaches `runJob`.
+ * @param {string} dir bundle directory
+ * @returns {{ ok: boolean, reds: Red[], spec: any, manifest: any, bridges: any[], blessing: any, history: any[] }}
+ */
+export function readBundle(dir: string): {
+    ok: boolean;
+    reds: Red[];
+    spec: any;
+    manifest: any;
+    bridges: any[];
+    blessing: any;
+    history: any[];
+};
+/**
+ * The IN-MEMORY `$BARELOOP_BUNDLE` substitution (the frozen spec's "two
+ * facts": the runner never touches the spec on disk, it substitutes the
+ * absolute bundle directory into a copy before `runJob`, and signs THAT
+ * substituted spec's hash — not the on-disk one). `approveHash` is the value
+ * an `--approve` flag / a `history.jsonl` row must record.
+ * @param {{ spec: any }} bundle a `readBundle` result (or anything carrying `.spec`)
+ * @param {string} bundleDir absolute or relative bundle directory
+ * @returns {{ spec: any, approveHash: string }}
+ */
+export function resolveBundleSpec(bundle: {
+    spec: any;
+}, bundleDir: string): {
+    spec: any;
+    approveHash: string;
+};
+/**
+ * TIGHTEN-ONLY envelope check (hamr Q8: raising the ceiling is a re-export,
+ * never a runner flag). Each GIVEN number must be ≤ the bundle spec's own —
+ * an absent field in the envelope trivially passes (nothing was asked to
+ * tighten), and a spec with no ceiling of its own for that field (only
+ * `maxWallMs` is ever absent — `budgetUsd` is required) has nothing to
+ * widen, so a given number passes there too.
+ * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
+ * @param {{ budgetUsd?: number, maxWallMs?: number }} envelope
+ * @returns {{ ok: boolean, reds: Red[] }}
+ */
+export function checkEnvelope(spec: any, envelope?: {
+    budgetUsd?: number;
+    maxWallMs?: number;
+}): {
+    ok: boolean;
+    reds: Red[];
+};
+/**
+ * Write `blessing.json`: the FIRST GREEN RUN on the importer's own machine
+ * signs the bundle as trustworthy (hamr Q2), so later runs need no
+ * `--approve` (hamr: "no-resign"). Overwrites any prior blessing — there is
+ * only ever one, for the bundle's current `bundleHash`.
+ * @param {string} dir bundle directory
+ * @param {{ bundleHash: string, runid: string, outcome: string, host?: string, blessedAt?: string }} record
+ * @returns {any} the blessing object written
+ */
+export function bless(dir: string, record: {
+    bundleHash: string;
+    runid: string;
+    outcome: string;
+    host?: string;
+    blessedAt?: string;
+}): any;
+/**
+ * Read `blessing.json` back and judge it against the bundle's CURRENT
+ * manifest hash. Three outcomes, never conflated: no blessing at all
+ * (`unblessed: true` — the bundle has simply never greened here, not a red);
+ * a blessing whose hash no longer matches the manifest (`blessing-stale` —
+ * the bundle was re-exported/edited since the run that blessed it); a match.
+ * @param {{ manifest: any, blessing: any }} bundle a `readBundle` result
+ * @returns {{ ok: boolean, unblessed: boolean, reds: Red[] }}
+ */
+export function verifyBlessing(bundle: {
+    manifest: any;
+    blessing: any;
+}): {
+    ok: boolean;
+    unblessed: boolean;
+    reds: Red[];
+};
+/**
+ * F128 preflight — can this bundle's close scripts actually resolve `import
+ * ... from 'bareloop'` at runtime? The bundle's own `package.json` declares
+ * `bareloop` as ITS dependency (`npm install` must be run INSIDE the bundle
+ * directory — validation step 2 was corrected 2026-09-06, see the dated
+ * addendum in `docs/product/EXPORT-BUILD.md`); nothing installs it for the
+ * bundle as a side effect of the bundle being installed as someone else's
+ * dependency. Left unchecked, a missing `node_modules` crashes every close
+ * stage deep inside the close-first precheck with a bare
+ * `ERR_MODULE_NOT_FOUND`, which surfaces as a generic `close-red` with no
+ * cure line (the live defect this fixes) — this check runs first and fails
+ * fast with the exact command to run.
+ *
+ * Resolves the bare specifier `'bareloop'` exactly as a close script would,
+ * from inside the bundle's own `close/` directory (the probe path itself
+ * need not exist — `createRequire`/`resolve` only use it to anchor the
+ * `node_modules` walk). Going through `require.resolve` also walks
+ * `bareloop`'s own `exports` map (the package root, `"."` -> `./src/
+ * index.js`), so a bare successful resolve already proves a real,
+ * exports-map-shaped `bareloop` package is reachable from THIS bundle's own
+ * dependency chain — not some unrelated global install. Any resolution
+ * counts (a direct `node_modules/bareloop`, a symlink into it, or a parent
+ * `node_modules/bareloop` up the directory chain) — it only has to resolve.
+ * @param {string} bundleDir
+ * @returns {{ ok: boolean, reds: Red[] }}
+ */
+export function checkBundleDeps(bundleDir: string): {
+    ok: boolean;
+    reds: Red[];
+};
+/**
+ * Append one row to `history.jsonl` — one `bareloop run` on this machine per
+ * line. Same convention as `spine.js`/`ledger.js`: `appendFileSync` opens
+ * with O_APPEND, so one line under PIPE_BUF is written atomically with
+ * respect to other appenders; there is no read-modify-write here to race.
+ * @param {string} dir bundle directory
+ * @param {any} row
+ */
+export function appendHistory(dir: string, row: any): void;
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};

package/types/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The one entry point. Never calls `process.exit` — always returns an exit
+ * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
+ * queued stdout on its own (F-something: `process.exit()` can discard it).
+ * @param {string[]} argv
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, now?: () => number, stdin?: any }} deps
+ * @returns {Promise<number>}
+ */
+export function main(argv: string[], deps?: {
+    env?: Record<string, string | undefined>;
+    stdout?: any;
+    stderr?: any;
+    cwd?: string;
+    provider?: any;
+    providerFor?: any;
+    judgeProvider?: any;
+    now?: () => number;
+    stdin?: any;
+}): Promise<number>;

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

@@ -1,5 +1,6 @@
 export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
+export { main as cliMain } from "./cli.js";
 export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
 export { globToPrefix, scanSecrets } from "./validate.js";
 export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
@@ -8,7 +9,7 @@ export { snapshotScope, evalExits } from "./exits.js";
 export { runJob, ACCOUNTED_ROUND_TYPES } from "./run.js";
 export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists, QUARANTINED_VERDICTS, QUARANTINED_CODE, quarantinesCredit, newestEligibleVersion, reuseEligibility, recordDoor } from "./bridges.js";
 export { renderListing, selectionPrompt } from "./selection.js";
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow } from "./reuse.js";
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow, shapeForkName } from "./reuse.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES, VOUCHED_RATE_SOURCES, rateProvenance, spendProvenance } from "./ledger.js";
 export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from "./workbranch.js";
 export { createReadShim, wrapReadTool, readShimArm, readShimStrategy, READ_SHIM_CAP, READ_SHIM_STRATEGY, READ_SHIM_DIFF_STRATEGY, READ_SHIM_ARMS } from "./readshim.js";
@@ -26,3 +27,5 @@ export { runBehaviour, formatBehaviour } from "./behaviour.js";
 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";