bareloop 0.21.0 → 0.23.0

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/declaredclose.d.ts

@@ -110,7 +110,8 @@ export function guardNames(closeDecl: any, verdictType: string): string[];
  *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
  *   humanRuling?: {decision: string, text?: string|null}|null,
  *   judgeLoop?: ((o: {system: string}) => any)|null,
- *   onJudgeCost?: ((c: any) => void)|null}} [opts]
+ *   onJudgeCost?: ((c: any) => void)|null,
+ *   callBounds?: (() => {timeoutMs?: number, deadlineMs?: number})|null}} [opts]
  * @returns {Promise<any>}
  */
 export function runDeclaredStages(stages: any[], redact?: (s: string) => string, opts?: {
@@ -129,6 +130,10 @@ export function runDeclaredStages(stages: any[], redact?: (s: string) => string,
         system: string;
     }) => any) | null;
     onJudgeCost?: ((c: any) => void) | null;
+    callBounds?: (() => {
+        timeoutMs?: number;
+        deadlineMs?: number;
+    }) | null;
 }): Promise<any>;
 /**
  * The trend reader's input for ONE close verdict, whichever executor produced

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/job.d.ts

@@ -207,6 +207,10 @@ export const CADENCE_UNITS: readonly string[];
  * subscription — its costUsd axis is NOTIONAL (API-equivalent value, not
  * billed), so it is a DISTINCT condition: rows never pool with anthropic-api
  * rows on the cost axis, and budgets sized for one do not transfer. */
+/** PRD item 28 (2026-09-06/09-09): `openai-api` — an OpenAI-shaped provider,
+ * constructed via `src/providers.js`'s factory. hamr's ruling (PRD 30.7):
+ * `deepseek-chat` is THE secondary provider (one, not a menu of half-tested
+ * models); the factory's tier table is where that lives, not this menu. */
 export const PROVIDERS: readonly string[];
 /** V3 environment label: declared keys only — every field is a lineage-key
  * candidate at N3. `provider` is part of the key by definition (top-level,

package/types/judged.d.ts

@@ -130,12 +130,13 @@ export function locatePrompt(card: any): string;
  * On every route out, red or clean, `onCost` fires exactly once with the honest
  * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
  * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
- *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void}} o
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void,
+ *   callBounds?: {timeoutMs?: number, deadlineMs?: number}}} o
  * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
  *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
  *   raw: ReturnType<typeof scrubRaw>}>}
  */
-export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt, onCost }: {
+export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt, onCost, callBounds, }: {
     artifactText: string;
     card: any;
     loopFactory: (o: {
@@ -148,6 +149,10 @@ export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt,
         costUsd: number | null;
         unpricedRounds: number;
     }) => void;
+    callBounds?: {
+        timeoutMs?: number;
+        deadlineMs?: number;
+    };
 }): Promise<{
     ok: boolean;
     facts: any | null;

package/types/kinds.d.ts

@@ -539,6 +539,11 @@ export type Red = {
  * funded honestly: this executor cannot reach the run's ledger, so every locate
  * call's cost is reported OUT through it, once per call, on every route including
  * the red ones — a paid call that leaves no meter record is F12 in a judge's coat.
+ * `callBounds` is F152/PRD 30.4's per-call TIME bound, read fresh before every
+ * locate attempt — the same derivation the run's own worker rounds carry
+ * (`callBounds()`, src/planrun.js). Absent is the honest unbounded default:
+ * an adopter or test that wires no clock through behaves exactly as before
+ * this field existed.
  * `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
  * toolchain per stage (a suite is the slow one) and a whole read is one opaque
  * await, so the shell gets told as each stage lands. It decides nothing, it is
@@ -571,6 +576,10 @@ export type Ctx = {
         costUsd: number | null;
         unpricedRounds: number;
     }) => void;
+    callBounds?: () => {
+        timeoutMs?: number;
+        deadlineMs?: number;
+    };
     onStage?: (row: {
         stage: string | null;
         kind: string | null;

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/providers.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Look up a provider's table entry. Throws a NAMED error on an unrecognized
+ * provider — never a silent default (the `resolveRates`-style-substring-
+ * match lesson: a forward hazard even at zero observed rounds, MEMORY.md).
+ * `src/job.js`'s `PROVIDERS` menu is the one place a spec's `provider`
+ * field is validated; this is the runtime construction seam it feeds.
+ * @param {string} providerName
+ * @returns {ProviderTableEntry}
+ */
+export function resolveProvider(providerName: string): ProviderTableEntry;
+/**
+ * Construct ONE provider instance for `providerName`/`model`, applying
+ * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)
+ * and the model's own request-key gating (`paramsFor`). `baseUrl` (PRD item
+ * 28, ruling (d), 2026-09-09: admitted in v1) is forwarded only when given —
+ * every provider constructor here defaults it on its own when absent.
+ * @param {string} providerName
+ * @param {{apiKey?: string, model?: string, baseUrl?: string}} [options]
+ */
+export function makeProvider(providerName: string, { apiKey, model, baseUrl }?: {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}): any;
+/**
+ * Build the `{provider, providerFor, judgeProvider}` triple both runners
+ * need (`src/cli.js`'s `buildProviders`, `scripts/run-u.mjs`'s top-level
+ * wiring) — ONE seam instead of two copies of the same construction and
+ * tier-memoization logic. `model`/`tierModels` are already-RESOLVED inputs
+ * (the caller runs `resolveWorkerModel` itself, exactly as both runners did
+ * before this factory existed — that decision stays where each runner's own
+ * `--model` flag/spec precedence lives, not duplicated in here).
+ *
+ * The JUDGE stays pinned to `anthropic-api`/`judgeModel` regardless of
+ * `providerName` — arbiter territory (PRD item 28: "the judge stays PINNED
+ * … regardless of the job's worker provider"). A signed `judge:{provider,
+ * model}` field with its own calibration record is PRD item 28 part (2),
+ * NOT built here; until it lands, the judge always needs its own
+ * `judgeApiKey` (today, always `ANTHROPIC_API_KEY`), independent of which
+ * key the worker used.
+ * @param {object} args
+ * @param {string} args.providerName spec.provider (or the anthropic-api default)
+ * @param {string|undefined} args.apiKey the WORKER's key, read from the provider's own `envKey`
+ * @param {string} args.model the already-resolved worker model id
+ * @param {Readonly<Record<string, string>>} args.tierModels the already-resolved tier -> model map (spec override folded in by the caller)
+ * @param {string|undefined} [args.baseUrl] spec.baseUrl, if any
+ * @param {string|undefined} args.judgeApiKey the judge's own key (today: `ANTHROPIC_API_KEY`)
+ * @param {string} args.judgeModel `JUDGE_MODEL`
+ */
+export function buildRunnerProviders({ providerName, apiKey, model, tierModels, baseUrl, judgeApiKey, judgeModel, }: {
+    providerName: string;
+    apiKey: string | undefined;
+    model: string;
+    tierModels: Readonly<Record<string, string>>;
+    baseUrl?: string | undefined;
+    judgeApiKey: string | undefined;
+    judgeModel: string;
+}): {
+    provider: any;
+    providerFor: (tier: string) => any;
+    judgeProvider: any;
+};
+/**
+ * Today's anthropic-api tier table — EXACTLY the `DEFAULT_TIER_MODELS` both
+ * runners hardcoded before this factory existed. Any change to these two
+ * values is a change to shipped anthropic-api behaviour, not a refactor.
+ */
+export const ANTHROPIC_TIER_MODELS: Readonly<{
+    sonnet: "claude-sonnet-5";
+    haiku: "claude-haiku-4-5-20251001";
+}>;
+/**
+ * DeepSeek (F149/F150) is a SINGLE model, not a tiered family — hamr's
+ * ruling above: one secondary provider, not a menu. Both tiers map to the
+ * same model id ON PURPOSE: `resolveWorkerModel`/a runner's `providerFor
+ * (tier)` only ever LOOK UP a tier's model id (src/job.js:818-827,
+ * scripts/run-u.mjs's `providerFor`) — neither assumes the tiers name
+ * different models — so repeating the one id is the honest representation
+ * of a single-model provider, not a second model masquerading as `haiku`.
+ * If DeepSeek (or a future openai-api entrant) ever ships a genuinely
+ * cheaper tier model, this is where it would earn its own `haiku` id.
+ */
+export const OPENAI_TIER_MODELS: Readonly<{
+    sonnet: "deepseek-chat";
+    haiku: "deepseek-chat";
+}>;
+export type ProviderTableEntry = {
+    /**
+     * the bare-agent provider class
+     */
+    ctor: new (options: any) => any;
+    /**
+     * the environment variable this provider reads its key from
+     */
+    envKey: string;
+    /**
+     * tier name -> model id
+     */
+    tiers: Readonly<Record<string, string>>;
+    /**
+     * per-model request-key/param gating, applied on TOP of {exposeErrorBody:true, apiKey, model, baseUrl?}
+     */
+    paramsFor: (model: string | undefined) => Record<string, any>;
+};

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/ratelimit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Is `err` an HTTP 429 (rate-limited) response? True ONLY for an explicit
+ * status of 429 on the error itself. Nothing else qualifies — not message
+ * text (a message merely containing "429" is not this), not `retryable`,
+ * not any other status. Symmetric with `isTransportFailure`'s own status
+ * check (src/transport.js), just reading the opposite branch of it.
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isRateLimited(err: any): boolean;
+/**
+ * The vendor's RAW stated wait, in milliseconds, parsed straight from the
+ * error message — no default, no margin, no cap. `null` when nothing in the
+ * message matches a known shape. Exported separately from `rateLimitWaitMs`
+ * so a caller that wants to report the vendor's own number on the spine
+ * (`statedMs`) never has to re-derive it from the margin-adjusted figure.
+ *
+ * bare-agent does not expose the vendor's `retry-after` /
+ * `x-ratelimit-reset-*` response headers on the thrown error (BA-26) — the
+ * delay exists only in the vendor's English message text, so this parses
+ * that text. Verified real shape (OpenAI, run `8ev2sdkn`, 2026-09-08):
+ * "Please try again in 11.996s." This also supports "try again in 1.5
+ * seconds", "try again in 20ms", "retry after 30s", and "retry after 30
+ * seconds" — case-insensitive.
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function statedWaitMs(err: any): number | null;
+/**
+ * How long to wait before retrying a 429, in milliseconds — or `null`
+ * meaning "do not retry at all" (either the parsed wait exceeds
+ * `RATE_LIMIT_MAX_WAIT_MS`, in which case waiting that long is the
+ * operator's decision, not ours).
+ *
+ * A parsed value gets `PARSED_DELAY_MARGIN_MS` added (the vendor's stated
+ * number is the earliest moment its window resets, not a safe one to fire
+ * on), capped so the margin itself can never push a parsed value over
+ * `RATE_LIMIT_MAX_WAIT_MS`. When nothing parses, `RATE_LIMIT_DEFAULT_WAIT_MS`
+ * is returned as-is, with no margin added (there is nothing to add margin
+ * to — it is already a conservative guess, not an earliest-moment reading).
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function rateLimitWaitMs(err: any): number | null;
+/** The fixed retry budget: ONE extra attempt after a 429. Never read from a
+ * job spec or CLI flag — raising it is arbiter territory, mirroring
+ * transport.js's TRANSPORT_RETRIES exactly (tighten-only doctrine). */
+export const RATE_LIMIT_RETRIES: 1;
+/** bare-agent's `Retry.call` (if ever used) counts ATTEMPTS, not retries;
+ * this module's own hand-rolled ladder (src/planrun.js) does the same for
+ * symmetry with TRANSPORT_MAX_ATTEMPTS. */
+export const RATE_LIMIT_MAX_ATTEMPTS: number;
+/** The hard cap on how long we will ever wait for a vendor-stated 429 delay.
+ * A vendor asking for longer than this is not honoured — we do not retry at
+ * all in that case. Waiting that long is the operator's decision, not ours
+ * (arbiter territory: nothing here escalates the wait past what hamr set). */
+export const RATE_LIMIT_MAX_WAIT_MS: 60000;
+/** Used only when the vendor's message carries no parseable delay at all. */
+export const RATE_LIMIT_DEFAULT_WAIT_MS: 5000;

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,27 @@
  * @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>`
+ *   NOTE: `job-end` can ALSO land with outcome 'runner-drained' (F140/PRD item
+ *   28(c)) — the `beforeExit` backstop's own terminal, emitted from OUTSIDE this
+ *   function's normal control flow when the process drains with no `job-end` at
+ *   all (a provider promise that never settled). It never appears as this
+ *   function's own RETURN value (nothing is left to receive it), only as the
+ *   spine's terminal record. Non-zero exit, `spendComplete:false` always, and
+ *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
+ *   unknown in-flight state is not a known-safe resume point.
  */
-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 +193,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 +226,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 */
 /**

package/types/transport.d.ts

@@ -2,11 +2,17 @@
  * Is `err` a transport-class failure — the request never produced an HTTP
  * response? True for: a TLS fault mid-record ("bad record mac" and kin), a
  * reset/broken/timed-out socket (ECONNRESET, EPIPE, ETIMEDOUT, ECONNREFUSED,
- * ENETUNREACH — by code on the error itself or on `err.cause`), and
- * `fetch failed` wrapping a network `cause`. False for anything carrying an
- * HTTP status (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
+ * ENETUNREACH — by code on the error itself or on `err.cause`), `fetch
+ * failed` wrapping a network `cause`, and — as of bare-agent 0.42.0 (BA-25)
+ * — a `ProviderError` whose `err.context.bound === 'transport'`: the
+ * response stream ended (`'aborted'`/`'error'`/premature `'close'`) after
+ * headers but before the body completed, which bare-agent itself rejects as
+ * retryable with no HTTP status. False for anything carrying an HTTP status
+ * (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
  * `err.retryable === false` — those are provider RESPONSES, not transport
- * casualties, and bare-agent's own policy governs them unchanged.
+ * casualties, and bare-agent's own policy governs them unchanged; both
+ * guards run BEFORE the `context.bound` check, so a status or an explicit
+ * `retryable:false` wins even if `bound` says 'transport'.
  * @param {any} err
  * @returns {boolean}
  */