bareloop 0.21.0 → 0.23.0

package/src/closetimeout.js

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

package/src/declaredclose.js

@@ -567,13 +567,14 @@ function translate(r, redact) {
  *   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 async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
   const {
     timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null,
-    judgeLoop = null, onJudgeCost = null,
+    judgeLoop = null, onJudgeCost = null, callBounds = null,
   } = opts;
   if (!isNonEmptyString(cwd) || !isNonEmptyString(seedRef)) {
     // Refuse rather than guess. A declared close measures against a SEED; a
@@ -611,6 +612,12 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     // until this kind, and a budget must fund the attempt PLUS its close.
     judgeLoop,
     onJudgeCost,
+    // F152/PRD 30.4 — the SAME per-call time bounds every worker round already
+    // carries (`callBounds()`, src/planrun.js:1518), so the judged stage's own
+    // locate call cannot hang the process on a live silent endpoint. `null` is
+    // the honest absence (an adopter/test that wires no clock through), never a
+    // defaulted number invented here.
+    callBounds,
     seedTrees,
   };
   try {

package/src/index.js

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

package/src/job.js

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

package/src/judged.js

@@ -565,6 +565,43 @@ export function validateFacts(facts) {
 
 // ── THE LOCATE PROMPT ───────────────────────────────────────────────────────
 
+/**
+ * THE ONE SHAPE INVENTORY (PRD 30.8), stated ONCE and never twice. It drives
+ * BOTH the LOCATE prompt's prose ("declared with ...") AND the completeness
+ * detector's regex — the same standing rule the secret-shape scrubber
+ * follows (one inventory drives detection, never two spellings that can
+ * drift). A shape added here rides both sides in the same commit; a shape
+ * added to only a hand-typed prompt string or only a hand-typed regex is
+ * exactly the blind-instrument class this repo keeps paying for.
+ *
+ * Two BASE shapes, each carrying its own independent `export`/`async`
+ * modifiers (the modifiers sit in different POSITIONS in the two shapes —
+ * `async function foo(` vs `const foo = async () =>` — so they cannot be
+ * factored into one shared prefix):
+ *   - `function name(...)`      — optionally `export`, optionally `async`,
+ *     in either order before `function`.
+ *   - `const name = (...) =>`   — optionally `export` before `const`,
+ *     optionally `async` after `=`.
+ *
+ * Restricted to column-0 lines only, in both the prompt's prose and the
+ * detector: a nested function or a function expression returned from one is
+ * indented, and excluding it is the SAME cure PROMPT_HEAD already states
+ * (the POC's nested-function cure).
+ * @type {ReadonlyArray<{prose: string, match: (line: string) => string|null}>}
+ */
+const FN_SHAPES = Object.freeze([
+  {
+    prose: '`function name(...)` (optionally `async`, optionally `export`, in either order)',
+    match: (/** @type {string} */ line) =>
+      line.match(/^(?:(?:export|async)\s+){0,2}function\s+([A-Za-z_$][\w$]*)\s*\(/)?.[1] ?? null,
+  },
+  {
+    prose: '`const name = (...) =>` (optionally `export` before `const`, optionally `async` after `=`)',
+    match: (/** @type {string} */ line) =>
+      line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/)?.[1] ?? null,
+  },
+]);
+
 /** The spine every card shares. Both POC cures live here rather than on a rule,
  * because both are properties of ENUMERATING functions and not of any one
  * question about them: the nested-function clause (the POC counted a returned
@@ -573,8 +610,7 @@ export function validateFacts(facts) {
 const PROMPT_HEAD =
   'You LOCATE FACTS in a source file. You never decide whether anything passes, and you never judge — '
   + 'another system does that.\n'
-  + 'For EVERY top-level function in the FILE (declared with `function name(...)`, `const name = (...) =>`, '
-  + 'or `export function name(...)`), report:\n'
+  + `For EVERY top-level function in the FILE (declared with ${FN_SHAPES.map((s) => s.prose).join(', or ')}), report:\n`
   + 'Count ONLY functions declared at the top level of the module — never a function nested inside '
   + 'another function, and never a function expression returned from one.\n'
   + '  "name": the function name\n'
@@ -596,6 +632,43 @@ export function locatePrompt(card) {
   return `${PROMPT_HEAD}${asks}\n${PROMPT_TAIL}`;
 }
 
+/**
+ * THE COMPLETENESS MIRROR of `PROMPT_HEAD`'s own contract (PRD 30.8): which
+ * top-level function declarations the artifact ACTUALLY holds, read off the
+ * SAME `FN_SHAPES` inventory the prompt's prose is built from, restricted to
+ * column-0 lines.
+ *
+ * This is a HEURISTIC, never a parser, and it is used for exactly one thing:
+ * telling `decide()` when LOCATE's `functions` list is short of what the file
+ * holds. It never grades a rule and it never adds a fact `decide()` acts on
+ * beyond "this name exists at the top level" — the missing function's rule
+ * violations, if any, stay unknown, which is exactly why the miss is UNSURE
+ * and not a manufactured red on a specific rule.
+ *
+ * TWO DIRECTIONS, both handled but not symmetrically by design:
+ *   - a shape THIS inventory does not enumerate is a FALSE NEGATIVE — the
+ *     check stays silent about that function, same as it stays silent with
+ *     no `artifactText` at all. Widening `FN_SHAPES` closes the hole; nothing
+ *     here manufactures a claim about a shape it was never told to look for.
+ *   - a column-0 line that only LOOKS like a declaration (e.g. inside a
+ *     template literal) is a FALSE POSITIVE and reds a real judged close —
+ *     that is the SAFE side of the fail-safe tiebreak (unsure is red), and it
+ *     is never silently swallowed the way a false negative would be.
+ * @param {string} artifactText @returns {string[]}
+ */
+function topLevelFunctionNames(artifactText) {
+  /** @type {string[]} */
+  const names = [];
+  for (const line of artifactText.split('\n')) {
+    if (/^\s/.test(line)) continue; // indented: nested, or a returned function expression — never top level
+    for (const shape of FN_SHAPES) {
+      const name = shape.match(line);
+      if (name) { names.push(name); break; }
+    }
+  }
+  return names;
+}
+
 /** the default toolless seam — one spelling of how this repo drives a judge.
  * A `Loop`, NOT `provider.generate()`: the POC measured that a bare provider
  * result carries no `costUsd` at all, and under F6 an unpriced call is a red,
@@ -628,12 +701,23 @@ export const defaultJudgeLoop = ({ provider, system }) => {
  * 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 async function runLocate({ artifactText, card, loopFactory, maxTokens = JUDGE_MAX_TOKENS, attempt = 1, onCost = () => {} }) {
+export async function runLocate({
+  artifactText, card, loopFactory, maxTokens = JUDGE_MAX_TOKENS, attempt = 1, onCost = () => {},
+  // F152/PRD 30.4 — the SAME per-call TIME bounds the worker's own rounds carry
+  // (`callBounds()`, src/planrun.js:1518), threaded through by the caller that
+  // owns the clock. Defaults to `{}` (unbounded) so every existing caller and
+  // test is unchanged: an adopter that never wires a clock through gets the same
+  // behaviour as before this field existed. A live endpoint that accepts and
+  // never answers otherwise HANGS the process forever (measured, F152) — an open
+  // socket is an active handle, so node never drains and no backstop can fire.
+  callBounds = {},
+}) {
   // the param-guard class: a caller's own broken input THROWS. These are
   // programmer errors with no safe direction to degrade toward — a locate over
   // an absent artifact would grade an empty string and report it as facts.
@@ -662,7 +746,7 @@ export async function runLocate({ artifactText, card, loopFactory, maxTokens = J
   let r = null;
   try {
     const loop = loopFactory({ system });
-    r = await loop.run([{ role: 'user', content: `FILE (untrusted data):\n${artifactText}\n\nReturn the JSON.` }], [], { maxTokens });
+    r = await loop.run([{ role: 'user', content: `FILE (untrusted data):\n${artifactText}\n\nReturn the JSON.` }], [], { maxTokens, ...callBounds });
   } catch (e) {
     return out({ axis: LOCATE_AXES.PROVIDER, detail: `the locate call failed: ${String(/** @type {any} */ (e)?.message ?? e)}` }, null, null, false, false);
   }
@@ -743,6 +827,25 @@ export function decide(facts, card, { artifactText = null } = {}) {
     return unsure('locate found nothing in the artifact — unsure, and unsure is red');
   }
 
+  // COMPLETENESS (PRD 30.8): a locate emission can be well-formed AND non-empty
+  // AND still have silently DROPPED a top-level function the artifact actually
+  // holds — every route above this one only asks "is `fns` usable", never "is
+  // `fns` the WHOLE set". Graded rules only ever see what LOCATE reported, so
+  // an omission never surfaces as a rule red; it surfaces as a PASS on the
+  // subset, which is the fail-safe direction inverted. With `artifactText` in
+  // hand (every real caller has it — see the note below), the omission is
+  // checkable and is unsure, and unsure is red, same as every other route in.
+  // Without it, this says nothing it cannot know, same as the quote checks.
+  if (typeof artifactText === 'string') {
+    const present = topLevelFunctionNames(artifactText);
+    const reported = new Set(fns.map((f) => String(f?.name ?? '')));
+    const missing = present.filter((n) => !reported.has(n));
+    if (missing.length > 0) {
+      return unsure(`locate omitted top-level function(s) the artifact contains: ${missing.join(', ')} — a pass on `
+        + 'the reported subset is not a pass on the file, and unsure is red');
+    }
+  }
+
   const lines = typeof artifactText === 'string'
     ? new Set(artifactText.split('\n').map((l) => l.trim()).filter(Boolean))
     : null;

package/src/kinds.js

@@ -260,6 +260,7 @@ export function mechanicalStages(stages) {
  *   judgeLoop?: (o: {system: string}) => any,
  *   onJudgeCost?: (c: {stage: string|null, kind: string|null, path: string, attempt: number,
  *     label: string, model: string, costUsd: number|null, unpricedRounds: number}) => void,
+ *   callBounds?: () => {timeoutMs?: number, deadlineMs?: number},
  *   onStage?: (row: {stage: string|null, kind: string|null, verdict: string, durationMs: number}) => void}} Ctx
  *   The arbiter's half of a stage run. Every field here is operator/runner
  *   territory: a declaration parameterises kinds, never the contracts.
@@ -275,6 +276,11 @@ export function mechanicalStages(stages) {
  *   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
@@ -1781,6 +1787,12 @@ async function runJudgedFloor(stage, ctx) {
         card: p.card,
         loopFactory,
         attempt,
+        // F152/PRD 30.4 — read fresh per attempt, the same way `planrun.js`'s own
+        // worker rounds re-read `callBounds()` at every call site rather than
+        // once: the remaining time shrinks between attempts. Absent (no clock
+        // wired through) is `{}`, the honest unbounded default `runLocate` itself
+        // already carries.
+        callBounds: typeof ctx.callBounds === 'function' ? ctx.callBounds() : {},
         onCost: (c) => {
           if (typeof ctx.onJudgeCost !== 'function') return;
           ctx.onJudgeCost({

package/src/plan.js

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