bareloop 0.34.0 → 0.36.0

package/types/panel/server.d.ts

@@ -50,6 +50,140 @@ export function checkTypeTitle(verdictType: string | null, atIso?: string | null
  * @returns {string}
  */
 export function formatTimestamp(ts: string | number | Date): string;
+/**
+ * P5 item 2 — may this run be resumed, and under which spec file? The ONE owner of
+ * "would the engine accept `--resume` for this run" on the panel side: it asks the SAME
+ * library readers the engine's own refusals come from (`readResume` with
+ * `CHECKPOINT_OUTCOMES`, `checkpointAgeGate`), plus the two facts the panel needs to
+ * spawn it (a signed spec file beside the run, whose hash is the one the run was signed
+ * under). `ok:false` means the panel declines to offer a button the engine would refuse
+ * by design; it carries a plain `why`.
+ *
+ * The spec file is the run's own `resolved-spec.json` or one of its
+ * `resolved-spec-r<k>.json` siblings (a resume under raised caps writes one), picked by
+ * HASH against the run's `job-start.specHash` — a run resumed under raised caps must be
+ * resumed again under ITS caps, never the original's. No match = no resume offered.
+ * @param {{ spine: string, job: string, pid?: number }} row
+ * @param {any[]} records the run's raw spine records
+ * @returns {{ok: true, specPath: string, spec: any, specHash: string, budgetUsd: number|null,
+ *   maxWallMin: number|null, spentUsd: number|null, spendComplete: boolean,
+ *   draftSpentUsd: number|null, draftSpendComplete: boolean|null, wallUsedMs: number|null}|{ok: false, why: string}}
+ */
+export function resumePlanFor(row: {
+    spine: string;
+    job: string;
+    pid?: number;
+}, records: any[]): {
+    ok: true;
+    specPath: string;
+    spec: any;
+    specHash: string;
+    budgetUsd: number | null;
+    maxWallMin: number | null;
+    spentUsd: number | null;
+    spendComplete: boolean;
+    draftSpentUsd: number | null;
+    draftSpendComplete: boolean | null;
+    wallUsedMs: number | null;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * P5-R — the Audit tab's LEG DIVIDERS (hamr 2026-10-02: "clear audit mention resume"). One per resume, CODE-OWNED
+ * fixed sentences (ui-verdict-words: never model text) built from how the previous leg ended (`after`) and what the
+ * run had spent when it stopped:
+ * `── stopped: money cap reached ($8.00) · resumed 2026-10-03 14:10 ──`.
+ * `beforePart` is the index of the first part of the leg that picked up (the parts list length when that leg has not
+ * started a part yet). Money is the chain's own spend at that leg's end on the ONE basis ({@link chainSpend}).
+ * @param {any[]} spineRecords the run's raw records
+ * @param {any[]} parts `summary.parts` (each carries `leg` on a resumed run)
+ * @returns {{leg: number, beforePart: number, after: string|null, at: string|null, text: string}[]}
+ */
+export function legDividersFor(spineRecords: any[], parts: any[]): {
+    leg: number;
+    beforePart: number;
+    after: string | null;
+    at: string | null;
+    text: string;
+}[];
+/**
+ * P5 item 1 — the ENDED block: why a run ended, what to do next, and which buttons the
+ * engine would accept. CODE-OWNED FIXED SENTENCES (ui-verdict-words: never model text);
+ * the only slot-fills are numbers and the engine's own recorded detail. ONE owner,
+ * feeding both `getRunDetail` (`ended`) and `summarizeRow` (`endedLine`). `null` while
+ * a run is live (no Ended block while running).
+ *
+ * The table (outcome → reason / next / buttons) is PANEL-BUILD.md P5 item 1. The
+ * Resume button appears only when `o.resume` says the engine would accept it; "Reuse workflow"
+ * (replaces P5 item 3, 2026-10-03) is offered on green rows only, and starts a NEW run.
+ * @param {{outcome: string|null, stopReason: string|null, spentUsd: number|null, budgetUsd: number|null, lastEscalation?: any}} summary
+ * @param {{died: boolean, lastThing: string|null}} death
+ * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean,
+ *   worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null}} [o]
+ *   `worktree` (P6 item 1): the run's worktree in the person's repo, from {@link worktreeOfRun}; absent for every other run
+ * @returns {{reason: string, next: string, line: string, actions: {id: string, label: string}[]}|null}
+ */
+export function endedFor(summary: {
+    outcome: string | null;
+    stopReason: string | null;
+    spentUsd: number | null;
+    budgetUsd: number | null;
+    lastEscalation?: any;
+}, death: {
+    died: boolean;
+    lastThing: string | null;
+}, o?: {
+    resume?: {
+        ok: boolean;
+        why?: string;
+    } | null;
+    destinationRefused?: string | null;
+    moneyHalt?: boolean;
+    worktree?: {
+        folder: string;
+        repo: string;
+        branch: string | null;
+        exists: boolean;
+    } | null;
+}): {
+    reason: string;
+    next: string;
+    line: string;
+    actions: {
+        id: string;
+        label: string;
+    }[];
+} | null;
+/**
+ * The Resume route's reader (P5 item 2): the listed row plus the resume plan, from the
+ * ONE {@link resumePlanFor} the Ended block asks. `null` when the runid is not listed
+ * or its spine is gone.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {{row: any, plan: any}|null}
+ */
+export function getResumeContext(runid: string, opts?: {
+    home?: string;
+}): {
+    row: any;
+    plan: any;
+} | null;
+/**
+ * The Stop route's reader (P5 item 5): the listed row, whether its LATEST leg is live (`runIsAlive`: the row's pid
+ * is the latest leg's, folded from the run list's `leg-start`), and whether its spine exists yet. `null` when the
+ * runid is not listed.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {{row: any, live: boolean, spineExists: boolean}|null}
+ */
+export function getStopContext(runid: string, opts?: {
+    home?: string;
+}): {
+    row: any;
+    live: boolean;
+    spineExists: boolean;
+} | null;
 /**
  * `GET /api/runs` — every listed run, NEWEST FIRST BY `at` (never by file/
  * append order — a backfill scan appends rows in sorted-PATH order, which
@@ -195,6 +329,127 @@ export function getRunRounds(runid: string, query?: {
 export function getRunJob(runid: string, opts?: {
     home?: string;
 }): any | null;
+/**
+ * The track record of a WORKFLOW: every LISTED run whose signed spec (the one its latest leg ran under) has this
+ * `workflowKey` — the same goal, checks, guardrails, model and close, whatever source, destination or caps. One run =
+ * ONE entry (a resumed run is one run, its FINAL outcome — `legsOf`), and a run that is still live is neither green
+ * nor not-green yet. `avgSpendUsd` / `avgWallMs` average the FINISHED runs (a recorded terminal) whose figure is exact
+ * (chain spend priced; working time from readable stamps, resume gaps excluded) — `null` when no run qualifies, never 0.
+ * Read from the runs the panel already lists: no registry, no plan handover (hamr ruling A).
+ * `opts.worker` narrows the record to runs on the same WORKER (provider + baseUrl + model — Model is open on a reuse, so
+ * the key no longer separates models): `undefined` = every model, a worker = only runs whose signed spec ran that one,
+ * `null` = no model chosen, so no run matches.
+ * @param {string} key a {@link workflowKey}
+ * @param {{ home?: string, worker?: {provider: string, baseUrl?: string, model: string}|null }} [opts]
+ * @returns {{runs: number, green: number, notGreen: number, live: number, finished: number, avgSpendUsd: number|null, avgWallMs: number|null}}
+ */
+export function trackRecordFor(key: string, opts?: {
+    home?: string;
+    worker?: {
+        provider: string;
+        baseUrl?: string;
+        model: string;
+    } | null;
+}): {
+    runs: number;
+    green: number;
+    notGreen: number;
+    live: number;
+    finished: number;
+    avgSpendUsd: number | null;
+    avgWallMs: number | null;
+};
+/**
+ * The estimate line above a reuse card (code-owned fixed text): `Same job — G green · N not green · about $X and
+ * M min a run`, from the workflow's own listed runs. What is unknown is said, never rendered as $0 or 0 min.
+ * @param {{runs?: number, green: number, notGreen: number, finished?: number, avgSpendUsd: number|null, avgWallMs?: number|null}|null} record
+ * @returns {string}
+ */
+export function reuseLine(record: {
+    runs?: number;
+    green: number;
+    notGreen: number;
+    finished?: number;
+    avgSpendUsd: number | null;
+    avgWallMs?: number | null;
+} | null): string;
+/**
+ * `start-from` (the route keeps its name) for one listed run: the card prefilled from the run's SIGNED job, which
+ * boxes are locked and which are open, and the track record. Locked boxes carry the signed values, read by the
+ * SAME readers the Job tab uses (`successFromSpec`/`guardrailsFromSpec`); the open four — Source, Destination, the
+ * $ cap and the Time cap — start at what the run had. `ok:false` when the run's signed job is not on disk (nothing
+ * to copy: change the job: Clear the card). `null` when the runid is not listed.
+ * @param {string} runid
+ * @param {{ home?: string, model?: string }} [opts] `model` = the Model box's current Name (the estimate counts only runs on that worker); absent = the card's own Model
+ * @returns {{ok: true, origin: {runid: string, job: string}, card: Record<string, any>, from: 'signed job',
+ *   locked: readonly string[], open: readonly string[], note: string|null,
+ *   specHash: string, workflowKey: string, spec: any, specPath: string,
+ *   trackRecord: ReturnType<typeof trackRecordFor>, line: string}|{ok: false, error: string}|null}
+ */
+export function getStartFrom(runid: string, opts?: {
+    home?: string;
+    model?: string;
+}): {
+    ok: true;
+    origin: {
+        runid: string;
+        job: string;
+    };
+    card: Record<string, any>;
+    from: "signed job";
+    locked: readonly string[];
+    open: readonly string[];
+    note: string | null;
+    specHash: string;
+    workflowKey: string;
+    spec: any;
+    specPath: string;
+    trackRecord: ReturnType<typeof trackRecordFor>;
+    line: string;
+} | {
+    ok: false;
+    error: string;
+} | null;
+/**
+ * Reuse workflow, for an IMPORTED job: the bundle is read AGAIN now and must be clean (`readBundle` — its own hash
+ * covers every close script, so a swapped script is `bundle-tampered` here), must resolve its own `bareloop`
+ * dependency (`checkBundleDeps`), and every close stage's signed sha256 must match the script's bytes on disk
+ * (`checkCloseByteSignature`, over the spec with `$BARELOOP_BUNDLE` resolved to this folder — the same in-memory
+ * substitution `bareloop run <bundle>` makes). The reuse spec is that resolved spec; the close scripts stay where
+ * they were just verified (the engine re-verifies their bytes at run start and before every close run). The person
+ * signs it on this machine at [Sign & run]. Same card, same locked/open boxes as a run's reuse. `null` when no such
+ * imported job.
+ * @param {string} id
+ * @param {{ home?: string, model?: string }} [opts] `model` as for {@link getStartFrom}
+ * @returns {{ok: true, origin: {runid: null, job: string, importId: string}, card: Record<string, any>, from: 'imported job',
+ *   locked: readonly string[], open: readonly string[], note: string|null, specHash: string, workflowKey: string, spec: any,
+ *   specPath: null, trackRecord: ReturnType<typeof trackRecordFor>, line: string}|{ok: false, error: string}|null}
+ */
+export function getStartFromImport(id: string, opts?: {
+    home?: string;
+    model?: string;
+}): {
+    ok: true;
+    origin: {
+        runid: null;
+        job: string;
+        importId: string;
+    };
+    card: Record<string, any>;
+    from: "imported job";
+    locked: readonly string[];
+    open: readonly string[];
+    note: string | null;
+    specHash: string;
+    workflowKey: string;
+    spec: any;
+    specPath: null;
+    trackRecord: ReturnType<typeof trackRecordFor>;
+    line: string;
+} | {
+    ok: false;
+    error: string;
+} | null;
 /**
  * Handle one request against the read-only API + the page. Exported
  * separately from {@link createPanelServer} so tests can drive it without a
@@ -211,7 +466,7 @@ export function getRunJob(runid: string, opts?: {
  * only `createPanelServer` below always supplies one.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
- * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes> }} opts
+ * @param {{ home?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes> }} opts
  */
 export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
     home?: string;
@@ -219,6 +474,8 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
     token?: string;
     authorRoutes?: ReturnType<typeof createAuthorRoutes>;
     settingsRoutes?: ReturnType<typeof createSettingsRoutes>;
+    runRoutes?: ReturnType<typeof createRunRoutes>;
+    importRoutes?: ReturnType<typeof createImportRoutes>;
 }): void;
 /**
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
@@ -238,7 +495,8 @@ export function handleRequest(req: import("node:http").IncomingMessage, res: imp
  * this package's own `bin/bareloop.mjs`).
  * @param {{ port?: number, home?: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: (...a: any[]) => any, bareloopBin?: string,
- *   fetchImpl?: typeof fetch }} [opts]
+ *   fetchImpl?: typeof fetch, settleMs?: number, userHome?: string,
+ *   openFolderSpawn?: (cmd: string, args: string[], o: object) => any, platform?: string }} [opts]
  * @returns {Promise<{ server: import('node:http').Server, port: number, token: string, close: () => Promise<void> }>}
  */
 export function createPanelServer(opts?: {
@@ -249,6 +507,10 @@ export function createPanelServer(opts?: {
     spawnFn?: (...a: any[]) => any;
     bareloopBin?: string;
     fetchImpl?: typeof fetch;
+    settleMs?: number;
+    userHome?: string;
+    openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
+    platform?: string;
 }): Promise<{
     server: import("node:http").Server;
     port: number;
@@ -299,4 +561,6 @@ export const ROUNDS_PAGE_DEFAULT: 50;
 export const ROUNDS_PAGE_MAX: 200;
 import { createAuthorRoutes } from './authorroutes.js';
 import { createSettingsRoutes } from './settingsroutes.js';
+import { createRunRoutes } from './runroutes.js';
+import { createImportRoutes } from './importroutes.js';
 import { DIED_MTIME_MS } from '../runlist.js';

package/types/panel/settingsroutes.d.ts

@@ -1,6 +1,9 @@
 /**
+ * `openFolderSpawn` / `platform` are test seams for the Open keys folder button (a real caller passes
+ * neither: `child_process.spawn` and `process.platform`).
  * @param {{ port: number, token: string, home?: string, env?: Record<string,string|undefined>,
- *   fetchImpl?: typeof fetch, now?: () => number }} opts
+ *   fetchImpl?: typeof fetch, now?: () => number, openFolderSpawn?: (cmd: string, args: string[], o: object) => any,
+ *   platform?: string }} opts
  */
 export function createSettingsRoutes(opts: {
     port: number;
@@ -9,6 +12,8 @@ export function createSettingsRoutes(opts: {
     env?: Record<string, string | undefined>;
     fetchImpl?: typeof fetch;
     now?: () => number;
+    openFolderSpawn?: (cmd: string, args: string[], o: object) => any;
+    platform?: string;
 }): {
     handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
 };

package/types/panel/status.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The status of one run.
+ * @param {{outcome: string|null|undefined, died?: boolean, category?: string|null, moneyHalt?: boolean}} o
+ *   `category` is the last escalation's category; `moneyHalt` is whether the spine carries a `money-halt` record
+ * @returns {{key: StatusKey, sign: string, word: string}}
+ */
+export function statusFor(o: {
+    outcome: string | null | undefined;
+    died?: boolean;
+    category?: string | null;
+    moneyHalt?: boolean;
+}): {
+    key: StatusKey;
+    sign: string;
+    word: string;
+};
+/** the sentence a passed run carries as its reason (the Ended block's `line`) */
+export const GOAL_MET_LINE: "goal met";
+/** @typedef {'running'|'waiting'|'passed'|'failed'|'capped'|'stopped'|'died'} StatusKey */
+/** the table: key -> sign + word */
+export const STATUS: Readonly<{
+    running: Readonly<{
+        sign: "▶";
+        word: "running";
+    }>;
+    waiting: Readonly<{
+        sign: "·";
+        word: "waiting";
+    }>;
+    passed: Readonly<{
+        sign: "✓";
+        word: "passed";
+    }>;
+    failed: Readonly<{
+        sign: "✗";
+        word: "failed";
+    }>;
+    capped: Readonly<{
+        sign: "✗";
+        word: "capped";
+    }>;
+    stopped: Readonly<{
+        sign: "✗";
+        word: "stopped";
+    }>;
+    died: Readonly<{
+        sign: "?";
+        word: "died";
+    }>;
+}>;
+export type StatusKey = "running" | "waiting" | "passed" | "failed" | "capped" | "stopped" | "died";

package/types/planrun.d.ts

@@ -77,25 +77,6 @@
  * @returns {string} the labelled block, or '' when there is nothing to show
  */
 export function closeGapBlock(gap: string | null | undefined): string;
-/**
- * BA-21 — the WRITE side of the pricing-provenance signal (read side: `rateProvenance` /
- * `spendProvenance` in src/ledger.js). bare-agent >=0.37 rides `rateSource` beside
- * `pricing` on every metering payload; both metering callbacks below forward it onto the
- * spine through THIS one helper, because two sites spelling one rule are two instruments
- * (the ripgrep fix that landed in ci.yml but not publish.yml).
- *
- * Forwarded VERBATIM — the write side reports what upstream said, and src/ledger.js is
- * the one place that decides what counts as a guess. And an ABSENT provenance stays
- * absent: a payload carrying no `rateSource` (bare-agent <0.37, and every round already
- * in the archive) emits no field at all, so a reader sees UNKNOWN rather than a label we
- * invented. Never defaulted to `null` here — `null` is upstream saying "nothing was
- * priced", which is a different fact from "nobody told us".
- * @param {any} arg an `onLlmResult` / `onTurn` payload
- * @returns {{rateSource?: string|null}} the field to spread into the spine record
- */
-export function rateSourceFields(arg: any): {
-    rateSource?: string | null;
-};
 /**
  * What the NEXT attempt is told about the bound that cut the previous one.
  *
@@ -415,12 +396,18 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   passes `false` so the three `--resume`-naming readouts below (`MONEY_OPTIONS`,
  *   the resume-plan-red option, the fix-loop terminal) say "resume is `run-u`-only
  *   in v1" instead of naming a flag that would fail if typed.
+ * @param {string|null} [opts.stopFile=null] P5 item 5 — the run's STOP REQUEST file
+ *   (`stopFilePath(spine)`, src/legs.js). Read at ONE seam, the round boundary of a step worker
+ *   (the `metered` callback, where the money cap binds): present = emit `stop-requested`, consume
+ *   the file, end the Loop after that round, and end the leg `stopped` (a checkpoint outcome, filed
+ *   the way a mid-step cap-halt is; resume re-enters that step). Nothing is in flight at that
+ *   point, so the spend is exact. `null` = no stop surface (the default).
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
- *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
+ *   'branch-red' | 'cap-halt' | 'wall-halt' | 'stopped' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable, stopFile }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -483,7 +470,9 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         receivedAt?: string | null;
     } | null | undefined;
     resumable?: boolean | undefined;
+    stopFile?: string | null | undefined;
 }): Promise<string>;
+export { rateSourceFields };
 /**
  * The runtime belt for F178 (`.git`) and F177's follow-up (`node_modules`) —
  * hamr's option B ruling (2026-09-14): block WRITING to either, never reading.
@@ -532,7 +521,10 @@ export const FORBIDDEN_WRITE_SEGMENT_PATTERN: RegExp;
  * shipped path routinely rides through.
  */
 export const BOUND_REASON_MAX: 200;
+/** the recorded reason for a step attempt whose round was cut at the output cap (F122 2A b) */
+export const TRUNCATED_REASON: "output cut at the token limit (max_tokens)";
 export type CategorizedError = Error & {
     category?: string;
     lib?: string;
 };
+import { rateSourceFields } from './text.js';

package/types/providerrows.d.ts

@@ -56,6 +56,18 @@ export function defaultUrlOf(provider: string): string;
  * @returns {string}
  */
 export function endpointOf(provider: string, baseUrl: string | null | undefined): string;
+/**
+ * A job's provider in plain words for a refusal line: the host its Base URL points at (else the
+ * shape's own default host, else the shape's label), plus the model when the spec names one.
+ * Never a key, a path or a status code.
+ * @param {{provider?: string, baseUrl?: string|null, model?: string|null}} spec
+ * @returns {string}
+ */
+export function providerInWords(spec: {
+    provider?: string;
+    baseUrl?: string | null;
+    model?: string | null;
+}): string;
 /**
  * The URL a row talks to, for display ('' = the vendor's own host, which has no URL to show).
  * @param {KeyRow} row

package/types/ralph.d.ts

@@ -1,3 +1,22 @@
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{env: NodeJS.ProcessEnv, cwd?: string, timeoutMs?: number}} o
+ * @returns {Promise<{error: (Error & {code?: string})|null, status: number|null, signal: string|null, stdout: string, stderr: string}>}
+ */
+export function spawnClose(cmd: string, args: string[], { env, cwd, timeoutMs }: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<{
+    error: (Error & {
+        code?: string;
+    }) | null;
+    status: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
  * `expect` → satisfied; any other exit → needs_revision (gap fed back).

package/types/replay.d.ts

@@ -36,6 +36,18 @@ export function auditWindow(jobStart?: {
     startTs: number;
     endTs: number;
 };
+/**
+ * One window PER LEG of a (possibly resumed) run (P5-R) — the ONE owner the panel and {@link replayRun} share. A
+ * run with no `leg-resume` marker is one leg and this is `[auditWindow(jobStart, jobEnd)]`, exactly as before. A
+ * resumed run's quiet time between two legs is nobody's, so a row another run wrote into a shared sidecar during it
+ * is outside every window; a leg that recorded no terminal (it died) ends where the next leg begins.
+ * @param {any[]} spineRecords
+ * @returns {{startTs: number, endTs: number}[]}
+ */
+export function auditWindowsOf(spineRecords: any[]): {
+    startTs: number;
+    endTs: number;
+}[];
 /**
  * Reconstruct one run's whole story from its spine + gate-audit. Pure: no
  * IO, no spine writes, no verdict. Malformed/non-object entries in either
@@ -109,6 +121,15 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
         skipping: any;
         divergence: any;
     } | null;
+    legs: {
+        leg: number;
+        after: string | null;
+        outcome: string | null;
+        startTs: any;
+        endTs: any;
+        startSeq: any;
+        endSeq: any;
+    }[];
     thisFileSpend: {
         value: any;
         source: "engagementSpentUsd" | "summed rounds";
@@ -178,9 +199,12 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
             label: string;
             error: string | null;
         } | null;
+        outcome: any;
+        stopReason?: string | null | undefined;
+        continued?: boolean | undefined;
+        tryNumber?: number | undefined;
         id: any;
         occurrence: any;
-        outcome: any;
     }[];
     iterations: {
         windowStartSeq: any;

package/types/replayio.d.ts

@@ -43,7 +43,7 @@ export function resolveSiblings(spinePath: string): {
  * 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,
- *   auditPathOverride?: string|null}} [opts]
+ *   auditPathOverride?: string|string[]|null}} [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
@@ -68,7 +68,7 @@ export function replayOne(spinePath: string, opts?: {
         skipped: number;
     };
     skipAudit?: boolean;
-    auditPathOverride?: string | null;
+    auditPathOverride?: string | string[] | null;
 }): ReturnType<typeof replayRun>;
 /**
  * List every spine found directly in `dir` (not recursive — same as the

package/types/reuse.d.ts

@@ -605,6 +605,11 @@ export const REUSE_GRADED_RED: readonly string[];
  * allowances the loop's remaining tries are meant to spend against, and the human
  * ones are the stop no further try can change (see `hardStop`).
  *
+ * `stopped` (PANEL-BUILD.md P5 item 5, hamr 2026-10-02): the PERSON ended the leg at a round
+ * boundary (a `<spine>.stop` request). Nothing was judged and nothing failed — finished steps stand on
+ * disk, the allowance is unspent, so it is a checkpoint exactly like a cap-halt. Arbiter-adjacent (it
+ * widens what resume may re-enter); ruled by hamr, not chosen by a builder.
+ *
  * `provider-red` folded in 2026-08-25 (PRD v1.80 TODO #4, F115 "Ruled: one transport
  * retry"; hamr's ruling verbatim: *"joins resume anyways and you decide but you are
  * given an honest readout and with 1 retry"*). It is a MACHINE halt, not a human one

package/types/run.d.ts

@@ -195,10 +195,13 @@
  *   passes `false` so the escalation tail's option strings say "resume is
  *   `run-u`-only in v1" instead of naming a flag that would fail if typed. Forwarded
  *   verbatim to the plan flow, which owns the three `--resume`-naming readouts.
+ * @param {string|null} [opts.stopFile=null] P5 item 5 — the run's STOP REQUEST file
+ *   (`stopFilePath(spine)`, src/legs.js), forwarded verbatim to the plan flow, which reads it at the
+ *   round-boundary seam (where the money cap binds) and ends the leg `stopped`. `null` = no stop surface.
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'stopped' | '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
@@ -209,7 +212,7 @@
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable, stopFile }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -271,6 +274,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         receivedAt?: string | null;
     } | null | undefined;
     resumable?: boolean | undefined;
+    stopFile?: string | null | undefined;
 }): Promise<string>;
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 /**