bareloop 0.21.0 → 0.23.0

package/src/run.js

@@ -106,7 +106,22 @@ async function primitiveSmoke(workdir) {
  *   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
@@ -202,13 +217,27 @@ async function primitiveSmoke(workdir) {
  * @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 async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -324,6 +353,15 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     // than guessing.
     verdictType: job.verdictType,
     ...(typeof provider?.model === 'string' ? { model: provider.model } : {}),
+    // PRD item 28 / F156 — WHICH provider actually ran, and against which
+    // endpoint. Report-only, but without it an archived spine cannot be
+    // segmented by provider at all: every cost, duration and outcome row from
+    // the day openai-api joined the menu would pool anthropic and non-anthropic
+    // runs into one contaminated aggregate, which is the reading error this repo
+    // has already paid for once. `baseUrl` rides along only when the job set one
+    // (an absent baseUrl is the vendor's own host, not an unknown).
+    provider: typeof job.provider === 'string' ? job.provider : null,
+    ...(typeof job.baseUrl === 'string' ? { baseUrl: job.baseUrl } : {}),
     // F118: replay reads this; report-only. `dirty` is deliberately omitted —
     // it can't be known without a shell, and null = unknown, never faked.
     code: (() => { const { version, sha } = codeVersion(); return { version, sha }; })(),
@@ -359,12 +397,46 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
       : {}),
   });
 
+  // F140/PRD item 28 (c) — the backstop that fires on the ABSENCE of a
+  // `job-end`. A provider promise that never settles (BA-25's class; 0.42.0
+  // closed the known drop cases per F141 but the class itself is "an
+  // instrument fires on absence", not a specific bug) lets node drain with
+  // nothing else holding the event loop, and the process exits with no
+  // terminal record at all — no escalation, no outcome, no way to tell a
+  // silent drain from an operator kill. `ended` is the one flag every
+  // job-end site sets via the local `end()` helper below (never a second
+  // spelling of "did we finish" that could fall out of sync with the real
+  // emits). One `beforeExit` listener per call, removed in the `finally` so
+  // multiple runs in one process (tests included) never leak listeners.
+  let ended = false;
+  /** @type {(outcome: string, extra?: object) => object} */
+  const end = (outcome, extra = {}) => {
+    ended = true;
+    return emit('job-end', { outcome, ...extra });
+  };
+  const onBeforeExit = () => {
+    if (ended) return;
+    // A drained run's in-flight spend is unknowable — the floor already
+    // accumulated is honest, an exact-looking total would not be (F6).
+    end('runner-drained', {
+      ...spend(),
+      spendComplete: false,
+      detail: 'process drained with no job-end — a provider call never settled (F140)',
+    });
+    // Never process.exit() (can discard queued stdout) — set the code and
+    // let node exit on its own; preserve a more specific code if one is
+    // already set.
+    process.exitCode = process.exitCode || 1;
+  };
+  process.once('beforeExit', onBeforeExit);
+
+  try {
   // 2. known-answer smoke before tokens (A3: silent degradation throws nothing)
   const smoke = await primitiveSmoke(workdir);
   emit('primitive-smoke', smoke);
   if (!smoke.ok) {
     emit('escalation', { category: 'smoke-red', decisionReady: true, decision: `The ${smoke.primitive} primitive failed its known-answer check — no run verdict is trustworthy on a degraded primitive.`, options: ['fix the primitive/store', 'abandon the run'], detail: smoke.detail });
-    emit('job-end', { outcome: 'smoke-red', ...spend() });
+    end('smoke-red', spend());
     return 'smoke-red';
   }
 
@@ -405,7 +477,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   };
   const pricingRed = () => {
     emit('escalation', { category: 'pricing-red', decisionReady: true, decision: 'A provider result carried no priced cost — the hard cap cannot govern spend it cannot see (unpriced is never free, F6).', options: ['bind a priced provider/model', 'abandon the run'], spentUsd });
-    emit('job-end', { outcome: 'pricing-red', ...spend() });
+    end('pricing-red', spend());
     return 'pricing-red';
   };
 
@@ -415,14 +487,14 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact
     });
     if (unpriced) return pricingRed();
     if (outcome.startsWith('step-red:')) {
-      emit('job-end', { outcome: 'step-red', step: outcome.slice('step-red:'.length), ...spend() });
+      end('step-red', { step: outcome.slice('step-red:'.length), ...spend() });
     } else if (outcome === 'provider-red' || outcome === 'step-stalled') {
       // F44: a transport-throw provider-red never returned a usage figure for the
       // failed call, so the priced sum is a FLOOR, not the total — spendComplete
@@ -432,10 +504,13 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
       // the known cost of self-heal — and an unbilled reissue is indistinguishable
       // from a billed one from here. Reporting the priced sum as exact would be F6
       // in a self-heal coat.
-      emit('job-end', { outcome, ...spend(), spendComplete: false });
+      end(outcome, { ...spend(), spendComplete: false });
     } else {
-      emit('job-end', { outcome, ...spend() });
+      end(outcome, spend());
     }
     return outcome;
   }
+  } finally {
+    process.removeListener('beforeExit', onBeforeExit);
+  }
 }

package/src/transport.js

@@ -3,14 +3,18 @@
 //
 // A transport failure is fetch THROWING — the request never produced an HTTP
 // response at all (a TLS fault mid-record, a reset socket, a DNS/network
-// failure). That is a DIFFERENT unknown from an HTTP response the provider
-// DID send (4xx/5xx/429): a response means the provider answered, so
-// bare-agent's own retry policy for those stays exactly what it is — this
-// module never widens that. Retrying only the no-response case is the whole
-// point: a call that dies mid-read may already have been billed (retry can
-// pay twice), so the retry budget stays as tight as hamr authorized it —
-// exactly one extra attempt, never configurable upward from a job spec or
-// argv (tighten-only doctrine).
+// failure) — OR bare-agent's own BA-25 `guardResponseSettles` rejecting a
+// response cut after headers but before the body completed (a peer
+// `'aborted'`/`'error'`/premature `'close'`), tagged `context.bound:
+// 'transport'` (bare-agent 0.42.0, node_modules/bare-agent/src/provider-http.js).
+// That is a DIFFERENT unknown from an HTTP response the provider DID send
+// (4xx/5xx/429): a response means the provider answered, so bare-agent's own
+// retry policy for those stays exactly what it is — this module never widens
+// that. Retrying only the no-response case is the whole point: a call that
+// dies mid-read may already have been billed (retry can pay twice), so the
+// retry budget stays as tight as hamr authorized it — exactly one extra
+// attempt, never configurable upward from a job spec or argv (tighten-only
+// doctrine).
 //
 // Scope: this module wires ONE seam — the worker Loop built in
 // src/planrun.js's `newLoop` (~line 2239), which is the ONE factory behind
@@ -31,11 +35,17 @@ export const TRANSPORT_MAX_ATTEMPTS = TRANSPORT_RETRIES + 1;
  * 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}
  */
@@ -47,6 +57,13 @@ export function isTransportFailure(err) {
   if (typeof status === 'number') return false;
   if (err.retryable === false) return false;
 
+  // BA-25 (bare-agent 0.42.0): bare-agent's own transport classification —
+  // `guardResponseSettles` tags a body-cut-after-headers rejection with
+  // `context.bound: 'transport'`. Only 'transport' qualifies here — a
+  // sibling bound like 'idle' (BA-19's deadline-idle guard) already
+  // qualifies via its ETIMEDOUT code below, never by bound alone.
+  if (err.context && err.context.bound === 'transport') return true;
+
   const codeOf = (e) => (e && typeof e.code === 'string' ? e.code : null);
   const TRANSPORT_CODES = new Set(['ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ECONNREFUSED', 'ENETUNREACH', 'EAI_AGAIN']);
   const code = codeOf(err) ?? codeOf(err.cause);

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

@@ -91,7 +91,7 @@ export function defaultSurveyor({ workdir, granted, auditPath, ctx }: {
  *
  * @param {{workdir: string, provider?: any,
  *   rounds?: number, minBytes?: number, blobMax?: number, maxTokens?: number, ctx?: boolean,
- *   attempts?: number, ceilingUsd?: number|null,
+ *   attempts?: number, ceilingUsd?: number|null, callTimeoutMs?: number,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any}) => any,
  *   createSurveyor?: (o: {workdir: string, granted: readonly string[], ctx: boolean}) => Promise<any>}} o
@@ -99,7 +99,7 @@ export function defaultSurveyor({ workdir, granted, auditPath, ctx }: {
  *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
  *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
  */
-export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, onCall, createLoop, createSurveyor, }: {
+export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, callTimeoutMs, onCall, createLoop, createSurveyor, }: {
     workdir: string;
     provider?: any;
     rounds?: number;
@@ -109,6 +109,7 @@ export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, m
     ctx?: boolean;
     attempts?: number;
     ceilingUsd?: number | null;
+    callTimeoutMs?: number;
     onCall?: (call: {
         label: string;
         costUsd: number | null;
@@ -205,6 +206,30 @@ export function buildSeedListing({ workdir, seedRef, sourcePaths, testPaths, lis
         tier: string;
     };
 }>;
+/**
+ * F152/PRD 30.4 — the scout's per-call IDLE bound. Every `loop.run()` in this
+ * module carried NO time bound at all: a live endpoint that accepts and never
+ * answers hangs the process forever (measured) — an open socket is an active
+ * handle, so node never drains and no backstop can fire.
+ *
+ * UNLIKE the run path (`callBounds()`, src/planrun.js:1518), this pipeline has
+ * NO wall clock to derive a bound FROM — the authoring pipeline is genuinely
+ * clockless (`src/authorjob.js`/`src/authorflow.js`/`scripts/run-author.mjs`
+ * carry a money ceiling, `ceilingUsd`/`capStop`, and never a `maxWallMs`).
+ * Rather than inventing a fresh number, this reuses the EXACT ceiling the run
+ * path itself falls back to when ITS OWN wall is unbounded
+ * (`PROVIDER_TIMEOUT_MS`, `src/clock.js` — BA-18's idle timeout, already an
+ * approved "no wall present" default one layer up): an authoring-time call is
+ * the identical situation, one call earlier.
+ *
+ * It bounds SOCKET INACTIVITY only (reset by every byte, per BA-18) — a call
+ * that is merely slow keeps streaming and is untouched; only a truly silent
+ * endpoint trips it. TIGHTEN-ONLY, like every cap in this file: this is an
+ * operator-set ceiling fixed here, not a param a caller or a signed spec may
+ * widen (a defaulted cap is a silent second ceiling, and there is no clock
+ * whose narrower reading could ever tighten it further).
+ */
+export const AUTHOR_CALL_TIMEOUT_MS: 600000;
 /** src/planrun.js:42 — the survey's hard round bound. */
 export const AUTHOR_SCOUT_ROUNDS: 8;
 /** src/planrun.js:44 — the survey is a PROMPT INGREDIENT for the authoring call. */

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