bareloop 0.33.0 → 0.35.0

package/types/runlist.d.ts

@@ -13,9 +13,12 @@ export function runlistHome(override?: string): string;
  */
 export function runlistPath(home?: string): string;
 /**
- * @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.
  */
 /**
  * Append one row to the run list, mkdir -p'ing the home directory first.
@@ -45,7 +48,10 @@ export function appendRun(row: RunRow, opts?: {
     reason?: "duplicate-runid";
 };
 /**
- * @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
@@ -61,6 +67,30 @@ export function appendRun(row: RunRow, opts?: {
 export function appendRunEvent(event: RunEvent, opts?: {
     home?: string;
 }): void;
+/**
+ * @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: LegStart, opts?: {
+    home?: string;
+}): void;
+/**
+ * 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: RunEvent[], row: {
+    runid: string;
+    leg?: number;
+}): boolean;
 /**
  * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
  * parser). An absent file reads as an empty list, not an error: a fresh
@@ -95,6 +125,20 @@ export function readRunList(opts?: {
  * @returns {boolean}
  */
 export function isLiveRunner(pid: number): boolean;
+/**
+ * The ONE "is this run alive" rule, for the panel's glyph ([▶] vs [?]) and the monthly limit's hold. A
+ * row that carries its runner's `pid` is alive exactly while that pid is a live bareloop runner
+ * ({@link isLiveRunner}) however quiet its spine; only a row with NO pid (an older row) falls back to
+ * the spine-mtime rule above. A run that has ENDED (a `job-end` on its spine) is a different fact the
+ * callers read off the spine itself — this answers "is a process still running it", nothing more.
+ * @param {{ pid?: number, spine: string }} row
+ * @param {number} [nowMs] the clock for the mtime fallback
+ * @returns {boolean}
+ */
+export function runIsAlive(row: {
+    pid?: number;
+    spine: string;
+}, nowMs?: number): boolean;
 /**
  * `bareloop runs backfill <dir>` — recursively scan `dir` (bounded to
  * {@link MAX_BACKFILL_DEPTH} levels, never into `node_modules`/`.git`,
@@ -146,6 +190,9 @@ export const MAX_BACKFILL_DEPTH: 6;
 /**
  * `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.
  */
 export type RunRow = {
     at: string;
@@ -156,8 +203,12 @@ export type RunRow = {
     via: "run-u" | "bundle" | "backfill";
     pid?: number;
     capUsd?: number;
+    leg?: number;
 };
 /**
+ * `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
@@ -172,4 +223,17 @@ export type RunEvent = {
     reason?: string;
     spentUsd?: number;
     spendComplete?: boolean;
+    leg?: number;
+};
+/**
+ * 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.
+ */
+export type LegStart = {
+    type: "leg-start";
+    runid: string;
+    leg: number;
+    pid?: number;
+    capUsd?: number;
+    at: string;
 };

package/types/text.d.ts

@@ -200,6 +200,25 @@ export function stampRaw<T extends {
     cause?: string | null;
     reason?: string | null;
 }): T;
+/**
+ * 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: any): {
+    rateSource?: string | null;
+};
 /**
  * The ceiling on ONE persisted raw. Sized to the survey's own prompt-ingredient
  * cap (`AUTHOR_SCOUT_BLOB_MAX`, 8000) rather than picked: the largest raw this