bareloop 0.22.0 → 0.24.0

package/src/ratelimit.js

@@ -0,0 +1,116 @@
+// PRD item 28's parked (a/b) ruling, hamr's verbatim call: "do a/b as a
+// fallback, and verify/validate + no regression." A vendor HTTP 429 is a
+// response — the provider answered, unlike src/transport.js's no-response
+// class — but unlike every other status this repo already declines to retry
+// (4xx/5xx generally, F115's own boundary), a 429 carries the ONE piece of
+// information that turns "retry blindly" into "retry honestly": the vendor's
+// own stated wait. This module is transport.js's SIBLING, not an extension
+// of it — `isTransportFailure` must keep returning FALSE for anything
+// carrying an HTTP status (429 included), and nothing here widens that.
+//
+// This is a FALLBACK, not the primary answer. The primary answer (F139,
+// measured 2026-09-08) is picking a worker model with adequate rate
+// headroom: gpt-4.1 = 30,000 TPM (429s deterministically on our workload,
+// 2 of 2 runs), gpt-4.1-mini = 200,000 TPM, gpt-5-mini/gpt-5 = 500,000 TPM.
+// One bounded retry only softens the failure mode when that primary answer
+// was not followed (or headroom was still exceeded); it does not replace it.
+
+/** 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 = RATE_LIMIT_RETRIES + 1;
+
+/** 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 = 60_000;
+
+/** Used only when the vendor's message carries no parseable delay at all. */
+export const RATE_LIMIT_DEFAULT_WAIT_MS = 5_000;
+
+/** A parsed delay is the EARLIEST moment the vendor's own window resets, not
+ * a safe one to fire on the dot — this margin is added to any PARSED value
+ * (never to the default) so the retry lands just after the window, not on
+ * its leading edge. Never allowed to push a parsed value over the cap. */
+const PARSED_DELAY_MARGIN_MS = 250;
+
+/**
+ * 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) {
+  if (err == null) return false;
+  const status = err.status ?? err.statusCode;
+  return status === 429;
+}
+
+/**
+ * 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) {
+  const message = String(err?.message ?? err ?? '');
+  const match = message.match(/(?:try again in|retry after)\s*([\d.]+)\s*(ms|milliseconds?|s|seconds?)?/i);
+  if (!match) return null;
+
+  const value = Number(match[1]);
+  if (!Number.isFinite(value) || value < 0) return null;
+
+  const unit = (match[2] ?? 's').toLowerCase();
+  const isMs = unit === 'ms' || unit.startsWith('millisecond');
+  return isMs ? value : value * 1000;
+}
+
+/**
+ * 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) {
+  const parsedMs = statedWaitMs(err);
+  if (parsedMs === null) {
+    return RATE_LIMIT_DEFAULT_WAIT_MS <= RATE_LIMIT_MAX_WAIT_MS ? RATE_LIMIT_DEFAULT_WAIT_MS : null;
+  }
+
+  // The RAW parsed value is what is judged against the cap ("a vendor asking
+  // for longer than this is not honoured") — the margin is added only AFTER
+  // that gate, and clamped so it can never itself push the result past the
+  // cap, but it never turns an already-honoured wait into a refusal.
+  if (parsedMs > RATE_LIMIT_MAX_WAIT_MS) return null;
+  if (parsedMs === 0) return 0;
+  return Math.min(parsedMs + PARSED_DELAY_MARGIN_MS, RATE_LIMIT_MAX_WAIT_MS);
+}

package/src/reuse.js

@@ -60,6 +60,7 @@ import { readGrade } from './trend.js';
 import { HITL_PAUSE, HUMAN_CHECKPOINTS } from './declaredclose.js';
 import { extractArtifact, priceOf } from './text.js';
 import { runJob as shippedRunJob, ACCOUNTED_ROUND_TYPES } from './run.js';
+import { PROVIDER_TIMEOUT_MS } from './clock.js';
 
 const require = createRequire(import.meta.url);
 const { Loop } = require('bare-agent');
@@ -416,7 +417,14 @@ export async function selectBridge({ registry, job, ask, provider, pinned = null
   let result;
   try {
     const loop = new Loop({ provider });
-    result = await loop.run([{ role: 'user', content: prompt }], [], { maxTokens: SELECTION_MAX_TOKENS });
+    // F152/PRD 30.4 — the picker's call carried no time bound at all: a live
+    // endpoint that accepts and never answers hangs the process forever
+    // (measured elsewhere in this repo). This runs BETWEEN bridge tries, not
+    // inside any one try's own signed `perTryWallMs`, so there is no wall to
+    // derive a tighter number from — the same "no clock here" reasoning
+    // `authorscout.js` documents, and the same fallback: the idle-timeout
+    // default the run path itself uses when ITS OWN wall is unbounded.
+    result = await loop.run([{ role: 'user', content: prompt }], [], { maxTokens: SELECTION_MAX_TOKENS, timeoutMs: PROVIDER_TIMEOUT_MS });
   } catch (e) {
     // a throw out of the selection call is TRANSPORT — a casualty, and the run stops on
     // it rather than quietly drafting cold on a decision that was never made

package/src/run.js

@@ -95,9 +95,14 @@ async function primitiveSmoke(workdir) {
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {string|null} [opts.judgeModel] SOFTGREEN — WHICH model the judge provider drives
+ *   (PRD item 32.1), resolved by the CALLER (`resolveJudge`, src/judged.js) and passed
+ *   through untouched. Travels with `judgeProvider`; absent, a judged stage stops as a
+ *   wiring gap rather than grading under an identity nobody named.
  * @param {any} [opts.judgeProvider] SOFTGREEN — the provider a JUDGED close stage runs its
- *   locate call through, wired by the operator and PINNED to `JUDGE_MODEL` (src/judged.js:
- *   the only tier with established injection resistance upstream). Forwarded to the plan
+ *   locate call through, built by the CALLER from the RESOLVED judge identity (PRD item
+ *   32.1: `resolveJudge`/`resolveJobJudge`, src/judged.js — the spec's signed `judge`
+ *   override, else the job's own worker provider and model), never pinned. Forwarded to the plan
  *   flow. It is its own seam and not `provider`/`providerFor`, because the judge tier is
  *   never a step knob and never agent-selectable; absent, a judged stage instrument-stops as
  *   a wiring gap rather than grading on whatever binding happened to be at hand. Its spend
@@ -228,8 +233,16 @@ async function primitiveSmoke(workdir) {
  *   '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, 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 }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = 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
@@ -345,6 +358,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 }; })(),
@@ -380,12 +402,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';
   }
 
@@ -426,7 +482,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';
   };
 
@@ -436,14 +492,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, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, 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
@@ -453,10 +509,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

@@ -147,6 +147,10 @@ export const SECRET_PATTERNS = [
   /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/,
   /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{16}/,
   /(?<![A-Za-z0-9_-])xox[bap]-[A-Za-z0-9-]{10,}/,
+  // Google/Gemini API key: `AIza` + 35 chars of [0-9A-Za-z_-] (39 total, fixed
+  // length by Google's own issuance format). Admitted with the gemini-api
+  // provider (PRD item 31.3, F160) — was missing on this branch until then.
+  /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}/,
 ];
 const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
 

package/types/authoring.d.ts

@@ -328,6 +328,36 @@ export const VERDICT_CLASSES: readonly string[];
 export const LOCKED_CLASSES: readonly string[];
 /** the classes v1 actually builds */
 export const LIVE_CLASSES: readonly string[];
+/** OFF THE MENU, but still built — a THIRD state, distinct from both lists above
+ * (PRD item 31.1, hamr 2026-09-09: *"retire hitl from list, keep its code"*, and
+ * *"if it's not on menu, you can't reach it, from menu"*).
+ *
+ * `hitl` was retired by ruling at v1.71 and the class moved to fwdloop (PRD item
+ * 29), but no constant was ever updated, so `runInterview` still returned
+ * `ok:true` for a hitl pick — an authorable job for a class this product no
+ * longer closes.
+ *
+ * Why this is NOT `LOCKED_CLASSES`. Locked means INEXPRESSIBLE: no guard battery
+ * exists, so `validateCloseDecl` cannot check the close and must refuse
+ * (`src/declaredclose.js:306`). hitl's battery, question set, composition rule and
+ * runtime all exist and are tested — locking it would make every one of them
+ * unreachable, which is not "keeping the code", it is abandoning it in place with
+ * its tests deleted. So the split is:
+ *
+ *   LOCKED_CLASSES   — no battery. Cannot be validated, cannot run. (empty today)
+ *   UNLISTED_CLASSES — battery exists, validates and RUNS. Just never OFFERED.
+ *   LIVE_CLASSES     — everything the system can validate and run (locked removed).
+ *
+ * Read by the AUTHORING surface only (`runInterview`, `authorClose`'s precheck).
+ * The spec validator, the close validator and the runtime deliberately do NOT
+ * read it: a hitl spec that already exists still validates and still runs, which
+ * is what keeps the code alive and under test. Nothing can AUTHOR a new one.
+ * @type {readonly string[]} */
+export const UNLISTED_CLASSES: readonly string[];
+/** what the authoring interview actually OFFERS: live, minus unlisted. This is
+ * "the menu" in hamr's sentence, and it is the only list an authoring refusal
+ * should ever name. */
+export const MENU_CLASSES: readonly string[];
 /**
  * The whole vocabulary, as DATA. `shape` and `asserts` are the strings the
  * authoring prompt renders (M3) — the prompt and this validator must judge the

package/types/authorjob.d.ts

@@ -81,7 +81,7 @@ export function refuseLockedKind(kind: string): Refusal;
  * @param {{answers: Record<string|number, any>, repoPath?: string|null, lang: string,
  *   verdictType?: string|null,
  *   questions?: Record<string|number, string>|null, generate?: Function, provider?: any,
- *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null,
+ *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null, judgeModel?: string|null,
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
@@ -91,7 +91,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   closeDecl: any, seedRef: string|null, authoring: any, judged: any, reds: Red[],
  *   stop: string|null, cost: any, interview: any}>}
  */
-export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, }: {
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, }: {
     answers: Record<string | number, any>;
     repoPath?: string | null;
     lang: string;
@@ -103,6 +103,7 @@ export function authorCloseForJob({ answers, repoPath, lang, verdictType, questi
     scout?: any;
     listing?: any;
     ceilingUsd?: number | null;
+    judgeModel?: string | null;
     onPhase?: (phase: string, data?: any) => void;
     onCall?: (call: {
         label: string;
@@ -207,12 +208,12 @@ export function assembleSpec(specDraft: any, { closeDecl, verdictType }: {
  *
  * @param {{spec: any, workdir: string, seedRef?: string|null, shellCapUsd?: number,
  *   timeoutMs?: number, seedFn?: Function, listingFn?: Function, seedReadFn?: Function,
- *   judgeLoop?: Function|null, onJudgeCost?: ((c: any) => void)|null, calibrateFn?: Function,
- *   ceilingUsd?: number|null, priorCalls?: any[]}} o
+ *   judgeLoop?: Function|null, judgeModel?: string|null, onJudgeCost?: ((c: any) => void)|null,
+ *   calibrateFn?: Function, ceilingUsd?: number|null, priorCalls?: any[]}} o
  * @returns {Promise<{ok: boolean, specHash: string|null, seedRef: string|null,
  *   gates: any, work: any[], guards: any[], stops: any[], reds: Red[], refusal: Refusal|null}>}
  */
-export function prepareSigning({ spec, workdir, seedRef, shellCapUsd, timeoutMs, seedFn, listingFn, seedReadFn, judgeLoop, onJudgeCost, calibrateFn, ceilingUsd, priorCalls, }: {
+export function prepareSigning({ spec, workdir, seedRef, shellCapUsd, timeoutMs, seedFn, listingFn, seedReadFn, judgeLoop, judgeModel, onJudgeCost, calibrateFn, ceilingUsd, priorCalls, }: {
     spec: any;
     workdir: string;
     seedRef?: string | null;
@@ -222,6 +223,7 @@ export function prepareSigning({ spec, workdir, seedRef, shellCapUsd, timeoutMs,
     listingFn?: Function;
     seedReadFn?: Function;
     judgeLoop?: Function | null;
+    judgeModel?: string | null;
     onJudgeCost?: ((c: any) => void) | null;
     calibrateFn?: Function;
     ceilingUsd?: number | null;
@@ -277,4 +279,6 @@ import { requiredAnswersFor } from './authorflow.js';
 import { VERDICT_CLASSES } from './authoring.js';
 import { LOCKED_CLASSES } from './authoring.js';
 import { LIVE_CLASSES } from './authoring.js';
-export { QUESTION_SETS, questionsFor, requiredAnswersFor, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES };
+import { UNLISTED_CLASSES } from './authoring.js';
+import { MENU_CLASSES } from './authoring.js';
+export { QUESTION_SETS, questionsFor, requiredAnswersFor, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, UNLISTED_CLASSES, MENU_CLASSES };

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

@@ -80,7 +80,13 @@ export function factsResist(facts: any, gold: any, artifactText: string): {
  * graded one: `ok` is false, the cases nobody bought are absent rather than recorded
  * as failures, and `casualty` stays null — the transport was fine, the operator's own
  * governance stopped the gate.
- * @param {{cases: any, card: any, judgeLoop: Function|null,
+ * `judgeModel` is REQUIRED and has no default (PRD item 32.1). It is the identity
+ * the caller resolved (`resolveJudge`, src/judged.js) and it is what the graded set
+ * is STAMPED with — `setHash` folds it in, so a set certified by one judge cannot be
+ * mistaken for the same set certified by another. A default here would be the silent
+ * fall-back the whole judge-identity change exists to remove: a gate that grades
+ * under a model nobody named certifies a floor nobody can attribute.
+ * @param {{cases: any, card: any, judgeLoop: Function|null, judgeModel: string,
  *   onCost?: (c: any) => void, attempts?: number, battery?: any[], batteryCard?: any,
  *   capStop?: () => 'cap-halt'|'pricing-red'|null}} o
  * @returns {Promise<{ok: boolean, stop: string|null, casualty: any,
@@ -90,10 +96,11 @@ export function factsResist(facts: any, gold: any, artifactText: string): {
  *   cardHash: string|null, casesHash: string|null, setHash: string|null,
  *   costUsd: number|null, knownUsd: number, spendComplete: boolean, calls: any[]}>}
  */
-export function runCalibration({ cases, card, judgeLoop, onCost, attempts, battery, batteryCard, capStop, }: {
+export function runCalibration({ cases, card, judgeLoop, judgeModel, onCost, attempts, battery, batteryCard, capStop, }: {
     cases: any;
     card: any;
     judgeLoop: Function | null;
+    judgeModel: string;
     onCost?: (c: any) => void;
     attempts?: number;
     battery?: any[];

package/types/cardauthor.d.ts

@@ -261,15 +261,16 @@ export function signJudgedArtifacts({ proposal, fix }: {
  *   - THE CASES land beside the stages as `calibration.cases` — a close-level
  *     artifact, because the set calibrates the RULER and not one stage's params,
  *     and because module 5's gate reads it before any stage runs.
- *   - THE JUDGE MODEL lands beside them as `calibration.judgeModel`, and it is the
- *     PIN (`JUDGE_MODEL`) rather than anything a caller may name. A calibration set
- *     is only worth the tier that graded it — §4.2's whole safety argument is worth
- *     exactly as much as BA-20's injection evidence, which is haiku-4.5's alone — so
- *     the set has to carry which tier certified it or nothing downstream can tell a
- *     signed floor from a bumped one. Storing it HERE, inside the spec, is what makes
- *     a bump flip `jobSpecHash`: the signature dies, the signer re-signs, and a
- *     re-sign is a re-run of the calibration gate. That is the docstring on
- *     `JUDGE_MODEL` finally given a detector instead of a promise (F45).
+ *   - THE JUDGE MODEL lands beside them as `calibration.judgeModel`. Since PRD item
+ *     32.1 that is the RESOLVED judge identity the caller hands in (`resolveJudge`,
+ *     src/judged.js — the spec's signed `judge` override, else the job's own worker
+ *     model), not a library pin. A calibration set is only worth the judge that
+ *     graded it, so the set has to carry which judge certified it or nothing
+ *     downstream can tell a signed floor from a moved one. Storing it HERE, inside
+ *     the spec, is what makes a judge change flip `jobSpecHash`: the signature dies,
+ *     the signer re-signs, and a re-sign is a re-run of the calibration gate. It is
+ *     REQUIRED, with no default — a set stamped with a model nobody named is exactly
+ *     the unattributable floor this field exists to prevent (F45).
  *
  * A card with NOWHERE TO LAND THROWS. It is a caller's own broken input — a
  * signed rubric folded into a close with no judged ruler — and there is no safe
@@ -278,12 +279,13 @@ export function signJudgedArtifacts({ proposal, fix }: {
  * The input is never mutated: a closeDecl is a signed artefact and rewriting a
  * caller's copy in place is how two readers come to disagree about what was
  * signed.
- * @param {any} closeDecl @param {{card: any, cases: any[]}} o
+ * @param {any} closeDecl @param {{card: any, cases: any[], judgeModel: string}} o
  * @returns {any} a new closeDecl
  */
-export function foldJudgedArtifacts(closeDecl: any, { card, cases }: {
+export function foldJudgedArtifacts(closeDecl: any, { card, cases, judgeModel }: {
     card: any;
     cases: any[];
+    judgeModel: string;
 }): any;
 /**
  * ONE compile call: the person's Q6 and Q7 in, a proposal out.

package/types/cli.d.ts

@@ -3,7 +3,7 @@
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
  * queued stdout on its own (F-something: `process.exit()` can discard it).
  * @param {string[]} argv
- * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, now?: () => number, stdin?: any }} deps
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any }} deps
  * @returns {Promise<number>}
  */
 export function main(argv: string[], deps?: {
@@ -14,6 +14,7 @@ export function main(argv: string[], deps?: {
     provider?: any;
     providerFor?: any;
     judgeProvider?: any;
+    judgeModel?: string | null;
     now?: () => number;
     stdin?: any;
 }): Promise<number>;

package/types/declaredclose.d.ts

@@ -110,7 +110,9 @@ 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]
+ *   judgeModel?: string|null,
+ *   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?: {
@@ -128,7 +130,12 @@ export function runDeclaredStages(stages: any[], redact?: (s: string) => string,
     judgeLoop?: ((o: {
         system: string;
     }) => any) | null;
+    judgeModel?: string | 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