bareloop 0.31.0 → 0.33.0

package/types/panel/settingsroutes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @param {{ port: number, token: string, home?: string, env?: Record<string,string|undefined>,
+ *   fetchImpl?: typeof fetch, now?: () => number }} opts
+ */
+export function createSettingsRoutes(opts: {
+    port: number;
+    token: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): {
+    handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, pathname: string, body: any) => boolean;
+};

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

@@ -0,0 +1,229 @@
+/**
+ * The key value to hand a provider: the `null` marker becomes the placeholder, anything else
+ * passes through unchanged.
+ * @template {string|undefined} T
+ * @param {T} raw
+ * @returns {T|string}
+ */
+export function usableKey<T extends string | undefined>(raw: T): T | string;
+/**
+ * What a key with no saved entry shows. Any name not listed is OpenAI-compatible with a
+ * blank URL and a blank Name.
+ * @param {string} envName
+ * @returns {{ name: string, shape: string, baseUrl: string }}
+ */
+export function defaultsFor(envName: string): {
+    name: string;
+    shape: string;
+    baseUrl: string;
+};
+/**
+ * @typedef {object} KeyRow
+ * @property {string} envName the key variable NAME (read-only label; never a value)
+ * @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.
+ * @param {{ filled: readonly string[], config: Record<string, any> }} src
+ * @returns {KeyRow[]}
+ */
+export function keyRows({ filled, config }: {
+    filled: readonly string[];
+    config: Record<string, any>;
+}): KeyRow[];
+/**
+ * The rows for a keys home. `undefined` home (a door that skipped the keys file) = no
+ * rows, so nothing resolves through the file and the provider's built-in variable stands.
+ * @param {string|undefined} home
+ * @returns {KeyRow[]}
+ */
+export function rowsForHome(home: string | undefined): KeyRow[];
+/**
+ * @param {string} provider
+ * @returns {string} the shape's default host ('' = the vendor's own)
+ */
+export function defaultUrlOf(provider: string): string;
+/**
+ * An endpoint in comparable form: blank = the shape's default host; scheme + host lower-cased,
+ * trailing slashes dropped.
+ * @param {string} provider
+ * @param {string|null|undefined} baseUrl
+ * @returns {string}
+ */
+export function endpointOf(provider: string, baseUrl: string | null | undefined): string;
+/**
+ * The URL a row talks to, for display ('' = the vendor's own host, which has no URL to show).
+ * @param {KeyRow} row
+ * @returns {string}
+ */
+export function shownUrl(row: KeyRow): string;
+/**
+ * Which row a `(provider, baseUrl[, model])` identity belongs to: the rows on that shape and
+ * endpoint; when several share it, the one whose Name is the model, else the first.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} id
+ * @returns {KeyRow|null}
+ */
+export function findRow(rows: readonly KeyRow[], { provider, baseUrl, model }: {
+    provider?: string | null;
+    baseUrl?: string | null;
+    model?: string | null;
+}): KeyRow | null;
+/**
+ * What Chat's Model menu offers and how a pick resolves: the row whose Name is the model
+ * (a blank Name is never offered). `baseUrl` is absent when blank, exactly as a spec omits it.
+ * @param {readonly KeyRow[]} rows
+ * @param {string} model
+ * @returns {{ provider: string, baseUrl?: string, envName: string, name: string }|null}
+ */
+export function modelChoiceFor(rows: readonly KeyRow[], model: string): {
+    provider: string;
+    baseUrl?: string;
+    envName: string;
+    name: string;
+} | null;
+/**
+ * The models Chat offers, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ id: string, envName: string, shape: string }[]}
+ */
+export function chatModels(rows: readonly KeyRow[]): {
+    id: string;
+    envName: string;
+    shape: string;
+}[];
+/**
+ * The key variable NAME a job on `(provider, baseUrl[, model])` reads: the matching row's
+ * variable, else the provider's built-in one (byte-identical to before for anything no row
+ * claims).
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ name: string, builtIn: string, chosen: boolean }}
+ */
+export function keyNameFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
+    name: string;
+    builtIn: string;
+    chosen: boolean;
+};
+/**
+ * The env a door hands to provider construction, with the matching row's key variable
+ * standing in for the provider's built-in one: `env[builtIn] = env[row.envName]` (the `null`
+ * no-key marker becomes {@link NO_KEY_PLACEHOLDER}). A copy — never mutates the input.
+ * No matching row and no marker = the env unchanged.
+ * @param {Record<string,string|undefined>} env
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @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";
+/**
+ * The API shapes the dropdown offers. `id` is the `src/providers.js` table name;
+ * `defaultUrl` is the host a blank Base URL means ('' = the vendor's own, unshown).
+ * @type {readonly {id: string, label: string, defaultUrl: string}[]}
+ */
+export const SHAPES: readonly {
+    id: string;
+    label: string;
+    defaultUrl: string;
+}[];
+/** The five empty lines a fresh keys file is created with, in this order. */
+export const PRESET_KEY_NAMES: readonly string[];
+/** A local server's default endpoint: Ollama's OpenAI-compatible host (LM Studio / llama.cpp: change the URL). */
+export const LOCAL_BASE_URL: "http://127.0.0.1:11434/v1";
+/**
+ * A key line whose value is the word `null` is SET and means "no real key": the row exists and
+ * the provider is handed this harmless stand-in (local servers ignore auth). It is not a
+ * secret and is never shown or logged as a key.
+ */
+export const NO_KEY_PLACEHOLDER: "no-key-needed";
+export type KeyRow = {
+    /**
+     * the key variable NAME (read-only label; never a value)
+     */
+    envName: string;
+    /**
+     * the model id Chat uses ('' = not offered in Chat)
+     */
+    name: string;
+    /**
+     * the `src/providers.js` table entry (the API shape's id)
+     */
+    provider: string;
+    /**
+     * 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`,
@@ -101,7 +141,12 @@ export function backfillRuns(dir: string, opts?: {
  * @returns {string}
  */
 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;
@@ -109,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

@@ -43,6 +43,16 @@ export function answerDoor(runId: string, decision: {
 export function main(argv: string[], deps?: Deps): Promise<number>;
 export type Deps = {
     env?: Record<string, string | undefined> | undefined;
+    /**
+     * P4a — a test seam naming the home whose `.env` keys file is loaded
+     * 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;
     /**
@@ -60,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
@@ -131,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 = {
@@ -154,5 +207,6 @@ export type RunCtx = {
     door: string | null;
     decide: string | null;
     text: string | null;
+    bundle?: BundleRun | undefined;
     deps: Deps;
 };