bareloop 0.19.1 → 0.21.0

package/src/cli.js

@@ -0,0 +1,460 @@
+// Export M2 (`docs/product/EXPORT-BUILD.md`) — the `bareloop` CLI. All logic
+// lives HERE, testable at $0 with an in-process `main(argv, deps)`; `bin/
+// bareloop.mjs` is a ~10-line adapter that supplies the real `deps` and turns
+// the returned exit code into `process.exitCode`.
+//
+// `deps.provider` (and `providerFor`/`judgeProvider`) is the ONE test seam: a
+// caller that supplies it skips the real-key check entirely (a scripted
+// provider IS the run, same as `tests/planrun.test.js`'s pattern). A caller
+// that does NOT supply one goes through the real path M1's frozen spec names:
+// a key from `ANTHROPIC_API_KEY` only, absent means print the operator
+// questions and spend nothing (`bareloop run`, step 3).
+//
+// Money/arbiter rules this module must not bend: `--budget`/`--wall` only
+// TIGHTEN a bundle's signed ceilings (`checkEnvelope`, M1); a bundle's
+// `bundleHash` (the human-facing signature) never changes when the runner
+// tightens — the SPEC that actually executes does, and this module mints a
+// FRESH `approvals` record over that tightened, `$BARELOOP_BUNDLE`-resolved
+// spec so `checkApproval` inside `runJob` always sees the spec it is about to
+// run, never the unresolved bundleHash. `history.jsonl` records both hashes
+// side by side (POC fact 2) so the pairing can never drift silently.
+
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline/promises';
+import { hostname } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync, mkdirSync, readFileSync, renameSync,
+} from 'node:fs';
+import {
+  dirname, isAbsolute, join, resolve,
+} from 'node:path';
+
+import {
+  exportBundle, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
+  runJob, makeSpine, loadRegistry, listingRow, jobSpecHash, resolveWorkerModel, JUDGE_MODEL,
+} from './index.js';
+
+const require = createRequire(import.meta.url);
+
+// The runner's own tier menu, the same spelling `scripts/run-u.mjs` uses (not
+// exported from `src/` — the tier->model mapping is runner territory, not the
+// library's). A `bareloop run` has no `--model` flag (not in the frozen
+// spec), so `flagModel` is always undefined and only the spec's own `model`
+// (if signed) or this default is ever in play.
+const DEFAULT_TIER_MODELS = { sonnet: 'claude-sonnet-5', haiku: 'claude-haiku-4-5-20251001' };
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isObj = (v) => typeof v === 'object' && v !== null;
+
+/**
+ * Build the real providers from an API key, exactly the way `scripts/run-
+ * u.mjs` does (provider/providerFor/judgeProvider from `bare-agent/
+ * providers`'s `AnthropicProvider`). `AnthropicProvider` itself lives in
+ * `bare-agent` (the one production dependency already budgeted for provider
+ * calls); this function only wires it up the same way the u-runner does —
+ * it is not arbiter logic (no budget/verdict/merge decision lives here).
+ * @param {string} apiKey
+ * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
+ */
+function buildProviders(apiKey, spec) {
+  const { AnthropicProvider } = require('bare-agent/providers');
+  const modelResolution = resolveWorkerModel({
+    specModel: isObj(spec) && typeof spec.model === 'string' ? spec.model : undefined,
+    flagModel: undefined,
+    defaultModel: DEFAULT_TIER_MODELS.sonnet,
+  });
+  const MODEL = modelResolution.model;
+  const provider = new AnthropicProvider({ apiKey, model: MODEL });
+  const TIER_MODELS = modelResolution.source === 'spec' ? { ...DEFAULT_TIER_MODELS, sonnet: MODEL } : DEFAULT_TIER_MODELS;
+  /** @type {Record<string, any>} */
+  const tierCache = {};
+  const providerFor = (/** @type {string} */ tier) => (tierCache[tier] ??= (TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] === MODEL ? provider : new AnthropicProvider({ apiKey, model: TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] })));
+  const judgeProvider = new AnthropicProvider({ apiKey, model: JUDGE_MODEL });
+  return { provider, providerFor, judgeProvider };
+}
+
+/** @param {string[]} args @returns {{ positional: string[], flags: Record<string, string|true> }} */
+function parseFlags(args) {
+  /** @type {string[]} */
+  const positional = [];
+  /** @type {Record<string, string|true>} */
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; } else flags[key] = true;
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+/** @returns {string} this package's own version, for the manifest's `bareloopVersion` */
+function readPackageVersion() {
+  const pkgUrl = new URL('../package.json', import.meta.url);
+  return JSON.parse(readFileSync(pkgUrl, 'utf8')).version;
+}
+
+/**
+ * Build the `closeScripts` map `exportBundle` expects (path -> source) and a
+ * copy of the spec whose `close[].cmd` paths are ABSOLUTE — M1's
+ * `exportBundle` only relocates `node <absolute path>.mjs …`. A relative path
+ * in a hand-authored spec is resolved against the spec FILE's own directory
+ * (the same "the spec's own location is the reference point" the u-runner
+ * uses when it resolves `jobs/<name>.json` off `import.meta.url`), not the
+ * process cwd.
+ * @param {any} spec @param {string} specFile absolute path to the spec file
+ */
+function loadCloseScripts(spec, specFile) {
+  const specDir = dirname(specFile);
+  const stages = Array.isArray(spec.close) ? spec.close : [];
+  const resolvedClose = stages.map((/** @type {any} */ stage) => {
+    if (!isObj(stage) || typeof stage.cmd !== 'string') return stage;
+    const parts = stage.cmd.trim().split(/\s+/);
+    if (parts[0] !== 'node' || parts.length < 2) return stage;
+    const scriptPath = parts[1];
+    const abs = isAbsolute(scriptPath) ? scriptPath : resolve(specDir, scriptPath);
+    return { ...stage, cmd: ['node', abs, ...parts.slice(2)].join(' ') };
+  });
+  /** @type {Record<string, string>} */
+  const closeScripts = {};
+  for (const stage of resolvedClose) {
+    if (!isObj(stage) || typeof stage.cmd !== 'string') continue;
+    const parts = stage.cmd.trim().split(/\s+/);
+    if (parts[0] === 'node' && parts[1] && isAbsolute(parts[1]) && existsSync(parts[1])) {
+      closeScripts[parts[1]] = readFileSync(parts[1], 'utf8');
+    }
+  }
+  return { resolvedSpec: { ...spec, close: resolvedClose }, closeScripts };
+}
+
+/** @param {import('./bundle.js').Red[]} reds @param {(s: string) => void} err */
+function printReds(reds, err) {
+  for (const r of reds) err(`${r.code} at ${r.path}: ${r.detail ?? ''}`.trim());
+}
+
+/**
+ * `bareloop export <jobs/x.json> --registry <dir> --out <dir>`
+ * @param {string[]} args @param {{ out: (s: string) => void, err: (s: string) => void, cwd: string }} ctx
+ */
+function doExport(args, { out, err, cwd }) {
+  const { positional, flags } = parseFlags(args);
+  const specPathArg = positional[0];
+  const registryDir = typeof flags.registry === 'string' ? flags.registry : undefined;
+  const outDirArg = typeof flags.out === 'string' ? flags.out : undefined;
+  if (!specPathArg || !registryDir || !outDirArg) {
+    err('usage: bareloop export <jobs/x.json> --registry <dir> --out <dir>');
+    return 1;
+  }
+  const specFile = resolve(cwd, specPathArg);
+  let specText;
+  try { specText = readFileSync(specFile, 'utf8'); } catch (e) {
+    err(`cannot read job spec at ${specFile}: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+  let spec;
+  try { spec = JSON.parse(specText); } catch (e) {
+    err(`job spec at ${specFile} is not valid JSON: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+  const { resolvedSpec, closeScripts } = loadCloseScripts(spec, specFile);
+  const bareloopVersion = readPackageVersion();
+  const r = exportBundle({
+    spec: resolvedSpec, closeScripts, registryDir: resolve(cwd, registryDir), outDir: resolve(cwd, outDirArg), bareloopVersion,
+  });
+  if (!r.ok) { printReds(r.reds, err); return 1; }
+  out(`bundleHash: ${r.bundleHash}`);
+  out('files:');
+  for (const f of Object.keys(r.manifest.files).sort()) out(`  ${f}`);
+  out("this bundle is unblessed until its first run greens on the importer's machine.");
+  return 0;
+}
+
+/**
+ * `bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`
+ * — the exact five-step order the frozen spec names; no step may be reordered.
+ * @param {string[]} args
+ * @param {{ out: (s: string) => void, err: (s: string) => void, cwd: string, env: Record<string,string|undefined>, now: () => number, deps: any }} ctx
+ */
+async function doRun(args, { out, err, cwd, env, now, deps }) {
+  const { positional, flags } = parseFlags(args);
+  const bundleDirArg = positional[0];
+  const repoArg = typeof flags.repo === 'string' ? flags.repo : undefined;
+  if (!bundleDirArg || !repoArg) {
+    err('usage: bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]');
+    return 1;
+  }
+  const bundleDir = resolve(cwd, bundleDirArg);
+  const repo = resolve(cwd, repoArg);
+
+  // 1. readBundle — N4: 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 line.
+  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. the key — ANTHROPIC_API_KEY only, UNLESS a caller already handed in a
+  // provider (the test seam). Absent and no injected provider: print the
+  // operator questions (the bundle's own README) and the hash, spend nothing.
+  let { provider, providerFor, judgeProvider } = deps;
+  if (!provider) {
+    const apiKey = env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      let readme = null;
+      try { readme = readFileSync(join(bundleDir, 'README.md'), 'utf8'); } catch { /* fall through to the hash alone */ }
+      if (readme) out(readme);
+      out(`bundleHash: ${bundle.manifest.bundleHash}`);
+      return 0;
+    }
+    ({ provider, providerFor, judgeProvider } = buildProviders(apiKey, bundle.spec));
+  }
+
+  // 4. blessing.
+  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; }
+    }
+    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');
+  }
+
+  // 5. the worktree — 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).
+  try {
+    execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+  } catch (e) {
+    err(`--repo ${repoArg} must be a git repository with at least one commit: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+  const runid = now().toString(36);
+  const worktree = join(repo, '.bareloop', 'wt', runid);
+  if (existsSync(worktree)) { err(`worktree already exists: ${worktree}`); return 1; }
+  mkdirSync(dirname(worktree), { recursive: true });
+  try {
+    execFileSync('git', ['-C', repo, 'worktree', 'add', '--detach', worktree, 'HEAD'], { encoding: 'utf8' });
+  } catch (e) {
+    err(`git worktree add failed: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+
+  // 6. resolve (in-memory $BARELOOP_BUNDLE substitution) + tighten + run. The
+  // envelope tightens the ACTUAL spec that runs (budgetUsd/maxWallMs have no
+  // separate runJob override — the library reads them off the spec itself),
+  // so `approveHash` is recomputed AFTER tightening: the runner mints its own
+  // fresh approval over the exact spec it is about to hand to runJob, never
+  // over the untightened one `resolveBundleSpec` first returned. The
+  // bundleHash a human approved never changes; only the executed spec's own
+  // hash does, and that hash is minted here, not signed by a person.
+  const resolved = resolveBundleSpec(bundle, bundleDir);
+  const runSpec = resolved.spec;
+  if (envelope.budgetUsd !== undefined) runSpec.budgetUsd = envelope.budgetUsd;
+  if (envelope.maxWallMs !== undefined) runSpec.maxWallMs = envelope.maxWallMs;
+  const approveHash = jobSpecHash(runSpec);
+
+  const runsDir = join(bundleDir, 'runs', runid);
+  mkdirSync(runsDir, { recursive: true });
+  const spineFile = join(runsDir, 'spine.jsonl');
+  const emit = makeSpine(spineFile);
+
+  let outcome;
+  try {
+    outcome = await runJob(runSpec, {
+      approvals: [{ specHash: approveHash, signer: 'bundle', ts: new Date(now()).toISOString() }],
+      workdir: worktree,
+      provider,
+      providerFor,
+      judgeProvider,
+      emit,
+      shellCapUsd: runSpec.budgetUsd,
+      readShim: 'cap',
+      scout: true,
+    });
+  } catch (e) {
+    err(`runJob crashed: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+
+  // the gate-audit relocation (POC fact 3, run-u.mjs:1293's move)
+  const auditSrc = join(worktree, 'gate-audit.jsonl');
+  if (existsSync(auditSrc)) renameSync(auditSrc, join(runsDir, 'gate-audit.jsonl'));
+
+  // the job-end record off THIS run's own spine — never fabricate a 0 for an
+  // unknown spend (F6/F12's class).
+  const events = readFileSync(spineFile, 'utf8').trimEnd().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const je = events.findLast((/** @type {any} */ e) => e.type === 'job-end');
+  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 */ }
+
+  // 7. history + (on a first green) the blessing.
+  appendHistory(bundleDir, {
+    runid,
+    at: new Date(now()).toISOString(),
+    outcome,
+    spentUsd,
+    spendComplete,
+    budgetUsd: runSpec.budgetUsd,
+    maxWallMs: runSpec.maxWallMs ?? null,
+    worktree,
+    branch,
+    bundleHash: manifest.bundleHash,
+    approveHash,
+  });
+  if (outcome === 'green' && !bundle.blessing) {
+    bless(bundleDir, {
+      bundleHash: manifest.bundleHash, blessedAt: new Date(now()).toISOString(), runid, outcome, host: hostname(),
+    });
+  }
+
+  // 8. the tail.
+  out(`outcome   ${outcome}`);
+  out(`spent     ${spentUsd == null ? 'UNKNOWN' : `${spendComplete === false ? '≥' : ''}$${spentUsd.toFixed(4)}`} of $${runSpec.budgetUsd}`);
+  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 (close-red, plan-red,
+  // escalated, cap/wall halts, worker-crash, provider-red, …) exits 1 so a
+  // caller scripting `bareloop run` off its exit code cannot mistake a red
+  // for a success. The tail print above is unchanged either way.
+  return outcome === 'green' || outcome === 'already-green' ? 0 : 1;
+}
+
+/**
+ * `bareloop history <bundleDir>`
+ * @param {string[]} args @param {{ out: (s: string) => void, err: (s: string) => void, cwd: string }} ctx
+ */
+function doHistory(args, { out, err, cwd }) {
+  const bundleDirArg = args[0];
+  if (!bundleDirArg) { err('usage: bareloop history <bundleDir>'); return 1; }
+  const dir = resolve(cwd, bundleDirArg);
+  const historyFile = join(dir, 'history.jsonl');
+  if (existsSync(historyFile)) {
+    out('history:');
+    for (const line of readFileSync(historyFile, 'utf8').split('\n')) {
+      if (line.trim()) out(`  ${line.trim()}`);
+    }
+  } else out('history: (no runs yet)');
+  const reg = loadRegistry(join(dir, 'bridges'));
+  if (reg.bridges.length > 0) {
+    out('bridges:');
+    for (const b of reg.bridges) out(`  ${JSON.stringify(listingRow(b))}`);
+  }
+  return 0;
+}
+
+/**
+ * The bare `bareloop` menu: `1 export  2 run  3 history  q quit`, then the
+ * SAME code path as the sub-command, asking its args line by line.
+ * @param {any} deps @param {{ out: (s: string) => void, err: (s: string) => void, cwd: string, env: any, now: () => number }} ctx
+ */
+async function runMenu(deps, ctx) {
+  const stdin = deps.stdin;
+  const stdout = deps.stdout;
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    ctx.out('1 export  2 run  3 history  q quit');
+    const choice = (await rl.question('> ')).trim().toLowerCase();
+    if (choice === '' || choice === 'q' || choice === 'quit') return 0;
+    if (choice === '1') {
+      const specPath = (await rl.question('job spec path: ')).trim();
+      const registry = (await rl.question('registry dir: ')).trim();
+      const outDir = (await rl.question('out dir: ')).trim();
+      return doExport([specPath, '--registry', registry, '--out', outDir], ctx);
+    }
+    if (choice === '2') {
+      const bundleDir = (await rl.question('bundle dir: ')).trim();
+      const repo = (await rl.question('repo path: ')).trim();
+      const budget = (await rl.question('budget (blank to skip): ')).trim();
+      const wall = (await rl.question('wall minutes (blank to skip): ')).trim();
+      const approve = (await rl.question('approve hash (blank to skip): ')).trim();
+      const args = [bundleDir, '--repo', repo];
+      if (budget) args.push('--budget', budget);
+      if (wall) args.push('--wall', wall);
+      if (approve) args.push('--approve', approve);
+      return await doRun(args, { ...ctx, deps });
+    }
+    if (choice === '3') {
+      const bundleDir = (await rl.question('bundle dir: ')).trim();
+      return doHistory([bundleDir], ctx);
+    }
+    ctx.err(`unknown choice ${JSON.stringify(choice)} — one of: 1, 2, 3, q`);
+    return 1;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * The one entry point. Never calls `process.exit` — always returns an exit
+ * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
+ * queued stdout on its own (F-something: `process.exit()` can discard it).
+ * @param {string[]} argv
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, now?: () => number, stdin?: any }} deps
+ * @returns {Promise<number>}
+ */
+export async function main(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+  const now = deps.now ?? (() => Date.now());
+  const out = (/** @type {string} */ s) => stdout.write(`${s}\n`);
+  const err = (/** @type {string} */ s) => stderr.write(`${s}\n`);
+  const ctx = { out, err, cwd, env, now, deps };
+
+  const [cmd, ...rest] = argv;
+  if (!cmd) return runMenu({ ...deps, stdin: deps.stdin ?? process.stdin, stdout }, ctx);
+  if (cmd === 'export') return doExport(rest, ctx);
+  if (cmd === 'run') return doRun(rest, ctx);
+  if (cmd === 'history') return doHistory(rest, ctx);
+  err(`unknown command ${JSON.stringify(cmd)} — one of: export, run, history`);
+  return 1;
+}

package/src/index.js

@@ -81,7 +81,7 @@ export { renderListing, selectionPrompt } from './selection.js';
 // at a review door, and a door with no row to act on can only describe a held learning
 // credit it has no way to release. STORAGE ONLY — nothing here selects, promotes or reuses
 // a bridge; those stay parked on `layer-3-reuse`.
-export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow } from './reuse.js';
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow, shapeForkName } from './reuse.js';
 // BA-21 pricing provenance rides out with the ledger because it is the same job: reading
 // a run's own spend record honestly. `rateProvenance`/`spendProvenance` answer "how much of
 // this was priced by a rate nobody vouched for" — REPORTING ONLY, no halt, no refusal.
@@ -252,3 +252,19 @@ export {
 // whether a changed file is one. The ONE place this list lives; exported so
 // bareloop.context.md can point an adopter here instead of re-deriving it.
 export { PROMPT_REGISTERS, isPromptFile } from './promptregisters.js';
+// Export M1 (`docs/product/EXPORT-BUILD.md`) — the bundle a `bareloop run`
+// (M2) drives from a clean consumer directory: a signed spec (close paths
+// rewritten to `$BARELOOP_BUNDLE/close/<script>`), the close scripts it
+// needs, and the job's whole registry history. `bundle.js` reads this
+// module's own export list at call time (never a hand-kept copy) to judge
+// whether a close script's imports are legal — a cycle by design, safe
+// because the binding is read only inside function bodies.
+export {
+  exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
+} from './bundle.js';
+// Export M2 (`docs/product/EXPORT-BUILD.md`) — the CLI's one entry point,
+// exported as `cliMain` (never `main`, a name generic enough to collide with
+// an adopter's own). `bin/bareloop.mjs` is the only other caller; this export
+// exists so an adopter driving `bareloop run` from their own script can do so
+// without spawning `bin/bareloop.mjs` as a child process.
+export { main as cliMain } from './cli.js';

package/src/planrun.js

@@ -642,6 +642,17 @@ ${scoutBlob || '(no scout notes)'}`;
  *   it.
  * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory)
  * @param {number} [opts.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
+ * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md):
+ *        `false` on a FRESH run (no `resumeSeed`) skips the survey entirely — `scoutBlob`
+ *        stays `''`, no `scout-start`/`scout-result`/`scout-empty` is emitted, and a single
+ *        `scout-skipped {reason:'operator-off'}` records it (a RECORD, never silence — the
+ *        resume skip's own rule). The planner then drafts from `(no scout notes)`
+ *        (line ~587) exactly as it does today when a scout returns an empty blob — OFF is
+ *        byte-identical to today's run everywhere but the survey. Precedence: when
+ *        `resumeSeed` is set the existing resume skip fires first and wins its own reason
+ *        (`resumed`); `operator-off` is only ever emitted on a fresh run. A non-boolean
+ *        THROWS a TypeError at entry (the `readShimArm` guard class) — a knob that
+ *        silently coerced would mislabel a bench row.
  * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
  *   reserved — a scout that spends every round on tools gets one toolless round to write its
  *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
@@ -805,7 +816,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -822,6 +833,11 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   // would be wrong and would look fine). Only the guard runs here; the flag itself
   // is still threaded onward as written.
   readShimArm(readShim);
+  // The scout switch's guard, same class and same door: a mis-typed value
+  // coerced by truthiness would run the scout under an "off" label (or skip it
+  // under an "on" one) and no reading of the results afterwards could recover
+  // which arm actually ran (docs/product/SCOUT-CONTRAST.md).
+  if (typeof scout !== 'boolean') throw new TypeError(`scout: expected boolean, got ${JSON.stringify(scout)}`);
   // G1's OTHER half, refused at the same $0 door. `validatePlan` reds `read-blind`
   // when a step grants `read` without the retrieval pair — but a step cannot grant
   // what the SIGNED CEILING does not offer, so against a spec whose `tools` lack
@@ -2456,6 +2472,15 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       reason: 'resumed', phase: resumeSeed.phase ?? null,
       meaning: 'the killed run already paid for this survey; its plan is reloaded, not re-drafted. A replan after this point drafts from an empty survey plus the failure brief.',
     });
+  } else if (scout === false) {
+    // The operator-off arm (docs/product/SCOUT-CONTRAST.md): a fresh run whose
+    // operator asked for no survey. Precedence already settled above — the
+    // resume branch fires first and wins its own reason, so this arm is only
+    // ever reached when there is nothing to resume from.
+    emit('scout-skipped', {
+      reason: 'operator-off',
+      meaning: 'the operator ran with --scout off; the planner drafts from "(no scout notes)"; no survey was paid for.',
+    });
   } else {
     emit('scout-start', { rounds: scoutRounds });
     try {

package/src/reuse.js

@@ -167,7 +167,7 @@ function sameCloseShape(entry, stageNames) {
  * to prevent.
  * @param {string} name @param {string[]} stageNames @returns {string}
  */
-function shapeForkName(name, stageNames) {
+export function shapeForkName(name, stageNames) {
   return `${name}-${createHash('sha256').update(stageNames.join('\n')).digest('hex').slice(0, 8)}`;
 }
 

package/src/run.js

@@ -171,6 +171,12 @@ async function primitiveSmoke(workdir) {
  *        frozen A0 baseline arm has to be exactly today, so a guard firing under a disabled
  *        shim would make the baseline a treatment arm. The default-flip belongs to a
  *        paid contrast nobody has approved yet (the `layerRoot` precedent, F41).
+ * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md),
+ *   forwarded verbatim to the plan flow: `false` on a fresh run (no `resumeSeed`) skips the
+ *   read-only survey and records `scout-skipped {reason:'operator-off'}` instead — the
+ *   planner drafts from `(no scout notes)`. Runner territory exactly like `readShim`: the
+ *   spec names no scout, so the signed hash is unaffected. A non-boolean THROWS at this
+ *   entry, before the ledger, before the approval gate (the `readShim` guard class).
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -202,7 +208,7 @@ async function primitiveSmoke(workdir) {
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, scout = true, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -211,6 +217,10 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // blind-instrument failure this programme keeps logging. Only the guard runs
   // here; the flag itself is threaded onward to the plan flow as written.
   readShimArm(readShim);
+  // The scout switch's guard, same class and same door (docs/product/SCOUT-CONTRAST.md):
+  // a mis-coerced value would run under the wrong label with no way to recover which arm
+  // actually fired from the results afterwards.
+  if (typeof scout !== 'boolean') throw new TypeError(`scout: expected boolean, got ${JSON.stringify(scout)}`);
   // 0. the ledger's counters, declared FIRST so that every job-end — including
   // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
   // not a zero: a consumer reads `undefined` and either crashes or launders it
@@ -405,7 +415,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact