bareloop 0.34.0 → 0.35.0

package/src/reuse.js

@@ -52,6 +52,7 @@ import { closeStagesOf } from './plan.js';
 import { MIN_WALL_MS, jobSpecHash } from './job.js';
 import { isObj, isNonEmptyString } from './validate.js';
 import { readGrade } from './trend.js';
+import { legsOf } from './legs.js';
 
 /** the paused-run TERMINAL and its spine record share one name (`runPlan` returns
  * it and `runJob` writes it onto `job-end`), spelled once in `declaredclose.js`
@@ -117,6 +118,11 @@ export const REUSE_GRADED_RED = Object.freeze(['escalated']);
  * allowances the loop's remaining tries are meant to spend against, and the human
  * ones are the stop no further try can change (see `hardStop`).
  *
+ * `stopped` (PANEL-BUILD.md P5 item 5, hamr 2026-10-02): the PERSON ended the leg at a round
+ * boundary (a `<spine>.stop` request). Nothing was judged and nothing failed — finished steps stand on
+ * disk, the allowance is unspent, so it is a checkpoint exactly like a cap-halt. Arbiter-adjacent (it
+ * widens what resume may re-enter); ruled by hamr, not chosen by a builder.
+ *
  * `provider-red` folded in 2026-08-25 (PRD v1.80 TODO #4, F115 "Ruled: one transport
  * retry"; hamr's ruling verbatim: *"joins resume anyways and you decide but you are
  * given an honest readout and with 1 retry"*). It is a MACHINE halt, not a human one
@@ -139,7 +145,7 @@ export const REUSE_GRADED_RED = Object.freeze(['escalated']);
  * does not end up with two lists that can drift, which is the exact failure this
  * constant exists to end (see the paragraph above).
  */
-export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', 'provider-red', ...HUMAN_CHECKPOINTS]);
+export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', 'provider-red', 'stopped', ...HUMAN_CHECKPOINTS]);
 
 /**
  * v1's definition of "the same KIND of recipe" — and it is the LOAD GATE's own: the
@@ -815,7 +821,16 @@ function readGradeSeed(seen) {
  *   spentUsd, spendComplete, carrySpentUsd, carrySpendComplete }`
  */
 export function readResume(events, { deathAt = null, direct = false, resumableOutcomes = [] } = {}) {
-  const list = Array.isArray(events) ? events.filter(isObj) : [];
+  let list = Array.isArray(events) ? events.filter(isObj) : [];
+  // P5-R: a DIRECT spine may be a resumed run's one file of several legs (src/legs.js). The checkpoint a resume
+  // continues from is the latest leg that reached a `job-start`, and that leg's own `job-start` DECLARES the fold
+  // it inherited (`priorSpentUsd`/`priorWallMs`/…) — so reading that one window and adding its rounds is the whole
+  // chain exactly once, never the earlier legs' rounds on top of a fold that already carries them. A spine with
+  // no marker is one leg and reads as it always did.
+  if (direct) {
+    const legs = legsOf(list);
+    if (legs.length > 1) list = (legs.findLast((l) => l.jobStart !== null) ?? legs[legs.length - 1]).records;
+  }
   /** which landed terminals are a CHECKPOINT rather than a graded row */
   const resumableHalt = new Set(Array.isArray(resumableOutcomes) ? resumableOutcomes : []);
   // the FIRST reuse-start is the envelope this spine was opened under. A resumed spine
@@ -1228,7 +1243,9 @@ export const PAUSE_TTL_MS = 60 * 24 * 60 * 60_000;
  * @returns {{ok: boolean, applies: boolean, ageMs: number|null, ttlMs: number, pausedAt: string|null, detail: string|null}}
  */
 export function checkpointAgeGate(events, { now = Date.now, ttlMs = PAUSE_TTL_MS } = {}) {
-  const list = Array.isArray(events) ? events.filter(isObj) : [];
+  const all = Array.isArray(events) ? events.filter(isObj) : [];
+  // P5-R: only the run's LATEST leg can be the one waiting — an earlier leg's pause was answered by the leg after it
+  const list = legsOf(all).at(-1)?.records ?? all;
   const end = list.filter((e) => e.type === 'job-end').at(-1) ?? null;
   const base = { applies: false, ageMs: null, ttlMs, pausedAt: null, detail: null };
   if (end?.outcome !== HITL_PAUSE) return { ...base, ok: true };

package/src/run.js

@@ -256,10 +256,13 @@ async function primitiveSmoke(workdir) {
  *   passes `false` so the escalation tail's option strings say "resume is
  *   `run-u`-only in v1" instead of naming a flag that would fail if typed. Forwarded
  *   verbatim to the plan flow, which owns the three `--resume`-naming readouts.
+ * @param {string|null} [opts.stopFile=null] P5 item 5 — the run's STOP REQUEST file
+ *   (`stopFilePath(spine)`, src/legs.js), forwarded verbatim to the plan flow, which reads it at the
+ *   round-boundary seam (where the money cap binds) and ends the leg `stopped`. `null` = no stop surface.
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'stopped' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  *   NOTE: `job-end` can ALSO land with outcome 'runner-drained' (F140/PRD item
  *   28(c)) — the `beforeExit` backstop's own terminal, emitted from OUTSIDE this
@@ -270,7 +273,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, 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 }) {
+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, stopFile = null }) {
   // 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
@@ -537,7 +540,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, 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,
+      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, stopFile,
       // 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

@@ -58,9 +58,12 @@ export function runlistPath(home) {
 }
 
 /**
- * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill', pid?: number, capUsd?: number }} RunRow
+ * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill', pid?: number, capUsd?: number, leg?: 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).
+ * `leg` (P5-R; only on a row {@link readRunList} FOLDED from `leg-start` entries, i.e. a RESUMED run):
+ * the number of the run's latest leg — a resumed run is the same run, one row, and its `pid`/`capUsd`
+ * are that latest leg's.
  */
 
 /**
@@ -101,7 +104,10 @@ export function appendRun(row, opts = {}) {
 }
 
 /**
- * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean }} RunEvent
+ * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean, leg?: number }} RunEvent
+ * `leg` (P5-R): which leg of the run the write-back is about; absent = leg 1 (every entry written before P5-R).
+ * A resumed run is ONE row, so `settled`/`released` are per leg: a later leg's `released` gives back THAT leg's
+ * claim and never removes the run.
  * 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
@@ -122,6 +128,43 @@ export function appendRunEvent(event, opts = {}) {
   try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
 }
 
+/**
+ * @typedef {{ type: 'leg-start', runid: string, leg: number, pid?: number, capUsd?: number, at: string }} LegStart
+ * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row
+ * instead of a second row. {@link readRunList} folds it into the row.
+ */
+
+/**
+ * Append one {@link LegStart}: a resumed run's leg claim. Not locked: one short line, one append. THROWS on IO failure.
+ * @param {LegStart} entry
+ * @param {{ home?: string }} [opts]
+ * @returns {void}
+ */
+export function appendLegStart(entry, opts = {}) {
+  const path = runlistPath(opts.home);
+  mkdirSync(runlistHome(opts.home), { recursive: true, mode: 0o700 });
+  appendFileSync(path, `${JSON.stringify({ ...entry, type: 'leg-start' })}\n`);
+  try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
+}
+
+/**
+ * The leg a write-back names (absent = 1).
+ * @param {{ leg?: number }} e
+ * @returns {number}
+ */
+const legOf = (e) => (Number.isInteger(e.leg) && /** @type {number} */ (e.leg) >= 1 ? /** @type {number} */ (e.leg) : 1);
+
+/**
+ * Has this row's LATEST leg been settled? The ONE spelling (the monthly limit and the settle writer share it).
+ * @param {RunEvent[]} events {@link readRunList}'s `events`
+ * @param {{ runid: string, leg?: number }} row
+ * @returns {boolean}
+ */
+export function isSettled(events, row) {
+  const leg = legOf(row);
+  return events.some((e) => e.type === 'settled' && e.runid === row.runid && legOf(e) === leg);
+}
+
 /**
  * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
  * parser). An absent file reads as an empty list, not an error: a fresh
@@ -136,20 +179,45 @@ export function readRunList(opts = {}) {
   const path = runlistPath(opts.home);
   if (!existsSync(path)) return { rows: [], skipped: 0, events: [] };
   const { records, skipped } = parseJsonl(path);
-  // the FIRST settle for a runid is authoritative: two runs may both close the same dead claim, and the
+  // the FIRST settle for a (runid, leg) 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}`;
+    const key = `${r.type}:${r.runid}:${legOf(r)}`;
     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 };
+  // a leg-1 `released` = the run never started: not listed. A LATER leg's `released` only gives that leg's claim back.
+  const released = new Set(events.filter((e) => e.type === 'released' && legOf(e) === 1).map((e) => e.runid));
+  const voided = new Set(events.filter((e) => e.type === 'released' && legOf(e) > 1).map((e) => `${e.runid}:${legOf(e)}`));
+  /** @type {Map<string, RunRow & {claimAt: number}>} */
+  const byRunid = new Map();
+  /** @type {(RunRow & {claimAt: number})[]} */
+  const rows = [];
+  records.forEach((r, i) => {
+    if (!r) return;
+    if (!r.type) {
+      if (released.has(r.runid)) return;
+      const row = { ...r, claimAt: i };
+      rows.push(row);
+      if (!byRunid.has(r.runid)) byRunid.set(r.runid, row);
+    } else if (r.type === 'leg-start') {
+      const row = byRunid.get(r.runid);
+      if (!row || !Number.isInteger(r.leg) || r.leg < 2 || voided.has(`${r.runid}:${r.leg}`) || r.leg <= legOf(row)) return;
+      // the run's pid/cap are its LATEST leg's; the claim's place in the file (the monthly limit's "who is above
+      // whom") is that leg-start line's, since that is where the leg claimed
+      row.leg = r.leg;
+      row.pid = r.pid;
+      row.capUsd = r.capUsd;
+      row.claimAt = i;
+    }
+  });
+  // file order = claim order: a resumed run's latest claim sits where its latest leg-start line is
+  const ordered = rows.some((r) => r.leg !== undefined) ? [...rows].sort((a, b) => a.claimAt - b.claimAt) : rows;
+  return { rows: ordered.map(({ claimAt: _c, ...row }) => row), skipped, events };
 }
 
 /**

package/src/text.js

@@ -308,3 +308,23 @@ export function stampRaw(raw, { cause = null, reason = null }) {
   raw.reason = reason === null || reason === undefined ? null : redactSecrets(reason);
   return raw;
 }
+
+/**
+ * BA-21 — the WRITE side of the pricing-provenance signal (read side: `rateProvenance` /
+ * `spendProvenance` in src/ledger.js). bare-agent >=0.37 rides `rateSource` beside
+ * `pricing` on every metering payload; both metering callbacks below forward it onto the
+ * spine through THIS one helper, because two sites spelling one rule are two instruments
+ * (the ripgrep fix that landed in ci.yml but not publish.yml).
+ *
+ * Forwarded VERBATIM — the write side reports what upstream said, and src/ledger.js is
+ * the one place that decides what counts as a guess. And an ABSENT provenance stays
+ * absent: a payload carrying no `rateSource` (bare-agent <0.37, and every round already
+ * in the archive) emits no field at all, so a reader sees UNKNOWN rather than a label we
+ * invented. Never defaulted to `null` here — `null` is upstream saying "nothing was
+ * priced", which is a different fact from "nobody told us".
+ * @param {any} arg an `onLlmResult` / `onTurn` payload
+ * @returns {{rateSource?: string|null}} the field to spread into the spine record
+ */
+export function rateSourceFields(arg) {
+  return arg && typeof arg === 'object' && 'rateSource' in arg ? { rateSource: arg.rateSource } : {};
+}

package/src/u-readout.js

@@ -16,6 +16,8 @@
 // leads; the leg is what this process actually bought, and dropping it would trade
 // one blindness for the other.
 
+import { legsOf } from './legs.js';
+
 /** minutes, at the precision the readout has ever claimed (~90%, hamr's ruling) */
 const min = (/** @type {number} */ ms) => (ms / 60_000).toFixed(1);
 
@@ -336,10 +338,16 @@ export function doorLines({ rerun, accept, pause }) {
  */
 export function deathAtOf({ watchdogAt, events } = {}) {
   const list = Array.isArray(events) ? events : [];
+  // P5-R: a resumed run is one spine of several legs. "Did this run end itself" is a question about its
+  // LATEST leg: an earlier leg's job-end says nothing about how the leg now being read stopped, and a
+  // watchdog note dated before this leg began is a different leg's note.
+  const last = legsOf(list).at(-1) ?? null;
+  const scope = last ? last.records : list;
   // a landed terminal is the run dating its own stop — nothing outside it is better
   // evidence about a run that was never killed
-  if (list.some((e) => e !== null && typeof e === 'object' && /** @type {any} */ (e).type === 'job-end')) return null;
+  if (scope.some((e) => e !== null && typeof e === 'object' && /** @type {any} */ (e).type === 'job-end')) return null;
   const at = typeof watchdogAt === 'string' ? Date.parse(watchdogAt) : NaN;
+  if (last && last.leg > 1 && last.startMs !== null && Number.isFinite(at) && at < last.startMs) return null;
   // an unreadable stamp is UNKNOWN, never a NaN handed to a fold (F6): the caller's
   // own default is the honest fallback
   return Number.isFinite(at) ? at : null;

package/src/u-watchdog.mjs

@@ -43,7 +43,7 @@
 //
 // Usage:
 //   node src/u-watchdog.mjs --spine <path> --pid <n>
-//        [--stale-ms N] [--wall-ms N] [--grace-ms N] [--dead-ms N] [--poll-ms N] [--term-grace-ms N]
+//        [--stale-ms N] [--wall-ms N] [--grace-ms N] [--dead-ms N] [--poll-ms N] [--term-grace-ms N] [--report <path>]
 import { statSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
 
 const arg = (/** @type {string} */ n, /** @type {string|null} */ dflt = null) => {
@@ -215,7 +215,9 @@ function stop(/** @type {string} */ reason, /** @type {string} */ judgement, /**
   // not a guard (F70: the instrument carrying the failure mode it exists to catch). The
   // kill below runs whether or not this succeeded; a failure is named on stderr so a
   // missing marker is never read as "the guard never fired".
-  const reportPath = `${spine}.watchdog.json`;
+  // a RESUMED leg writes its own note beside the run's one spine (P5-R: `<spine>.leg<N>.watchdog.json`), so a
+  // later leg never overwrites the earlier leg's evidence; the default is the file every run has always had
+  const reportPath = arg('report') ?? `${spine}.watchdog.json`;
   const tmpPath = `${reportPath}.tmp`;
   try {
     writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`);