bareloop 0.31.0 → 0.33.0

package/src/authorrun.js

@@ -100,6 +100,9 @@
 //                  item 34 L17) — `run-interview.mjs` asks for it and writes it
 //                  in; a draft missing one, or naming one the provider factory
 //                  does not know, dies here loud, listing the known table.
+import { keysForDoor } from './keysfile.js';
+import { applyConfiguredKey, judgeRatesFor, keyNameFor, ratesFor, rowsForHome } from './providerrows.js';
+import { ConfigError } from './config.js';
 import {
   readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, renameSync, statSync,
 } from 'node:fs';
@@ -119,6 +122,7 @@ import { scanSecrets, redactSecrets } from './validate.js';
 import { detectLanguage } from './detectlang.js';
 import { closeJudges, GATE_AUDIT_FILE } from './kinds.js';
 import { resolveProvider, buildRunnerProviders, apiKeyProblem } from './providers.js';
+import { commandFor } from './invoke.js';
 import { readSourceManifest, missingDependencies } from './source.js';
 import { tallyCalls } from './text.js';
 import {
@@ -141,6 +145,7 @@ class ExitSignal extends Error {
 /**
  * @typedef {object} Deps
  * @property {Record<string,string|undefined>} [env]
+ * @property {string} [keysHome] P4a — test seam: load this home's `.env` keys file even when `env` is injected.
  * @property {NodeJS.ReadStream} [stdin]
  * @property {NodeJS.WritableStream} [stdout]
  * @property {NodeJS.WritableStream} [stderr]
@@ -162,13 +167,16 @@ class ExitSignal extends Error {
  * @returns {Promise<number>} an exit code — never calls process.exit
  */
 export async function main(argv, deps = {}) {
-  const env = deps.env ?? process.env;
+  // P4a item 1 — the keys file fills what the shell leaves unset (shell wins).
+  const keys = keysForDoor(deps);
+  const env = keys.env;
   const stdin = deps.stdin ?? process.stdin;
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
+  if (keys.warning && deps.env === undefined) stderr.write(`WARNING: ${keys.warning}\n`);
   const out = (/** @type {string} */ s = '') => { stdout.write(`${s}\n`); };
   const err = (/** @type {string} */ s) => { stderr.write(`${s}\n`); };
-  const invokedAs = deps.invokedAs ?? 'node scripts/run-author.mjs';
+  const invokedAs = deps.invokedAs ?? commandFor('author', undefined);
   let exitCode = 0;
   try {
   /** the close precheck / seed read spawns real toolchains; the slowest stage is a
@@ -499,8 +507,12 @@ export async function main(argv, deps = {}) {
 
   // Secrets load from the environment; they never enter argv (a command line is
   // world-readable on /proc) and they are never printed.
-  const AUTHOR_ENV_KEY = /** @type {NonNullable<typeof providerEntry>} */ (providerEntry).envKey;
-  const apiKey = env[AUTHOR_ENV_KEY];
+  // P4a item 4 — the key variable the person picked in Settings (config.json) stands in for
+  // the provider's built-in one; none picked = the built-in. Names only.
+  const keyCfg = rowsForHome(keys.home);
+  const authorEnv = applyConfiguredKey(env, PROVIDER_NAME, baseUrl, keyCfg);
+  const AUTHOR_ENV_KEY = keyNameFor(PROVIDER_NAME, baseUrl, keyCfg).name;
+  const apiKey = authorEnv[/** @type {NonNullable<typeof providerEntry>} */ (providerEntry).envKey];
   if (!apiKey) { err(`${AUTHOR_ENV_KEY} not set (secrets load from the environment — never the tree, never argv)`); throw new ExitSignal(2); }
   // F181 — a key that carries a line break/control char/stray whitespace (a
   // two-line secret-store entry, e.g.) reads as "set" by the presence check
@@ -509,12 +521,22 @@ export async function main(argv, deps = {}) {
   // echoes the value or the reason's source.
   const AUTHOR_KEY_PROBLEM = apiKeyProblem(apiKey);
   if (AUTHOR_KEY_PROBLEM) { err(`${AUTHOR_ENV_KEY} ${AUTHOR_KEY_PROBLEM} — refusing rather than crashing mid-call (never trimmed or repaired; fix the value at its source)`); throw new ExitSignal(2); }
+  // The customer's own price on the author's key row (USD per 1M in config.json) — resolved once here at
+  // $0, before any provider is built, and handed to every model call this run makes (scout, declaration
+  // loop, confirm turn, calibration judge). A bad price refuses here; it never falls back to the guess.
+  /** @type {ReturnType<typeof ratesFor>} */
+  let authorPrice = null;
+  try { authorPrice = ratesFor(PROVIDER_NAME, baseUrl, keyCfg); } catch (e) {
+    if (!(e instanceof ConfigError)) throw e;
+    err(`${e.message} — refusing to start rather than guess a price. Nothing spent.`);
+    throw new ExitSignal(2);
+  }
   /** The judge's key follows the RESOLVED judge provider's own env var, with
    * `JUDGE_API_KEY` as the role-named override in front (PRD item 32.3) — the same
    * contract `scripts/run-u.mjs` keeps, so one story covers both surfaces. When the
    * judge IS the authoring provider this is the key already read above. */
   const judgeKeyFor = (/** @type {string} */ providerName) => (
-    env.JUDGE_API_KEY ?? env[resolveProvider(providerName).envKey]
+    env.JUDGE_API_KEY ?? (providerName === PROVIDER_NAME ? authorEnv : applyConfiguredKey(env, providerName, undefined, keyCfg))[resolveProvider(providerName).envKey]
   );
 
   /** F6 — an unpriced call makes the TOTAL unknown, and unknown is reported as
@@ -789,7 +811,7 @@ export async function main(argv, deps = {}) {
    * bound to `CONFIRM_SYSTEM`, never the authoring `generate` above (that one
    * is bound to `AUTHOR_SYSTEM`). Same provider instance, a different system
    * prompt: reusing `generate` would run the wrong system prompt silently. */
-  const confirmGenerate = makeLoopGenerate(provider, { system: CONFIRM_SYSTEM });
+  const confirmGenerate = makeLoopGenerate(provider, { system: CONFIRM_SYSTEM, rates: authorPrice?.rates ?? null });
 
   // ── PLAIN-FOLDER SOURCE: A NAMED $0 STOP, NO MODEL CALL (F191; PRD item 33 M3
   // piece 4, step S6, D5 amended 2026-09-21) ──────────────────────────────────
@@ -858,7 +880,8 @@ export async function main(argv, deps = {}) {
       // malformed field travels as `null` and `authorPrompt` simply states nothing.
       writeScope: Array.isArray(draft.writeScope) ? draft.writeScope : null,
       provider,
-      generate: makeLoopGenerate(provider),
+      generate: makeLoopGenerate(provider, { rates: authorPrice?.rates ?? null }),
+      rates: authorPrice?.rates ?? null,
       // ONE number, both paid seams (the survey's and the declaration loop's) — the
       // advertised ceiling and the enforced ceiling are the same ceiling
       ceilingUsd: CEILING_USD,
@@ -1051,6 +1074,21 @@ export async function main(argv, deps = {}) {
         const judge = judges
           ? resolveJobJudge(spec, PROVIDER_NAME, resolveWorkerModel)
           : null;
+        // the judge's price: the judge model's own row (`judgeRatesFor`) — on the author's endpoint when the
+        // judge is the same provider, else the row for the judge's own provider. A bad one refuses here,
+        // before the calibration gate spends anything — beside the judge-key check, the same door.
+        /** @type {ReturnType<typeof ratesFor>} */
+        let judgePrice = null;
+        if (judge) {
+          try {
+            judgePrice = judgeRatesFor(judge, PROVIDER_NAME, baseUrl, authorPrice, keyCfg);
+          } catch (e) {
+            if (!(e instanceof ConfigError)) throw e;
+            err(`${e.message} — refusing before the calibration gate spends anything`);
+            archiveGateAudit();
+            throw new ExitSignal(2);
+          }
+        }
         // F181 — the judge key is required exactly when `judges` is true (this
         // script has no presence check on it today; adding one is out of this
         // finding's scope). What this door DOES owe, the same as the worker
@@ -1120,7 +1158,7 @@ export async function main(argv, deps = {}) {
           // number would silently widen it.
           ceilingUsd: CEILING_USD,
           priorCalls: [...metered],
-          judgeLoop: judgeProvider ? (o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+          judgeLoop: judgeProvider ? (o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system, rates: judgePrice?.rates ?? null }) : null,
           // the seam's other half (PRD item 32.1): the graded set is STAMPED with
           // this, and the close later refuses to grade under any other identity.
           judgeModel: judge?.model ?? null,
@@ -1225,8 +1263,8 @@ export async function main(argv, deps = {}) {
           // <path>` and reads this SAME prepared copy's own source manifest for
           // the workdir and seed — so the command below is the whole of what a
           // person needs to run their own job, nothing left to hand off.
-          // `providerEntry.envKey` (never a hardcoded ANTHROPIC_API_KEY) is the
-          // same F187 rule scripts/run-u.mjs's own hint already follows.
+          // `keyNameFor` (never a hardcoded ANTHROPIC_API_KEY, never the provider's built-in name
+          // when the job's key row names another) is the same F187 rule run-u's own hint follows.
           // hamr's ruling 2026-09-28 (2nd addendum) — `totalCost.costUsd === null`
           // means this pipeline's own metered list carried at least one unpriced
           // call (`tallyCalls`'s `spendComplete: false`), so the drafting fold is
@@ -1239,7 +1277,7 @@ export async function main(argv, deps = {}) {
               + 'and run-u will enforce the remainder (Cap $ minus this) as ITS ceiling — pass --draft-spent-usd exactly as shown below, never a rounded or re-typed figure.');
           }
           out('\nTo run it (the same signature and gates as any other job — nothing here bypasses them):');
-          out(`  ${providerEntry.envKey}=... node scripts/run-u.mjs --spec ${specFile} --approve ${hash}${draftSpentUsd > 0 ? ` --draft-spent-usd ${draftSpentUsd}${draftIncomplete ? ' --draft-spend-incomplete' : ''}` : ''}`);
+          out(`  ${keyNameFor(PROVIDER_NAME, baseUrl, keyCfg, spec.model).name}=... ${commandFor('run-u', deps.invokedAs)} --spec ${specFile} --approve ${hash}${draftSpentUsd > 0 ? ` --draft-spent-usd ${draftSpentUsd}${draftIncomplete ? ' --draft-spend-incomplete' : ''}` : ''}`);
           emit('author-end', { outcome: 'prepared', specHash: hash });
         }
       }

package/src/authorscout.js

@@ -342,8 +342,8 @@ export async function defaultSurveyor({ workdir, granted, auditPath = join(workd
 }
 
 /** the default loop seam — one spelling of how this repo drives a model */
-const defaultLoop = (/** @type {any} */ { system, policy, onLlmResult, provider }) =>
-  new Loop({ provider, system, policy, onLlmResult });
+const defaultLoop = (/** @type {any} */ { system, policy, onLlmResult, provider, rates }) =>
+  new Loop({ provider, system, policy, onLlmResult, ...(rates ? { rates } : {}) });
 
 /**
  * Run the authoring scout.
@@ -376,7 +376,8 @@ const defaultLoop = (/** @type {any} */ { system, policy, onLlmResult, provider
  *   rounds?: number, minBytes?: number, blobMax?: number, maxTokens?: number, ctx?: boolean,
  *   attempts?: number, ceilingUsd?: number|null, callTimeoutMs?: number,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
- *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any}) => any,
+ *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any, rates?: {in: number, out: number}}) => any,
+ *   rates?: {in: number, out: number}|null,
  *   createSurveyor?: (o: {workdir: string, granted: readonly string[], ctx: boolean}) => Promise<any>}} o
  * @returns {Promise<Survey & {raw: string, raws: ReturnType<typeof scrubRaw>[],
  *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
@@ -398,6 +399,7 @@ export async function runAuthorScout({
   callTimeoutMs = AUTHOR_CALL_TIMEOUT_MS,
   onCall = () => {},
   createLoop = defaultLoop,
+  rates = null,
   createSurveyor = defaultSurveyor,
 }) {
   const callTimeout = Number.isFinite(Number(callTimeoutMs)) && Number(callTimeoutMs) > 0
@@ -406,6 +408,8 @@ export async function runAuthorScout({
   const granted = AUTHOR_SCOUT_VERBS;
   const system = SCOUT_SYSTEM + strategyFor([...granted]);
   const surveyor = await createSurveyor({ workdir, granted, ctx });
+  // the customer's own price for this provider's key row (USD per 1K, `ratesFor`); absent = the built-in guess
+  const priced = rates ? { rates } : {};
   /** @type {{label: string, costUsd: number|null, unpricedRounds: number}[]} */
   const calls = [];
   /** @type {ReturnType<typeof scrubRaw>[]} */
@@ -519,7 +523,7 @@ export async function runAuthorScout({
           }
           return surveyor.onLlmResult ? surveyor.onLlmResult(arg) : undefined;
         };
-        loop = createLoop({ system, policy: surveyor.policy, onLlmResult: metered, provider });
+        loop = createLoop({ system, policy: surveyor.policy, onLlmResult: metered, provider, ...priced });
 
         const r = await settled(loop.run([{ role: 'user', content: scoutPrompt(workdir) }], surveyor.tools,
           { cacheMessages: true, maxTokens, timeoutMs: callTimeout }));
@@ -558,7 +562,7 @@ export async function runAuthorScout({
         const recoveryHalt = recoveryWanted ? capStop({ ceilingUsd, ...tallyCalls(calls) }) : null;
         if (recoveryHalt) budgetStop = recoveryHalt;
         if (recoveryWanted && !recoveryHalt) {
-          const recovery = createLoop({ system, policy: surveyor.policy, onLlmResult: surveyor.onLlmResult, provider });
+          const recovery = createLoop({ system, policy: surveyor.policy, onLlmResult: surveyor.onLlmResult, provider, ...priced });
           // F147 (second instance; sibling fix: src/planrun.js `askFrom`, commit
           // 031ffe1): `r.msgs` is a prior `loop.run()`'s returned transcript,
           // which bare-agent already prepended `system` to (Loop.run, loop.js
@@ -591,7 +595,7 @@ export async function runAuthorScout({
       } else {
         // THE RE-ASK. Toolless by construction, over the survey's own
         // conversation, naming only what failed mechanically.
-        const reask = createLoop({ system, policy: surveyor.policy, onLlmResult: surveyor.onLlmResult, provider });
+        const reask = createLoop({ system, policy: surveyor.policy, onLlmResult: surveyor.onLlmResult, provider, ...priced });
         // F147 (second instance; sibling fix: src/planrun.js `askFrom`, commit
         // 031ffe1): `lastMsgs` is a prior `loop.run()`'s returned transcript
         // (system already prepended by bare-agent); `reask` is built with the

package/src/bundlerun.js

@@ -0,0 +1,266 @@
+// One runner (`feat/one-runner`) — `bareloop run <bundle> --repo <path>` is a thin DOOR to
+// the same engine `bareloop run-u` drives (`src/userrun.js`), not a second runner. This
+// module does only what is bundle-specific and $0: the bundle's own integrity/deps/
+// envelope/blessing checks, the fresh git worktree (planned here, CREATED by the engine's
+// `prepareTree` hook once its own refusals — keys, monthly limit — have passed), the
+// tightened spec and its hash, and, after the engine returns, the bundle's history row,
+// its first-green blessing and the merge hints. Providers, keys, judge, monthly limit,
+// watchdog, readout and run list are the engine's — nothing here talks to a model.
+//
+// The signature the engine checks is `approve === jobSpecHash(spec)`. A bundle's human
+// signature is its `bundleHash` (checked here, step 3); the executed spec is the tightened,
+// `$BARELOOP_BUNDLE`-resolved one, so the door hands the engine the hash of exactly that
+// spec — the equality stays a real check (the spec the engine sees is the spec hashed).
+// `bundleHash` never changes when the runner tightens; `history.jsonl` records both hashes.
+
+import { hostname } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import {
+  readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
+} from './bundle.js';
+import { jobSpecHash } from './job.js';
+import { parseJsonl } from './replayio.js';
+import { startRun, resumeRun } from './userrun.js';
+
+/**
+ * `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 async function bundleMain(args, {
+  out, err, cwd, env, now, deps, keysHome, parseFlags, printReds,
+}) {
+  const { positional, flags } = parseFlags(args);
+  const bundleDirArg = positional[0];
+  const repoArg = typeof flags.repo === 'string' ? flags.repo : undefined;
+  const resumeArg = typeof flags.resume === 'string' ? flags.resume : undefined;
+  if (flags.resume === true || (!bundleDirArg) || (resumeArg === undefined && !repoArg)) {
+    err('usage: bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]\n'
+      + '       bareloop run <bundleDir> --resume <runid> [--repo <path>] [--budget N] [--wall MIN] [--approve <bundleHash>]');
+    return 1;
+  }
+  const bundleDir = resolve(cwd, bundleDirArg);
+
+  // 1. readBundle — this must complete, clean, before anything else touches the bundle or
+  // the repo. Any red (incl. bundle-tampered) stops here.
+  const bundle = readBundle(bundleDir);
+  if (!bundle.ok) { printReds(bundle.reds, err); return 1; }
+
+  // 1b. F128 — the bundle's OWN node_modules must carry `bareloop` before anything else
+  // runs. Left unchecked, the close crashes deep inside runJob's close-first precheck with
+  // a bare ERR_MODULE_NOT_FOUND, reported as an unhelpful generic close-red with no cure.
+  const depsCheck = checkBundleDeps(bundleDir);
+  if (!depsCheck.ok) { printReds(depsCheck.reds, err); return 1; }
+
+  // 2. checkEnvelope — tighten-only, wall given in minutes -> ms.
+  /** @type {{ budgetUsd?: number, maxWallMs?: number }} */
+  const envelope = {};
+  if (flags.budget !== undefined) {
+    const n = Number(flags.budget);
+    if (!Number.isFinite(n)) { err(`--budget must be a number, got ${JSON.stringify(flags.budget)}`); return 1; }
+    envelope.budgetUsd = n;
+  }
+  if (flags.wall !== undefined) {
+    const n = Number(flags.wall);
+    if (!Number.isFinite(n)) { err(`--wall must be a number of minutes, got ${JSON.stringify(flags.wall)}`); return 1; }
+    envelope.maxWallMs = n * 60_000;
+  }
+  const envCheck = checkEnvelope(bundle.spec, envelope);
+  if (!envCheck.ok) { printReds(envCheck.reds, err); return 1; }
+
+  // 3. blessing — BEFORE any key is read (the engine reads the key last).
+  const { manifest } = bundle;
+  if (!bundle.blessing) {
+    // The runid that ACTUALLY minted this bundle's own signed spec — the bridge VERSION
+    // (base or shape fork; both ship into bridges/) whose recorded specHash equals the
+    // resolved bundle spec's jobSpecHash. NOT the bridge's first history row: a job can be
+    // re-exported/rebased many times, and only the version at THIS exact hash proves
+    // anything for THIS bundle.
+    const { approveHash: mintMatchHash } = resolveBundleSpec(bundle, bundleDir);
+    let mintRunid = null;
+    for (const b of bundle.bridges) {
+      const versions = Array.isArray(b.versions) ? b.versions : [];
+      const v = versions.find((/** @type {any} */ ver) => ver.specHash === mintMatchHash);
+      if (v) { mintRunid = v.runid; break; }
+    }
+    // the bundle's own README (the operator questions) belongs on this first-run screen:
+    // the engine, not this door, now refuses a missing key.
+    let readme = null;
+    try { readme = readFileSync(join(bundleDir, 'README.md'), 'utf8'); } catch { /* the hash alone */ }
+    if (readme) out(readme);
+    out('first run — this bundle has never been blessed on this machine.');
+    out(mintRunid ? `minting run: ${mintRunid} (spine not bundled in v1)` : 'no version at this hash');
+    out(`bundleHash: ${manifest.bundleHash}`);
+    if (flags.approve !== manifest.bundleHash) {
+      err(`--approve ${manifest.bundleHash} is required for the first run of an unblessed bundle`);
+      return 1;
+    }
+  } else {
+    const vb = verifyBlessing(bundle);
+    if (!vb.ok) { printReds(vb.reds, err); return 1; }
+    if (flags.approve) out('already blessed, --approve ignored');
+  }
+
+  // 4. the tree — refuse a non-repo, a repo with no commit, or a collision; ALWAYS fresh,
+  // never reused (a reused worktree reads last run's edits as "already-green" — the
+  // negative POC's exact finding). Only PLANNED here: the engine creates it (prepareTree)
+  // after its own $0 refusals, so a refusal leaves no worktree behind. A RESUME is the one
+  // exception: it re-enters the SAME worktree its halted run left (recorded in that run's
+  // `run.json`), and a gone tree is a stop, never a silent fresh start.
+  const runid = now().toString(36);
+  /** @type {string} */
+  let repo;
+  /** @type {string} */
+  let seed;
+  /** @type {string} */
+  let worktree;
+  /** @type {string|null} */
+  let deadSpine = null;
+  if (resumeArg !== undefined) {
+    if (!/^[a-z0-9]+$/.test(resumeArg)) { err(`--resume ${JSON.stringify(resumeArg)} is not a run id of this bundle`); return 1; }
+    const deadRunJson = join(bundleDir, 'runs', resumeArg, 'run.json');
+    /** @type {any} */
+    let rec;
+    try { rec = JSON.parse(readFileSync(deadRunJson, 'utf8')); } catch {
+      err(`--resume ${resumeArg}: no readable ${deadRunJson} — not a run of this bundle (or one that never started)`);
+      return 1;
+    }
+    if (typeof rec?.worktree !== 'string' || typeof rec?.seed !== 'string' || typeof rec?.repo !== 'string') {
+      err(`--resume ${resumeArg}: ${deadRunJson} does not record a worktree, seed and repo`);
+      return 1;
+    }
+    if (repoArg !== undefined && resolve(cwd, repoArg) !== rec.repo) {
+      err(`--repo ${repoArg} is not the repo run ${resumeArg} used (${rec.repo}) — a resume re-enters that run's own worktree`);
+      return 1;
+    }
+    if (!existsSync(rec.worktree)) {
+      err(`--resume ${resumeArg}: its worktree ${rec.worktree} is gone — a resume needs the tree the halted run left`);
+      return 1;
+    }
+    repo = rec.repo;
+    seed = rec.seed;
+    worktree = rec.worktree;
+    deadSpine = join(bundleDir, 'runs', resumeArg, 'spine.jsonl');
+  } else {
+    repo = resolve(cwd, /** @type {string} */ (repoArg));
+    try {
+      seed = execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+    } catch (e) {
+      err(`--repo ${repoArg} must be a git repository with at least one commit: ${/** @type {Error} */ (e).message}`);
+      return 1;
+    }
+    worktree = join(repo, '.bareloop', 'wt', runid);
+    if (existsSync(worktree)) { err(`worktree already exists: ${worktree}`); return 1; }
+  }
+
+  // 5. resolve (in-memory $BARELOOP_BUNDLE substitution) + tighten. The envelope tightens
+  // the ACTUAL spec that runs (budgetUsd/maxWallMs have no separate override — the library
+  // reads them off the spec itself), so the hash is computed AFTER tightening: the door
+  // mints its own approval over the exact spec it hands the engine, never over the
+  // untightened one. The bundleHash a human approved never changes.
+  const runSpec = resolveBundleSpec(bundle, bundleDir).spec;
+  if (envelope.budgetUsd !== undefined) runSpec.budgetUsd = envelope.budgetUsd;
+  if (envelope.maxWallMs !== undefined) runSpec.maxWallMs = envelope.maxWallMs;
+  const approveHash = jobSpecHash(runSpec);
+
+  const runDir = join(bundleDir, 'runs', runid);
+  const spineFile = join(runDir, 'spine.jsonl');
+  // `run.json` is written by EVERY leg (a resume leg's points at the SAME worktree/seed): it is
+  // the bundle-local, always-present record of where the tree is — history.jsonl is written only
+  // at job-end (a killed run has none) and the run list is machine-global.
+  const prepareTree = () => {
+    if (deadSpine === null) {
+      mkdirSync(dirname(worktree), { recursive: true });
+      try {
+        execFileSync('git', ['-C', repo, 'worktree', 'add', '--detach', worktree, 'HEAD'], { encoding: 'utf8' });
+      } catch (e) {
+        throw new Error(`git worktree add failed: ${/** @type {Error} */ (e).message}`);
+      }
+    }
+    mkdirSync(runDir, { recursive: true });
+    writeFileSync(join(runDir, 'run.json'), `${JSON.stringify({
+      runid, worktree, seed, repo, at: new Date(now()).toISOString(), ...(resumeArg === undefined ? {} : { resumedFrom: resumeArg }),
+    }, null, 2)}\n`);
+  };
+
+  // 6. the engine. `deps` passes through exactly as `bareloop run-u` passes it, so every
+  // test seam (provider/providerFor/judgeProvider/runlistHome/keysHome) is the same one.
+  let engineCode;
+  try {
+    /** @type {import('./userrun.js').RunOpts} */
+    const opts = {
+      workdir: worktree,
+      seed,
+      approve: approveHash,
+      deps: { ...deps, env, out, err, ...(keysHome === undefined ? {} : { keysHome }) },
+      bundle: {
+        runid,
+        runDir,
+        // the bare re-invocation prefix; the leg's OWN tightened ceilings (only those the person passed) ride as
+        // DATA so the engine, which knows the halt kind and the spend, spells the printed line. Text only.
+        invoke: `bareloop run ${bundleDirArg} --repo ${repo}`,
+        tightened: {
+          ...(envelope.budgetUsd === undefined ? {} : { budgetUsd: envelope.budgetUsd }),
+          ...(flags.wall === undefined ? {} : { wallMin: Number(flags.wall) }),
+        },
+        signedBudgetUsd: bundle.spec.budgetUsd,
+        printApprove: manifest.bundleHash,
+        prepareTree,
+      },
+    };
+    engineCode = deadSpine === null ? await startRun(runSpec, opts) : await resumeRun(deadSpine, { ...opts, spec: runSpec });
+  } catch (e) {
+    err(`${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+
+  // 7. history + (on a first green) the blessing — off THIS run's own spine, tolerant of
+  // a torn line. No job-end (a $0 refusal, a crash) means no history row, as ever.
+  const events = existsSync(spineFile) ? parseJsonl(spineFile).records : [];
+  const je = events.findLast((/** @type {any} */ e) => e.type === 'job-end');
+  if (!je) return engineCode;
+  const outcome = je.outcome;
+  const spentUsd = je.spentUsd ?? null;
+  const spendComplete = je.spendComplete ?? null;
+  let branch = null;
+  try { branch = execFileSync('git', ['-C', worktree, 'rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf8' }).trim(); } catch { /* leave null — reported honestly below */ }
+  appendHistory(bundleDir, {
+    runid,
+    at: new Date(now()).toISOString(),
+    outcome,
+    spentUsd,
+    spendComplete,
+    budgetUsd: runSpec.budgetUsd,
+    maxWallMs: runSpec.maxWallMs ?? null,
+    worktree,
+    branch,
+    bundleHash: manifest.bundleHash,
+    approveHash,
+    ...(resumeArg === undefined ? {} : { resumedFrom: resumeArg }),
+  });
+  if (outcome === 'green' && !bundle.blessing) {
+    bless(bundleDir, {
+      bundleHash: manifest.bundleHash, blessedAt: new Date(now()).toISOString(), runid, outcome, host: hostname(),
+    });
+  }
+
+  // 8. the merge hints (the engine printed the outcome/spend readout).
+  out(`branch    ${branch ?? 'UNKNOWN (could not read the worktree branch)'}`);
+  out(`worktree  ${worktree}`);
+  if (branch) out(`merge     git merge ${branch}   (merge stays human — this CLI never merges)`);
+  out(`the worktree is kept until you remove it: git worktree remove ${worktree}`);
+  // exit 0 ONLY for a real green — every other outcome exits 1 so a caller scripting
+  // `bareloop run` off its exit code cannot mistake a red for a success. The engine's own
+  // 2 (refusal) / 3 (spine leak) are preserved.
+  return engineCode || (outcome === 'green' || outcome === 'already-green' ? 0 : 1);
+}