bareloop 0.33.0 → 0.35.0

package/src/draftspend.js

@@ -0,0 +1,82 @@
+// Drafting spend that never became a run (self-review 2026-10-05, hamr's ruling A).
+//
+// A panel authoring session pays for model calls (survey, declaration, confirm turn) BEFORE any run exists.
+// That spend rode only in memory (`state.draftSpentUsd`) and reached disk when the session was signed and run
+// (`--draft-spent-usd` -> the run's spine). Abandon, a refusal, or a panel restart lost it, while the monthly
+// limit and the Money tab never counted it. So the session writes `<session dir>/draft-spend.json` after EVERY
+// metered call (one owner: the session's `onCall`, src/panel/authorsession.js), and the money readers
+// (`readLegs`, src/monthly.js) add every session folder that carries one and NEVER became a run.
+//
+// "Became a run" = some run-list row's `spine` or `patient` path sits inside that session's folder: a signed run
+// already carries its drafting spend through `--draft-spent-usd`, so counting the file too would double it.
+// Month attribution is the file's `startedAt` (the first metered call): fixed once written, so a session's
+// figure never moves between months as spend continues, the same start-date rule a run's leg uses.
+// `spendComplete: false` = "at least", never $0 (F6).
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { readRunList, runlistHome } from './runlist.js';
+
+export const DRAFT_SPEND_FILE = 'draft-spend.json';
+
+/**
+ * @typedef {object} DraftSpend
+ * @property {string} sessionId
+ * @property {number} spentUsd the known floor of the session's drafting spend
+ * @property {boolean} spendComplete false = `spentUsd` is a floor ("at least")
+ * @property {string|null} provider the worker's provider shape (`anthropic-api` | `openai-api` | ...)
+ * @property {string|null} baseUrl
+ * @property {string|null} model
+ * @property {string} startedAt ISO, the first metered call
+ * @property {string} updatedAt ISO, the latest metered call
+ */
+
+/**
+ * (Re)write `<dir>/draft-spend.json` atomically (tmp + rename).
+ * @param {string} dir the session's folder
+ * @param {DraftSpend} rec
+ * @returns {void}
+ */
+export function writeDraftSpend(dir, rec) {
+  const file = join(dir, DRAFT_SPEND_FILE);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`);
+  renameSync(tmp, file);
+}
+
+/** @param {string} p @param {string} dir @returns {boolean} */
+const inside = (p, dir) => typeof p === 'string' && (resolve(p) === dir || resolve(p).startsWith(dir + sep));
+
+/**
+ * Every session folder's drafting spend that never became a run.
+ * @param {{ home?: string, sessionsRoot?: string }} [opts] `home` = the bareloop config dir (as everywhere in src/monthly.js); the sessions live in `<home>/panel-sessions` unless `sessionsRoot` names them
+ * @returns {DraftSpend[]}
+ */
+export function readOrphanDraftSpends(opts = {}) {
+  const root = resolve(opts.sessionsRoot ?? join(runlistHome(opts.home), 'panel-sessions'));
+  if (!existsSync(root)) return [];
+  /** @type {string[]} */
+  let names;
+  try { names = readdirSync(root); } catch { return []; }
+  const { rows } = readRunList({ home: opts.home });
+  /** @type {DraftSpend[]} */
+  const out = [];
+  for (const name of names) {
+    const dir = join(root, name);
+    const file = join(dir, DRAFT_SPEND_FILE);
+    if (!existsSync(file)) continue;
+    if (rows.some((r) => inside(r.spine, dir) || (r.patient && inside(r.patient, dir)))) continue;
+    try {
+      const j = JSON.parse(readFileSync(file, 'utf8'));
+      if (!j || typeof j !== 'object' || !Number.isFinite(j.spentUsd)) throw new Error('unreadable');
+      out.push({
+        sessionId: String(j.sessionId ?? name), spentUsd: j.spentUsd, spendComplete: j.spendComplete === true,
+        provider: typeof j.provider === 'string' ? j.provider : null, baseUrl: typeof j.baseUrl === 'string' ? j.baseUrl : null,
+        model: typeof j.model === 'string' ? j.model : null, startedAt: String(j.startedAt), updatedAt: String(j.updatedAt),
+      });
+    } catch {
+      // a file that names money but cannot be read is unknown spend: an "at least" of $0, dated unknown
+      out.push({ sessionId: name, spentUsd: 0, spendComplete: false, provider: null, baseUrl: null, model: null, startedAt: 'unreadable', updatedAt: 'unreadable' });
+    }
+  }
+  return out;
+}

package/src/exits.js

@@ -23,7 +23,7 @@
 //     unrunnable check is a stop, never a silent pass).
 
 import { createHash } from 'node:crypto';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { globToPrefix } from './validate.js';
 
@@ -62,6 +62,15 @@ export async function snapshotScope(dir, scope) {
   const prefix = globToPrefix(scope);
   /** @type {Map<string, string>} */
   const snap = new Map();
+  // A scope whose prefix names a single regular FILE (a file-valued writeScope
+  // becomes `src/x.js/**`) snapshots that one file, keyed by the prefix itself —
+  // readdir on a file throws ENOTDIR, which read as an empty tree forever (F212).
+  try {
+    if ((await stat(join(dir, prefix))).isFile()) {
+      snap.set(prefix, createHash('sha256').update(await readFile(join(dir, prefix))).digest('hex'));
+      return snap;
+    }
+  } catch { /* missing or unreadable: fall through to the directory path */ }
   /** @type {string[]} */
   let entries;
   try {

package/src/interviewrun.js

@@ -722,7 +722,8 @@ export async function main(argv, deps = {}) {
   }
 
   // ── 6. the paid step, which is a DIFFERENT process under a DIFFERENT ceiling ─
-  const RUN_AUTHOR = fileURLToPath(new URL('../scripts/run-author.mjs', import.meta.url));
+  // the PACKAGED door (`bin/` ships; `scripts/` does not): `bareloop author` takes the same flags as run-author
+  const BARELOOP_BIN = fileURLToPath(new URL('../bin/bareloop.mjs', import.meta.url));
   const childArgs = [
     '--source', TREE, '--answers', answersFile, '--draft', draftFile,
     '--verdict', VERDICT, '--out', OUT,
@@ -742,7 +743,7 @@ export async function main(argv, deps = {}) {
     say(`It runs under the AUTHORING ceiling (${CEILING_USD === null ? 'UNBOUNDED — you gave no --budget' : `$${CEILING_USD}`}), which is not the job's $${draft.budgetUsd}.`);
     say('It stops at prepareSigning: it never signs, and it never runs the job.');
   } else {
-    say('NEXT — running run-author.mjs on this source stops right away, at $0: no scout, no confirm turn, no model call.');
+    say('NEXT — running bareloop author on this source stops right away, at $0: no scout, no confirm turn, no model call.');
     say('It never signs and never runs the job — bareloop has no checks for this kind of job yet.');
   }
   say('');
@@ -780,11 +781,11 @@ export async function main(argv, deps = {}) {
   if (!KEYED) {
     say('');
     if (providerEnvKey && keyProblem) {
-      say(`  (${providerEnvKey} is set but ${keyProblem} — run-author refuses without a clean key; secrets are never trimmed or repaired, only reported)`);
+      say(`  (${providerEnvKey} is set but ${keyProblem} — bareloop author refuses without a clean key; secrets are never trimmed or repaired, only reported)`);
     } else {
       say(providerEnvKey
-        ? `  (${providerEnvKey} is not set in this shell — run-author refuses without it; secrets load from the environment, never the tree)`
-        : `  (provider "${PROVIDER}" is not in the runnable table — run-author will refuse it loud; this is not a key problem)`);
+        ? `  (${providerEnvKey} is not set in this shell — bareloop author refuses without it; secrets load from the environment, never the tree)`
+        : `  (provider "${PROVIDER}" is not in the runnable table — bareloop author will refuse it loud; this is not a key problem)`);
     }
     // The repair, in plain words and WITHOUT a command: which secret store a person
     // keeps their key in is theirs, and printing one specific incantation would be
@@ -801,9 +802,9 @@ export async function main(argv, deps = {}) {
     : null;
   if (depsGapAtHandoff) {
     say('');
-    say(`  The copy still has no installed packages (${depsGapAtHandoff.reason}) — run-author would only instrument-stop on it.`);
+    say(`  The copy still has no installed packages (${depsGapAtHandoff.reason}) — bareloop author would only instrument-stop on it.`);
     say(`    cd ${prep.tree} && ${depsGapAtHandoff.command}`);
-    say('  then run run-author.mjs yourself with the command above.');
+    say('  then run bareloop author yourself with the command above.');
   }
   say('');
   // The default is NO, and it is the same lean the pause's doors take: the answer that
@@ -832,9 +833,9 @@ export async function main(argv, deps = {}) {
     exitCode = 0;
   } else {
     say('');
-    const child = spawnSyncFn(process.execPath, [RUN_AUTHOR, ...childArgs], { stdio: 'inherit' });
+    const child = spawnSyncFn(process.execPath, [BARELOOP_BIN, 'author', ...childArgs], { stdio: 'inherit' });
     if (child.error) {
-      say(`run-author could not be started (${child.error.message}) — the command above still stands.`);
+      say(`bareloop author could not be started (${child.error.message}) — the command above still stands.`);
       exitCode = 2;
     } else {
       // the child's own exit is the answer: a refusal there is a RESULT, and flattening

package/src/job.js

@@ -289,8 +289,8 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
   }
 
   if (spec.budgetUsd === undefined) red('missing-required', 'budgetUsd');
-  else if (!(typeof spec.budgetUsd === 'number' && spec.budgetUsd > 0 && spec.budgetUsd <= shellCapUsd)) {
-    red('bounds', 'budgetUsd', `0 < budget <= shell cap ${shellCapUsd} (cap-not-estimate; no self-adjusted budgets, ever)`);
+  else if (!(typeof spec.budgetUsd === 'number' && Number.isFinite(spec.budgetUsd) && spec.budgetUsd > 0 && spec.budgetUsd <= shellCapUsd)) {
+    red('bounds', 'budgetUsd', `a finite 0 < budget <= shell cap ${shellCapUsd} (cap-not-estimate; no self-adjusted budgets, ever)`);
   }
 
   // T (PRD v1.27/v1.29) — TIME, with exactly budgetUsd's status: operator input,
@@ -884,6 +884,43 @@ export function jobSpecHash(job) {
   return createHash('sha256').update(c).digest('hex');
 }
 
+/**
+ * The fields a "Reuse workflow" run may change: where the work lands (the write fence, `writeScope`, and a
+ * `destination`/`source` where a spec ever carries them) and the two ceilings. Everything else in a signed spec is
+ * the WORKFLOW — goal, checks, guardrails, close (the worker model is the third kind, {@link WORKFLOW_KEY_IDENTITY_FIELDS}). ONE list, shared by {@link workflowKey} and by the panel's
+ * reuse (so what the key ignores is exactly what the person may edit, never two spellings).
+ */
+export const REUSE_OPEN_SPEC_FIELDS = Object.freeze(['source', 'destination', 'writeScope', 'budgetUsd', 'maxWallMs']);
+
+/**
+ * The worker-identity fields {@link workflowKey} ALSO ignores (hamr 2026-10-04: Model is open on a reuse; the Name
+ * chosen in Settings carries its provider and baseUrl with it). They stay inside {@link jobSpecHash}, so what the person
+ * signs still covers the model the run will use. Kept apart from {@link REUSE_OPEN_SPEC_FIELDS} on purpose: those are the
+ * fields the page's boxes edit directly; these three change together, as one Settings row.
+ */
+export const WORKFLOW_KEY_IDENTITY_FIELDS = Object.freeze(['provider', 'baseUrl', 'model']);
+
+/**
+ * The identity of a WORKFLOW (Reuse workflow, hamr 2026-10-03): sha256 over the signed spec WITHOUT the fields a
+ * reuse may change ({@link REUSE_OPEN_SPEC_FIELDS}) and the worker identity ({@link WORKFLOW_KEY_IDENTITY_FIELDS}). Two runs
+ * share a workflow key iff they ran the same goal, checks, guardrails and close — whatever source they ran on, wherever they wrote, whatever caps they had.
+ * It is NOT a signature: {@link jobSpecHash} (which covers the caps and the fence) stays what the person signs, and
+ * a reuse lands on a NEW jobSpecHash with the SAME workflowKey. Same never-throws contract as `jobSpecHash`, and
+ * the same resolved-`tools` form, so an omitted-`tools` spec and its spelled-out menu share a key.
+ * @param {object} job
+ * @returns {string} sha256 hex
+ */
+export function workflowKey(job) {
+  let c;
+  try {
+    /** @type {any} */
+    const rest = isObj(job) ? { ...job } : job;
+    if (isObj(rest)) for (const f of [...REUSE_OPEN_SPEC_FIELDS, ...WORKFLOW_KEY_IDENTITY_FIELDS]) delete rest[f];
+    c = canon(resolveSpec(rest));
+  } catch { c = '\u0000unhashable'; }
+  return createHash('sha256').update(`workflow-key-v1\n${c}`).digest('hex');
+}
+
 /**
  * Does an approval record cover this exact spec version? Pure predicate — the
  * N2 runner refuses to run without it; nothing here writes or prompts. The

package/src/judged.js

@@ -64,7 +64,7 @@
 // redacts at its emission boundary, the same split `src/kinds.js` documents.
 
 import { createRequire } from 'node:module';
-import { extractArtifact, priceOf, scrubRaw } from './text.js';
+import { extractArtifact, priceOf, scrubRaw, rateSourceFields } from './text.js';
 import { resolveProvider } from './providers.js';
 
 const require = createRequire(import.meta.url);
@@ -793,10 +793,28 @@ function topLevelFunctionNames(artifactText) {
  * so the priced seam is the only legal one.
  * `rates` is the customer's own price for the judge's row (USD per 1K, `ratesFor`'s
  * `rates`); null/absent = bare-agent's built-in guess, exactly as before.
- * @param {{provider: any, system: string, rates?: {in: number, out: number}|null}} o */
+ * @param {{provider: any, system: string, rates?: {in: number, out: number}|null}} o
+ * @returns {{run: (msgs: any[], tools: any[], opts?: any) => Promise<any>}} */
 export const defaultJudgeLoop = ({ provider, system, rates = null }) => {
   const { Loop } = require('bare-agent');
-  return new Loop({ provider, system, ...(rates ? { rates } : {}) });
+  // BA-21: the Loop's run RESULT carries no `rateSource` — only the per-call metering event
+  // does (`onLlmResult`). Capture it there and ride it on the result, so `runLocate` can
+  // forward it to the judge-round record beside `costUsd`. Absent (no round metered) = no key.
+  /** @type {{rateSource: string|null}|null} */
+  let seen = null;
+  const loop = new Loop({
+    provider, system, ...(rates ? { rates } : {}),
+    onLlmResult: (/** @type {{rateSource?: string|null}} */ m) => {
+      if (m && typeof m === 'object' && 'rateSource' in m) seen = { rateSource: m.rateSource ?? null };
+    },
+  });
+  return {
+    run: async (/** @type {any[]} */ msgs, /** @type {any[]} */ tools, /** @type {any} */ opts) => {
+      seen = null;
+      const res = await loop.run(msgs, tools, opts);
+      return res && typeof res === 'object' && seen ? { ...res, rateSource: /** @type {any} */ (seen).rateSource } : res;
+    },
+  };
 };
 
 // ── LOCATE: one attempt ─────────────────────────────────────────────────────
@@ -821,7 +839,7 @@ export const defaultJudgeLoop = ({ provider, system, rates = null }) => {
  * On every route out, red or clean, `onCost` fires exactly once with the honest
  * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
  * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
- *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void,
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number, rateSource?: string|null}) => void,
  *   callBounds?: {timeoutMs?: number, deadlineMs?: number}}} o
  * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
  *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
@@ -852,7 +870,9 @@ export async function runLocate({
   /** @param {{axis: string, detail: string}|null} red @param {any} facts @param {any} r @param {boolean} truncated @param {boolean} parseError */
   const out = (red, facts, r, truncated, parseError) => {
     const { costUsd, unpricedRounds } = r === null ? { costUsd: null, unpricedRounds: 0 } : priceOf(r);
-    onCost({ costUsd, unpricedRounds });
+    // BA-21: the round's provenance rides beside the cost when the loop carried it (see
+    // `defaultJudgeLoop`); a loop that never metered a rate adds no key.
+    onCost({ costUsd, unpricedRounds, ...rateSourceFields(r) });
     return {
       ok: red === null, facts, red, costUsd, unpricedRounds, truncated, parseError,
       raw: scrubRaw({

package/src/kinds.js

@@ -67,6 +67,7 @@ import { join, sep } from 'node:path';
 import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
 import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL } from './judged.js';
+import { rateSourceFields } from './text.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
  * hand-written closes already spoke (exit code is truth) */
@@ -1871,6 +1872,7 @@ async function runJudgedFloor(stage, ctx) {
           ctx.onJudgeCost({
             stage: stage?.name ?? null, kind: stage?.kind ?? null, path: rel, attempt,
             label: LOCATE_LABEL, model: judgeModel, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
+            ...rateSourceFields(c),
           });
         },
       });

package/src/ledger.js

@@ -23,6 +23,7 @@ import { readFileSync, appendFileSync, existsSync } from 'node:fs';
 import { basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { HITL_PAUSE, HITL_DECISION_RED } from './declaredclose.js';
+import { legsOf } from './legs.js';
 
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES = Object.freeze([
@@ -67,6 +68,7 @@ const QUOTED_VERB_RE = /"([a-z0-9-]+)"/;
 const EXCLUDED_ESCALATIONS = new Set([
   'cap-halt',           // a budget story, not a lib bug
   'wall-halt',          // the TIME budget's version of the same story (T, PRD v1.27)
+  'stopped',            // the PERSON's stop (P5 item 5) — a checkpoint, never a lib bug
   // A stall is the ABSENCE of beats, not an observed provider failure: nothing
   // saw the transport fail, so the typed-lib route rendered a live ask reading
   // "bare-agent: the provider path failed — worker stalled…" and aimed a bug at
@@ -408,12 +410,11 @@ export function updateLedger({ ledgerFile, spineFiles }) {
 // ── BA-21 pricing provenance: the READ side (REPORTING ONLY) ─────────────────
 // bare-agent >=0.37 rides `rateSource` beside `pricing` on every metering payload,
 // and the plan flow forwards it verbatim onto `worker-round`/`judge-round`/`worker-turn`
-// (`rateSourceFields`, src/planrun.js — the write side).
+// (`rateSourceFields`, src/text.js — the write side).
 //
-// NAMED rather than papered over: `judge-round`'s own payload (src/kinds.js's
-// `onJudgeCost({...})`) does not carry `rateSource` yet, so every judge round reads
-// UNKNOWN provenance today — correctly, by the same rule that governs the archive, and
-// the day that payload forwards the field the emit site already spreads it.
+// `judge-round`'s payload (src/kinds.js's `onJudgeCost({...})`) forwards `rateSource` from the
+// judge Loop's per-call metering (`defaultJudgeLoop`, src/judged.js); a judge round whose loop
+// carried none — and every judge round archived before this — reads UNKNOWN, by the archive rule.
 //
 // `pricing` is UNCHANGED and still strictly two-valued ('priced'|'unpriced'). Nothing
 // below reads it, nothing below decides anything, and no new escalation category exists:
@@ -526,9 +527,103 @@ export function floorsFromRecords(records) {
   }
   const spendFloorUsd = pricedCount > 0 ? spendSum : null;
 
-  const withTs = records.filter((r) => r && typeof r === 'object' && typeof r.ts === 'string');
-  const firstMs = withTs.length ? Date.parse(withTs[0].ts) : NaN;
-  const lastMs = withTs.length ? Date.parse(withTs[withTs.length - 1].ts) : NaN;
-  const wallFloorMs = Number.isFinite(firstMs) && Number.isFinite(lastMs) && lastMs >= firstMs ? lastMs - firstMs : null;
+  // P5-R: a resumed run is one spine of several legs — the wall floor is the sum of each leg's own
+  // first -> last window, the quiet time between legs excluded (hamr 2026-10-02, 2A). One leg (every spine
+  // before P5-R) reads exactly as it always did.
+  const legs = legsOf(records.filter((r) => r && typeof r === 'object'));
+  let wallFloorMs = null;
+  let sum = 0;
+  let known = 0;
+  for (const l of legs) {
+    const withTs = l.records.filter((r) => typeof r.ts === 'string');
+    const firstMs = withTs.length ? Date.parse(withTs[0].ts) : NaN;
+    const lastMs = withTs.length ? Date.parse(withTs[withTs.length - 1].ts) : NaN;
+    if (Number.isFinite(firstMs) && Number.isFinite(lastMs) && lastMs >= firstMs) { sum += lastMs - firstMs; known += 1; }
+  }
+  if (known > 0) wallFloorMs = sum;
   return { spendFloorUsd, wallFloorMs };
 }
+
+/**
+ * One run's own spend, off its spine records: this LEG's figure (never the chain fold),
+ * plus the drafting spend the run was signed with (counted once — on the first leg only).
+ * @param {any[]} records ONE leg's records
+ * @param {{ withDraft?: boolean }} [o] `withDraft: false` leaves the drafting spend out (a caller folding the CHAIN's own spend, which never held it)
+ * @returns {{ usd: number, complete: boolean }}
+ */
+export function legSpend(records, { withDraft = true } = {}) {
+  const jobStart = records.find((r) => r && r.type === 'job-start') ?? null;
+  const jobEnd = records.findLast((r) => r && r.type === 'job-end') ?? null;
+  const rounds = records.filter((r) => r && SPEND_RECORD_TYPES.includes(r.type));
+  const pricedSum = rounds.reduce((a, r) => (typeof r.costUsd === 'number' && Number.isFinite(r.costUsd) ? a + r.costUsd : a), 0);
+  const unpriced = rounds.filter((r) => !(typeof r.costUsd === 'number' && Number.isFinite(r.costUsd))).length;
+  let usd = pricedSum;
+  let complete = false;
+  if (jobEnd) {
+    const eng = jobEnd.engagementSpentUsd;
+    usd = typeof eng === 'number' && Number.isFinite(eng) ? eng : pricedSum;
+    complete = jobEnd.spendComplete === true && unpriced === 0;
+  }
+  // drafting spend: a RESUMED / door-rerun leg carries the flag again but the first leg already counted it
+  const resumed = !!jobStart && 'priorSpentUsd' in jobStart;
+  if (withDraft && jobStart && !resumed && typeof jobStart.draftSpentUsd === 'number' && Number.isFinite(jobStart.draftSpentUsd) && jobStart.draftSpentUsd > 0) {
+    usd += jobStart.draftSpentUsd;
+    if (jobStart.draftSpendComplete === false) complete = false;
+  }
+  return { usd, complete };
+}
+
+/**
+ * A WHOLE RUN's own spend (P5-R: a resumed run is one spine of several legs): the sum of each leg's own
+ * figure ({@link legSpend}), never the declared chain fold. ONE basis — every leg's own rounds — so a leg is
+ * counted once: the last leg's `job-end.spentUsd` also carries the earlier legs, and adding it to the
+ * earlier legs' own figures would count them twice. A leg with no terminal (it died) is a floor, so the run
+ * is `complete: false`. A spine with no marker is one leg and reads exactly as {@link legSpend} always did.
+ * @param {any[]} records one spine's records
+ * @param {{ withDraft?: boolean }} [o]
+ * @returns {{ usd: number, complete: boolean, lastLegUsd: number }} `lastLegUsd`: the latest leg's own share (what a claim still held for it is measured against)
+ */
+export function runSpend(records, o = {}) {
+  const legs = legsOf(records);
+  if (legs.length === 0) return { usd: 0, complete: false, lastLegUsd: 0 };
+  let usd = 0;
+  let complete = true;
+  let lastLegUsd = 0;
+  for (const l of legs) {
+    const s = legSpend(l.records, o);
+    usd += s.usd;
+    if (!s.complete) complete = false;
+    lastLegUsd = s.usd;
+  }
+  return { usd, complete, lastLegUsd };
+}
+
+/**
+ * What a FINISHED run's whole chain spent, for a caller that folds it forward (the review door's rerun opens a
+ * new run under the same signed ceiling). One basis per shape: a spine of ONE leg is read by its terminal's own
+ * chain total (`job-end.spentUsd`, which already carries whatever fold that leg inherited — what every door has
+ * always read); a resumed run's several legs are the first leg's own inherited fold (spend the file does not
+ * hold) plus each leg's OWN spend, so a later leg's terminal total — which also carries the earlier legs — is
+ * never added on top of them. Not finite / no terminal = `usd: 0, complete: false` (never an exact-looking 0).
+ * @param {any[]} records one spine's records
+ * @returns {{ usd: number, complete: boolean }}
+ */
+export function chainSpend(records) {
+  const legs = legsOf(records);
+  const num = (/** @type {unknown} */ v) => typeof v === 'number' && Number.isFinite(v);
+  if (legs.length <= 1) {
+    const je = legs[0]?.jobEnd ?? null;
+    const known = num(je?.spentUsd);
+    return { usd: known ? je.spentUsd : 0, complete: known && je?.spendComplete !== false };
+  }
+  const head = legs[0].jobStart;
+  let usd = num(head?.priorSpentUsd) && head.priorSpentUsd > 0 ? head.priorSpentUsd : 0;
+  let complete = head?.priorSpendComplete !== false;
+  for (const l of legs) {
+    const s = legSpend(l.records, { withDraft: false });
+    usd += s.usd;
+    if (!s.complete) complete = false;
+  }
+  return { usd, complete };
+}
+

package/src/legs.js

@@ -0,0 +1,171 @@
+// P5-R (hamr 2026-10-02: "one run, one id, one file ... never two") — a RESUMED run is the SAME run.
+// Its spine is one append-only file; each resume appends a `leg-resume` marker and then the new
+// leg's own records. This module is the ONE owner of "where does a leg start and end": every reader
+// that needs a leg (the resume reader, replay, the monthly limit, the panel, the readout) asks
+// `legsOf` and never re-derives a boundary on its own — two spellings of one boundary is how a
+// money figure counts leg 1 twice.
+//
+// Pure: no imports, no file IO. The text-level torn-line rule lives in `parseSpineText` below, beside
+// the boundary rule it depends on (a torn line is tolerated exactly where the writer leaves one).
+//
+// A spine with NO marker (every run written before P5-R, and every run nobody resumed) is ONE leg:
+// `legsOf` over it returns that file's records, unchanged.
+
+/** The marker record's `type`. */
+export const LEG_RESUME = 'leg-resume';
+
+/**
+ * @typedef {object} Leg
+ * @property {number} leg 1-based position in file order (the marker's own `leg` field is never trusted over the order)
+ * @property {any|null} start the leg's first record (the `leg-resume` marker for leg 2+; the file's first record for leg 1)
+ * @property {any|null} end the leg's last record
+ * @property {any[]} records every record of the leg, in file order, marker included
+ * @property {any|null} jobStart the leg's own `job-start` (null: it ended before runJob wrote one)
+ * @property {any|null} jobEnd the leg's own LAST `job-end` (null: it died, or it is still running)
+ * @property {string|null} outcome the leg's terminal: its `job-end` outcome, else a `run-end` outcome (a $0 refusal), else null
+ * @property {string|null} after leg 1: null. Leg 2+: how the PREVIOUS leg ended, as the marker declares it
+ *   (else derived from that leg's own terminal), `'died'` when it recorded none
+ * @property {number|null} startMs `Date.parse` of the start record's `ts`
+ * @property {number|null} endMs `Date.parse` of the end record's `ts`
+ */
+
+/** @param {any} r @returns {number|null} */
+function tsOf(r) {
+  const t = typeof r?.ts === 'string' ? Date.parse(r.ts) : NaN;
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Split one spine's parsed records into its legs. Pure.
+ * @param {any[]} events one spine's parsed records, in file order
+ * @returns {Leg[]} always at least one leg for a non-empty list; `[]` for an empty one
+ */
+export function legsOf(events) {
+  const list = Array.isArray(events) ? events.filter((e) => e && typeof e === 'object') : [];
+  if (list.length === 0) return [];
+  /** @type {any[][]} */
+  const groups = [[]];
+  for (const e of list) {
+    // a marker opens a new leg — but never an EMPTY leg 1: a file whose first record IS a marker
+    // (a spine somebody truncated) still reads as leg 1 = the marker, not an invented empty leg
+    if (e.type === LEG_RESUME && groups[groups.length - 1].length > 0) groups.push([]);
+    groups[groups.length - 1].push(e);
+  }
+  /** @type {Leg[]} */
+  const legs = [];
+  groups.forEach((records, i) => {
+    const jobStart = records.find((r) => r.type === 'job-start') ?? null;
+    const jobEnd = records.findLast((r) => r.type === 'job-end') ?? null;
+    const runEnd = records.findLast((r) => r.type === 'run-end') ?? null;
+    const outcome = typeof jobEnd?.outcome === 'string' ? jobEnd.outcome
+      : (typeof runEnd?.outcome === 'string' ? runEnd.outcome : null);
+    const marker = records[0].type === LEG_RESUME ? records[0] : null;
+    const prev = i > 0 ? legs[i - 1] : null;
+    /** @type {string|null} */
+    let after = null;
+    if (i > 0) after = typeof marker?.after === 'string' && marker.after !== '' ? marker.after : (prev?.outcome ?? 'died');
+    legs.push({
+      leg: i + 1,
+      start: records[0],
+      end: records[records.length - 1],
+      records,
+      jobStart,
+      jobEnd,
+      outcome,
+      after,
+      startMs: tsOf(records[0]),
+      endMs: tsOf(records[records.length - 1]),
+    });
+  });
+  return legs;
+}
+
+/**
+ * The legs' WORKING time, gap excluded (hamr 2026-10-02, 2A: only working time charges the wall). Each leg
+ * counts first record → last record; the quiet time between one leg's end and the next leg's marker is
+ * nobody's. `null` = unknown (no leg carries two parseable stamps) — never 0. A leg whose stamps are
+ * unreadable adds nothing, so the figure is a FLOOR, `complete: false`.
+ * @param {Leg[]} legs
+ * @returns {{ ms: number|null, complete: boolean }}
+ */
+export function legsWallMs(legs) {
+  let ms = 0;
+  let known = 0;
+  let complete = legs.length > 0;
+  for (const l of legs) {
+    if (l.startMs !== null && l.endMs !== null && l.endMs >= l.startMs) { ms += l.endMs - l.startMs; known += 1; } else complete = false;
+  }
+  return { ms: known === 0 ? null : ms, complete: complete && known > 0 };
+}
+
+/**
+ * Parse a spine's TEXT, tolerant exactly where the writer leaves damage. A kill mid-append leaves a torn
+ * line; a resume never edits it (the spine is append-only forever) — it writes one `\n` and starts a fresh
+ * line, so the torn bytes end up alone on their own line, immediately BEFORE a `leg-resume` marker. That
+ * line, and the file's own last two lines (the older tail rule: a kill mid-append of the file's final
+ * record), are tolerated and named. An unparseable line anywhere else is `corrupt`: a reconstruction from
+ * it would invent a history.
+ * @param {string} raw
+ * @returns {{ records: any[], tolerated: {line: number, why: 'tail'|'before-leg-resume'}[], corrupt: {line: number, message: string}|null }}
+ *   `line` is 1-based. Only the FIRST corrupt line is reported.
+ */
+export function parseSpineText(raw) {
+  const lines = String(raw).split('\n');
+  /** @type {any[]} */
+  const records = [];
+  /** @type {{line: number, why: 'tail'|'before-leg-resume'}[]} */
+  const tolerated = [];
+  /** @type {{line: number, message: string}|null} */
+  let corrupt = null;
+  const BAD = Symbol('torn');
+  /** @type {any[]} undefined = blank line, BAD = unparseable */
+  const parsed = lines.map((l) => {
+    if (!l.trim()) return undefined;
+    try { return JSON.parse(l); } catch { return BAD; }
+  });
+  /** the next non-blank line's parse result after index i, skipping blanks */
+  const nextOf = (/** @type {number} */ i) => {
+    for (let j = i + 1; j < lines.length; j += 1) if (parsed[j] !== undefined) return parsed[j];
+    return undefined;
+  };
+  lines.forEach((line, i) => {
+    const p = parsed[i];
+    if (p === undefined) return;
+    if (p !== BAD) { records.push(p); return; }
+    if (i >= lines.length - 2) { tolerated.push({ line: i + 1, why: 'tail' }); return; }
+    // EXACTLY one torn line directly before a marker: the shape a resume leaves. Two in a row is not that
+    // shape — the first of them has a corrupt line (not a marker) after it, and is reported.
+    const next = nextOf(i);
+    if (next && next.type === LEG_RESUME) { tolerated.push({ line: i + 1, why: 'before-leg-resume' }); return; }
+    if (corrupt === null) {
+      let message = 'unparseable';
+      try { JSON.parse(line); } catch (/** @type {any} */ e) { message = e.message; }
+      corrupt = { line: i + 1, message };
+    }
+  });
+  return { records, tolerated, corrupt };
+}
+
+/**
+ * Where leg `leg`'s watchdog kill note lives. Leg 1 keeps the name every run has always had
+ * (`<spine>.watchdog.json`); a resumed leg's note sits beside it (`<spine>.leg<N>.watchdog.json`) so one
+ * leg never overwrites another's evidence of how it died.
+ * @param {string} spineFile
+ * @param {number} leg 1-based
+ * @returns {string}
+ */
+export function watchdogNotePath(spineFile, leg) {
+  return leg <= 1 ? `${spineFile}.watchdog.json` : `${spineFile}.leg${leg}.watchdog.json`;
+}
+
+/**
+ * P5 item 5 (Stop) — where a run's STOP REQUEST lives: a file beside its spine. The panel's stop route writes it;
+ * the engine reads it at the between-steps seam (src/planrun.js) and consumes it. One spelling, here, so the route
+ * and the engine can never name two files. A request belongs to ONE leg: the engine deletes it when it honours it,
+ * when the leg ends, and again at the start of the next leg (src/userrun.js).
+ * @param {string} spineFile
+ * @returns {string}
+ */
+export function stopFilePath(spineFile) {
+  return `${spineFile}.stop`;
+}