bareloop 0.14.0 → 0.15.0

package/src/run.js

@@ -17,6 +17,7 @@ import { validateJob, jobSpecHash, checkApproval } from './job.js';
 import { runPlan } from './planrun.js';
 import { SMOKE_STORE, resolveHumanRuling } from './kinds.js';
 import { readShimArm } from './readshim.js';
+import { codeVersion } from './codeversion.js';
 
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 
@@ -303,6 +304,19 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   emit('job-start', {
     job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd,
     shape: 'plan', goal: job.goal,
+    // F117: replay reads these; report-only. `verdictType` is a REQUIRED spec
+    // field (src/job.js:552 reds `missing-required` before this line is ever
+    // reached), so it is always a real validated string here, never a
+    // fabricated default. `model` rides along only when the shell-owned
+    // provider binding actually carries one (bare-agent's Loop reads
+    // `baseProvider.model` directly — src/planrun.js:76's own comment); a
+    // native/clipipe call path with no such provider omits the field rather
+    // than guessing.
+    verdictType: job.verdictType,
+    ...(typeof provider?.model === 'string' ? { model: provider.model } : {}),
+    // F118: replay reads this; report-only. `dirty` is deliberately omitted —
+    // it can't be known without a shell, and null = unknown, never faked.
+    code: (() => { const { version, sha } = codeVersion(); return { version, sha }; })(),
     // RESUME (v1.46 §3) — the DECLARED fold, the `try-start` precedent one level
     // down. A reader reconstructing a chain of resumes must add only each attempt's
     // OWN new rounds; without this record the second resume of a halted run would

package/types/codeversion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Report-only stamp of the bareloop code this process is running as. Never
+ * throws — an unreadable package.json or absent `.git` reads as `null`,
+ * honestly, rather than crashing a caller over a report field.
+ * @returns {{ version: string|null, sha: string|null, dirty: null }}
+ */
+export function codeVersion(): {
+    version: string | null;
+    sha: string | null;
+    dirty: null;
+};
+/**
+ * First 8 characters of a sha, or null. Mirrors the short-sha convention
+ * `replay.js` already uses for `specHash` (`s.specHash.slice(0, 8)`).
+ * @param {string|null|undefined} sha
+ * @returns {string|null}
+ */
+export function shortSha(sha: string | null | undefined): string | null;

package/types/index.d.ts

@@ -23,4 +23,6 @@ export { scrubRaw, RAW_PERSIST_MAX, RAW_TRIM_MARKER } from "./text.js";
 export { authorClose, authorPrompt, declarationSchema, makeLoopGenerate, MAX_REVISIONS, QUESTION_SETS, GREEN_QUESTIONS, SOFTGREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor } from "./authorflow.js";
 export { validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade, DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS, HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS } from "./declaredclose.js";
 export { runBehaviour, formatBehaviour } from "./behaviour.js";
+export { replayRun, formatReplay } from "./replay.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";
+export { PROMPT_REGISTERS, isPromptFile } from "./promptregisters.js";

package/types/ledger.d.ts

@@ -103,6 +103,20 @@ export const LEDGER_CLASSES: readonly string[];
  * reads as a GUESS rather than as vouched. The fail-safe direction, by construction.
  */
 export const VOUCHED_RATE_SOURCES: readonly string[];
+/** The spend records a run's money is read from. `worker-round` and `judge-round` are the
+ * ACCOUNTED types — exactly `ACCOUNTED_ROUND_TYPES` in src/run.js, which is the ledger that
+ * enforces the budget (F12). `judge-round` is the softgreen rung's judged floor: the first
+ * spend a CLOSE has ever had, and a provenance readout that skipped it would be blind to the
+ * one seam whose rate nobody has audited. `worker-turn` is the native surface's per-turn
+ * attribution — unpriced by design, included so the readout covers every metering row the
+ * plan flow writes rather than only the ones carrying money. The attempt-level totals
+ * (`worker-result`, `worker-plan`) are ECHOES of these same rounds and are excluded, for
+ * the same reason the ledger in run.js excludes them: counting them double-counts.
+ *
+ * Re-spelled rather than imported (src/run.js imports this module's siblings and a cycle
+ * buys nothing here) — `tests/ledger.test.js` asserts the two spellings agree, because a
+ * spend-slicing instrument that misses a writer is the F45 class this list exists to avoid. */
+export const SPEND_RECORD_TYPES: readonly string[];
 export type ProvenanceBucket = {
     rounds: number;
     usd: number;

package/types/promptregisters.d.ts

@@ -0,0 +1,31 @@
+/**
+ * True when `path` names one of the inventoried prompt-register files. Accepts
+ * either a repo-root-relative path (`src/tools.js`) or an absolute/relative
+ * path ending in one (`/home/x/bareloop/src/tools.js`, `./src/tools.js`) — git
+ * hands the check root-relative paths, but a caller working from an absolute
+ * path should not have to strip the prefix itself.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isPromptFile(path: string): boolean;
+/**
+ * One entry in the prompt-register inventory: a file known to carry
+ * model-facing prompt/instruction text, and the name(s) that live there for a
+ * human reading this file. `name` may point at a named const OR at a function
+ * that builds a prompt inline (e.g. `scoutPrompt()`) — the check only ever
+ * keys on `file`.
+ * @typedef {{file: string, name: string}} PromptRegisterEntry
+ */
+/** @type {ReadonlyArray<PromptRegisterEntry>} */
+export const PROMPT_REGISTERS: ReadonlyArray<PromptRegisterEntry>;
+/**
+ * One entry in the prompt-register inventory: a file known to carry
+ * model-facing prompt/instruction text, and the name(s) that live there for a
+ * human reading this file. `name` may point at a named const OR at a function
+ * that builds a prompt inline (e.g. `scoutPrompt()`) — the check only ever
+ * keys on `file`.
+ */
+export type PromptRegisterEntry = {
+    file: string;
+    name: string;
+};

package/types/replay.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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
+ * array are skipped and counted, never thrown on.
+ *
+ * A step id can recur (a replan re-executes the same step): `steps[].occurrence`
+ * is 1 for that id's first step-start..step-end pair, 2 for its second, etc.
+ * Every field on an occurrence — rounds, toolCalls, checks, treeChanged, wallMs,
+ * spentUsd — is scoped to records strictly between ITS OWN start/end `seq`,
+ * never pooled across every occurrence sharing the id.
+ *
+ * A run whose spine carries no `step-start` at all (the plan's only step was
+ * already-green-skipped on a resumed leg, or a genuinely legacy loop-only
+ * shape) has no STEPS timeline to build — `timelineKind` reads `'iterations'`
+ * and `iterations[]` is populated from `iteration-start`/`close-verdict`/
+ * `run-end`/`escalation` instead. `steps`/`iterations` are never both
+ * populated: exactly one is non-empty, selected by `timelineKind`.
+ *
+ * @param {any[]} spineEvents parsed records from `u-<id>.jsonl`
+ * @param {any[]} [auditEvents] parsed records from the sibling `-gate-audit.jsonl`
+ * @param {{runId?: string|null}} [opts] `runId`: caller-supplied (the spine
+ *   carries no run-id field of its own — see the file header)
+ */
+export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
+    runId?: string | null;
+}): {
+    runId: string | null;
+    job: any;
+    verdictType: any;
+    model: any;
+    code: {
+        version: any;
+        sha: any;
+    } | null;
+    goal: any;
+    lastEscalation: any;
+    budgetUsd: any;
+    specHash: any;
+    branch: any;
+    outcome: any;
+    stopReason: string | null;
+    spentUsd: any;
+    spendComplete: boolean;
+    floorReasons: string[];
+    transportRetryCount: number;
+    transportRetriesOutsideWindows: number;
+    wallMs: number | null;
+    chainClock: {
+        source: "wall-halt" | "wall-clock";
+        elapsedMs: number;
+        requestedMs: number | null;
+        enforcedMs: number | null;
+        bounded: boolean;
+    } | null;
+    resumed: boolean;
+    resumeSeed: {
+        phase: any;
+        completed: any;
+        skipping: any;
+        divergence: any;
+    } | null;
+    thisFileSpend: {
+        value: any;
+        source: "engagementSpentUsd" | "summed rounds";
+        totalRounds: number;
+        unpricedRounds: number;
+    };
+    spendMismatch: {
+        spentUsd: any;
+        thisFileUsd: any;
+        diffUsd: number;
+    } | null;
+    timelineKind: "steps" | "iterations";
+    steps: {
+        checks: {
+            passed: number;
+            failed: number;
+        };
+        treeChanged: boolean;
+        rounds: number;
+        toolCalls: number;
+        wallMs: number | null;
+        spentUsd: number | null;
+        unpricedRounds: number;
+        tripped: {
+            category: any;
+            detail: string | null;
+        } | null;
+        transportRetries: {
+            count: number;
+            label: string;
+            error: string | null;
+        } | null;
+        id: any;
+        occurrence: any;
+        outcome: any;
+    }[];
+    iterations: {
+        rounds: number;
+        toolCalls: number;
+        wallMs: number | null;
+        spentUsd: number | null;
+        unpricedRounds: number;
+        tripped: {
+            category: any;
+            detail: string | null;
+        } | null;
+        transportRetries: {
+            count: number;
+            label: string;
+            error: string | null;
+        } | null;
+        iteration: any;
+        verdict: any;
+        boundary: any;
+        closeStage: {
+            verdict: any;
+            stages: any;
+        } | null;
+    }[];
+    replans: any;
+    close: {
+        source: "close-verdict" | "outer-close";
+        iteration: number | null;
+        verdict: string | null;
+        stages: any[] | null;
+    } | null;
+    ending: {
+        record: any;
+        before: any[];
+        escalation: any;
+    };
+    behaviour: {
+        totalCalls: number;
+        byTool: Record<string, number>;
+        denied: number;
+        uniquePaths: number;
+        repeats: number;
+        repeatPct: number | null;
+    };
+    memoryCache: any;
+    skipped: number;
+};
+/**
+ * Render a {@link replayRun} summary as one printable page: a header block
+ * (goal/shape/signed/branch/outcome/spent), a timeline (steps or iterations,
+ * whichever the spine has), the CLOSE section (never omitted), the ending
+ * (last record + 3 before it, plus an out-of-window escalation), the
+ * behaviour block, and the MEMORY-CACHE line (always printed — `not armed on
+ * this run` when there is no record, never silently absent).
+ * @param {ReturnType<typeof replayRun>} summary
+ * @returns {string}
+ */
+export function formatReplay(summary: ReturnType<typeof replayRun>): string;
+/**
+ * One `--all` row's raw field strings for one real spine:
+ * `id  job  shape  outcome  spend  wall  steps  reason`. `reason` is
+ * `category — <first clause of detail, cut at 60 chars>` off the last
+ * escalation — never the generic `decision` prose. `-` on a green row;
+ * `no job-end (killed mid-run)` when the spine never reached a `job-end` at
+ * all (outcome itself is `null`) — a distinct, named case, not folded into
+ * the ordinary escalation reason.
+ * @param {ReturnType<typeof replayRun>} summary
+ * @returns {{id: string, resumed: boolean, job: string, shape: string, class: string, model: string, outcome: string, hadTransportRetries: boolean, spend: string, wall: string, steps: string, reason: string}}
+ */
+export function summarizeForAllLine(summary: ReturnType<typeof replayRun>): {
+    id: string;
+    resumed: boolean;
+    job: string;
+    shape: string;
+    class: string;
+    model: string;
+    outcome: string;
+    hadTransportRetries: boolean;
+    spend: string;
+    wall: string;
+    steps: string;
+    reason: string;
+};
+/**
+ * Render every row {@link summarizeForAllLine} built for one directory's
+ * spines as a fixed-column, aligned table WITH a header row (plus any
+ * `<name>  not-a-spine` lines interleaved at their original position — those
+ * are not part of the aligned columns, since a filename carries no outcome/
+ * spend/wall of its own). Never CSV: columns are padded, not delimited.
+ * @param {Array<{kind: 'spine', row: ReturnType<typeof summarizeForAllLine>}|{kind: 'not-a-spine', name: string}>} entries
+ * @returns {string}
+ */
+export function formatAllLines(entries: Array<{
+    kind: "spine";
+    row: ReturnType<typeof summarizeForAllLine>;
+} | {
+    kind: "not-a-spine";
+    name: string;
+}>): string;