bareloop 0.31.0 → 0.33.0

package/src/providerrows.js

@@ -0,0 +1,301 @@
+// PANEL-BUILD.md P4b — the Providers rows, driven by the keys file. NOTHING here is a
+// hardcoded provider list: one row exists per key in `~/.config/bareloop/.env` that has a
+// value; each row's Name / API shape / Base URL come from config.json `keys.<ENV NAME>`
+// (src/config.js), else the per-name defaults below. This is NOT a new provider table:
+// a row's API shape names an entry that already exists in `src/providers.js`
+// (`PROVIDER_TABLE`), and a row's Base URL is that provider's `baseUrl` option.
+//
+// This module is also THE one owner of "model -> key + shape + URL": Chat's Model menu,
+// the author doors and the run doors all resolve through `findRow` / `keyNameFor` /
+// `applyConfiguredKey` / `modelChoiceFor` below — no second lookup exists. Key VALUES
+// never pass through here — only names.
+import { resolveProvider } from './providers.js';
+import { readConfig, ConfigError } from './config.js';
+import { filledKeyNames } from './keysfile.js';
+
+/** 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 = Object.freeze([
+  Object.freeze({ id: 'anthropic-api', label: 'Anthropic', defaultUrl: 'https://api.anthropic.com/v1' }),
+  Object.freeze({ id: 'openai-api', label: 'OpenAI-compatible', defaultUrl: 'https://api.openai.com/v1' }),
+  Object.freeze({ id: 'gemini-api', label: 'Gemini', defaultUrl: '' }),
+]);
+
+/** The five empty lines a fresh keys file is created with, in this order. */
+export const PRESET_KEY_NAMES = Object.freeze(['ANTHROPIC_API_KEY', 'DEEPSEEK_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY', 'LOCAL_API_KEY']);
+
+/** 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';
+
+/**
+ * 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(raw) {
+  return raw === 'null' ? NO_KEY_PLACEHOLDER : raw;
+}
+
+/**
+ * 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) {
+  switch (envName) {
+    case 'ANTHROPIC_API_KEY': return { name: 'claude-sonnet-5', shape: 'anthropic-api', baseUrl: '' };
+    case 'DEEPSEEK_API_KEY': return { name: 'deepseek-flash', shape: 'openai-api', baseUrl: DEEPSEEK_BASE_URL };
+    case 'GEMINI_API_KEY': return { name: '', shape: 'gemini-api', baseUrl: '' };
+    case 'LOCAL_API_KEY': return { name: '', shape: 'openai-api', baseUrl: LOCAL_BASE_URL };
+    default: return { name: '', shape: 'openai-api', baseUrl: '' };
+  }
+}
+
+/**
+ * @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)
+ * @property {unknown} [priceInPerM] the customer's own price, USD per 1M input tokens — carried RAW
+ *   (present only when the config row names it); {@link ratesFor} is the one place that validates it
+ * @property {unknown} [priceOutPerM] the same, for output tokens
+ */
+
+/**
+ * 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 }) {
+  const saved = config?.keys && typeof config.keys === 'object' && !Array.isArray(config.keys) ? config.keys : {};
+  return filled.map((envName) => {
+    const d = defaultsFor(envName);
+    const s = saved[envName] && typeof saved[envName] === 'object' ? saved[envName] : {};
+    return {
+      envName,
+      name: typeof s.name === 'string' ? s.name : d.name,
+      provider: SHAPES.some((x) => x.id === s.shape) ? s.shape : d.shape,
+      baseUrl: typeof s.baseUrl === 'string' ? s.baseUrl : d.baseUrl,
+      ...(Object.hasOwn(s, 'priceInPerM') ? { priceInPerM: s.priceInPerM } : {}),
+      ...(Object.hasOwn(s, 'priceOutPerM') ? { priceOutPerM: s.priceOutPerM } : {}),
+    };
+  });
+}
+
+/**
+ * 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) {
+  if (home === undefined) return [];
+  return keyRows({ filled: filledKeyNames(home), config: readConfig({ home }).config });
+}
+
+/**
+ * @param {string} provider
+ * @returns {string} the shape's default host ('' = the vendor's own)
+ */
+export function defaultUrlOf(provider) {
+  return SHAPES.find((s) => s.id === provider)?.defaultUrl ?? '';
+}
+
+/**
+ * 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, baseUrl) {
+  const raw = (typeof baseUrl === 'string' && baseUrl.trim() !== '' ? baseUrl : defaultUrlOf(provider)).trim();
+  if (raw === '') return '';
+  try {
+    const u = new URL(raw);
+    return `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, '')}`;
+  } catch { return raw.replace(/\/+$/, ''); }
+}
+
+/**
+ * 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) {
+  return row.baseUrl.trim() !== '' ? row.baseUrl : defaultUrlOf(row.provider);
+}
+
+/**
+ * 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, { provider, baseUrl, model }) {
+  if (typeof provider !== 'string') return null;
+  const want = endpointOf(provider, baseUrl);
+  const same = rows.filter((r) => r.provider === provider && endpointOf(r.provider, r.baseUrl) === want);
+  if (same.length === 0) return null;
+  return (model ? same.find((r) => r.name === model) : undefined) ?? same[0];
+}
+
+/**
+ * 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, model) {
+  const r = model === '' ? undefined : rows.find((x) => x.name === model);
+  if (!r) return null;
+  return { provider: r.provider, ...(r.baseUrl.trim() !== '' ? { baseUrl: r.baseUrl.trim() } : {}), envName: r.envName, name: r.name };
+}
+
+/**
+ * The models Chat offers, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ id: string, envName: string, shape: string }[]}
+ */
+export function chatModels(rows) {
+  return rows.filter((r) => r.name !== '').map((r) => ({
+    id: r.name, envName: r.envName, shape: SHAPES.find((s) => s.id === r.provider)?.label ?? r.provider,
+  }));
+}
+
+/**
+ * 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, baseUrl, rows, model) {
+  const builtIn = resolveProvider(/** @type {string} */ (provider)).envKey;
+  const row = findRow(rows, { provider, baseUrl, model });
+  return row && row.envName !== builtIn
+    ? { name: row.envName, builtIn, chosen: true }
+    : { name: builtIn, builtIn, chosen: false };
+}
+
+/**
+ * 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, provider, baseUrl, rows, model) {
+  if (typeof provider !== 'string') return env;
+  let k;
+  try { k = keyNameFor(provider, baseUrl, rows, model); } catch { return env; } // unknown provider: resolveProvider's own named throw fires at its own door
+  const value = env[k.name];
+  if (!k.chosen && value !== 'null') return env;
+  return { ...env, [k.builtIn]: usableKey(value) };
+}
+
+/**
+ * A per-1M price for a readout: two decimals at least ($1.20), more when the number needs them so a
+ * tiny price never rounds to $0.00 or $0.01 ($0.006, $0.0004).
+ * @param {number} n USD per 1M tokens
+ * @returns {string}
+ */
+function perMoney(n) {
+  const shown = String(n);
+  if (!shown.includes('e') && (shown.split('.')[1] ?? '').length >= 2) return `$${shown}`;
+  if (shown.includes('e')) return `$${n.toFixed(12).replace(/0+$/, '').replace(/\.$/, '')}`;
+  return `$${n.toFixed(2)}`;
+}
+
+/**
+ * The one readout line for a resolved customer price, preview and run tail alike:
+ * `yours: in $0.006 / out $1.20 per 1M tokens (DEEPSEEK_API_KEY row)`.
+ * @param {{ inPerM: number, outPerM: number, envName: string }} price a {@link ratesFor} result
+ * @returns {string}
+ */
+export function priceReadout(price) {
+  return `yours: in ${perMoney(price.inPerM)} / out ${perMoney(price.outPerM)} per 1M tokens (${price.envName} row)`;
+}
+
+/**
+ * The customer's own price for the row a `(provider, baseUrl[, model])` identity belongs to —
+ * the SAME row match {@link keyNameFor} uses (`findRow`), so the price and the key always come
+ * from one row. `null` = no price set (the run keeps bare-agent's built-in guess, byte-identical
+ * to before). Both fields or neither, each a finite number >= 0, USD per 1M tokens; anything
+ * else throws `ConfigError` naming the row and field — a bad price never silently falls back to
+ * the guess. `rates` is bare-agent's `Loop({ rates })` shape (USD per 1K); `inPerM`/`outPerM`
+ * are what a readout prints.
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ rates: { in: number, out: number }, inPerM: number, outPerM: number, envName: string }|null}
+ */
+export function ratesFor(provider, baseUrl, rows, model) {
+  const row = findRow(rows, { provider, baseUrl, model });
+  if (!row) return null;
+  const hasIn = row.priceInPerM !== undefined;
+  const hasOut = row.priceOutPerM !== undefined;
+  if (!hasIn && !hasOut) return null;
+  if (hasIn !== hasOut) {
+    throw new ConfigError(`keys.${row.envName} sets ${hasIn ? 'priceInPerM' : 'priceOutPerM'} but not ${hasIn ? 'priceOutPerM' : 'priceInPerM'} — set both prices (USD per 1M tokens) or neither`);
+  }
+  for (const field of /** @type {const} */ (['priceInPerM', 'priceOutPerM'])) {
+    const v = row[field];
+    if (!(typeof v === 'number' && Number.isFinite(v) && v >= 0)) {
+      throw new ConfigError(`keys.${row.envName}.${field} must be a number, 0 or more (USD per 1M tokens) — fix it in config.json or remove both price lines`);
+    }
+  }
+  const inPerM = /** @type {number} */ (row.priceInPerM);
+  const outPerM = /** @type {number} */ (row.priceOutPerM);
+  return { rates: { in: inPerM / 1000, out: outPerM / 1000 }, inPerM, outPerM, envName: row.envName };
+}
+
+/**
+ * The price a judge's rounds are booked at. A price belongs to the MODEL's row: when the judge is
+ * the worker's own provider it calls the worker's endpoint, so a row on that endpoint NAMED for the
+ * judge's model prices it ({@link ratesFor}); a judge model that is absent or names no row there
+ * keeps the worker's price (the worker's row, or none = the guess). A different provider resolves
+ * on its own default endpoint, as before. A bad price on the resolved row throws like `ratesFor`.
+ * The judge's KEY is chosen elsewhere (`applyConfiguredKey`, by the worker's model), so the two
+ * can come from different rows — same provider + endpoint, judge model naming another row.
+ * @param {{ provider: string, model?: string|null }} judge
+ * @param {string|null|undefined} workerProvider
+ * @param {string|null|undefined} workerBaseUrl
+ * @param {ReturnType<typeof ratesFor>} workerPrice what the worker's own rounds are booked at
+ * @param {readonly KeyRow[]} rows
+ * @returns {ReturnType<typeof ratesFor>}
+ */
+export function judgeRatesFor(judge, workerProvider, workerBaseUrl, workerPrice, rows) {
+  if (judge.provider !== workerProvider) return ratesFor(judge.provider, undefined, rows, judge.model);
+  const want = endpointOf(judge.provider, workerBaseUrl);
+  const named = judge.model ? rows.some((r) => r.provider === judge.provider && endpointOf(r.provider, r.baseUrl) === want && r.name === judge.model) : false;
+  return named ? ratesFor(judge.provider, workerBaseUrl, rows, judge.model) : workerPrice;
+}

package/src/providers.js

@@ -396,7 +396,9 @@ export async function checkProviderReachable({
     return { reachable: true, modelListed, status: 'ok', note: null };
   } catch (/** @type {any} */ e) {
     const cls = e?.name === 'AbortError' ? 'timeout' : (e?.code || e?.name || 'network-error');
-    return { reachable: false, modelListed: null, status: String(cls), note: `request failed: ${cls}` };
+    // connection refused surfaces as fetch's bare TypeError ("fetch failed") — say it plainly
+    const refused = e?.name === 'TypeError' || e?.code === 'ECONNREFUSED' || e?.cause?.code === 'ECONNREFUSED';
+    return { reachable: false, modelListed: null, status: String(cls), note: refused ? `nothing answering at ${req.url}` : `request failed: ${cls}` };
   } finally {
     clearTimeout(timer);
   }

package/src/run.js

@@ -95,6 +95,11 @@ async function primitiveSmoke(workdir) {
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {{in: number, out: number}|null} [opts.rates] the CUSTOMER's own price for the worker's key row
+ *   (`ratesFor`, src/providerrows.js — USD per 1K tokens), resolved once by the door and handed to every
+ *   worker/planner Loop as bare-agent's `rates` (rounds then read `rateSource:'caller'`). Absent = the
+ *   built-in guess, exactly as before. A Loop-driven provider only: a native session reports its own cost.
+ * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's own key row
  * @param {string|null} [opts.judgeModel] SOFTGREEN — WHICH model the judge provider drives
  *   (PRD item 32.1), resolved by the CALLER (`resolveJudge`, src/judged.js) and passed
  *   through untouched. Travels with `judgeProvider`; absent, a judged stage stops as a
@@ -265,7 +270,7 @@ async function primitiveSmoke(workdir) {
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, draftSpentUsd = 0, draftSpendComplete = true, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, rates = null, judgeRates = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, draftSpentUsd = 0, draftSpendComplete = true, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -532,7 +537,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
       // hamr's ruling 2026-09-28 — ONE cap covers drafting + run: the run's
       // enforced ceiling is the signed `budgetUsd` (unchanged, still in the
       // spec hash) MINUS whatever drafting already spent on this job before

package/src/runlist.js

@@ -13,7 +13,7 @@
 // caller doesn't know one) — a relative path here would resolve differently
 // depending on who later reads the file. `via` says how the row was minted:
 // `'run-u'` (src/userrun.js, the person-path run), `'bundle'`
-// (src/cli.js:doRun, `bareloop run`), or `'backfill'` (`bareloop runs
+// (src/userrun.js's bundle door, `bareloop run`), or `'backfill'` (`bareloop runs
 // backfill`, reconstructed from an archived spine already on disk).
 //
 // SECRETS: a row carries only paths/ids/names — never a key, a prompt, or any
@@ -29,6 +29,7 @@
 
 import {
   existsSync, mkdirSync, appendFileSync, chmodSync, readdirSync, statSync,
+  readFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import {
@@ -57,7 +58,9 @@ export function runlistPath(home) {
 }
 
 /**
- * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill' }} RunRow
+ * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill', pid?: number, capUsd?: number }} RunRow
+ * `pid`/`capUsd` (optional; older and backfilled rows carry neither): the runner's process id and the
+ * leg's $ cap — what the monthly limit holds while that pid is a live bareloop runner (src/monthly.js).
  */
 
 /**
@@ -87,7 +90,8 @@ export function appendRun(row, opts = {}) {
   mkdirSync(home, { recursive: true, mode: 0o700 });
   if (existsSync(path)) {
     const { records } = parseJsonl(path);
-    if (records.some((r) => r && r.runid === row.runid)) {
+    // only RUN rows count: a settled/released event names the same runid for another purpose
+    if (records.some((r) => r && !r.type && r.runid === row.runid)) {
       return { appended: false, reason: 'duplicate-runid' };
     }
   }
@@ -96,18 +100,86 @@ export function appendRun(row, opts = {}) {
   return { appended: true };
 }
 
+/**
+ * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean }} RunEvent
+ * A claim's write-back, appended (never rewritten) beside the run rows. `settled` = the run's claim on the
+ * monthly limit is over (`spentUsd`/`spendComplete` are its final figure, `by` is WHO wrote it: the run itself
+ * at its `job-end`, or the next run that found its process gone, `reason: 'process gone'`). `released` = the
+ * claim was taken and then given back unspent, its run never started. The month's totals keep reading real
+ * spend off the spines; an event only releases the hold and records who wrote it.
+ */
+
+/**
+ * Append one {@link RunEvent}. Not locked: one short line, one append. THROWS on IO failure.
+ * @param {RunEvent} event
+ * @param {{ home?: string }} [opts]
+ * @returns {void}
+ */
+export function appendRunEvent(event, opts = {}) {
+  const path = runlistPath(opts.home);
+  mkdirSync(runlistHome(opts.home), { recursive: true, mode: 0o700 });
+  appendFileSync(path, `${JSON.stringify(event)}\n`);
+  try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
+}
+
 /**
  * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
  * parser). An absent file reads as an empty list, not an error: a fresh
- * install has never run `appendRun` yet.
+ * install has never run `appendRun` yet. FOLDS the file: `rows` are the RUNS
+ * only (an event line is never listed as a run, and a run whose claim was
+ * `released` never started, so it is not listed either); `events` are the
+ * write-backs, in file order.
  * @param {{ home?: string }} [opts]
- * @returns {{ rows: RunRow[], skipped: number }}
+ * @returns {{ rows: RunRow[], skipped: number, events: RunEvent[] }}
  */
 export function readRunList(opts = {}) {
   const path = runlistPath(opts.home);
-  if (!existsSync(path)) return { rows: [], skipped: 0 };
+  if (!existsSync(path)) return { rows: [], skipped: 0, events: [] };
   const { records, skipped } = parseJsonl(path);
-  return { rows: records, skipped };
+  // the FIRST settle for a runid is authoritative: two runs may both close the same dead claim, and the
+  // second note is a duplicate (a `released` line likewise); file order decides, later copies are ignored
+  const seen = new Set();
+  /** @type {RunEvent[]} */
+  const events = records.filter((r) => {
+    if (!r || (r.type !== 'settled' && r.type !== 'released')) return false;
+    const key = `${r.type}:${r.runid}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  const released = new Set(events.filter((e) => e.type === 'released').map((e) => e.runid));
+  const rows = records.filter((r) => r && !r.type && !released.has(r.runid));
+  return { rows, skipped, events };
+}
+
+/**
+ * Is this pid a live bareloop runner? `process.kill(pid, 0)` says whether the
+ * pid exists (EPERM = it exists, just not ours); `/proc/<pid>/cmdline` says whether it is a
+ * bareloop runner — a recycled pid that now belongs to some other program is NOT. A runner is
+ * a node executable (argv[0] is `node`, `nodejs`, `node22`, ...) with a later argv entry named
+ * `bareloop`, `bareloop.mjs`, `run-u.mjs` or `u-watchdog.mjs` (the basename, so the npm bin
+ * symlink counts), or a process whose argv[0] is itself one of those names. A non-node program
+ * that merely has such a name in its arguments (`nvim /x/bareloop`, `git -C /x/bareloop`) is not
+ * a runner. Residual, accepted: a recycled pid that is a node program with such an argument
+ * still reads as a runner. The wrong direction to err is "not a runner" on a real live run — it
+ * would release that run's cap. Where `/proc` is unreadable (not Linux, or not ours) the
+ * existence test alone decides: alive. The ONE spelling — the monthly limit's holds, and
+ * `--resume`'s old-pid check share it.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isLiveRunner(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); } catch (/** @type {any} */ e) { if (e?.code !== 'EPERM') return false; }
+  /** @type {string|null} */
+  let cmdline = null;
+  try { cmdline = readFileSync(`/proc/${pid}/cmdline`, 'utf8'); } catch { /* no /proc, or not ours */ }
+  if (cmdline === null) return true;
+  const names = ['bareloop', 'bareloop.mjs', 'run-u.mjs', 'u-watchdog.mjs'];
+  const [argv0 = '', ...rest] = cmdline.split('\0');
+  const first = basename(argv0);
+  if (names.includes(first)) return true;
+  return first.startsWith('node') && rest.some((a) => names.includes(basename(a)));
 }
 
 /**
@@ -128,6 +200,19 @@ function runidForSpine(spinePath) {
   return resolveSiblings(spinePath).runId;
 }
 
+// DIED (hamr's ruling B, 2026-09-25): a run with no `job-end` never shares
+// the failed glyph — [✗] stays reserved for a run whose close/arbiter
+// actually rendered a "no" (a real result). A spine that just stops, with
+// no ending ever recorded, is a DIFFERENT fact (killed, crashed, or the
+// machine slept) and gets its own [?] glyph. The distinguishing signal is
+// the spine FILE's own mtime, never wall-clock "now minus job-start" (a
+// resumed/paused run can legitimately sit quiet for a long time without
+// having died): still fresh (written to within this window) reads as the
+// existing `running` [▶] state; older than this reads as died. Tighten-only,
+// named so a future change is a deliberate, visible edit. Lives here (not in
+// the panel) because the monthly limit reads the same rule (src/monthly.js).
+export const DIED_MTIME_MS = 10 * 60 * 1000;
+
 // A backfill scan of a real patients directory can be arbitrarily deep
 // (person-path runs archive several levels down: `<dir>/<proj>/out/
 // source-<x>/<proj>-bareloop/u-<id>.jsonl`, 4 levels under the dir a person

package/src/source.js

@@ -441,11 +441,15 @@ async function fetchOnce(url, timeoutMs) {
  * never hands a repo source's destination to `copyOut` — wiring it into
  * `writeScope` is M3/M4's job, not this one.
  * @param {{source: string, into: string, destination?: string,
- *   fetchTimeoutMs?: number}} args `fetchTimeoutMs` is test-only — production
- *   callers omit it and get `PROVIDER_TIMEOUT_MS`.
+ *   fetchTimeoutMs?: number, afterScan?: () => (void|Promise<void>)}} args
+ *   `fetchTimeoutMs` is test-only — production callers omit it and get
+ *   `PROVIDER_TIMEOUT_MS`. `afterScan` is a test seam too: called exactly once,
+ *   after the secret scan finished and before the freeze loop re-reads any
+ *   file's bytes, so a test can swap a file inside that window
+ *   deterministically. Production never sets it; absent, behaviour is unchanged.
  * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: object}|SourceRefusal>}
  */
-export async function prepareSource({ source, into, destination, fetchTimeoutMs = PROVIDER_TIMEOUT_MS }) {
+export async function prepareSource({ source, into, destination, fetchTimeoutMs = PROVIDER_TIMEOUT_MS, afterScan }) {
   const intoAbs = resolve(into);
   if (existsSync(intoAbs)) {
     return refuse('into-exists', `${intoAbs} already exists — a source door writes a FRESH tree, never reuses one (the export worktree rule)`);
@@ -674,6 +678,7 @@ export async function prepareSource({ source, into, destination, fetchTimeoutMs
   // (verified: 0o755 in, 0o755 out; a plain `writeFile` defaults to 0o644),
   // so the replacement chmod's the destination from a fresh `stat` to keep
   // that behaviour unchanged.
+  if (afterScan) await afterScan();
   for (let i = 0; i < frozen.files.length; i += 1) {
     const f = frozen.files[i];
     const dest = join(treeDir, treeRel(f.rel));