bareloop 0.32.0 → 0.33.0

package/types/bundlerun.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`
+ * `bareloop run <bundleDir> --resume <runid> [--repo <path>] [--budget N] [--wall MIN] [--approve <bundleHash>]`
+ * @param {string[]} args
+ * @param {{
+ *   out: (s: string) => void, err: (s: string) => void, cwd: string,
+ *   env: Record<string,string|undefined>, now: () => number, deps: any, keysHome?: string,
+ *   parseFlags: (a: string[]) => { positional: string[], flags: Record<string, string|true> },
+ *   printReds: (reds: import('./bundle.js').Red[], err: (s: string) => void) => void,
+ * }} ctx
+ * @returns {Promise<number>}
+ */
+export function bundleMain(args: string[], { out, err, cwd, env, now, deps, keysHome, parseFlags, printReds, }: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    now: () => number;
+    deps: any;
+    keysHome?: string;
+    parseFlags: (a: string[]) => {
+        positional: string[];
+        flags: Record<string, string | true>;
+    };
+    printReds: (reds: import("./bundle.js").Red[], err: (s: string) => void) => void;
+}): Promise<number>;

package/types/invoke.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The command that runs `flow`, spelled the way the caller reached this flow: `bareloop <flow>`
+ * when `invokedAs` names the CLI, else the source-tree script.
+ * @param {Flow} flow @param {string|undefined} invokedAs
+ * @returns {string}
+ */
+export function commandFor(flow: Flow, invokedAs: string | undefined): string;
+export type Flow = "run-u" | "interview" | "author";

package/types/judged.d.ts

@@ -382,9 +382,13 @@ export const JUDGE_RULE_IDS: readonly string[];
 export const CALIBRATION_SIZE: 10;
 /** the two verdicts a case may expect — `decide()`'s own closed set */
 export const CASE_VERDICTS: readonly string[];
-export function defaultJudgeLoop({ provider, system }: {
+export function defaultJudgeLoop({ provider, system, rates }: {
     provider: any;
     system: string;
+    rates?: {
+        in: number;
+        out: number;
+    } | null;
 }): import("bare-agent").Loop;
 export type RuleRed = {
     fn: string;

package/types/monthly.d.ts

@@ -29,22 +29,22 @@ 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, resumingSpine?: string|null }} [opts] `now` = the clock for the in-flight test; `resumingSpine` = the spine a resume continues: that leg reserves its spend only, never its unspent cap (the resume's own leg cap is that remainder)
+ * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [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)
  * @returns {Leg[]}
  */
 export function readLegs(opts?: {
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
 }): Leg[];
 /**
- * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `resumingSpine`: see {@link readLegs}
+ * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`: see {@link readLegs}
  * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's)
  */
 export function monthSpend(opts?: {
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
 }): {
     usd: number;
     atLeast: boolean;
@@ -108,18 +108,18 @@ export function spendSummary(opts?: {
  */
 export function monthlyLimitOf(config: Record<string, any>, home?: string): number | null;
 /**
- * Does a run with this $ cap fit in what is left this month (running jobs counted at their full cap, except the spine a resume continues — `resumingSpine` — which counts its real spend)? No limit set (key absent or null) = ok, no check; a limit that is present but not a
+ * Does a run with this $ cap fit in what is left this month (a run still held counts at its full cap)? No limit set (key absent or null) = ok, no check; a limit that is present but not a
  * 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, resumingSpine?: string|null }} args
+ * @param {{ capUsd: number, home?: 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, resumingSpine }: {
+export function checkMonthlyRoom({ capUsd, home, now, aboveRunid }: {
     capUsd: number;
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
 }): MonthlyRoom;
 /**
  * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal).
@@ -127,6 +127,40 @@ export function checkMonthlyRoom({ capUsd, home, now, resumingSpine }: {
  * @returns {string|null} null when the run fits
  */
 export function monthlyRefusalText(room: MonthlyRoom): string | null;
+/**
+ * Close every claim ABOVE `aboveRunid` (file order) whose process is gone: a pid-bearing run row with no
+ * `settled` entry whose pid is not a live bareloop runner gets `{ type: 'settled', by: <closer>, reason:
+ * 'process gone', spentUsd: <its spine's floor>, spendComplete: false }` appended — so every claim gets a
+ * write-back, attributed. Two runs may both close the same dead claim; readers take the FIRST note.
+ * @param {{ home?: string, by: string, aboveRunid?: string }} args `by` = the run doing the closing
+ * @returns {number} how many notes were appended
+ */
+export function settleDeadClaims({ home, by, aboveRunid }: {
+    home?: string;
+    by: string;
+    aboveRunid?: string;
+}): number;
+/**
+ * The CLAIM (hamr 2026-09-30: whoever runs first claims the limit and holds it; no lock file, records
+ * only): the run APPENDS its row first (`row` carries its `pid` and `capUsd`), then reads the run list.
+ * Only the claims ABOVE its own row count — a live one is held at its cap (a dead one is closed with an
+ * attributed note and counts its real spend); rows below yield to it. If `capUsd` fits, it runs; if not
+ * 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
+ * @returns {{ room: MonthlyRoom, claimed: boolean }}
+ */
+export function claimRun({ row, capUsd, home, now }: {
+    row: import("./runlist.js").RunRow;
+    capUsd: number;
+    home?: string;
+    now?: () => number;
+}): {
+    room: MonthlyRoom;
+    claimed: boolean;
+};
+export { isLiveRunner };
 export type Leg = {
     /**
      * when the run was listed
@@ -190,3 +224,4 @@ export type MonthlyRoom = {
      */
     atLeast: boolean;
 };
+import { isLiveRunner } from './runlist.js';

package/types/planrun.d.ts

@@ -195,6 +195,10 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   `false` → the drafter has no tools, so a native session would report NO cost — return a
  *   metered claude-json TEXT provider (`--output-format json`, `parse:'claude-json'`) instead,
  *   so its spend is never invisible. The Loop path (`anthropic-api`) never touches this.
+ * @param {{in: number, out: number}|null} [opts.rates] the customer's own price for the worker's key row (USD per
+ *   1K tokens, `ratesFor`) — handed to the one Loop that drives worker, scout and planner rounds, so they read
+ *   `rateSource:'caller'`; null = bare-agent's built-in guess. Not applied to a native (CLI) session, which reports its own cost.
+ * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's Loop
  * @param {string|null} [opts.judgeModel] softgreen — WHICH model that judge provider drives
  *   (PRD item 32.1). Resolved by the CALLER (`resolveJudge`, src/judged.js: the spec's signed
  *   `judge` override, else the job's own worker model), never pinned in this library. It
@@ -416,7 +420,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -425,6 +429,14 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         maxTurns: number;
         hasTools: boolean;
     }) => any) | undefined;
+    rates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
+    judgeRates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
     judgeModel?: string | null | undefined;
     judgeProvider?: any;
     emit: (type: string, data?: object) => object;

package/types/providerrows.d.ts

@@ -23,6 +23,9 @@ export function defaultsFor(envName: string): {
  * @property {string} name the model id Chat uses ('' = not offered in Chat)
  * @property {string} provider the `src/providers.js` table entry (the API shape's id)
  * @property {string} baseUrl the saved Base URL ('' = the shape's default host)
+ * @property {unknown} [priceInPerM] the customer's own price, USD per 1M input tokens — carried RAW
+ *   (present only when the config row names it); {@link ratesFor} is the one place that validates it
+ * @property {unknown} [priceOutPerM] the same, for output tokens
  */
 /**
  * The rows: one per name in `filled`, saved entry over defaults.
@@ -122,6 +125,59 @@ export function keyNameFor(provider: string | null | undefined, baseUrl: string
  * @returns {Record<string,string|undefined>}
  */
 export function applyConfiguredKey(env: Record<string, string | undefined>, provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): Record<string, string | undefined>;
+/**
+ * The one readout line for a resolved customer price, preview and run tail alike:
+ * `yours: in $0.006 / out $1.20 per 1M tokens (DEEPSEEK_API_KEY row)`.
+ * @param {{ inPerM: number, outPerM: number, envName: string }} price a {@link ratesFor} result
+ * @returns {string}
+ */
+export function priceReadout(price: {
+    inPerM: number;
+    outPerM: number;
+    envName: string;
+}): string;
+/**
+ * The customer's own price for the row a `(provider, baseUrl[, model])` identity belongs to —
+ * the SAME row match {@link keyNameFor} uses (`findRow`), so the price and the key always come
+ * from one row. `null` = no price set (the run keeps bare-agent's built-in guess, byte-identical
+ * to before). Both fields or neither, each a finite number >= 0, USD per 1M tokens; anything
+ * else throws `ConfigError` naming the row and field — a bad price never silently falls back to
+ * the guess. `rates` is bare-agent's `Loop({ rates })` shape (USD per 1K); `inPerM`/`outPerM`
+ * are what a readout prints.
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ rates: { in: number, out: number }, inPerM: number, outPerM: number, envName: string }|null}
+ */
+export function ratesFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
+    rates: {
+        in: number;
+        out: number;
+    };
+    inPerM: number;
+    outPerM: number;
+    envName: string;
+} | null;
+/**
+ * The price a judge's rounds are booked at. A price belongs to the MODEL's row: when the judge is
+ * the worker's own provider it calls the worker's endpoint, so a row on that endpoint NAMED for the
+ * judge's model prices it ({@link ratesFor}); a judge model that is absent or names no row there
+ * keeps the worker's price (the worker's row, or none = the guess). A different provider resolves
+ * on its own default endpoint, as before. A bad price on the resolved row throws like `ratesFor`.
+ * The judge's KEY is chosen elsewhere (`applyConfiguredKey`, by the worker's model), so the two
+ * can come from different rows — same provider + endpoint, judge model naming another row.
+ * @param {{ provider: string, model?: string|null }} judge
+ * @param {string|null|undefined} workerProvider
+ * @param {string|null|undefined} workerBaseUrl
+ * @param {ReturnType<typeof ratesFor>} workerPrice what the worker's own rounds are booked at
+ * @param {readonly KeyRow[]} rows
+ * @returns {ReturnType<typeof ratesFor>}
+ */
+export function judgeRatesFor(judge: {
+    provider: string;
+    model?: string | null;
+}, workerProvider: string | null | undefined, workerBaseUrl: string | null | undefined, workerPrice: ReturnType<typeof ratesFor>, rows: readonly KeyRow[]): ReturnType<typeof ratesFor>;
 /** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
 export const DEEPSEEK_BASE_URL: "https://api.deepseek.com/v1";
 /**
@@ -161,4 +217,13 @@ export type KeyRow = {
      * the saved Base URL ('' = the shape's default host)
      */
     baseUrl: string;
+    /**
+     * the customer's own price, USD per 1M input tokens — carried RAW
+     * (present only when the config row names it); {@link ratesFor} is the one place that validates it
+     */
+    priceInPerM?: unknown;
+    /**
+     * the same, for output tokens
+     */
+    priceOutPerM?: unknown;
 };

package/types/run.d.ts

@@ -34,6 +34,11 @@
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {{in: number, out: number}|null} [opts.rates] the CUSTOMER's own price for the worker's key row
+ *   (`ratesFor`, src/providerrows.js — USD per 1K tokens), resolved once by the door and handed to every
+ *   worker/planner Loop as bare-agent's `rates` (rounds then read `rateSource:'caller'`). Absent = the
+ *   built-in guess, exactly as before. A Loop-driven provider only: a native session reports its own cost.
+ * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's own key row
  * @param {string|null} [opts.judgeModel] SOFTGREEN — WHICH model the judge provider drives
  *   (PRD item 32.1), resolved by the CALLER (`resolveJudge`, src/judged.js) and passed
  *   through untouched. Travels with `judgeProvider`; absent, a judged stage stops as a
@@ -204,7 +209,7 @@
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -216,6 +221,14 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
+    rates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
+    judgeRates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
     judgeModel?: string | null | undefined;
     judgeProvider?: any;
     capRuns?: number | undefined;

package/types/runlist.d.ts

@@ -13,7 +13,9 @@ 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' }} RunRow
+ * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill', pid?: number, capUsd?: 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).
  */
 /**
  * Append one row to the run list, mkdir -p'ing the home directory first.
@@ -42,19 +44,57 @@ export function appendRun(row: RunRow, opts?: {
     appended: boolean;
     reason?: "duplicate-runid";
 };
+/**
+ * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean }} RunEvent
+ * 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
+ * claim was taken and then given back unspent, its run never started. The month's totals keep reading real
+ * spend off the spines; an event only releases the hold and records who wrote it.
+ */
+/**
+ * Append one {@link RunEvent}. Not locked: one short line, one append. THROWS on IO failure.
+ * @param {RunEvent} event
+ * @param {{ home?: string }} [opts]
+ * @returns {void}
+ */
+export function appendRunEvent(event: RunEvent, opts?: {
+    home?: string;
+}): void;
 /**
  * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
  * parser). An absent file reads as an empty list, not an error: a fresh
- * install has never run `appendRun` yet.
+ * install has never run `appendRun` yet. FOLDS the file: `rows` are the RUNS
+ * only (an event line is never listed as a run, and a run whose claim was
+ * `released` never started, so it is not listed either); `events` are the
+ * write-backs, in file order.
  * @param {{ home?: string }} [opts]
- * @returns {{ rows: RunRow[], skipped: number }}
+ * @returns {{ rows: RunRow[], skipped: number, events: RunEvent[] }}
  */
 export function readRunList(opts?: {
     home?: string;
 }): {
     rows: RunRow[];
     skipped: number;
+    events: RunEvent[];
 };
+/**
+ * Is this pid a live bareloop runner? `process.kill(pid, 0)` says whether the
+ * pid exists (EPERM = it exists, just not ours); `/proc/<pid>/cmdline` says whether it is a
+ * bareloop runner — a recycled pid that now belongs to some other program is NOT. A runner is
+ * a node executable (argv[0] is `node`, `nodejs`, `node22`, ...) with a later argv entry named
+ * `bareloop`, `bareloop.mjs`, `run-u.mjs` or `u-watchdog.mjs` (the basename, so the npm bin
+ * symlink counts), or a process whose argv[0] is itself one of those names. A non-node program
+ * that merely has such a name in its arguments (`nvim /x/bareloop`, `git -C /x/bareloop`) is not
+ * a runner. Residual, accepted: a recycled pid that is a node program with such an argument
+ * still reads as a runner. The wrong direction to err is "not a runner" on a real live run — it
+ * would release that run's cap. Where `/proc` is unreadable (not Linux, or not ours) the
+ * existence test alone decides: alive. The ONE spelling — the monthly limit's holds, and
+ * `--resume`'s old-pid check share it.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isLiveRunner(pid: number): boolean;
 /**
  * `bareloop runs backfill <dir>` — recursively scan `dir` (bounded to
  * {@link MAX_BACKFILL_DEPTH} levels, never into `node_modules`/`.git`,
@@ -103,6 +143,10 @@ export function backfillRuns(dir: string, opts?: {
 export function formatRunRow(row: RunRow): string;
 export const DIED_MTIME_MS: number;
 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).
+ */
 export type RunRow = {
     at: string;
     runid: string;
@@ -110,4 +154,22 @@ export type RunRow = {
     spine: string;
     patient: string | null;
     via: "run-u" | "bundle" | "backfill";
+    pid?: number;
+    capUsd?: number;
+};
+/**
+ * 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
+ * claim was taken and then given back unspent, its run never started. The month's totals keep reading real
+ * spend off the spines; an event only releases the hold and records who wrote it.
+ */
+export type RunEvent = {
+    runid: string;
+    type: "settled" | "released";
+    by: string;
+    at: string;
+    reason?: string;
+    spentUsd?: number;
+    spendComplete?: boolean;
 };

package/types/source.d.ts

@@ -72,15 +72,20 @@ export function looksLikeRepoSource(source: string): boolean;
  * 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,
- *   fetchTimeoutMs?: number}} args `fetchTimeoutMs` is test-only — production
- *   callers omit it and get `PROVIDER_TIMEOUT_MS`.
+ *   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>}
  */
-export function prepareSource({ source, into, destination, fetchTimeoutMs }: {
+export function prepareSource({ source, into, destination, fetchTimeoutMs, afterScan }: {
     source: string;
     into: string;
     destination?: string;
     fetchTimeoutMs?: number;
+    afterScan?: () => (void | Promise<void>);
 }): Promise<{
     stop: null;
     into: string;

package/types/userrun.d.ts

@@ -48,6 +48,11 @@ export type Deps = {
      * even when `env` is injected; production never sets it.
      */
     keysHome?: string | undefined;
+    /**
+     * the command this run was actually reached through (`src/invoke.js`);
+     * `src/cli.js` passes `'bareloop run-u'`, `scripts/run-u.mjs` passes none.
+     */
+    invokedAs?: string | undefined;
     out?: ((s: string) => void) | undefined;
     err?: ((s: string) => void) | undefined;
     /**
@@ -65,6 +70,45 @@ export type Deps = {
      */
     runlistHome?: string | undefined;
 };
+/**
+ * The one-runner door's hand-in (`src/bundlerun.js`, the exported bundle's `bareloop run`):
+ * where a bundle run's books live and how it prints its own re-invocation. Set ONLY by
+ * that caller through `startRun`/`resumeRun` opts, in-process — `main`'s argv never builds
+ * it, so a local job cannot reach it. Absent, every use below is today's expression.
+ */
+export type BundleRun = {
+    /**
+     * the run id (also the `runs/<runid>` directory name)
+     */
+    runid: string;
+    /**
+     * `<bundle>/runs/<runid>`: spine.jsonl, gate-audit.jsonl and close/ live here
+     */
+    runDir: string;
+    /**
+     * the bare re-invocation prefix printed in resume hints (`bareloop run <bundle> --repo <path>`), no ceiling flags
+     */
+    invoke: string;
+    /**
+     * the ceilings the person tightened on THIS leg; printed after `invoke` on every resume line except a money halt's (which never prints the exhausted `--budget`)
+     */
+    tightened: {
+        budgetUsd?: number;
+        wallMin?: number;
+    };
+    /**
+     * the bundle's SIGNED spec budgetUsd (the tightened leg ceiling is `spec.budgetUsd`); printed only, never enforced from here
+     */
+    signedBudgetUsd: number;
+    /**
+     * the hash printed after `--approve` in those hints (the bundle's, not the run spec's)
+     */
+    printApprove: string;
+    /**
+     * creates the run's tree (fresh worktree) and its books; the engine calls it once every $0 refusal has passed, so a refusal leaks nothing
+     */
+    prepareTree: () => void;
+};
 export type RunOpts = {
     /**
      * the parsed, not-yet-validated job spec — read by
@@ -136,6 +180,10 @@ export type RunOpts = {
      * how a "go edit the spec" hint should read
      */
     specDesc?: string | undefined;
+    /**
+     * set only by the bundle door (see `BundleRun`)
+     */
+    bundle?: BundleRun | undefined;
     deps?: Deps | undefined;
 };
 export type RunCtx = {
@@ -159,5 +207,6 @@ export type RunCtx = {
     door: string | null;
     decide: string | null;
     text: string | null;
+    bundle?: BundleRun | undefined;
     deps: Deps;
 };