bareloop 0.27.0 → 0.29.0

package/types/authorreadout.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @param {{goal?: string|null, closeDecl?: any}} spec the RESOLVED spec — the bytes
+ *   that get hashed and signed, never the operator's draft and never the authored
+ *   half on its own.
+ * @returns {string[]} one console line each, in print order.
+ */
+export function declarationLines({ goal, closeDecl }: {
+    goal?: string | null;
+    closeDecl?: any;
+}): string[];
+/**
+ * F176'S FALLBACK, SAID OUT LOUD — the revise ladder kept the NEWEST SOUND
+ * declaration rather than the last one it happened to try, because "kept the
+ * last accepted revision" is not the same claim as "kept the best revision"
+ * (docs/logs/FINDINGS.md F176). Absent on every run where the fallback never
+ * fired (the overwhelming majority), which is why this returns an EMPTY list
+ * rather than a "no fallback" line — a green close has nothing to say here and
+ * printing it every run would be noise, not information.
+ * @param {{fellBack?: {from: string, to: string, brokenStages: string[]}|null}|null} authoring `authored.authoring`
+ * @returns {string[]}
+ */
+export function fellBackLines(authoring: {
+    fellBack?: {
+        from: string;
+        to: string;
+        brokenStages: string[];
+    } | null;
+} | null): string[];
+/**
+ * THE TWO SIGNED JUDGED ARTIFACTS, as a person reads them before signing
+ * (softgreen modules 4+5). Absent on a close that judges nothing, which is why
+ * this returns an EMPTY list rather than a "no card" line: a green close has no
+ * rubric and saying so every run is noise, not information.
+ *
+ * The CARD is printed in full — it is short, it is the whole standard the judge
+ * will hold the work to, and it is the signer's own words. The CASES are printed
+ * as a ROSTER (id, verdict, itemized reds) rather than in full: ten real source
+ * artifacts is a page of code the terminal cannot usefully show, and what a
+ * signer checks at this surface is that both polarities are there and that each
+ * red names something they recognise. The artifacts themselves are in the spec
+ * file, which is named right above this block.
+ * @param {{closeDecl?: any}} spec the RESOLVED spec
+ * @returns {string[]}
+ */
+export function rubricLines({ closeDecl }: {
+    closeDecl?: any;
+}): string[];
+/**
+ * THE CONFIRM TURN'S OPEN QUESTIONS (PRD item 33 M3 piece 4, ruling 5's D3
+ * addendum) — shown at the SIGNING readout, from `authored.json`'s own
+ * `confirmed.openQuestions`, never added to the signed spec format itself
+ * (D4: the closeDecl's `notes` are the model's own record; this is the
+ * person's "fix" text from a round that hit the 2-round cap, ruling 5,
+ * passed to the composer verbatim rather than spending a 3rd call, D3). A
+ * close with none is shown as `(none)` rather than an empty line — the
+ * absence is itself part of what the signer reads before signing.
+ * @param {{openQuestions?: string[]}|null} confirmed `authored.confirmed`
+ * @returns {string[]}
+ */
+export function openQuestionLines(confirmed: {
+    openQuestions?: string[];
+} | null): string[];
+/**
+ * F175's open half, said at the SIGNING readout too (run mu0voeo4, hamr's
+ * 2026-09-16 ruling) — every question the plan raised that "Confirm" or
+ * "Type the goal yourself" forced the person to answer inline, from
+ * `authored.json`'s own `confirmed.answeredQuestions`. Shown only when
+ * non-empty (the overwhelming majority of plans raise no question at all,
+ * and printing an empty block every run would be noise, not information) —
+ * unlike {@link openQuestionLines}, an empty list here says nothing, because
+ * absence is the ordinary case, not a fact the signer needs flagged.
+ * @param {{answeredQuestions?: string[]}|null} confirmed `authored.confirmed`
+ * @returns {string[]}
+ */
+export function answeredQuestionLines(confirmed: {
+    answeredQuestions?: string[];
+} | null): string[];
+/**
+ * THE CALIBRATION GATE'S OWN READOUT — the one gate that spends money, and the
+ * one whose rows a signer has to read case by case.
+ *
+ * ITEMIZED, never an aggregate percentage: "9/10" tells a person nothing about
+ * which line of their own rubric is wrong, and the fix for a miss is a card line
+ * or a corrected case (§4.3's ceiling). A CASUALTY prints under its own name and
+ * says so, because a dead judge is not a failed set.
+ * @param {any} calibration `signing.gates.calibration`
+ * @returns {string[]}
+ */
+export function calibrationLines(calibration: any): string[];
+/**
+ * THE AUTHORING CEILING, parsed from `--budget`. Housed here for the same reason
+ * the readout above is: the runner is a script, and a rule no test can reach is a
+ * rule nothing checks.
+ *
+ * ABSENT IS UNBOUNDED, and that is the only way to get there. A malformed value
+ * is an ERROR rather than a fallback: `--budget banana` silently collapsing to
+ * "no ceiling" is precisely the failure this flag exists to prevent, wearing the
+ * operator's own typo. Zero and negatives are rejected on the same rule — a
+ * ceiling that can fund nothing is a typo for "unbounded" far more often than it
+ * is a request, and the honest way to ask for nothing is not to ask.
+ *
+ * There is NO DEFAULT anywhere in this function, deliberately: a defaulted cap is
+ * a silent second ceiling (the `maxWallMs` precedent), and the number is the
+ * operator's to set or to decline.
+ * @param {string|null} raw the argv value, or null when the flag was not given
+ * @returns {{ceilingUsd: number|null, error: string|null}}
+ */
+export function parseCeiling(raw: string | null): {
+    ceilingUsd: number | null;
+    error: string | null;
+};
+/**
+ * The ceiling's header line. An UNBOUNDED run is ANNOUNCED — printed before the
+ * provider is built, so it reaches stdout ahead of the first paid byte rather
+ * than being inferred from the total afterwards. An unbounded run is legal; it is
+ * never allowed to be an accident.
+ * @param {number|null} ceilingUsd
+ */
+export function ceilingLine(ceilingUsd: number | null): string;
+/**
+ * ONE PROGRESS PHASE, as a console line.
+ *
+ * The pipeline used to run up to ~15 minutes saying nothing between
+ * `author-start` and its result — a real survey ladder, a real declaration
+ * ladder, and a real toolchain per close stage, all inside one await. Silence
+ * and a hang are the same bytes on a terminal, and the operator's only lever is
+ * to kill a run that may be working.
+ *
+ * It says WHAT is happening, never how far along it is: there is no honest
+ * fraction to print (a survey attempt has no progress, and a suite stage
+ * finishes when it finishes), and an invented percentage is a number nobody
+ * measured. What it does carry is the two facts a person waiting actually uses —
+ * which phase, and how long the last thing took.
+ *
+ * `durationMs` prints as UNKNOWN when it is absent rather than as 0 (F6's rule,
+ * in its time form): a stage whose duration was never measured did not take no
+ * time.
+ * @param {string} phase @param {any} [data]
+ * @returns {string}
+ */
+export function phaseLine(phase: string, data?: any): string;
+/**
+ * ONE crashed authoring run, ready for the spine.
+ *
+ * It exists because a crash used to leave NO body. `run-author.mjs` awaited the
+ * paid pipeline at the top level, so a throw anywhere inside it went to the
+ * operator's terminal as an unhandled rejection and the spine kept exactly one
+ * line — `author-start` — which is byte-for-byte what a run still in flight looks
+ * like. The terminal scrolls; the spine is the record.
+ *
+ * The STACK is the evidence (the incident that minted this had no idea WHERE the
+ * throw came from), and a stack is the one field here that can be arbitrarily
+ * long and can quote anything the process had open. So it goes through `scrubRaw`
+ * — the ONE persist boundary for a raw blob — which redacts it over the same
+ * `SECRET_PATTERNS` inventory the validator reds on and bounds it with the bound
+ * announcing its own size (F28). Nothing here is hand-rolled: a second spelling
+ * of either rule is how the two drift.
+ *
+ * A non-Error throw (a string, a plain object) is honest rather than coerced into
+ * an Error shape: it has no `name`, so `name` is `null`, and `String(err)` is what
+ * lands in the raw.
+ * @param {unknown} err whatever was thrown
+ * @returns {{name: string|null, message: string|null, code: string|null,
+ *   raw: ReturnType<typeof scrubRaw>}}
+ */
+export function crashRecord(err: unknown): {
+    name: string | null;
+    message: string | null;
+    code: string | null;
+    raw: ReturnType<typeof scrubRaw>;
+};
+import { scrubRaw } from './text.js';

package/types/authorrun.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @typedef {object} Deps
+ * @property {Record<string,string|undefined>} [env]
+ * @property {NodeJS.ReadStream} [stdin]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {string} [invokedAs] the command name this run was actually
+ *   reached through, for the usage message ONLY — `scripts/run-author.mjs`
+ *   supplies none (defaults to its own real invocation), `src/cli.js` passes
+ *   `'bareloop author'` so a person who typed that is told to re-run THAT,
+ *   never a script path they never invoked and may not have on disk.
+ */
+/**
+ * Parses this script's own argv shape and runs the authoring pipeline
+ * (scout, declaration loop, D9's gates) against the given (or real)
+ * stdin/stdout. `scripts/run-author.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>} an exit code — never calls process.exit
+ */
+export function main(argv: string[], deps?: Deps): Promise<number>;
+export type Deps = {
+    env?: Record<string, string | undefined> | undefined;
+    stdin?: NodeJS.ReadStream | undefined;
+    stdout?: NodeJS.WritableStream | undefined;
+    stderr?: NodeJS.WritableStream | undefined;
+    /**
+     * the command name this run was actually
+     * reached through, for the usage message ONLY — `scripts/run-author.mjs`
+     * supplies none (defaults to its own real invocation), `src/cli.js` passes
+     * `'bareloop author'` so a person who typed that is told to re-run THAT,
+     * never a script path they never invoked and may not have on disk.
+     */
+    invokedAs?: string | undefined;
+};

package/types/behaviour.d.ts

@@ -39,8 +39,10 @@ export function runBehaviour(events: Array<{
  * Render a {@link runBehaviour} summary as the agreed printable block
  * (2–4 short lines). A zero-call run formats plainly ("0 tool calls") rather
  * than a NaN-laced percentage — an empty run is a complete, reportable
- * answer, not a division error.
- * @param {ReturnType<typeof runBehaviour>} summary
+ * answer, not a division error. `summary === null` means the caller never
+ * had a gate-audit sidecar to read at all (see `replayRun`'s `auditAvailable`
+ * option) — that reads as "unknown", never coerced to a 0-call summary.
+ * @param {ReturnType<typeof runBehaviour>|null} summary
  * @returns {string}
  */
-export function formatBehaviour(summary: ReturnType<typeof runBehaviour>): string;
+export function formatBehaviour(summary: ReturnType<typeof runBehaviour> | null): string;

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, judgeModel?: string|null, 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, runlistHome?: string }} deps
  * @returns {Promise<number>}
  */
 export function main(argv: string[], deps?: {
@@ -17,4 +17,5 @@ export function main(argv: string[], deps?: {
     judgeModel?: string | null;
     now?: () => number;
     stdin?: any;
+    runlistHome?: string;
 }): Promise<number>;

package/types/index.d.ts

@@ -24,7 +24,8 @@ export { scrubRaw, RAW_PERSIST_MAX } from "./text.js";
 export { authorClose, MAX_REVISIONS, questionsFor, requiredAnswersFor } from "./authorflow.js";
 export { validateCloseDecl, runDeclaredStages, declaredStages, HUMAN_PAUSE } from "./declaredclose.js";
 export { runBehaviour, formatBehaviour } from "./behaviour.js";
-export { replayRun, formatReplay } from "./replay.js";
+export { replayRun, formatReplay, summarizeForAllLine, formatAllLines } from "./replay.js";
+export { replayOne, listSpines, readHistoryLog } from "./replayio.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, AUTHORED_SPEC_FIELDS } from "./authorjob.js";
 export { PROMPT_REGISTERS, isPromptFile } from "./promptregisters.js";
 export { exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps } from "./bundle.js";

package/types/interviewrun.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @typedef {object} Deps
+ * @property {Record<string,string|undefined>} [env]
+ * @property {NodeJS.ReadStream} [stdin]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {typeof realSpawnSync} [spawnSync] the TEST SEAM for the final
+ *   paid-step offer — a caller that supplies this never actually spawns
+ *   `scripts/run-author.mjs`.
+ * @property {string} [invokedAs] the command name this run was actually
+ *   reached through, for the usage message ONLY — `scripts/run-interview.mjs`
+ *   supplies none (defaults to its own real invocation), `src/cli.js` passes
+ *   `'bareloop interview'` so a person who typed that is told to re-run THAT,
+ *   never a script path they never invoked and may not have on disk.
+ */
+/**
+ * Parses this script's own argv shape and runs the interview against the
+ * given (or real) stdin/stdout. `scripts/run-interview.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>} an exit code — never calls process.exit
+ */
+export function main(argv: string[], deps?: Deps): Promise<number>;
+export type Deps = {
+    env?: Record<string, string | undefined> | undefined;
+    stdin?: NodeJS.ReadStream | undefined;
+    stdout?: NodeJS.WritableStream | undefined;
+    stderr?: NodeJS.WritableStream | undefined;
+    /**
+     * the TEST SEAM for the final
+     * paid-step offer — a caller that supplies this never actually spawns
+     * `scripts/run-author.mjs`.
+     */
+    spawnSync?: typeof realSpawnSync | undefined;
+    /**
+     * the command name this run was actually
+     * reached through, for the usage message ONLY — `scripts/run-interview.mjs`
+     * supplies none (defaults to its own real invocation), `src/cli.js` passes
+     * `'bareloop interview'` so a person who typed that is told to re-run THAT,
+     * never a script path they never invoked and may not have on disk.
+     */
+    invokedAs?: string | undefined;
+};
+import { spawnSync as realSpawnSync } from 'node:child_process';

package/types/panel/server.d.ts

@@ -0,0 +1,265 @@
+/**
+ * `[✓]`/`[✗]`/`[▶]` — the ONLY vocabulary a result is ever rendered in
+ * (auto-memory `ui-verdict-words.md`: never the words green/red/soft-green
+ * anywhere in the page). `null` (no `job-end` reached — a killed-mid-run or
+ * still-running spine) reads `▶` — the same "in progress / unresolved" glyph
+ * P1's own four-glyph vocabulary reserves for that state; a genuinely still-
+ * running attempt and an archived spine that never reached its own end are
+ * the same fact from this read-only side: no verdict has been recorded yet.
+ * @param {string|null} outcome
+ * @returns {'✓'|'✗'|'▶'}
+ */
+export function glyphForOutcome(outcome: string | null): "\u2713" | "\u2717" | "\u25B6";
+/**
+ * `deterministic` (green) / `rubric` (soft-green) / `unknown` (a class this
+ * reader doesn't recognize) — the settled UI wording (PANEL-BUILD.md §6),
+ * never the internal `green`/`soft-green` spelling. Item 3 (2026-09-25): a
+ * spine with NO `verdictType` (pre-F117) is genuinely ambiguous UNLESS its
+ * own run date (`atIso`, the job-start ts) predates {@link
+ * SOFTGREEN_ADMITTED_ISO} — in that one case, `deterministic` was the only
+ * check type that could have run, so it is reported as such (not fabricated:
+ * derived from the frozen historical fact that soft-green did not exist
+ * yet), paired with {@link checkTypeTitle}'s tooltip explaining the
+ * derivation rather than presenting it as if it had been directly recorded.
+ * `atIso` is optional so every existing single-arg caller/test keeps its
+ * prior behavior (no date -> 'unknown', same as before this item).
+ * @param {string|null} verdictType
+ * @param {string|null} [atIso] the run's own job-start timestamp
+ * @returns {'deterministic'|'rubric'|'unknown'}
+ */
+export function checkTypeLabel(verdictType: string | null, atIso?: string | null): "deterministic" | "rubric" | "unknown";
+/**
+ * The tooltip/title text for {@link checkTypeLabel}'s pre-softgreen-cutoff
+ * branch — `null` for every other case (a real `verdictType` needs no
+ * explanation; a genuinely unknown one has none to give).
+ * @param {string|null} verdictType
+ * @param {string|null} [atIso]
+ * @returns {string|null}
+ */
+export function checkTypeTitle(verdictType: string | null, atIso?: string | null): string | null;
+/**
+ * `YYYY-MM-DD HH:MM` (local time, 24h, zero-padded) — the ONE
+ * timestamp-WITH-TIME format this page ever shows (a plain date elsewhere
+ * stays `YYYY-MM-DD`, e.g. `row.at.slice(0,10)`, untouched — that's a
+ * different, shorter field, not this helper's concern). Used instead of a
+ * locale-dependent `toLocaleString()` spelling (F195: the died "why" line
+ * read `9/9/2026, 11:49:40 AM`, inconsistent with every other date on the
+ * page) so a future second timestamp-with-time spot routes through the same
+ * one function rather than growing its own `toLocale*` call.
+ * @param {string|number|Date} ts
+ * @returns {string}
+ */
+export function formatTimestamp(ts: string | number | Date): string;
+/**
+ * `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
+ * does not track chronological `at` order; a plain `.reverse()` here once
+ * silently mis-sorted any list `appendRun` didn't build strictly
+ * chronologically), each enriched with a cheap ($0, `skipAudit:true`)
+ * summary. A row with an unparseable/missing `at` sorts last (Unix epoch 0),
+ * never crashes the sort or floats to the top. Ties (identical `at`) keep
+ * their original file order among themselves (stable sort) rather than an
+ * arbitrary one. The Workflows view (item 2, 2026-09-26 merge) groups this
+ * SAME payload by job client-side (`groupRunsByJob` in `index.html`) rather
+ * than a second server-side endpoint, so the glyph/checkType mapping is
+ * still computed in exactly one place.
+ * @param {{ home?: string }} [opts]
+ * @returns {any[]}
+ */
+export function listRuns(opts?: {
+    home?: string;
+}): any[];
+/**
+ * `GET /api/runs/:runid` — the full replay for the Run tab: steps (or
+ * iterations), counters, summary-box fields. Looks `runid` up in the run
+ * list FIRST and reads only the path stored there (path safety — see file
+ * header); `null` when the runid is not in the list at all (caller renders
+ * 404).
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunDetail(runid: string, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * `GET /api/runs/:runid/audit` — the Audit tab's rows, off the run's own
+ * gate-audit sidecar (name-convention resolution, `src/replayio.js`'s
+ * `resolveSiblings`), scoped to this run's own ts window (see {@link
+ * runAuditWindow} — a sidecar can carry other runs' rows). A row's real
+ * fields (`ts`, `action.type`, `action.path`, `decision`) plus `partIndex`/
+ * `partLabel`/`attemptN` — see {@link makePartLookup} (build item C,
+ * 2026-09-26 rewrite): derived from the row's own ROUND's `seq` matched
+ * against `summary.parts`' own attempt windows, never phase-string guessing.
+ * `reason` names WHY `partIndex` is `null`: `'no-round'` (the row's `ts` falls
+ * before the very first model call) vs `'unassigned'` (a round exists but its
+ * seq matched no part window — an honest gap, never fabricated) vs `null`
+ * when `partIndex` is real.
+ * `round` — see
+ * {@link makeRoundLookup}. A `phase:'record'`/`action.type:'llm'` row (item
+ * 2: every MODEL CALL, `decision` always `null` on the real record) is
+ * marked `kind:'model-call'` with its own `result.{costUsd,tokens,
+ * durationMs}` surfaced directly (never re-derived); every other row is
+ * `kind:'tool-call'`, unchanged.
+ * `reason` distinguishes the two ways this can come back empty (item 1,
+ * 2026-09-25): `'no-sidecar'` — no gate-audit sidecar was ever written for
+ * this run (an older version, or a run-u/native path that never emitted one)
+ * — vs `'sidecar-empty'` — a sidecar file DOES exist but has zero rows FOR
+ * THIS RUN'S OWN WINDOW (the run made no tool/model calls the gate audited,
+ * or every row on disk belongs to a different run sharing the same
+ * filename). The client renders these as two different sentences; never a
+ * bare empty table for either.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {{runid: string, rows: any[], raw: string, empty: boolean, reason: 'no-sidecar'|'sidecar-empty'|null}|null}
+ */
+export function getRunAudit(runid: string, opts?: {
+    home?: string;
+}): {
+    runid: string;
+    rows: any[];
+    raw: string;
+    empty: boolean;
+    reason: "no-sidecar" | "sidecar-empty" | null;
+} | null;
+/**
+ * `GET /api/runs/:runid/rounds?part=<index>&attempt=<n>&offset=&limit=`
+ * — build item C (2026-09-26 rewrite): the Audit tab's expandable attempt
+ * detail, built server-side in one endpoint and rendered lazily on expand.
+ * REPLACES the earlier step-id/occurrence/`FIX_LOOP_STEP_ID`-sentinel/
+ * `timelineKind` branching (three separate ways to resolve a window,
+ * deleted here) with ONE rule: `part` indexes directly into
+ * `summary.parts` (`src/replay.js`'s own ONE ordered part list — scout,
+ * plan, each step occurrence, replan, fix, judge, or a single `run` part on
+ * an old spine), and `attempt` indexes into THAT part's own `attempts` array
+ * — every part kind already carries at least one (a real per-attempt list
+ * for `step`/`fix`, or a single synthetic whole-part attempt for
+ * scout/plan/replan/judge/run, `src/replay.js`'s `wholePartAttempt`). No
+ * second windowing pass: each attempt's own `startSeq`/`endSeq` is read
+ * directly off `replayOne`'s already-computed summary.
+ * Tool calls per round reuse {@link getRunAudit}'s own already-scoped,
+ * already-round-tagged rows — filtered to this round's number, never
+ * re-derived. `toolLogSaved:false` (no gate-audit sidecar at all) still
+ * returns every round from the spine's own worker-round records, each with
+ * `toolCalls: null` (never a fabricated empty array — the client renders
+ * "tool calls: no log saved").
+ * Pagination: `offset`/`limit` slice the ATTEMPT's rounds list (never a
+ * round's own tool-call list) — `limit` defaults to {@link
+ * ROUNDS_PAGE_DEFAULT}, clamped to {@link ROUNDS_PAGE_MAX}; the response
+ * always carries `totalRounds` so the client can print "showing A–B of N",
+ * never a silently truncated list.
+ * `null` when the run isn't listed, the requested part/attempt index doesn't
+ * resolve to a real window, or the spine file is missing — the caller
+ * renders 404, same posture as {@link getRunAudit}/{@link getRunJob}.
+ * @param {string} runid
+ * @param {{ part?: number, attempt?: number, offset?: number, limit?: number }} query
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunRounds(runid: string, query?: {
+    part?: number;
+    attempt?: number;
+    offset?: number;
+    limit?: number;
+}, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * `GET /api/runs/:runid/job` — the Job tab, filled from the first source
+ * that actually resolves (item 2, 2026-09-25), in order:
+ *  (a) the bundle's own `spec.json` (a `bareloop run` bundle keeps one
+ *      beside its `runs/` dir) — the pre-existing path, unchanged;
+ *  (b) `jobs/<job>.json` in the repo's own jobs/ dir (resolved from the
+ *      package root) — its `jobSpecHash` is compared against the run's own
+ *      job-start `specHash`; a mismatch is shown, never hidden (the job may
+ *      have been edited since this run signed it);
+ *  (c) NEW (item 2, 2026-09-25): the run's own `resolved-spec.json`, found
+ *      beside the spine via {@link sourceNearSpine} — a person-path (`--spec`
+ *      or a source-seed-backed JOBS-table row) run's signed copy, never
+ *      searched for, only read when the on-disk shape unambiguously names it;
+ *  (d) the run's own job-start record (goal/model/budgetUsd/verdictType only
+ *      — a narrower, unsigned record, `resolved:false`);
+ *  else every spec-only field reads `'not recorded'`, never fabricated.
+ * `resolvedFrom` names which of these actually supplied the fields, shown in
+ * the page. `source`/`destination` are resolved SEPARATELY from the rest (any
+ * branch above may supply the goal/close/etc while carrying no source.json of
+ * its own) — from the source front door's manifest when `sourceNearSpine`
+ * finds one, else the run list's own recorded `patient` path for a `source`
+ * with no manifest, else `'not recorded'`. `success`/`guardrails`/`tools` come
+ * from the resolved SPEC only (a) (b) (c) — a job-start record and `none()`
+ * carry no close/writeScope/tools at all, so those stay `'not recorded'`.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunJob(runid: string, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * Handle one request against the read-only API + the page. Exported
+ * separately from {@link createPanelServer} so tests can drive it without a
+ * real listening socket where that is simpler (most path-safety/405 tests
+ * still go through a real socket, per the build spec).
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ home?: string, port: number }} opts
+ */
+export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
+    home?: string;
+    port: number;
+}): void;
+/**
+ * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
+ * non-zero-exit failure — this never falls back to another port (see file
+ * header). Resolves once actually listening; rejects on a bind error
+ * (including `EADDRINUSE`) with a `.port` field on the error for the
+ * caller's message.
+ * @param {{ port?: number, home?: string }} [opts]
+ * @returns {Promise<{ server: import('node:http').Server, port: number, close: () => Promise<void> }>}
+ */
+export function createPanelServer(opts?: {
+    port?: number;
+    home?: string;
+}): Promise<{
+    server: import("node:http").Server;
+    port: number;
+    close: () => Promise<void>;
+}>;
+/**
+ * `bareloop panel [--port N]` — the CLI entry (`src/cli.js` dispatch).
+ * Never picks a different port on collision (see file header): prints a
+ * loud, named error to stderr and returns 1.
+ * @param {string[]} argv
+ * @param {{ out: (s: string) => void, err: (s: string) => void, runlistHome?: string }} ctx
+ * @returns {Promise<number>}
+ */
+export function panelMain(argv: string[], ctx: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    runlistHome?: string;
+}): Promise<number>;
+/**
+ * A runid, as it appears in a URL path segment — never a raw filesystem
+ * path. `~` is included so a backfill-disambiguated runid (F197:
+ * `src/runlist.js`'s `backfillRuns`, e.g. `run~2` when two archived spines
+ * derive the same filename-based runid) is a legal, reachable id, never a
+ * 400.
+ */
+export const RUNID_RE: RegExp;
+/** Default bind port (PANEL-BUILD.md P1: checked free on the build machine, not guaranteed elsewhere — the server still fails loudly on collision, see {@link createPanelServer}). */
+export const DEFAULT_PORT: 4700;
+/**
+ * Soft-green was admitted at commit 30df0f9 (2026-08-18) — before that,
+ * `green` was the only admissible verdict type, so a run started before this
+ * moment that carries no `verdictType` at all (pre-F117 spine) really was
+ * deterministic; there was no other check type it could have been. Tighten-
+ * only, named so a future change is a deliberate, visible edit (item 3,
+ * 2026-09-25).
+ */
+export const SOFTGREEN_ADMITTED_ISO: "2026-08-18T00:00:00.000Z";
+export const DIED_MTIME_MS: number;
+/** The default/max page size for {@link getRunRounds} — tighten-only,
+ * named so a future change is a deliberate, visible edit (item 5,
+ * 2026-09-25). */
+export const ROUNDS_PAGE_DEFAULT: 50;
+export const ROUNDS_PAGE_MAX: 200;

package/types/planrun.d.ts

@@ -365,7 +365,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   it the deterministic name would collide with that very branch and the collision walk
  *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
  *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
- * @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 (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
  *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
  *   on the leg that pauses; it is never authored, never defaulted, and never inferred.
@@ -456,7 +456,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     resumeBranch?: string | null | undefined;
     humanRuling?: {
         decision: string;
-        text?: string;
+        text?: string | null;
     } | null | undefined;
     heldRuling?: {
         decision: string;