bareloop 0.26.0 → 0.28.0

package/types/replayio.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Parse one JSONL file into records, tolerant of a malformed line (counted
+ * in `skipped`, never thrown on). Mirrors `scripts/behaviour-readout.mjs`'s
+ * own parse.
+ * @param {string} file
+ * @returns {{records: any[], skipped: number}}
+ */
+export function parseJsonl(file: string): {
+    records: any[];
+    skipped: number;
+};
+/**
+ * `true` when `name` (a bare filename, not a path) is a gate-audit or lag
+ * sidecar by NAME convention — the one filename rule that holds across the
+ * whole archive.
+ * @param {string} name
+ */
+export function isSidecarByName(name: string): boolean;
+/**
+ * `true` when `records` carries at least one `job-start` (present on every
+ * real spine checked, first record or not — a reuse/battery run nests one or
+ * more ordinary `runJob` calls inside it) or `run-start` (ralph's own inner
+ * loop marker, present on most but not all real spines).
+ * @param {any[]} records
+ */
+export function looksLikeSpine(records: any[]): boolean;
+/**
+ * `<name>.jsonl` → `<name>-gate-audit.jsonl` in the same directory, and the
+ * bare run id for display — the run id lives only in the filename (no spine
+ * record carries it; see `src/replay.js`'s header). A leading `u-` (the
+ * run-u convention) is stripped; every other prefix (`battery-A1-`,
+ * `reuse-`, …) is kept verbatim, since it is the only thing distinguishing
+ * that run from its siblings in the same directory.
+ * @param {string} spinePath
+ * @returns {{runId: string, auditPath: string|null}}
+ */
+export function resolveSiblings(spinePath: string): {
+    runId: string;
+    auditPath: string | null;
+};
+/**
+ * Read one run's spine (+ its gate-audit sidecar, when present) off disk and
+ * hand both to {@link replayRun}. Read-only, $0, mints no verdict.
+ * @param {string} spinePath absolute or cwd-relative path to a `.jsonl` spine
+ * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean}} [opts]
+ *   `preParsedSpine`: avoids a second parse of the same file when the caller
+ *   ({@link listSpines}) already read it once to run {@link looksLikeSpine}.
+ *   `skipAudit` (PR #23 review item 5, 2026-08-26, carried over): a
+ *   directory listing never opens the gate-audit sidecar at all —
+ *   `summarizeForAllLine` reads none of the fields that sidecar feeds inside
+ *   `replayRun`, so reading every run's sidecar in a directory listing was
+ *   pure unused I/O, multiplied by every spine found.
+ * @returns {ReturnType<typeof replayRun>}
+ */
+export function replayOne(spinePath: string, opts?: {
+    preParsedSpine?: {
+        records: any[];
+        skipped: number;
+    };
+    skipAudit?: boolean;
+}): ReturnType<typeof replayRun>;
+/**
+ * List every spine found directly in `dir` (not recursive — same as the
+ * script this replaces): one entry per `.jsonl` file that is not a sidecar
+ * by name, each either `{kind:'spine', row}` ({@link summarizeForAllLine}'s
+ * row) or `{kind:'not-a-spine', name}` when the file's content doesn't look
+ * like a spine. Feeds `formatAllLines` (`src/replay.js`) for the printed
+ * table — this function does no formatting of its own, only IO + detection.
+ * @param {string} dir
+ * @returns {Array<{kind: 'spine', row: ReturnType<typeof summarizeForAllLine>}|{kind: 'not-a-spine', name: string}>}
+ */
+export function listSpines(dir: string): Array<{
+    kind: "spine";
+    row: ReturnType<typeof summarizeForAllLine>;
+} | {
+    kind: "not-a-spine";
+    name: string;
+}>;
+/**
+ * Read a bundle's `history.jsonl` (one `bareloop run` row per line, written
+ * by `appendHistory` in `src/bundle.js`) — the single reader for this file,
+ * replacing `src/cli.js`'s own hand-rolled `readFileSync`/split. Tolerant of
+ * a malformed line the same way {@link parseJsonl} is (counted in
+ * `skipped`, never thrown on).
+ * @param {string} file absolute path to `history.jsonl`
+ * @returns {{rows: any[], skipped: number}}
+ */
+export function readHistoryLog(file: string): {
+    rows: any[];
+    skipped: number;
+};
+import { replayRun } from './replay.js';
+import { summarizeForAllLine } from './replay.js';

package/types/reuse.d.ts

@@ -234,7 +234,7 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
  * abandoned attempt twice in a chain of resumes.
  *
  * @param {any[]} events the dead spine's events, parsed, in file order
- * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: string[]}} [opts]
+ * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: readonly string[]}} [opts]
  *   `deathAt`: when the process is judged to have died (the watchdog's kill record,
  *   which is later and better evidence than the last event). Defaults to the last
  *   event's own timestamp — the last sign of life there is.
@@ -246,7 +246,7 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
 export function readResume(events: any[], { deathAt, direct, resumableOutcomes }?: {
     deathAt?: number | null;
     direct?: boolean;
-    resumableOutcomes?: string[];
+    resumableOutcomes?: readonly string[];
 }): any;
 /**
  * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it

package/types/run.d.ts

@@ -143,7 +143,7 @@
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
- * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ * @param {{decision: string, text?: string|null}|null} [opts.humanRuling] N4 — the SIGNER's
  *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
  *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
  *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
@@ -219,7 +219,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     layerRoot?: boolean | undefined;
     humanRuling?: {
         decision: string;
-        text?: string;
+        text?: string | null;
     } | null | undefined;
     heldRuling?: {
         decision: string;

package/types/source.d.ts

@@ -88,6 +88,51 @@ export function prepareSource({ source, into, destination, fetchTimeoutMs }: {
     manifestPath: string;
     manifest: object;
 } | SourceRefusal>;
+/**
+ * THE INSTALL-GAP DETECTOR (PRD item 33 close-out, `docs/product/PRD.md:450-452`,
+ * hamr's ruling 2026-09-14, option A): `prepareSource` copies ONLY git-tracked
+ * files (hamr's ruling, `docs/product/ITEM33-BUILD.md:225-239` — unchanged by
+ * this function), so a JS/TS repo's prepared copy never carries `node_modules`,
+ * and every close stage needing a tool (`tsc`, a test runner) instrument-stops
+ * with nothing telling the person why. bareloop NEVER runs an install itself —
+ * it only ever touches gated primitives, and a shell-out to `npm`/etc from
+ * inside this module would be exactly the verb hamr's law reserves for the
+ * worker's own granted tools, never the arbiter-side machinery that decides
+ * whether a run even starts. This is a pure, $0 DETECTOR: it names the gap and
+ * the exact command a person runs THEMSELVES in the copy, then returns.
+ *
+ * JS/TS ONLY for now — a repo in another detected language returns `null`
+ * here unconditionally (no `package.json` to find), which is the correct
+ * "nothing to report" reading, not a gap in this function; per-language
+ * dependency-gap data for other languages is M3b's job
+ * (`docs/product/ITEM33-BUILD.md`, "M3b"), not this one's.
+ *
+ * SUBFOLDER-AS-REPO (ruling 2 addendum, commit 2a020d8): a subfolder job
+ * freezes the WHOLE repo, so `package.json` may sit at the repo root, at the
+ * subfolder itself, or anywhere between — the SAME nearest-manifest-walking-up
+ * rule `detectLanguage` (`src/detectlang.js`) applies, done independently here
+ * (not by importing `detectLanguage`) to avoid a `source.js` ⇄ `detectlang.js`
+ * import cycle, since `detectlang.js` already imports `nearestGitAncestor`
+ * from this module.
+ *
+ * @param {string} treeDir the prepared tree's root (`prepareSource`'s
+ *   returned `tree`, e.g. `<into>/tree` — a REPO source sits directly at this
+ *   root; every other kind sits under `input/` inside it and has no repo
+ *   dependency story yet, so callers only need this for a `kind: 'repo'`
+ *   manifest)
+ * @param {string} [sourceSubdir] the manifest's own `sourceSubdir` ('' or
+ *   undefined when Source IS the repo root)
+ * @returns {{manager: string, command: string, reason: string}|null} `null`
+ *   when there is nothing to report: no JS/TS manifest found walking up from
+ *   `sourceSubdir` to `treeDir`, the nearest one found has no dependencies,
+ *   `node_modules` is already there, or the manifest cannot even be read as
+ *   JSON (an invalid `package.json` is "cannot tell", never a false alarm).
+ */
+export function missingDependencies(treeDir: string, sourceSubdir?: string): {
+    manager: string;
+    command: string;
+    reason: string;
+} | null;
 /**
  * The delivered name (M2b fix 4, kept under D3): a destination FILE of
  * `/home/me/profile.md` lands as `/home/me/profile-2026-09-12.md`, and a

package/types/text.d.ts

@@ -100,6 +100,41 @@ export function capStop({ ceilingUsd, knownUsd, spendComplete }: {
     knownUsd: number;
     spendComplete: boolean;
 }): "cap-halt" | "pricing-red" | null;
+/**
+ * THE ONE SPELLING of "was this throw a call casualty, or something else" —
+ * F179/F180's seam. `authorscout.js`'s `settled` narrows a rejected
+ * `loop.run()` to this one class: swallowing every throw would launder a
+ * budget `HaltError`, a programming bug, or any other named terminal into
+ * "the call failed" — the exact class of dishonesty this repo refuses (an
+ * unknown reported as a known).
+ *
+ * bare-agent 0.42.0's `OpenAIProvider.generate` used to throw a raw
+ * `SyntaxError` from an unguarded `JSON.parse(tc.function.arguments)` after
+ * a billed HTTP round (F179/BA-27) — this predicate used to admit that class
+ * too. bare-agent 0.43.0 fixed it upstream (`parseToolCalls`, shared by
+ * OpenAIProvider and Ollama): a malformed tool-call arguments string now
+ * returns a priced round with `toolCalls: []` plus its own `malformedToolCall`
+ * marker instead of throwing. Verified against 0.43.0's installed source that
+ * no provider bareloop constructs (`AnthropicProvider`, `OpenAIProvider`,
+ * `GeminiProvider` — `src/providers.js`) can still throw a JSON `SyntaxError`
+ * out of `generate()` after a billed round: Anthropic and Gemini read tool-call
+ * arguments as already-parsed objects off their own response shape (nothing to
+ * `JSON.parse`), and every provider's raw-HTTP-body parse is already
+ * try/catch-wrapped inside `_request`, converted to a plain `Error` before it
+ * can reach here. bareloop never streams a provider response. So the
+ * SyntaxError branch this predicate used to carry is dead code and was
+ * removed in the same change that bumped to bare-agent 0.43.0 — re-add it (or
+ * a narrower successor) only if a real provider is found to reintroduce the
+ * class.
+ *
+ * A `HaltError` is deliberately excluded — it is bare-agent's own governance
+ * exit (a budget/turn cap), never a transport casualty, and this predicate
+ * must never launder one into a mere "the call failed".
+ * @param {any} err
+ * @returns {string|null} a short reason when `err` is an admitted casualty class,
+ *   `null` for everything else (including `HaltError`) — the caller re-throws on `null`.
+ */
+export function callCasualty(err: any): string | null;
 /**
  * ONE raw model emission, ready to persist.
  *

package/types/u-patient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reset a patient to its frozen seed and drop its `.litectx` store.
+ *
+ * @param {string} wd absolute path to the patient's tree (a git repo with >=1 commit)
+ * @param {string} seed the frozen seed commit
+ * @returns {{ head: string, storeRemoved: boolean }} `head` is the short sha the tree
+ *   now stands at; `storeRemoved` says whether a store was actually there to remove
+ *   (so a caller can print the truth rather than a claim).
+ */
+export function coldReset(wd: string, seed: string): {
+    head: string;
+    storeRemoved: boolean;
+};
+/**
+ * F186 — the patient's own `.gitignore` denies `*.jsonl`, so `coldReset`'s
+ * `git clean -fd` (no `-x`) never removes a `gate-audit.jsonl` already
+ * sitting at the tree root — it can only be there from an EARLIER run
+ * against this same patient (an authoring scout, or a prior worker run)
+ * that never got archived out. Left in place, THIS run's own Gate (which
+ * writes to that same path) would append to it, and the end-of-run rename
+ * that claims the whole file as "this run's own audit" would silently
+ * carry every earlier run's rows too — a harness slicing a shared append-
+ * only log has to account for every writer inside its window.
+ *
+ * Call this AFTER `coldReset` and BEFORE this run's own Gate ever opens: at
+ * that point a `gate-audit.jsonl` sitting in the tree is provably not this
+ * run's, because coldReset just proved the tree is unable to have produced
+ * one since the seed reset. NOT for a resume — a halted run's own gate
+ * audit already in the tree it resumes into is that SAME run's prior leg,
+ * not a stranger's; callers on the resume path must not call this.
+ *
+ * @param {string} wd absolute path to the patient's tree, just cold-reset
+ * @param {string} spineDir absolute path to this run's spine directory
+ * @param {string} runid this run's own id (the same one every other spine
+ *   file for this run is named after)
+ * @returns {string|null} the path the stale file was moved to, or `null`
+ *   when there was nothing to move
+ */
+export function moveStaleGateAudit(wd: string, spineDir: string, runid: string): string | null;

package/types/u-readout.d.ts

@@ -0,0 +1,247 @@
+/**
+ * A token count, k/M-abbreviated — 2 decimals at and above a million (the tail's own
+ * `.2M`-shaped resolution matters more once six figures are folded into a suffix), 1
+ * decimal in the thousands, and the bare integer under that (a two- or three-digit
+ * round is more readable plain than as `"0.2k"`).
+ * @param {number} n
+ * @returns {string}
+ */
+export function fmtTokens(n: number): string;
+/**
+ * THE TOKENS TAIL LINE — hamr's 2026-09-01 order: `job-end` carries dollars only, and
+ * the run tail never prints a token total anywhere, though tokens exist per round on
+ * `worker-round.usage` and `judge-round.usage`
+ * ({inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens}).
+ *
+ * Summed off THIS LEG's own spine, over every round TYPE that spends money —
+ * worker-round AND judge-round (house rule: a spend-slicing instrument must enumerate
+ * every round type that spends, or it silently undercounts). `worker-result` is an
+ * ATTEMPT-LEVEL ECHO of round sums, not a round, and is deliberately never matched
+ * here — folding it in would double the real figure.
+ *
+ * A round whose `usage` is missing or not an object (today: every `judge-round` — the
+ * payload at `src/planrun.js`'s `onJudgeCost` does not carry one) is counted as
+ * UNKNOWN, never laundered into a silent 0 — the same rule `costUsd` already lives by
+ * (F6/F44): an unpriced round is reported as unpriced, not folded into the total as
+ * if it cost nothing.
+ *
+ * @param {{events: any[]}} o `events` this leg's own parsed spine, never a folded
+ *   chain — a resumed leg's tokens are this leg's own bill, same as `rounds` above it.
+ * @returns {string}
+ */
+export function tokensLine({ events }: {
+    events: any[];
+}): string;
+/**
+ * The banner's wall line: what this run has consumed of its signed cap.
+ * @param {{legMs: number, priorWallMs?: number, wallLabel: string}} o
+ *   `legMs`: wall this process bought. `priorWallMs`: wall its predecessors burnt,
+ *   as `readResume` folded it (0/absent on a cold run). `wallLabel`: the signed cap
+ *   as the runner spells it, including the honest UNBOUNDED prose.
+ * @returns {string}
+ */
+export function wallLine({ legMs, priorWallMs, wallLabel }: {
+    legMs: number;
+    priorWallMs?: number;
+    wallLabel: string;
+}): string;
+/**
+ * THE EVIDENCE PACKAGE (N4, ruling 2) — what a person is shown before they answer.
+ *
+ * *"Before/after changes plus every mechanical stage's result; never a bare
+ * 'approve?'"*. The LIBRARY assembles the facts and puts them on the `hitl-pause`
+ * spine record — the ask the close itself declared, every stage's own result, and
+ * WHICH files the run changed (`src/planrun.js`'s `emitHitlPause`). This renders
+ * them, and adds the one thing a library cannot state honestly from where it sits:
+ * the LINE-level diff, which needs a screen and a repository in front of it.
+ *
+ * Nothing here derives a verdict, and nothing here decides. It is a readout of a
+ * record that already exists — so an absence is written as prose (F6: an empty
+ * stage list is "the checkpoint carries none", never a blank screen that reads as
+ * "nothing happened") and a trim is announced (F28).
+ *
+ * @param {{pause: any, diff: {lines: string[], truncated?: number, untracked?: string[],
+ *   unavailable?: string|null}|null}} o `pause` the spine record; `diff` what the
+ *   runner read off the patient, or null when it did not look.
+ * @returns {string[]} lines, ready to print
+ */
+export function evidencePackage({ pause, diff }: {
+    pause: any;
+    diff: {
+        lines: string[];
+        truncated?: number;
+        untracked?: string[];
+        unavailable?: string | null;
+    } | null;
+}): string[];
+/**
+ * THE REVIEW DOOR's package (softgreen module 8) — the same evidence, at the door
+ * at the END of a run rather than at a stage inside the close.
+ *
+ * It is a SEPARATE renderer from `evidencePackage` and deliberately so: that one
+ * opens with *"this run reached the one stage a machine cannot render, and it is
+ * waiting on you"*, which at a review door would be false twice over — the machine
+ * rendered every stage, and the run is over. What a person needs told here is the
+ * opposite fact: a verdict was minted, it STANDS, and what happens to the work is
+ * theirs. The stage/changed/diff body is shared, because it is the same evidence.
+ * @param {{door: any, diff?: any}} o
+ * @returns {string[]}
+ */
+export function reviewDoorPackage({ door, diff }: {
+    door: any;
+    diff?: any;
+}): string[];
+/**
+ * The door's OWN `close-timing-red` refusal (F137, hamr's ruling 2026-09-07,
+ * `docs/product/CLOSE-INTEGRITY-BUILD.md` "Ruled 2026-09-07"): when the
+ * door's timing pass (`resolveCloseTimeoutMs`) times out, the accept must
+ * REFUSE outright rather than fall through to the library's 120s default —
+ * mirroring the wording/options list `scripts/run-u.mjs`'s in-run
+ * `close-timing-red` escalation already prints (~line 1173), never a second
+ * invented phrasing. Pure so the wording is unit-testable without spawning
+ * the script or waiting out the real 600s timing-preflight ceiling.
+ * @param {{names: string}} args comma-joined names of the stage(s) that timed out
+ * @returns {string[]}
+ */
+export function doorTimingRedLines({ names }: {
+    names: string;
+}): string[];
+/**
+ * The three doors AT THE REVIEW DOOR. Same order and the same rule as
+ * `doorLines` (rerun leads, ~40% rubber-stamp), different consequences: this run
+ * is OVER, so a rerun is a fresh engagement rather than a continuation, and a
+ * pause keeps the door rather than a step checkpoint.
+ * @param {{rerun: string, accept: string, pause: string, ttlDays: number, held: boolean}} o
+ * @returns {string[]}
+ */
+export function runDoorLines({ rerun, accept, pause, ttlDays, held }: {
+    rerun: string;
+    accept: string;
+    pause: string;
+    ttlDays: number;
+    held: boolean;
+}): string[];
+/**
+ * THE THREE DOORS, rendered — and the 2026-08-12 §4 rule is the ORDER.
+ *
+ * ~40% of human reviewers approve without reading. That datum is a design input:
+ * the default must lean toward rerun and never toward accept, because a default
+ * that costs one extra cycle when wrong is cheap and a default that mints a green
+ * nobody read is the failure mode the whole class exists to prevent.
+ *
+ * "Default" here is which door the prompt LEADS with — never an action taken for
+ * the operator. No door happens without its flag, and this says so.
+ *
+ * The third door is PAUSE (2026-08-18), not cancel. hamr: *"what's the point of
+ * cancel anyways? pause can resume — that would be more honest"*. A person who does
+ * not want to carry on today is not making a permanent judgment, and the door should
+ * not ask them to: the checkpoint keeps, and an unanswered one expires on its own.
+ *
+ * @param {{rerun: string, accept: string, pause: string}} invocations the exact
+ *   command each door costs, so nobody has to reconstruct one
+ * @returns {string[]}
+ */
+export function doorLines({ rerun, accept, pause }: {
+    rerun: string;
+    accept: string;
+    pause: string;
+}): string[];
+/**
+ * WHEN THE DEAD LEG STOPPED — the input `readResume` folds into `priorWallMs`, and
+ * therefore what the resumed leg's wall remainder is computed from.
+ *
+ * The runner has two candidate witnesses and they answer different questions:
+ *
+ *  - the WATCHDOG's kill record (`<spine>.watchdog.json`), which is written when the
+ *    outside guard reaps a run. For a run that was killed it is later and better
+ *    evidence than the last spine event: the process was alive, silently, right up to
+ *    the signal, and billing only to its last emitted event would under-report the
+ *    wall it really burnt.
+ *  - the SPINE's own landed terminal (`job-end`). A run that wrote one did not die —
+ *    it ENDED ITSELF and dated its own stop.
+ *
+ * So the preference order is not "the later record wins", it is "the run's own record
+ * wins when there is one". N4 §1.6 is where that distinction stopped being academic:
+ * a `hitl-pause` is a clean terminal a person may answer days later, and any record
+ * dated after it bills their deciding time to the run's wall. The POC measured the
+ * shape — a report 45 days after the pause made `RESUME_WALL_MS` exactly 0, dooming
+ * the resumed leg before it opened, on a run that had barely started. W-2 holds by
+ * construction only if this reads the pause.
+ *
+ * Returning `null` is not a failure: it hands `readResume` back its own documented
+ * default (the last event's timestamp), which for a clean terminal IS the terminal.
+ *
+ * @param {{watchdogAt?: unknown, events?: unknown}} o `watchdogAt` as the report
+ *   spells it (an ISO string, or anything at all — the file is read off disk);
+ *   `events` the dead spine, parsed.
+ * @returns {number|null} ms, or null to leave the default in place
+ */
+export function deathAtOf({ watchdogAt, events }?: {
+    watchdogAt?: unknown;
+    events?: unknown;
+}): number | null;
+/**
+ * WHERE A RESUME PICKS UP — the preview's `at` line, which is what says how much of
+ * the signed dollars this leg can still spend.
+ *
+ * `readStepCheckpoint` (src/reuse.js) knows two phases and a null: `steps` (re-enter
+ * the plan at the first unfinished step), `close` (every step landed; the close and
+ * its fix loop are what is left), and no checkpoint at all (the halt landed before a
+ * plan was accepted). The runner rendered those three directly, and a PAUSE fits none
+ * of them cleanly:
+ *
+ *  - a pause happens AFTER the plan's steps, at the close's human stage. On the
+ *    fixture a person actually meets, the checkpoint reads `phase:'steps'` with every
+ *    step green (the pause site emits no `outer-close` of its own), so the step
+ *    arithmetic ran off the end and printed `at step 2 of 1 "(unknown)"` — a step
+ *    count larger than the plan and an id nobody drafted. hamr found it on the first
+ *    resume preview he read;
+ *  - and the same walk-off is reachable one terminal over, with no person involved:
+ *    a kill between the last `step-end` and the `outer-close` leaves exactly that
+ *    shape, and read `step 3 of 2`.
+ *
+ * So the count is never allowed to exceed the plan, and the PHASE is said in words.
+ * Rendering only; it decides nothing and bounds nothing.
+ *
+ * @param {{seed: {phase?: string, plan?: any, completedSteps?: any[]}|null|undefined,
+ *   paused: boolean}} o `seed` is `readResume`'s `restart.seed`; `paused` is the
+ *   recorded terminal being `hitl-pause` — read off the spine, never off a flag.
+ * @returns {string[]} lines, ready to print
+ */
+export function resumeAtLines({ seed, paused }: {
+    seed: {
+        phase?: string;
+        plan?: any;
+        completedSteps?: any[];
+    } | null | undefined;
+    paused: boolean;
+}): string[];
+/**
+ * F97 — the DOOMED RESUME read, the one the operator should make before signing.
+ *
+ * `u-msn0uccv` spent $0.82 re-entering the exact plan whose action was the diagnosed
+ * defect, carrying `priorReplans: 2` and `priorReplanGrantUsed: true`. A resume does
+ * not re-draft — `scout-skipped {reason:"resumed"}` and the plan comes back
+ * byte-for-byte — so with the replan ledger empty there was no mechanism left that
+ * could replace it. Two attempts, 26 rounds, 0 writes, `step-red` with money and
+ * minutes still on the clock. Nothing in the library was at fault; every part of that
+ * leg reported honestly. The DECISION to fire was the defect, and the read that would
+ * have refused it costs $0: both facts are already parsed by the preview gate.
+ *
+ * WARNING ONLY. This never blocks and never changes behaviour — a resume of a
+ * mechanical gap (a named wall, a count) converts on re-entry all the time, and the
+ * operator is the one who can tell which kind of gap it is. Blocking here would be
+ * this file inventing a gate; the arbiter's gates are signed, not derived from a
+ * readout module.
+ *
+ * @param {{seed?: {phase?: string}|null, replans?: number, replanGrantUsed?: boolean}|null} [restart]
+ *   `readResume`'s `restart` fold: WHERE it picks up and WHAT LEDGER it inherited.
+ * @returns {boolean} true only for the shape F97 measured.
+ */
+export function doomedResume(restart?: {
+    seed?: {
+        phase?: string;
+    } | null;
+    replans?: number;
+    replanGrantUsed?: boolean;
+} | null): boolean;

package/types/userrun.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A fresh run — today's `--job` / `--spec` path. `opts.workdir`/`opts.seed`/
+ * `opts.spineName` name the patient (the JOBS-table row, or the `--spec`
+ * manifest's own reading of it, when called through `main`/`scripts/run-u.mjs`).
+ * @param {any} spec the parsed, not-yet-validated job spec
+ * @param {RunOpts} [opts]
+ * @returns {Promise<number>} an exit code — never calls process.exit
+ */
+export function startRun(spec: any, opts?: RunOpts): Promise<number>;
+/**
+ * A halted run — today's `--resume` path.
+ * @param {string} runId the runid (or an explicit spine path, for tests)
+ * @param {RunOpts & {decide?: string|null, text?: string|null}} [opts]
+ * @returns {Promise<number>} an exit code — never calls process.exit
+ */
+export function resumeRun(runId: string, opts?: RunOpts & {
+    decide?: string | null;
+    text?: string | null;
+}): Promise<number>;
+/**
+ * A finished run's review door — today's `--door` path.
+ * @param {string} runId the runid (or an explicit spine path, for tests)
+ * @param {{decide: string|null, text?: string|null}} decision
+ * @param {RunOpts} [opts]
+ * @returns {Promise<number>} an exit code — never calls process.exit
+ */
+export function answerDoor(runId: string, decision: {
+    decide: string | null;
+    text?: string | null;
+}, opts?: RunOpts): Promise<number>;
+/**
+ * Parses this runner's own argv shape — the JOBS table's `--job <key>` /
+ * `--spec <path>`, plus `--resume`/`--door`/`--decide`/`--text`/
+ * `--review-door`/`--approve`/`--registry`/`--workflow`/`--model`/
+ * `--read-shim`/`--scout` — and dispatches to whichever of the three doors
+ * above the flags name. `scripts/run-u.mjs` is the thin adapter over this,
+ * the same shape `bin/bareloop.mjs` already is over `src/cli.js`'s own
+ * `main(argv, deps)`.
+ * @param {string[]} argv
+ * @param {Deps} [deps]
+ * @returns {Promise<number>}
+ */
+export function main(argv: string[], deps?: Deps): Promise<number>;
+export type Deps = {
+    env?: Record<string, string | undefined> | undefined;
+    out?: ((s: string) => void) | undefined;
+    err?: ((s: string) => void) | undefined;
+    /**
+     * the TEST SEAM: supplying this skips the real-key
+     * check entirely, the same shape `src/cli.js`'s `main(argv, deps)` uses.
+     */
+    provider?: any;
+    providerFor?: ((tier: string) => any) | undefined;
+    judgeProvider?: any;
+};
+export type RunOpts = {
+    /**
+     * the parsed, not-yet-validated job spec — read by
+     * `resumeRun`/`answerDoor`, whose positional argument is the runid rather
+     * than the spec (unlike `startRun`, which takes `spec` positionally and
+     * never reads this).
+     */
+    spec?: any;
+    /**
+     * the patient's tree
+     */
+    workdir?: string | undefined;
+    /**
+     * the patient's frozen seed commit
+     */
+    seed?: string | undefined;
+    /**
+     * the spine directory name, beside `workdir`
+     */
+    spineName?: string | undefined;
+    /**
+     * the raw `--model` tier name (`sonnet`/`haiku`), or null for the default
+     */
+    model?: string | null | undefined;
+    /**
+     * the raw `--read-shim` arm name, or null for the default
+     */
+    readShim?: string | null | undefined;
+    /**
+     * the raw `--scout` value (`on`/`off`), or null for the default
+     */
+    scout?: string | null | undefined;
+    /**
+     * a bridge registry directory
+     */
+    registry?: string | null | undefined;
+    /**
+     * the registry's workflow name (defaults to `spec.job`)
+     */
+    workflow?: string | null | undefined;
+    /**
+     * the spec hash being signed; omitted previews only
+     */
+    approve?: string | null | undefined;
+    /**
+     * opt in to a green-class run opening a review door
+     */
+    reviewDoor?: boolean | undefined;
+    /**
+     * how the re-invocation commands this prints should name the job (`--job x` / `--spec <path>`)
+     */
+    selector?: string | undefined;
+    /**
+     * how a "go edit the spec" hint should read
+     */
+    specDesc?: string | undefined;
+    deps?: Deps | undefined;
+};
+export type RunCtx = {
+    spec: any;
+    specPath: string;
+    selector: string;
+    specDesc: string;
+    workdir: string;
+    seed: string;
+    spineName: string;
+    model: string | null;
+    readShim: string | null;
+    scout: string | null;
+    registry: string | null;
+    workflow: string | null;
+    approve: string | null;
+    reviewDoor: boolean;
+    resume: string | null;
+    door: string | null;
+    decide: string | null;
+    text: string | null;
+    deps: Deps;
+};