bareloop 0.30.0 → 0.32.0

package/types/providerrows.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The key value to hand a provider: the `null` marker becomes the placeholder, anything else
+ * passes through unchanged.
+ * @template {string|undefined} T
+ * @param {T} raw
+ * @returns {T|string}
+ */
+export function usableKey<T extends string | undefined>(raw: T): T | string;
+/**
+ * What a key with no saved entry shows. Any name not listed is OpenAI-compatible with a
+ * blank URL and a blank Name.
+ * @param {string} envName
+ * @returns {{ name: string, shape: string, baseUrl: string }}
+ */
+export function defaultsFor(envName: string): {
+    name: string;
+    shape: string;
+    baseUrl: string;
+};
+/**
+ * @typedef {object} KeyRow
+ * @property {string} envName the key variable NAME (read-only label; never a value)
+ * @property {string} name the model id Chat uses ('' = not offered in Chat)
+ * @property {string} provider the `src/providers.js` table entry (the API shape's id)
+ * @property {string} baseUrl the saved Base URL ('' = the shape's default host)
+ */
+/**
+ * The rows: one per name in `filled`, saved entry over defaults.
+ * @param {{ filled: readonly string[], config: Record<string, any> }} src
+ * @returns {KeyRow[]}
+ */
+export function keyRows({ filled, config }: {
+    filled: readonly string[];
+    config: Record<string, any>;
+}): KeyRow[];
+/**
+ * The rows for a keys home. `undefined` home (a door that skipped the keys file) = no
+ * rows, so nothing resolves through the file and the provider's built-in variable stands.
+ * @param {string|undefined} home
+ * @returns {KeyRow[]}
+ */
+export function rowsForHome(home: string | undefined): KeyRow[];
+/**
+ * @param {string} provider
+ * @returns {string} the shape's default host ('' = the vendor's own)
+ */
+export function defaultUrlOf(provider: string): string;
+/**
+ * An endpoint in comparable form: blank = the shape's default host; scheme + host lower-cased,
+ * trailing slashes dropped.
+ * @param {string} provider
+ * @param {string|null|undefined} baseUrl
+ * @returns {string}
+ */
+export function endpointOf(provider: string, baseUrl: string | null | undefined): string;
+/**
+ * The URL a row talks to, for display ('' = the vendor's own host, which has no URL to show).
+ * @param {KeyRow} row
+ * @returns {string}
+ */
+export function shownUrl(row: KeyRow): string;
+/**
+ * Which row a `(provider, baseUrl[, model])` identity belongs to: the rows on that shape and
+ * endpoint; when several share it, the one whose Name is the model, else the first.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} id
+ * @returns {KeyRow|null}
+ */
+export function findRow(rows: readonly KeyRow[], { provider, baseUrl, model }: {
+    provider?: string | null;
+    baseUrl?: string | null;
+    model?: string | null;
+}): KeyRow | null;
+/**
+ * What Chat's Model menu offers and how a pick resolves: the row whose Name is the model
+ * (a blank Name is never offered). `baseUrl` is absent when blank, exactly as a spec omits it.
+ * @param {readonly KeyRow[]} rows
+ * @param {string} model
+ * @returns {{ provider: string, baseUrl?: string, envName: string, name: string }|null}
+ */
+export function modelChoiceFor(rows: readonly KeyRow[], model: string): {
+    provider: string;
+    baseUrl?: string;
+    envName: string;
+    name: string;
+} | null;
+/**
+ * The models Chat offers, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ id: string, envName: string, shape: string }[]}
+ */
+export function chatModels(rows: readonly KeyRow[]): {
+    id: string;
+    envName: string;
+    shape: string;
+}[];
+/**
+ * The key variable NAME a job on `(provider, baseUrl[, model])` reads: the matching row's
+ * variable, else the provider's built-in one (byte-identical to before for anything no row
+ * claims).
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ name: string, builtIn: string, chosen: boolean }}
+ */
+export function keyNameFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
+    name: string;
+    builtIn: string;
+    chosen: boolean;
+};
+/**
+ * The env a door hands to provider construction, with the matching row's key variable
+ * standing in for the provider's built-in one: `env[builtIn] = env[row.envName]` (the `null`
+ * no-key marker becomes {@link NO_KEY_PLACEHOLDER}). A copy — never mutates the input.
+ * No matching row and no marker = the env unchanged.
+ * @param {Record<string,string|undefined>} env
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {Record<string,string|undefined>}
+ */
+export function applyConfiguredKey(env: Record<string, string | undefined>, provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): Record<string, string | undefined>;
+/** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
+export const DEEPSEEK_BASE_URL: "https://api.deepseek.com/v1";
+/**
+ * The API shapes the dropdown offers. `id` is the `src/providers.js` table name;
+ * `defaultUrl` is the host a blank Base URL means ('' = the vendor's own, unshown).
+ * @type {readonly {id: string, label: string, defaultUrl: string}[]}
+ */
+export const SHAPES: readonly {
+    id: string;
+    label: string;
+    defaultUrl: string;
+}[];
+/** The five empty lines a fresh keys file is created with, in this order. */
+export const PRESET_KEY_NAMES: readonly string[];
+/** A local server's default endpoint: Ollama's OpenAI-compatible host (LM Studio / llama.cpp: change the URL). */
+export const LOCAL_BASE_URL: "http://127.0.0.1:11434/v1";
+/**
+ * A key line whose value is the word `null` is SET and means "no real key": the row exists and
+ * the provider is handed this harmless stand-in (local servers ignore auth). It is not a
+ * secret and is never shown or logged as a key.
+ */
+export const NO_KEY_PLACEHOLDER: "no-key-needed";
+export type KeyRow = {
+    /**
+     * the key variable NAME (read-only label; never a value)
+     */
+    envName: string;
+    /**
+     * the model id Chat uses ('' = not offered in Chat)
+     */
+    name: string;
+    /**
+     * the `src/providers.js` table entry (the API shape's id)
+     */
+    provider: string;
+    /**
+     * the saved Base URL ('' = the shape's default host)
+     */
+    baseUrl: string;
+};

package/types/providers.d.ts

@@ -98,6 +98,40 @@ export function buildRunnerProviders({ providerName, apiKey, model, tierModels,
     providerFor: (tier: string) => any;
     judgeProvider: any;
 };
+/**
+ * $0 reachability check: a GET against `providerName`'s own models-list
+ * endpoint, server-side, with the key in a header — NEVER a completion
+ * request, so it never spends a token (PANEL-BUILD.md P3 build item 7: "the
+ * person must get feedback BEFORE drafting if the chosen model can't
+ * work"). Reused, unmodified, by the panel's model-readiness route today
+ * (`src/panel/authorroutes.js`) and by the future Settings providers
+ * table's own "test" column (PANEL-BUILD.md P4) — ONE function, not two
+ * hand-typed copies of the same probe.
+ *
+ * NEVER returns the key, never logs it — the key only ever appears in a
+ * request header sent straight to the provider's own host.
+ * @param {object} o
+ * @param {string} o.providerName
+ * @param {string} o.apiKey
+ * @param {string} [o.model] when given, the response is also checked for this model id
+ * @param {string} [o.baseUrl]
+ * @param {typeof fetch} [o.fetchImpl] TEST SEAM — defaults to the real global `fetch`
+ * @param {number} [o.timeoutMs] defaults to 4000 — a flaky endpoint must never hang the caller
+ * @returns {Promise<{reachable: boolean, modelListed: boolean|null, status: string, note: string|null}>}
+ */
+export function checkProviderReachable({ providerName, apiKey, model, baseUrl, fetchImpl, timeoutMs, }: {
+    providerName: string;
+    apiKey: string;
+    model?: string | undefined;
+    baseUrl?: string | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<{
+    reachable: boolean;
+    modelListed: boolean | null;
+    status: string;
+    note: string | null;
+}>;
 /**
  * The launch-time warning lines for an ADMITTED-PENDING-PROBE provider, or
  * `null` when the provider has paid for its own end-to-end probe (and for an

package/types/replay.d.ts

@@ -89,6 +89,8 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
     stopReason: string | null;
     spentUsd: any;
     spendComplete: boolean;
+    draftSpentUsd: any;
+    draftSpendComplete: boolean | null;
     floorReasons: string[];
     transportRetryCount: number;
     transportRetriesOutsideWindows: number;
@@ -239,6 +241,35 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, audi
     memoryCache: any;
     skipped: number;
 };
+/**
+ * hamr's ruling 2026-09-28 ("one cap covers drafting + run") — the ONE
+ * spend display for a run that may carry a drafting share, so every surface
+ * that shows a run's money (the CLI's own `spent` line, the panel's Run tab
+ * summary/counters, the Runs list row, the Audit header, the Job tab) reads
+ * the same string rather than each hand-composing its own. `spendCore` is
+ * already-formatted text (`money(...)`, or a `died`/floor line's "at least
+ * $X") — this only decides whether to append the `(<draft> drafting)`
+ * clause and the `of $<cap>` tail, never re-derives the money itself.
+ * Unchanged (`spendCore` alone, or `spendCore of $cap`) when there is no
+ * drafting share — a run without one prints exactly what it always did.
+ *
+ * hamr's ruling 2026-09-28 (2nd addendum) — an INCOMPLETE drafting fold
+ * (`draftSpendComplete === false`) is a floor, not a total, and F6's rule
+ * ("unpriced is never free, a floor never dresses as exact") applies here
+ * exactly as it does to `spendCore` itself: the drafting clause reads `at
+ * least $X drafting`, and because a reader summing the two figures would
+ * otherwise take the LEADING number as exact too, `spendCore` itself also
+ * gains the `at least ` prefix — unless it already carries one (a `died`
+ * floor, or an already-prefixed caller), never doubled.
+ * @param {string} spendCore already-formatted spend text (e.g. `$3.71` or `at least $2.00`)
+ * @param {number|null} draftSpentUsd the drafting share, or null when there isn't one
+ * @param {number|null} [budgetUsd] the signed cap, appended as `of $X.XX` when given
+ * @param {boolean|null} [draftSpendComplete] whether the drafting fold above was EXACT;
+ *   `null`/`undefined`/`true` all read as exact (never a new enum value elsewhere) —
+ *   only an explicit `false` triggers the floor wording.
+ * @returns {string}
+ */
+export function moneyWithDraft(spendCore: string, draftSpentUsd: number | null, budgetUsd?: number | null, draftSpendComplete?: boolean | null): string;
 /**
  * Render a {@link replayRun} summary as one printable page: a header block
  * (goal/shape/signed/branch/outcome/spent), a timeline (steps or iterations,

package/types/replayio.d.ts

@@ -42,7 +42,8 @@ export function resolveSiblings(spinePath: string): {
  * 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]
+ * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean,
+ *   auditPathOverride?: 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
@@ -50,6 +51,15 @@ export function resolveSiblings(spinePath: string): {
  *   `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.
+ *   `auditPathOverride` (build item 7, 2026-09-28): when a caller has ALREADY
+ *   resolved the real audit path through the one shared resolver
+ *   (`src/panel/server.js`'s `resolveAuditPathForRow`, which also covers a
+ *   still-LIVE run's during-run sidecar location — this function's own
+ *   `resolveSiblings` call only ever finds the FINISHED-run convention), it
+ *   passes that path here (`null` included) instead of letting this
+ *   function re-derive a finished-only path on its own. `undefined` (the
+ *   default) keeps the original resolveSiblings-only behaviour — every
+ *   existing caller is unaffected.
  * @returns {ReturnType<typeof replayRun>}
  */
 export function replayOne(spinePath: string, opts?: {
@@ -58,6 +68,7 @@ export function replayOne(spinePath: string, opts?: {
         skipped: number;
     };
     skipAudit?: boolean;
+    auditPathOverride?: string | null;
 }): ReturnType<typeof replayRun>;
 /**
  * List every spine found directly in `dir` (not recursive — same as the

package/types/run.d.ts

@@ -73,6 +73,29 @@
  *   load gate refuses one: a refusal returns the distinct `recipe-stale` outcome with zero
  *   spend rather than silently drafting cold, because starting a paid run on a decision
  *   nobody made is the same class of error as widening a cap to manufacture a green.
+ * @param {number} [opts.draftSpentUsd=0] hamr's ruling 2026-09-28 ("one cap covers
+ *   drafting + run") — money the AUTHORING pipeline (`authorCloseForJob`/
+ *   `prepareSigning`, run under the SAME signed `budgetUsd` as its ceiling) already
+ *   spent on THIS job before it was ever signed. The signed `budgetUsd` stays the
+ *   one number in the spec hash; this shrinks the RUN's own enforced ceiling by
+ *   what drafting already took, so the two phases never spend more than the one
+ *   cap together. Deliberately NOT `priorSpentUsd` — that key means "a previous
+ *   ATTEMPT of this same run died and folded its spend forward" and is read by
+ *   `readResume`/`replay.js`'s `resumed` flag; a drafting spend is not a resume and
+ *   must never make an ordinary first run of a job read as one. It is also never
+ *   folded into `spentUsd` (the run's own ledger, cumulative-so-far and what a
+ *   resume's `priorSpentUsd` seeds) or into `engagementSpentUsd` — drafting is a
+ *   DIFFERENT phase's spend, reported beside the run's, never inside it. A garbage
+ *   value (non-finite, negative) is read as 0, belted exactly like `priorSpentUsd`.
+ * @param {boolean} [opts.draftSpendComplete=true] hamr's ruling 2026-09-28 — was the
+ *   `draftSpentUsd` fold above EXACT? The authoring pipeline's own metered-call list can
+ *   go unpriced (F6) exactly like a resumed attempt's can, and the unknown does not heal
+ *   by folding forward. A NEW field beside `draftSpentUsd`, never a new state inside
+ *   `spendComplete`/`priorSpendComplete` — those answer "is THIS run's own ledger exact,"
+ *   this answers "was the OTHER phase's ledger exact," and the two must never merge into
+ *   one flag or a floor drafting spend could read as an exact run. Read only when
+ *   `draftSpentUsd` itself is emitted; a garbage value is read as `true` (the same belt
+ *   `priorSpendComplete` gets — an unreadable flag never manufactures a false floor).
  * @param {number} [opts.priorSpentUsd=0] RESUME (module C) — money a PREVIOUS, killed
  *   attempt of this same try already spent. It seeds the ledger, so the restarted
  *   attempt runs under the REMAINDER of the signed `budgetUsd` and the terminal
@@ -181,7 +204,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, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, 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, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -201,6 +224,8 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     closeTimeoutMs?: number | undefined;
     closeDir?: string | null | undefined;
     bridge?: unknown;
+    draftSpentUsd?: number | undefined;
+    draftSpendComplete?: boolean | undefined;
     priorSpentUsd?: number | undefined;
     priorSpendComplete?: boolean | undefined;
     priorWallMs?: number | undefined;

package/types/runlist.d.ts

@@ -101,6 +101,7 @@ export function backfillRuns(dir: string, opts?: {
  * @returns {string}
  */
 export function formatRunRow(row: RunRow): string;
+export const DIED_MTIME_MS: number;
 export const MAX_BACKFILL_DEPTH: 6;
 export type RunRow = {
     at: string;

package/types/userrun.d.ts

@@ -43,6 +43,11 @@ export function answerDoor(runId: string, decision: {
 export function main(argv: string[], deps?: Deps): Promise<number>;
 export type Deps = {
     env?: Record<string, string | undefined> | undefined;
+    /**
+     * P4a — a test seam naming the home whose `.env` keys file is loaded
+     * even when `env` is injected; production never sets it.
+     */
+    keysHome?: string | undefined;
     out?: ((s: string) => void) | undefined;
     err?: ((s: string) => void) | undefined;
     /**
@@ -92,6 +97,21 @@ export type RunOpts = {
      * the raw `--scout` value (`on`/`off`), or null for the default
      */
     scout?: string | null | undefined;
+    /**
+     * the raw `--draft-spent-usd` value (hamr's
+     * ruling 2026-09-28, "one cap covers drafting + run"), or null when the job never
+     * drafted through the panel/`bareloop author`. Parsed and validated in `execute`
+     * (finite, >= 0, else refused) — never coerced silently, the same param-guard
+     * class `--read-shim`/`--scout` already are.
+     */
+    draftSpentUsd?: string | null | undefined;
+    /**
+     * the raw `--draft-spend-incomplete` presence-
+     * flag (hamr's ruling 2026-09-28, 2nd addendum) — whether the drafting fold above was a
+     * FLOOR, never an exact figure. A new field beside `draftSpentUsd`, same param-guard
+     * class, no value to misread.
+     */
+    draftSpendIncomplete?: boolean | undefined;
     /**
      * a bridge registry directory
      */
@@ -129,6 +149,8 @@ export type RunCtx = {
     model: string | null;
     readShim: string | null;
     scout: string | null;
+    draftSpentUsd: string | null;
+    draftSpendIncomplete: boolean;
     registry: string | null;
     workflow: string | null;
     approve: string | null;