bareloop 0.27.0 → 0.28.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/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/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;

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/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;