bareloop 0.19.1 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,96 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.21.0] — 2026-09-06
+
+### Added
+
+- **Export/run a bundle** (`docs/product/EXPORT-BUILD.md`, frozen 2026-09-05). New
+  `src/bundle.js`: `exportBundle` mints a plain directory bundle (signed spec with
+  `close[].cmd` rewritten under `$BARELOOP_BUNDLE`, the close scripts, and the job's
+  registry history) from a job that already carries a real green at its current spec
+  hash — refuses (typed reds, nothing written) on an unrelocatable close cmd, a script
+  collision, an import this module cannot verify or that bareloop's own `src/index.js`
+  does not export, or no bridge at the spec's hash. `bundleHash(dir)` / `readBundle(dir)`
+  recompute the signature from disk and red `bundle-tampered` on any mismatch — the load-
+  bearing check that stands between a swapped close script and a fake green (N4).
+  `resolveBundleSpec`, `checkEnvelope` (tighten-only budget/wall), `bless`/`verifyBlessing`
+  (first-run approval, no-resign on later runs), and `appendHistory` round out the module.
+- **`bareloop` CLI and `bin/`.** New `bin/bareloop.mjs` (the package's first `bin` entry)
+  and `src/cli.js`'s `main(argv, deps)` — exported from the package root as `cliMain` —
+  implement `bareloop export|run|history` plus a bare numbered menu. `run` orders its
+  steps as: tamper check, tighten-only envelope check, provider key (or the injected
+  test-seam provider), blessing/approval, a fresh `git worktree add --detach` per run,
+  then `runJob` itself; the tail prints the outcome, spend, and the `git merge` command —
+  merge stays human, the CLI never merges. `bin/` added to `package.json`'s `files`.
+- **`checkBundleDeps(bundleDir)`** (`src/bundle.js`, F128): resolves `bareloop` from the
+  bundle's own `close/` directory (`createRequire(...).resolve('bareloop')`, walking the
+  package's own `exports` map) and reds typed `bundle-deps-missing` — with the exact cure
+  line `cd <bundleDir> && npm install` — when it cannot. `bareloop run` calls it as literal
+  step 1b, right after the tamper check and before the envelope check, the key, and any
+  worktree, so a bundle installed the wrong way (as someone else's dependency, never `npm
+  install`ed inside its own directory) fails fast with a fix instead of crashing deep
+  inside a close stage with a bare `ERR_MODULE_NOT_FOUND`.
+- **`close-absolute-path` export guard** (`src/bundle.js`, F129): `exportBundle` now refuses
+  a close script whose source bakes in a string literal that is an absolute POSIX path
+  which exists on the exporting machine and is outside an allow-listed system prefix — a
+  close judges the `cwd` the runner gives it, never a path baked into its own source. Pins
+  the live defect where a hardcoded `WORKDIR` made the close judge the original patient
+  checkout instead of a fresh worktree, minting `already-green` at $0.
+- **The aurora close now reads `process.cwd()`** (`scripts/u-spawner-close.mjs`) instead of a
+  hardcoded absolute `WORKDIR`, so it judges the tree the runner actually hands it rather than
+  the original patient checkout — the fix behind F129, validated live by a fourth paid fire
+  that went green from a fresh detached worktree (`docs/logs/FINDINGS.md`, F130's closing
+  pointer).
+
+### Fixed
+
+- **F128 — `bareloop run` exit code now reflects the run outcome.** Previously every
+  invocation that reached the tail exited `0` regardless of outcome — a close-red, plan-
+  red, escalated, cap/wall-halted, or crashed run all read as CLI success. `run` now
+  returns `0` only for `green`/`already-green`; every other outcome exits `1`, so a caller
+  scripting off the exit code can no longer mistake a red run for a green one. The tail's
+  printed lines are unchanged.
+- **F128 — the "minting run" line named the wrong run.** On a bundle's first (unblessed)
+  run, the notice printed the bridge's FIRST history row's `runid`, not the run that
+  actually minted the bundle's own signed spec. It now searches every bridge version
+  across ALL shipped bridges (base + shape fork) for the one whose `specHash` equals the
+  resolved `$BARELOOP_BUNDLE` spec's `jobSpecHash`, and prints "no version at this hash"
+  (honestly, never a guess) when none matches — which cross-machine is the common case,
+  since the historic mint's real script path and the importer's own bundle path rarely
+  coincide.
+- **`bin/bareloop.mjs`: a closed stdout reader (`| head`) no longer crashes with an
+  unhandled `EPIPE`.** `process.stdout` now has an `'error'` listener that exits `0` on
+  `EPIPE` (the one legitimate `process.exit()` in this file — the reader is gone, so
+  there is no queued output left to lose) and re-throws anything else.
+- **`scripts/replay-row.mjs`** — a $0 registry-row replay from an archived green spine: mints
+  the row a real run would have written via `writeRunGreenRow` had it been launched with
+  `--registry`, using the same seam and the same input derivation `scripts/run-u.mjs` uses.
+  Given it a permanent home this session (was scratchpad-only).
+
+## [0.20.0] — 2026-09-05
+
+### Added
+
+- Operator-only scout OFF switch (`docs/product/SCOUT-CONTRAST.md`): `runJob`/`runPlan`
+  accept `scout` (boolean, default `true`); `false` on a fresh run skips the read-only
+  survey and records `scout-skipped { reason: 'operator-off' }` instead — the planner
+  drafts from `(no scout notes)`. `scripts/run-u.mjs --scout on|off` is the runner
+  surface, modelled on `--read-shim`; a non-boolean/unrecognised value throws/exits
+  before a token is spent. Runner territory — the signed spec hash is unaffected.
+  Measured (F126): both arms green on `aurora-u-spawner-types`, OFF cost $0.37 more
+  (inside the $0.40 noise band) — the scout is not dead weight; the switch stays as a
+  probe knob, no default flip.
+
+### Docs
+
+- Export scoping and lock: `docs/product/EXPORT-SCOPING.md` (tree facts, proposed
+  bundle shape) and `docs/product/EXPORT-BUILD.md` (frozen build spec — worktree,
+  no-resign-on-tighten) record hamr's interview answers ahead of the export build
+  itself; no code shipped yet.
+- G4 counting-rule scoping (`docs/product/G4-SCOPING.md`) and the first `docs/logs/BENCH.md`
+  bench-ledger row.
+
 ## [0.19.1] — 2026-09-02
 
 ### Fixed

package/README.md

@@ -133,6 +133,20 @@ works, **export the whole workflow** — with its self-healing harness — and r
 anywhere. The point is to stop trial-and-erroring your way to the workflow that fits a job.
 Find it once, keep it, reuse it. It is a seed of something bigger over time.
 
+### Export a job
+
+```bash
+bareloop export jobs/my-maintainer.json --registry ./bridges --out ./my-maintainer.bareloop
+bareloop run ./my-maintainer.bareloop --repo /path/to/checkout --approve <bundleHash printed above>
+```
+
+`export` only ships a job that has already earned a real green — it refuses to bundle an
+unproven draft. The first `run` on a new machine asks you to approve the bundle's printed
+hash; once that run goes green, later runs need no re-approval as long as the bundle stays
+unchanged. Every run works in its own fresh git worktree and leaves the merge to you. Full
+contract — flags, approval/blessing rules, exit codes — in
+[`bareloop.context.md`](bareloop.context.md).
+
 ## Running it
 
 bareloop runs locally, as you. Secrets load from the environment and never enter the tree or

package/bareloop.context.md

@@ -958,7 +958,7 @@ Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
 `coordination-red` — a failure between units (scope contention, step order, store
 races), never to be folded into worker/interpreter reds.
 
-### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, readShim?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
+### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, readShim?, scout?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
 
 The last seven are the RESUME fold and are documented under *Resuming a killed run* below; they
 default to `0` / `true` / `0` / `null` / `[]` / `null` / `null`, so a fresh run passes none of them.
@@ -1027,6 +1027,20 @@ arm replaces the CLI-display cap rather than stacking on it; a non-capping arm l
 installed *inside* the shim, so native never loses its bound. Default-flip pending a paid contrast;
 see CHANGELOG for the replay numbers behind it.
 
+**`scout` (default `true`) — the operator-only off switch** (`docs/product/SCOUT-CONTRAST.md`),
+threaded verbatim from `runJob` to `runPlan`. `false` on a FRESH run (no `resumeSeed`) skips the
+read-only survey entirely — `scout-start`/`scout-result`/`scout-empty` never fire, and a single
+`scout-skipped { reason: 'operator-off', meaning }` records it (a RECORD, never silence — the
+resume skip's own rule). The planner then drafts from `(no scout notes)` exactly as it does today
+when a scout returns an empty blob; nothing else observable changes. Precedence when both a
+resumed leg and `scout:false` are in play: the resume skip fires first and wins its own reason
+(`resumed`) — `operator-off` is only ever emitted on a fresh run. A non-boolean value **throws**
+a `TypeError` at the same door as the `readShim` arm guard, before a token is spent. It is a probe
+knob, not a product default — the spec names no scout, so the signed hash is unaffected — and
+`scripts/run-u.mjs --scout on|off` (default `on`) is its runner-territory surface, modelled on
+`--read-shim`: an unrecognised value exits 2 at argv, and every re-invocation the runner prints
+carries `--scout off` when set, so a resume never silently drops the arm.
+
 **The two hitl terminals (N4 slice 1, doors re-cut 2026-08-18)** are the class's whole surface
 at this layer, and each is a CLEAN exit (`spendComplete` stays true — only the two casualties floor). `hitl-pause` is a
 decision-ready CHECKPOINT: the close reached a stage no machine can render, so the run stops
@@ -2497,6 +2511,221 @@ An unresolvable `--range` (no such ref — a fresh clone with no `origin`, a det
 checkout that never fetched) is a **skip**, printed and exited 0: a missing baseline is
 not a rule violation, never a red.
 
+### Bundles — export a job, run it elsewhere (`src/bundle.js`, `src/cli.js`, `bin/bareloop.mjs`)
+
+`docs/product/EXPORT-BUILD.md` (frozen build spec, 2026-09-05). A **bundle** is a plain
+directory that ships a proven job — spec, close scripts, and registry history — so it can
+run on a different machine without this repo. `npm pack` is its shipping form (there is no
+separate tarball step).
+
+```
+<job>.bareloop/
+  manifest.json       { schema:"bundle-v1", job, exportedAt, bareloopVersion, files:{...}, bundleHash }
+  spec.json           the job spec; close[].cmd rewritten to "node $BARELOOP_BUNDLE/close/<script> …"
+  close/<script>.mjs  the close script(s), verbatim except `from '../src/…'` → `from 'bareloop'`
+  bridges/*.json      the job's whole registry history for this job name (greens and reds)
+  README.md           the operator questions, in the order `bareloop run` asks them
+  blessing.json        absent at export; written by the run that first greens it
+  history.jsonl        absent at export; one line appended per `bareloop run` on this machine
+  runs/<runid>/        absent at export; one per run — that run's own spine.jsonl + gate-audit.jsonl
+```
+
+**`bundleHash`** = sha256 over the sorted `path:contentSha256` lines of exactly `spec.json`
+and every `close/*` file (`hashFilesMap` in `src/bundle.js`) — nothing else. `manifest.json`,
+`README.md`, `bridges/*`, `blessing.json`, `history.jsonl` and `runs/` are all **outside**
+the hash on purpose: they are records, not the arbiter. This is the one signature a human
+approves and the CLI stores.
+
+**Code-vs-spec, verified by reading `src/bundle.js`/`src/cli.js`:** `exportBundle` DOES write
+a `package.json` (name/version/`dependencies: {"bareloop": "^…"}`, `private: true`, `type:
+"module"`), outside `bundleHash` on purpose (editing it never trips `bundle-tampered`) — this
+corrects an earlier, now-stale reading of this section that claimed no `package.json` was
+written; `tests/bundle.test.js` proves both the write and the hash-exclusion directly. The
+`runs/<runid>/` directory (this run's relocated `spine.jsonl`/`gate-audit.jsonl`,
+written by `bareloop run`, step 6 below) is real and live but is not in the frozen spec's
+layout table at all. `history.jsonl`'s row also carries `bundleHash` and `approveHash`
+(the POC-fact correction, below) beyond the fields the original layout table named.
+
+#### `src/bundle.js` — pure, no provider/process calls
+
+| function | args → returns | notes |
+|---|---|---|
+| `exportBundle(o)` | `{ spec, closeScripts, registryDir, outDir, bareloopVersion }` → `{ ok, reds, dir, bundleHash, manifest }` | mints the directory above. Every check runs before anything touches disk — a red means nothing was written |
+| `bundleHash(dir)` | `dir` → sha256 hex | recomputes from what is on disk right now; throws only if `dir` itself is not a directory |
+| `readBundle(dir)` | `dir` → `{ ok, reds, spec, manifest, bridges, blessing, history }` | never throws; every failure is a typed red. Runs the tamper check (below) whenever both a manifest and a spec parsed |
+| `resolveBundleSpec(bundle, bundleDir)` | a `readBundle` result + the bundle dir → `{ spec, approveHash }` | the in-memory `$BARELOOP_BUNDLE` → absolute `bundleDir` substitution; `approveHash` is `jobSpecHash` of the *substituted* spec, never the unresolved one |
+| `checkEnvelope(spec, envelope)` | `spec` (already resolved) + `{ budgetUsd?, maxWallMs? }` → `{ ok, reds }` | tighten-only: a given number must be ≤ the spec's own |
+| `bless(dir, record)` | `dir` + `{ bundleHash, runid, outcome, host?, blessedAt? }` → the blessing object | writes/overwrites `blessing.json`; there is only ever one, for the bundle's current hash |
+| `verifyBlessing(bundle)` | a `readBundle` result → `{ ok, unblessed, reds }` | `unblessed: true` (no red) means never blessed here; a red means blessed-but-stale |
+| `appendHistory(dir, row)` | `dir` + a plain object → `void` | atomic append to `history.jsonl` (`appendFileSync`, same convention as `spine.js`/`ledger.js`) |
+
+**Every red code `src/bundle.js` can emit, and when:**
+
+| code | fires in | meaning |
+|---|---|---|
+| `invalid-value` | `exportBundle` (`spec.job` missing, `spec.close` empty/absent, `outDir` exists and is not a directory), `checkEnvelope` (a given `budgetUsd`/`maxWallMs` is not a positive finite number) | a shape the caller must fix before minting/tightening anything |
+| `outdir-not-empty` | `exportBundle` | `outDir` exists and already holds files — export never merges into a prior bundle |
+| `registry-unreadable` | `exportBundle` | `registryDir` itself could not be read (bubbled from `loadRegistry`) |
+| `no-bridge-at-hash` | `exportBundle` | no bridge named `spec.job` in `registryDir` carries a green (bridge-level or on any stored version) at `jobSpecHash(spec)` — export ships a run that actually happened, never an unproven draft |
+| `close-cmd-unrelocatable` | `exportBundle` | a `close[].cmd` is not exactly `node <absolute path>.mjs …` — the one shape this module can relocate under `$BARELOOP_BUNDLE` |
+| `close-script-missing` | `exportBundle` | a stage's `cmd` names a script `closeScripts` carries no source for |
+| `close-script-collision` | `exportBundle` | two different close script paths share one basename — a flat `close/` directory would silently clobber one |
+| `close-import-unparsed` | `exportBundle` | a close script's import is a shape this module cannot verify at all — default import, `* as ns`, mixed default+named/namespace, a bare side-effect import, a dynamic `import()`, or a relative import that does not point into `src/` (a sibling file never ships in `close/`). Fails safe rather than silently accepting what it cannot read |
+| `close-import-unexported` | `exportBundle` | a close script imports a name from bareloop's own `src` that `src/index.js` does not export |
+| `close-absolute-path` | `exportBundle` (F129) | a close script's source bakes in a quoted string literal that is an absolute POSIX path which `existsSync` finds real on the exporting machine and which is not under an allow-listed system prefix (`/usr/`, `/bin/`, `/sbin/`, `/lib/`, `/lib64/`, `/dev/`, `/etc/`, `/proc/`, `/sys/`, `/opt/`). **A close judges `process.cwd()` — the runner's cwd — never a path baked into the script (F8/F129):** the live defect this catches is a hardcoded `WORKDIR` making a close judge the ORIGINAL patient checkout instead of the fresh worktree it was actually pointed at, minting a fake `already-green` at $0. A nonexistent absolute-looking literal is a NAME, not a proven hazard, and is not flagged — the check is deliberately monotone and simple, not clever (see `absolutePathLiteralsOf`'s JSDoc for its named limits: string concatenation and cross-machine-only paths are invisible to it) |
+| `bundle-missing` | `readBundle` | `dir` is not a directory at all |
+| `manifest-invalid` / `spec-invalid` | `readBundle` | `manifest.json`/`spec.json` could not be read or parsed |
+| `bundle-tampered` | `readBundle` | manifest and spec both parsed, but the recomputed `bundleHash` (from what's really on disk) does not match the stored one — **the load-bearing check, N4 below** |
+| `bundle-deps-missing` | `checkBundleDeps` (F128) | the bundle's own `close/` directory cannot resolve `require.resolve('bareloop')` — the bundle was installed the WRONG way (as someone else's dependency) instead of `cd <bundleDir> && npm install`. `bareloop run` calls this as literal step 1b, right after the tamper check, before the envelope check, the key, and any worktree |
+| `envelope-widen` | `checkEnvelope` | a given `budgetUsd`/`maxWallMs` exceeds the bundle's own signed ceiling — raising one is a re-export, never a runner flag |
+| `blessing-stale` | `verifyBlessing` | `blessing.json` exists but its `bundleHash` no longer matches the manifest's — the bundle was re-exported/edited since the run that blessed it; re-export and re-approve |
+
+**N4 — why `readBundle`'s tamper check must run before anything else touches the bundle.**
+`jobSpecHash` covers `close[].cmd` as a *path*, not the script's bytes, so a swapped close
+script leaves the signed spec's own hash intact. `runJob`'s close-first precheck
+(`src/planrun.js`) would then read the swapped script's fake "already green" as a genuine
+one — a fake green, $0 spent, no work done, reported as success. `readBundle`'s
+`bundle-tampered` red is therefore not a courtesy check: it is the only thing standing
+between a swapped script and a fake green, so `bareloop run` calls it as literal step 1,
+before the envelope check, before the key check, before the worktree, before `runJob` is
+ever reached.
+
+#### The CLI — `bareloop export | run | history`, `bin/bareloop.mjs`
+
+`bin/bareloop.mjs` is a ~10-line adapter: it supplies the real `deps` (real `env`/`stdout`/
+`stderr`/`cwd`/`stdin`) and turns the returned number into `process.exitCode` — never
+`process.exit()`, which can discard queued stdout under a slow reader. All logic lives in
+`src/cli.js`'s `main(argv, deps)`, exported from the package root as **`cliMain`**
+(`export { main as cliMain } from './cli.js'` — renamed on export so it never collides with
+some other module's own generic `main`). `cliMain(argv, deps)` is the in-process test/
+integration seam: pass `deps.provider` (and optionally `providerFor`/`judgeProvider`) and the
+real `ANTHROPIC_API_KEY` check is skipped entirely — a scripted provider *is* the run, the
+same seam `tests/planrun.test.js` uses. `deps` also accepts `env`, `stdout`, `stderr`, `cwd`,
+`now`, `stdin` — omit any of them and the real `process.*` equivalent is used.
+
+Bare `bareloop` (no sub-command) prints a numbered menu — `1 export  2 run  3 history  q
+quit` — and asks each sub-command's arguments one line at a time over the SAME code paths
+below.
+
+- **`bareloop export <jobs/x.json> --registry <dir> --out <dir>`** → resolves the spec's
+  close-script paths against the spec file's own directory (never the process cwd), calls
+  `exportBundle`. On success prints `bundleHash:`, the sorted file list, and "this bundle is
+  unblessed until its first run greens on the importer's machine." Exit `1` on any red or
+  missing flag, `0` on success.
+
+- **`bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`**
+  — the exact order below; no step is ever reordered:
+  1. `readBundle(bundleDir)` — the tamper check (N4, above). Any red stops here, exit `1`.
+  2. `checkBundleDeps(bundleDir)` (F128) — can the bundle's own `close/` directory resolve
+     `require.resolve('bareloop')`? A bundle installed the WRONG way (as someone else's
+     dependency — see the corrected adopter flow below) has no `node_modules` of its own,
+     which would otherwise crash the close deep inside the precheck with a bare
+     `ERR_MODULE_NOT_FOUND`. A red here (`bundle-deps-missing`) prints the exact cure line
+     (`cd <bundleDir> && npm install`) and stops, exit `1`, before the envelope check, the
+     key, or any worktree.
+  3. `checkEnvelope(spec, { budgetUsd?, maxWallMs? })` — `--wall` is minutes, converted to ms.
+     A red (an invalid number, or a widen) stops here, exit `1`.
+  4. The provider key: `deps.provider` if the caller injected one (the test seam), else
+     `ANTHROPIC_API_KEY` from `env`. Absent and no injected provider: print the bundle's own
+     `README.md` plus `bundleHash:`, spend nothing, **exit `0`** (this is a legitimate,
+     non-error stop, not a red).
+  5. Blessing. No `blessing.json` yet: print the "first run" notice + the minting-run line
+     (F128-corrected — see below), the `bundleHash`, and **require** `--approve <bundleHash>`
+     to match exactly, or exit `1`. A `blessing.json` present: `verifyBlessing` must pass
+     (`blessing-stale` stops here, exit `1`); a `--approve` flag is accepted but ignored with
+     a printed note ("no-resign" — hamr's ruling).
+  6. The worktree: refuse (exit `1`) if `--repo` is not a git repo with ≥1 commit, or if
+     `<repo>/.bareloop/wt/<runid>` already exists; otherwise `git worktree add --detach
+     <repo>/.bareloop/wt/<runid> HEAD` — **always fresh, never reused** (a reused worktree
+     would read a prior run's edits as "already-green" — a negative POC's exact finding).
+  7. `resolveBundleSpec` (the `$BARELOOP_BUNDLE` substitution) → tighten `budgetUsd`/
+     `maxWallMs` on that resolved spec in memory if `--budget`/`--wall` were given → mint a
+     **fresh** `approveHash = jobSpecHash(that tightened+resolved spec)` (the runner signs
+     the spec it is actually about to run; the human-approved `bundleHash` never changes) →
+     `runJob(runSpec, { approvals: [{ specHash: approveHash, signer: 'bundle', ts }], workdir:
+     worktree, provider, providerFor, judgeProvider, emit, shellCapUsd: runSpec.budgetUsd,
+     readShim: 'cap', scout: true })`, spine written to `<bundleDir>/runs/<runid>/spine.jsonl`.
+     A thrown `runJob` crash is caught and reported, exit `1`.
+  8. The worktree's `gate-audit.jsonl` is moved to `<bundleDir>/runs/<runid>/gate-audit.jsonl`
+     (same relocation `scripts/run-u.mjs` does for in-repo runs). `spentUsd`/`spendComplete`
+     are read off this run's own `job-end` spine event — never fabricated as `0` when unknown.
+  9. `appendHistory` — one `history.jsonl` line: `{ runid, at, outcome, spentUsd,
+     spendComplete, budgetUsd, maxWallMs, worktree, branch, bundleHash, approveHash }` (the
+     `bundleHash` ↔ `approveHash` pairing, POC fact 2, so the human-signed hash and the
+     hash actually enforced can never drift apart silently). A `green` outcome on a still-
+     unblessed bundle also calls `bless(bundleDir, { bundleHash, runid, outcome, host })`.
+  10. The tail: `outcome`, `spent` (`≥$…` when `spendComplete === false`, `UNKNOWN` when
+      `spentUsd` is `null`), `branch`, `worktree`, a `git merge <branch>` instruction
+      ("merge stays human — this CLI never merges"), and "the worktree is kept until you
+      remove it: `git worktree remove <worktree>`" (F110: never delete it for the user).
+      **Exit `0` ONLY for `green`/`already-green` (F128) — every other outcome (close-red,
+      plan-red, escalated, cap/wall-halted, provider-red, a crashed `runJob`, …) exits `1`,**
+      so a caller scripting off the exit code can never mistake a red run for a green one.
+      The tail's printed lines are unchanged either way.
+
+  **Adopter flow, corrected (F128, 2026-09-06 — hamr's paid fire found the frozen spec's
+  validation step 2 named the wrong install shape):** `npm install <bundle dir>` run from a
+  clean CONSUMER directory installs the bundle AS that consumer's own dependency — it never
+  installs the bundle's OWN declared dependency (`package.json`'s `bareloop`), which its
+  close scripts need at run time. The correct flow is **`cd <bundle> && npm install`** (reads
+  the bundle's own `package.json`), then **`./node_modules/.bin/bareloop run . --repo <path>
+  …`**. `checkBundleDeps` (above) is the fail-safe that catches the wrong-shape install
+  before any close ever runs; see `docs/logs/FINDINGS.md` F128 for the full account
+  (grounded in the real crashed spine) and `docs/product/EXPORT-BUILD.md`'s dated addendum.
+
+  **Minting-run line, corrected (F128).** The first-run notice used to print the shipped
+  bridge's FIRST history row's `runid`, unconditionally. It now searches every bridge
+  VERSION across all shipped bridges (base + shape fork) for the one whose `specHash` equals
+  the resolved `$BARELOOP_BUNDLE` spec's `jobSpecHash`, printing `minting run: <runid> (spine
+  not bundled in v1)` on a match or **`no version at this hash`** (never a guessed runid)
+  when none matches — which, cross-machine, is the common case, since the historic mint's
+  real close-script path and the importer's own bundle path essentially never coincide.
+
+- **`bareloop history <bundleDir>`** → prints every `history.jsonl` line verbatim, then
+  every bridge's `listingRow(b)` from `<bundleDir>/bridges`. Always exit `0`; "(no runs
+  yet)" when `history.jsonl` doesn't exist.
+
+**Tighten-only budget/wall.** `--budget`/`--wall` on `bareloop run` may only lower the
+bundle's own signed `budgetUsd`/`maxWallMs` — `checkEnvelope`'s `envelope-widen` red refuses
+anything higher. Raising a ceiling is a re-export (a new signed bundle), never a runner flag.
+
+**First-run approval, blessing, no-resign.** The bundle's own signed `bundleHash` is what a
+human reads and accepts with `--approve` on the run that first blesses it. That first GREEN
+writes `blessing.json`; every later run on that machine, against that same unchanged bundle,
+needs no `--approve` at all ("no-resign", hamr's ruling) — it only has to pass
+`verifyBlessing`. Editing the bundle after blessing (or re-exporting it) changes
+`manifest.bundleHash`, so the stored blessing goes stale (`blessing-stale`) and the human
+has to approve again.
+
+**Fresh worktree per run; merge stays human.** Every `bareloop run` creates a brand-new
+`git worktree add --detach <repo>/.bareloop/wt/<runid>` off `HEAD` and hands that path to
+`runJob` as `workdir` — the caller's own checkout is never touched, and no worktree is ever
+reused (reuse would let a prior run's uncommitted edits masquerade as this run's own green).
+The CLI never merges anything itself: the tail prints the exact `git merge <branch>` command
+and leaves the worktree in place until the human removes it.
+
+**`history.jsonl` row shape** — one JSON object per line, one line per `bareloop run` on this
+machine: `{ runid, at, outcome, spentUsd, spendComplete, budgetUsd, maxWallMs, worktree,
+branch, bundleHash, approveHash }`. `bundleHash` is the bundle's own signed manifest hash
+(unchanged across tightened runs); `approveHash` is the hash of the actual, possibly-
+tightened, `$BARELOOP_BUNDLE`-resolved spec that run executed — the two are recorded side
+by side so a tightened run's real approval can never be confused with the bundle's headline
+signature.
+
+**Vocabulary:** `close-red` means the close **instrument** itself broke — it could not run,
+never finished, was killed, or crashed without judging anything (`CLOSE_FAULTS`, above) —
+never a judgment about the work. `plan-red` means the close ran, judged, and rendered a real
+**no**. A `readBundle`/`checkEnvelope`/`checkBundleDeps` red is a bundle-shape, envelope, or
+dependency refusal (before any provider call); it is none of those three — call it what it
+is: a bundle-red, an envelope-red, or a deps-red, not a close verdict. (F128's live defect
+would, unfixed, have shown up as `close-red` at runtime for a reason that had nothing to do
+with the close itself — `checkBundleDeps` exists precisely so a wrong-shape install never
+reaches that far.)
+
+**What is NOT in v1 (hamr Q7):** the review door at the run's tail, `soft-green`, any
+provider but `anthropic-api`, spine bundling for `formatReplay` on the minting run (only its
+`runid` is noted), and tarball packing — a bundle is a plain directory; use `npm pack` on it
+yourself if you want a tarball.
 
 ## Architecture
 

package/bin/bareloop.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Export M2 — a thin adapter. ALL logic lives in `src/cli.js`; this file only
+// supplies the real deps and turns the returned exit code into
+// `process.exitCode` (never `process.exit()`, which can discard queued
+// stdout under a slow reader).
+import { main } from '../src/cli.js';
+
+// A reader closing early (e.g. `| head`) makes a queued stdout write throw
+// EPIPE — the one legitimate `process.exit()` in this file: the reader is
+// gone, so there is no more queued output to lose by exiting immediately,
+// and re-throwing would print a scary stack trace for ordinary pipe usage.
+process.stdout.on('error', (e) => {
+  if (e.code === 'EPIPE') process.exit(0);
+  throw e;
+});
+
+const code = await main(process.argv.slice(2), {
+  env: process.env,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  cwd: process.cwd(),
+  stdin: process.stdin,
+});
+process.exitCode = code;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bareloop",
-  "version": "0.19.1",
-  "description": "Workflows that earn their own design, with receipts \u2014 agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
+  "version": "0.21.0",
+  "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -11,6 +11,9 @@
       "default": "./src/index.js"
     }
   },
+  "bin": {
+    "bareloop": "bin/bareloop.mjs"
+  },
   "license": "Apache-2.0",
   "author": "hamr0",
   "engines": {
@@ -38,6 +41,7 @@
   "homepage": "https://github.com/hamr0/bareloop#readme",
   "files": [
     "src/",
+    "bin/",
     "types/",
     "NOTICE",
     "bareloop.context.md",