bareloop 0.27.0 → 0.29.0

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,141 @@
+/**
+ * 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;
+    /**
+     * F196 — a test seam for `appendRun`'s
+     * (src/runlist.js) `home` override, the same shape `deps.provider` already
+     * is. Production never sets it; `appendRun` falls through to its own
+     * `os.homedir()`-based default.
+     */
+    runlistHome?: string | undefined;
+};
+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;
+};