bareloop 0.34.0 → 0.36.0

package/src/worktree.js

@@ -0,0 +1,120 @@
+// The ONE spelling of "a run's tree is a git worktree inside the person's own repo"
+// (`<repo>/.bareloop/wt/<id>`, detached at the repo's HEAD). Two doors make that tree: the bundle runner
+// (`src/bundlerun.js`) and the panel's drafting session (`src/panel/authorsession.js`, through the source
+// door's `worktree` option). Neither carries its own copy of the `git worktree add` call.
+//
+// Plain git, no dependency. Every helper takes the repo ROOT (the directory whose `.git` is the real
+// repository), never a subfolder.
+
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** the line that hides bareloop's own folder from the person's `git status` (anchored at the repo root) */
+export const EXCLUDE_LINE = '/.bareloop/';
+
+/** the line that hides installed packages at any depth */
+export const NODE_MODULES_LINE = 'node_modules/';
+
+/** the person's git hooks never run for anything bareloop does in their repo: one spelling, used by `addWorktree` and `commitWork` */
+const NO_HOOKS = ['-c', 'core.hooksPath=/dev/null/bareloop-no-hooks'];
+
+/** where a run's worktree lives in the person's repo @param {string} repo @param {string} id */
+export function worktreePath(repo, id) {
+  return join(repo, '.bareloop', 'wt', id);
+}
+
+/**
+ * `git worktree add --detach <dir> HEAD` in `repo` (none of the person's hooks run), creating `dir`'s parent first. Throws
+ * `Error('git worktree add failed: …')` — a caller decides whether that is a stop or a refusal.
+ * @param {string} repo @param {string} dir
+ */
+export function addWorktree(repo, dir) {
+  mkdirSync(dirname(dir), { recursive: true });
+  try {
+    execFileSync('git', [...NO_HOOKS, '-C', repo, 'worktree', 'add', '--detach', dir, 'HEAD'], { encoding: 'utf8' });
+  } catch (e) {
+    throw new Error(`git worktree add failed: ${/** @type {Error} */ (e).message}`);
+  }
+}
+
+/**
+ * How many paths `git status --porcelain` lists in `repo` (tracked edits AND untracked files); 0 for a clean
+ * tree. A repo git cannot read counts as 0 — this feeds a notice, never a refusal.
+ * @param {string} repo @returns {number}
+ */
+export function uncommittedCount(repo) {
+  try {
+    const out = execFileSync('git', ['-C', repo, 'status', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split('\n').filter((l) => l.trim() !== '').length;
+  } catch { return 0; }
+}
+
+/** the short sha of `repo`'s HEAD, or null @param {string} repo @returns {string|null} */
+export function shortHead(repo) {
+  try {
+    return execFileSync('git', ['-C', repo, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * Hide `.bareloop/` and `node_modules/` (packages installed in a worktree must not read as worker writes) from the person's own `git status` through the repo's PRIVATE exclude file
+ * (`<common-git-dir>/info/exclude`), never their tracked `.gitignore`. The common dir, not `.git`: in a linked
+ * worktree `.git` is a file and the shared `info/exclude` lives in the main repository's git dir. Idempotent —
+ * each line is checked separately and never written twice.
+ * @param {string} repo
+ * @returns {boolean} true when the line was added now
+ */
+export function hideBareloopDir(repo) {
+  const common = execFileSync('git', ['-C', repo, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  const exclude = join(resolve(repo, common), 'info', 'exclude');
+  mkdirSync(dirname(exclude), { recursive: true });
+  const text = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+  const have = new Set(text.split('\n').map((l) => l.trim()));
+  const missing = [EXCLUDE_LINE, NODE_MODULES_LINE].filter((l) => !have.has(l));
+  if (missing.length === 0) return false;
+  const add = `${missing.join('\n')}\n`;
+  if (text === '') writeFileSync(exclude, add);
+  else appendFileSync(exclude, `${text.endsWith('\n') ? '' : '\n'}${add}`);
+  return true;
+}
+
+/**
+ * Remove a run's worktree folder from `repo` (`git worktree remove --force`: the folder may hold untracked
+ * scratch — a `.litectx/` index, the gate-audit file — and what matters is on the branch by now). Never throws.
+ * @param {string} repo @param {string} dir
+ * @returns {boolean} true when the folder is gone afterwards
+ */
+export function removeWorktree(repo, dir) {
+  try {
+    execFileSync('git', ['-C', repo, 'worktree', 'remove', '--force', dir], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch { /* fall through: report what is on disk */ }
+  return !existsSync(dir);
+}
+
+/** a commit bareloop makes in the person's repo is authored by bareloop (never their global config), signs nothing, runs none of their hooks */
+const COMMIT_CONFIG = [
+  '-c', 'user.name=bareloop', '-c', 'user.email=bareloop@localhost', '-c', 'commit.gpgsign=false',
+  ...NO_HOOKS,
+];
+
+/** what never goes into the work commit: the arbiter's own books and installed packages */
+const NOT_WORK = [':(exclude).smoke', ':(exclude).litectx', ':(exclude)gate-audit.jsonl', ':(exclude,glob)**/node_modules/**'];
+
+/**
+ * The run's final commit, on whatever branch the worktree stands on: everything the run changed except the
+ * arbiter's books and `node_modules`. Nothing changed = no commit (a green with nothing to commit is still a green).
+ * Throws on a git failure — the caller must not remove a worktree whose work is not safely on the branch.
+ * @param {string} dir the worktree
+ * @param {string} message
+ * @returns {{committed: boolean, sha: string}}
+ */
+export function commitWork(dir, message) {
+  const run = (/** @type {string[]} */ args) => execFileSync('git', ['-C', dir, ...COMMIT_CONFIG, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  run(['add', '-A', '--', '.', ...NOT_WORK]);
+  const staged = run(['diff', '--cached', '--name-only']).trim();
+  if (staged !== '') run(['commit', '-q', '-m', message]);
+  return { committed: staged !== '', sha: run(['rev-parse', '--short', 'HEAD']).trim() };
+}

package/types/draftspend.d.ts

@@ -0,0 +1,141 @@
+/**
+ * One line of the drafting log. `no` = the step's position in the session's progress list (a step id can repeat).
+ *  - `step-start`  {no, id, label, at}
+ *  - `step-end`    {no, status: 'done'|'failed', label, at}   (a re-opened step writes `step-reopen` {no, at} first)
+ *  - `call`        {no, step, label, model, costUsd (null stays null), unpricedRounds, at}: one METERED model call
+ *    (no token counts: the call path does not carry them without reworking the library, so none are recorded)
+ * @typedef {{kind: string, no: number, at: string, [k: string]: any}} DraftEvent
+ */
+/**
+ * Append one event to `<dir>/draft-log.jsonl`. Best-effort like draft-spend.json: a disk fault never stops the draft.
+ * @param {string} dir the session's folder
+ * @param {DraftEvent} ev
+ * @returns {void}
+ */
+export function appendDraftLog(dir: string, ev: DraftEvent): void;
+/**
+ * @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: string, rec: DraftSpend): void;
+/**
+ * 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?: {
+    home?: string;
+    sessionsRoot?: string;
+}): DraftSpend[];
+/**
+ * The session folder a run-list row became a run in: the folder under `<home>/panel-sessions` that carries a drafting
+ * log and holds the row's `spine` or `patient` ("became a run", the same rule as {@link readOrphanDraftSpends}).
+ * A Reuse-workflow run, a CLI run and an imported run sit in no such folder.
+ * @param {{spine?: string, patient?: string|null}} row
+ * @param {{ home?: string, sessionsRoot?: string }} [opts]
+ * @returns {string|null}
+ */
+export function sessionDirForRow(row: {
+    spine?: string;
+    patient?: string | null;
+}, opts?: {
+    home?: string;
+    sessionsRoot?: string;
+}): string | null;
+/**
+ * Fold `<dir>/draft-log.jsonl` into one record per drafting step, each with its calls. A line that cannot be parsed is
+ * skipped (a torn last line must not hide the rest).
+ * @param {string} dir
+ * @returns {{no: number, id: string, label: string, status: 'running'|'done'|'failed', startedAt: string, endedAt: string|null, wallMs: number|null,
+ *   calls: {label: string, model: string|null, costUsd: number|null, unpricedRounds: number, at: string}[]}[]}
+ */
+export function readDraftSteps(dir: string): {
+    no: number;
+    id: string;
+    label: string;
+    status: "running" | "done" | "failed";
+    startedAt: string;
+    endedAt: string | null;
+    wallMs: number | null;
+    calls: {
+        label: string;
+        model: string | null;
+        costUsd: number | null;
+        unpricedRounds: number;
+        at: string;
+    }[];
+}[];
+/**
+ * The DRAFTING PART of a run (hamr 2026-10-06, option A): the first part of the run's views, built from the session's
+ * drafting log. `null` when the run did not come out of a panel session, or the log carries no metered call (a Reuse
+ * workflow run, a CLI run, a run older than the log). The part's money is the SPINE's figure (`job-start.draftSpentUsd`,
+ * passed in) — the log's calls are shown beside it, never summed into a second total; `null` spine figure = no part.
+ * @param {{spine?: string, patient?: string|null}} row
+ * @param {{draftSpentUsd: number|null, draftSpendComplete: boolean|null}} spine the run's own drafting figures
+ * @param {{ home?: string, sessionsRoot?: string }} [opts]
+ * @returns {any|null}
+ */
+export function draftingPartFor(row: {
+    spine?: string;
+    patient?: string | null;
+}, spine: {
+    draftSpentUsd: number | null;
+    draftSpendComplete: boolean | null;
+}, opts?: {
+    home?: string;
+    sessionsRoot?: string;
+}): any | null;
+export const DRAFT_SPEND_FILE: "draft-spend.json";
+/** the session's drafting LOG: an append-only JSONL beside draft-spend.json (one owner: the session, src/panel/authorsession.js). Three event kinds, see {@link DraftEvent}. */
+export const DRAFT_LOG_FILE: "draft-log.jsonl";
+/**
+ * One line of the drafting log. `no` = the step's position in the session's progress list (a step id can repeat).
+ *  - `step-start`  {no, id, label, at}
+ *  - `step-end`    {no, status: 'done'|'failed', label, at}   (a re-opened step writes `step-reopen` {no, at} first)
+ *  - `call`        {no, step, label, model, costUsd (null stays null), unpricedRounds, at}: one METERED model call
+ *    (no token counts: the call path does not carry them without reworking the library, so none are recorded)
+ */
+export type DraftEvent = {
+    kind: string;
+    no: number;
+    at: string;
+    [k: string]: any;
+};
+export type DraftSpend = {
+    sessionId: string;
+    /**
+     * the known floor of the session's drafting spend
+     */
+    spentUsd: number;
+    /**
+     * false = `spentUsd` is a floor ("at least")
+     */
+    spendComplete: boolean;
+    /**
+     * the worker's provider shape (`anthropic-api` | `openai-api` | ...)
+     */
+    provider: string | null;
+    baseUrl: string | null;
+    model: string | null;
+    /**
+     * ISO, the first metered call
+     */
+    startedAt: string;
+    /**
+     * ISO, the latest metered call
+     */
+    updatedAt: string;
+};

package/types/job.d.ts

@@ -93,6 +93,17 @@ export function checkMenu(close: any[]): {
  * @returns {string} sha256 hex
  */
 export function jobSpecHash(job: object): string;
+/**
+ * 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: object): string;
 /**
  * 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
@@ -259,6 +270,20 @@ export const PROVIDERS: readonly string[];
  * candidate at N3. `provider` is part of the key by definition (top-level,
  * not duplicated here). */
 export const CONDITION_KEYS: readonly string[];
+/**
+ * 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: readonly string[];
+/**
+ * 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: readonly string[];
 /**
  * — `verb` and `lib` ride request-reds as structured data (the ledger keys on them, never on prose).
  * `lib` is the TERRITORY the demand lands against, stamped HERE at the emit site

package/types/ledger.d.ts

@@ -95,6 +95,50 @@ export function floorsFromRecords(records: any[]): {
     spendFloorUsd: number | null;
     wallFloorMs: number | null;
 };
+/**
+ * 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: any[], { withDraft }?: {
+    withDraft?: boolean;
+}): {
+    usd: number;
+    complete: boolean;
+};
+/**
+ * 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: any[], o?: {
+    withDraft?: boolean;
+}): {
+    usd: number;
+    complete: boolean;
+    lastLegUsd: number;
+};
+/**
+ * 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: any[]): {
+    usd: number;
+    complete: boolean;
+};
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES: readonly string[];
 /**

package/types/legs.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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: any[]): Leg[];
+/**
+ * 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: Leg[]): {
+    ms: number | null;
+    complete: boolean;
+};
+/**
+ * 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: string): {
+    records: any[];
+    tolerated: {
+        line: number;
+        why: "tail" | "before-leg-resume";
+    }[];
+    corrupt: {
+        line: number;
+        message: string;
+    } | null;
+};
+/**
+ * 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: string, leg: number): string;
+/**
+ * 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 round seam of a step worker (src/planrun.js `metered`) 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: string): string;
+/** The marker record's `type`. */
+export const LEG_RESUME: "leg-resume";
+export type Leg = {
+    /**
+     * 1-based position in file order (the marker's own `leg` field is never trusted over the order)
+     */
+    leg: number;
+    /**
+     * the leg's first record (the `leg-resume` marker for leg 2+; the file's first record for leg 1)
+     */
+    start: any | null;
+    /**
+     * the leg's last record
+     */
+    end: any | null;
+    /**
+     * every record of the leg, in file order, marker included
+     */
+    records: any[];
+    /**
+     * the leg's own `job-start` (null: it ended before runJob wrote one)
+     */
+    jobStart: any | null;
+    /**
+     * the leg's own LAST `job-end` (null: it died, or it is still running)
+     */
+    jobEnd: any | null;
+    /**
+     * the leg's terminal: its `job-end` outcome, else a `run-end` outcome (a $0 refusal), else null
+     */
+    outcome: string | null;
+    /**
+     * 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
+     */
+    after: string | null;
+    /**
+     * `Date.parse` of the start record's `ts`
+     */
+    startMs: number | null;
+    /**
+     * `Date.parse` of the end record's `ts`
+     */
+    endMs: number | null;
+};

package/types/monthly.d.ts

@@ -1,18 +1,8 @@
-/**
- * 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
- * @returns {{ usd: number, complete: boolean }}
- */
-export function legSpend(records: any[]): {
-    usd: number;
-    complete: boolean;
-};
 /**
  * One run's wall time off its spine: job-start -> job-end when the run ended (exact), else the
  * first -> last record floor (the SAME floor a died / still-running run's "at least" wall uses,
  * `floorsFromRecords`). `ms` null = unknown — never 0.
- * @param {any[]} records
+ * @param {any[]} records one spine's records (one leg or several)
  * @returns {{ ms: number|null, complete: boolean }}
  */
 export function legWall(records: any[]): {
@@ -29,21 +19,23 @@ export function legTokens(records: any[]): number;
 /**
  * Every listed run as one {@link Leg}. The ONE reader the month total, the all-time total
  * and the per-provider figures share.
- * @param {{ home?: string, now?: () => number, aboveRunid?: string, thisMonthOnly?: boolean }} [opts] `now` = the clock for the no-pid in-flight test; `aboveRunid` = read only the runs listed EARLIER in the file than that run (a claim yields to the claims above it, never below); `thisMonthOnly` = do not parse the spine of a run listed in another local month (the refusal check drops it anyway) unless its claim is still held
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string, thisMonthOnly?: boolean }} [opts] `sessionsRoot` = where the panel's sessions live (default `<home>/panel-sessions`); `now` = the clock for the no-pid in-flight test; `aboveRunid` = read only the runs listed EARLIER in the file than that run (a claim yields to the claims above it, never below); `thisMonthOnly` = do not parse the spine of a run listed in another local month (the refusal check drops it anyway) unless its claim is still held
  * @returns {Leg[]}
  */
 export function readLegs(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
     thisMonthOnly?: boolean;
 }): Leg[];
 /**
- * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`: see {@link readLegs}
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`, `sessionsRoot`: see {@link readLegs}
  * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number, heldUsd: number, heldRuns: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's); `heldUsd` = what in-progress runs set aside beyond what they have spent (`reservedUsd - usd`), over `heldRuns` runs
  */
 export function monthSpend(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
 }): {
@@ -59,12 +51,13 @@ export function monthSpend(opts?: {
  * (rows from `rowIdFor`; a run on no known row lands under its own provider name, never
  * pooled into another row). Any leg with unknown spend makes the figure it belongs to
  * an "at least".
- * @param {{ home?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
+ * @param {{ home?: string, sessionsRoot?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
  * @returns {{ tokensByRow: Record<string, number>, total: {usd: number, atLeast: boolean, tokens: number}, month: {usd: number, atLeast: boolean, tokens: number},
  *   byProvider: Record<string, {label: string, monthUsd: number, monthAtLeast: boolean, totalUsd: number, totalAtLeast: boolean, tokens: number, vouchedRounds: number, otherRounds: number, monthWallMs: number|null, monthWallAtLeast: boolean, totalWallMs: number|null, totalWallAtLeast: boolean}> }}
  */
 export function spendSummary(opts?: {
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     rows?: readonly import("./providerrows.js").KeyRow[];
 }): {
@@ -117,12 +110,13 @@ export function monthlyLimitOf(config: Record<string, any>, home?: string): numb
  * number above 0 throws `ConfigError`.
  * Compared in whole cents. Also throws `ConfigError` when config.json is unreadable — a gate
  * whose own instrument is broken refuses; it never silently runs with no limit.
- * @param {{ capUsd: number, home?: string, now?: () => number, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
+ * @param {{ capUsd: number, home?: string, sessionsRoot?: string, now?: () => number, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
  * @returns {MonthlyRoom}
  */
-export function checkMonthlyRoom({ capUsd, home, now, aboveRunid }: {
+export function checkMonthlyRoom({ capUsd, home, now, aboveRunid, sessionsRoot }: {
     capUsd: number;
     home?: string;
+    sessionsRoot?: string;
     now?: () => number;
     aboveRunid?: string;
 }): MonthlyRoom;
@@ -154,14 +148,17 @@ export function settleDeadClaims({ home, by, aboveRunid }: {
  * it appends `{type:'released', reason:'refused'}` and reports the refusal, nothing spent. No limit set =
  * no claim (`claimed: false`; the caller lists the run as it always did). An unreadable config, or a row
  * that cannot be written, throws `ConfigError` — the gate refuses, never reads "no limit".
- * @param {{ row: import('./runlist.js').RunRow, capUsd: number, home?: string, now?: () => number }} args
+ * A RESUMED leg (`leg` 2+, P5-R) claims the same way but appends a `leg-start` beside the run's one row
+ * (the row itself is added only when the list has none), and a refusal gives back THAT leg's claim.
+ * @param {{ row: import('./runlist.js').RunRow, capUsd: number, home?: string, now?: () => number, leg?: number }} args
  * @returns {{ room: MonthlyRoom, claimed: boolean }}
  */
-export function claimRun({ row, capUsd, home, now }: {
+export function claimRun({ row, capUsd, home, now, leg }: {
     row: import("./runlist.js").RunRow;
     capUsd: number;
     home?: string;
     now?: () => number;
+    leg?: number;
 }): {
     room: MonthlyRoom;
     claimed: boolean;
@@ -213,6 +210,10 @@ export type Leg = {
      * the spine was missing/unreadable or the listed date was bad (spend unknown)
      */
     unreadable: boolean;
+    /**
+     * drafting spend of a panel session that never became a run (src/draftspend.js) — not a run: no wall, not counted in `runs`
+     */
+    draft?: boolean | undefined;
 };
 export type MonthlyRoom = {
     ok: boolean;
@@ -237,3 +238,7 @@ export type MonthlyRoom = {
      */
     heldRuns?: number | undefined;
 };
+import { legSpend } from './ledger.js';
+import { runSpend } from './ledger.js';
+import { chainSpend } from './ledger.js';
+export { legSpend, runSpend, chainSpend };

package/types/movefile.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param {string} src
+ * @param {string} dst
+ * @param {{ rename?: (a: string, b: string) => void }} [deps] test seam: the rename to try first
+ * @returns {void}
+ */
+export function moveFile(src: string, dst: string, deps?: {
+    rename?: (a: string, b: string) => void;
+}): void;

package/types/npminstall.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The env npm sees: the panel's own env minus every credential `CLOSE_ENV_DENY` names (never re-spelled).
+ * `npm ci` needs no provider key; a private registry token (NPM_TOKEN) is stripped too, so such a repo
+ * simply falls back to the person's own install.
+ * @param {NodeJS.ProcessEnv} base
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function npmEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Run `npm ci --ignore-scripts` in `cwd`. Async (never blocks the panel's event loop); argv array, no shell.
+ * @param {string} cwd the directory holding package.json + the lock file
+ * @param {{timeoutMs?: number, env?: NodeJS.ProcessEnv, run?: typeof spawnClose}} [o] `run` is the test seam
+ * @returns {Promise<{ok: true}|{ok: false, reason: string}>}
+ */
+export function runNpmCi(cwd: string, { timeoutMs, env, run }?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    run?: typeof spawnClose;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Wall-clock cap for one `npm ci`: 10 minutes. A cold install of a large repo is minutes, never an hour;
+ * past this the person is better served by the printed command in their own terminal. Operator-set. */
+export const NPM_CI_TIMEOUT_MS: 600000;
+/** the lock files whose gap command is `npm ci` (the rule table in src/source.js, LOCKFILE_COMMANDS) */
+export const NPM_CI_LOCKS: readonly string[];
+import { spawnClose } from './ralph.js';

package/types/panel/authorroutes.d.ts

@@ -40,7 +40,8 @@ export function checkHumanGuard(req: import("node:http").IncomingMessage, { toke
  * deliberately has none of).
  * @param {{ port: number, token: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: typeof realSpawn, bareloopBin?: string,
- *   jobsDir?: string, fetchImpl?: typeof fetch, home?: string }} opts
+ *   jobsDir?: string, fetchImpl?: typeof fetch, home?: string,
+ *   startFrom?: {get: (runid: string, o?: {model?: string}) => any, getImport: (id: string, o?: {model?: string}) => any} }} opts
  */
 export function createAuthorRoutes(opts: {
     port: number;
@@ -52,10 +53,31 @@ export function createAuthorRoutes(opts: {
     jobsDir?: string;
     fetchImpl?: typeof fetch;
     home?: string;
+    startFrom?: {
+        get: (runid: string, o?: {
+            model?: string;
+        }) => any;
+        getImport: (id: string, o?: {
+            model?: string;
+        }) => any;
+    };
 }): {
     handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
     sessions: Map<string, any>;
 };
+/**
+ * The panel's OWN 2-decimal money render for a chat line — hamr's ruling
+ * 2026-09-28 (2nd addendum, panel money 2-decimals): a positive amount below
+ * a cent reads `<$0.01`, never `$0.00` (a real cost must never read as
+ * free). This is the server-side (Node, chat-text) sibling of
+ * `src/panel/index.html`'s own inline `panelMoney` — the two can't share
+ * code (one runs in the browser as inlined script, the other in Node), the
+ * same duplication `src/replay.js`'s `money()`/`index.html`'s `money()`
+ * already carry, so both apply the identical rule rather than drift.
+ * @param {number} n a non-negative dollar amount
+ * @returns {string}
+ */
+export function panelMoney2(n: number): string;
 /**
  * THE ONLY function in this file (or anywhere in the panel) that spawns a
  * run. Refuses unless the session is `prepared` AND the hash the request