bareloop 0.34.0 → 0.36.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
@@ -160,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;
@@ -170,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
@@ -186,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/source.d.ts

@@ -71,19 +71,25 @@ export function looksLikeRepoSource(source: string): boolean;
  * as declared, unvalidated by `proveDestination`, and `frontDoorFromManifest`
  * never hands a repo source's destination to `copyOut` — wiring it into
  * `writeScope` is M3/M4's job, not this one.
- * @param {{source: string, into: string, destination?: string,
+ * `worktree` (P6 item 1, repo sources ONLY — ignored for every other kind): instead of COPYING the repo, make the
+ * run's tree a detached git worktree of the person's own repo at that directory (the shared
+ * `src/worktree.js`, the bundle door's own spelling), hide `.bareloop/` from their `git status`, and record the
+ * worktree and the repo root in the manifest. `into` then holds only `source.json`; the tree is `worktree`, at the
+ * repo's current commit (uncommitted edits are NOT in it). No seed commit is made — the seed IS the repo's HEAD.
+ * @param {{source: string, into: string, destination?: string, worktree?: string,
  *   fetchTimeoutMs?: number, afterScan?: () => (void|Promise<void>)}} args
  *   `fetchTimeoutMs` is test-only — production callers omit it and get
  *   `PROVIDER_TIMEOUT_MS`. `afterScan` is a test seam too: called exactly once,
  *   after the secret scan finished and before the freeze loop re-reads any
  *   file's bytes, so a test can swap a file inside that window
  *   deterministically. Production never sets it; absent, behaviour is unchanged.
- * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: object}|SourceRefusal>}
+ * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: Record<string, any>}|SourceRefusal>}
  */
-export function prepareSource({ source, into, destination, fetchTimeoutMs, afterScan }: {
+export function prepareSource({ source, into, destination, worktree, fetchTimeoutMs, afterScan }: {
     source: string;
     into: string;
     destination?: string;
+    worktree?: string;
     fetchTimeoutMs?: number;
     afterScan?: () => (void | Promise<void>);
 }): Promise<{
@@ -91,7 +97,7 @@ export function prepareSource({ source, into, destination, fetchTimeoutMs, after
     into: string;
     tree: string;
     manifestPath: string;
-    manifest: object;
+    manifest: Record<string, any>;
 } | SourceRefusal>;
 /**
  * THE INSTALL-GAP DETECTOR (PRD item 33 close-out, `docs/product/PRD.md:450-452`,
@@ -127,13 +133,15 @@ export function prepareSource({ source, into, destination, fetchTimeoutMs, after
  *   manifest)
  * @param {string} [sourceSubdir] the manifest's own `sourceSubdir` ('' or
  *   undefined when Source IS the repo root)
- * @returns {{manager: string, command: string, reason: string}|null} `null`
+ * @returns {{dir: string, lockFile: string|null, manager: string, command: string, reason: string}|null} `null`
  *   when there is nothing to report: no JS/TS manifest found walking up from
  *   `sourceSubdir` to `treeDir`, the nearest one found has no dependencies,
  *   `node_modules` is already there, or the manifest cannot even be read as
  *   JSON (an invalid `package.json` is "cannot tell", never a false alarm).
  */
 export function missingDependencies(treeDir: string, sourceSubdir?: string): {
+    dir: string;
+    lockFile: string | null;
     manager: string;
     command: string;
     reason: 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

package/types/userrun.d.ts

@@ -129,6 +129,12 @@ export type RunOpts = {
      * the spine directory name, beside `workdir`
      */
     spineName?: string | undefined;
+    /**
+     * the source door's own directory (`source.json`, and the spine directory beside it).
+     * Default `dirname(workdir)` — the copied-tree layout, where the tree is `<into>/tree`. A repo job on a WORKTREE
+     * (P6 item 1) has its tree inside the person's repo, so its `into` is passed explicitly.
+     */
+    into?: string | undefined;
     /**
      * the raw `--model` tier name (`sonnet`/`haiku`), or null for the default
      */
@@ -194,6 +200,10 @@ export type RunCtx = {
     workdir: string;
     seed: string;
     spineName: string;
+    /**
+     * see `RunOpts.into`
+     */
+    into?: string | undefined;
     model: string | null;
     readShim: string | null;
     scout: string | null;

package/types/worktree.d.ts

@@ -0,0 +1,48 @@
+/** where a run's worktree lives in the person's repo @param {string} repo @param {string} id */
+export function worktreePath(repo: string, id: string): string;
+/**
+ * `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: string, dir: string): void;
+/**
+ * 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: string): number;
+/** the short sha of `repo`'s HEAD, or null @param {string} repo @returns {string|null} */
+export function shortHead(repo: string): string | 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: string): boolean;
+/**
+ * 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: string, dir: string): boolean;
+/**
+ * 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: string, message: string): {
+    committed: boolean;
+    sha: string;
+};
+/** 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/";