bareloop 0.20.0 → 0.22.0

package/bareloop.context.md

@@ -134,7 +134,8 @@ minting claim, or the shell-owned retry cap — all unknown-field reds.
 | `conditions` | `{ providerPath?, closeVerbosity?, taskFraming?, scaffold? }` | declared keys only, string values — the environment label (consumed by the N3 lineage key; recorded on spines from run one) |
 | `cadence` | `{ unit: hour\|day\|week, every: 1..30 }` | validated now, consumed at N5 (Scheduler) |
 | `budgetUsd` | `0 < n <= shell cap` | ceiling chain: workflow ≤ job ≤ shell — each layer may tighten, never exceed |
-| `maxWallMs` | optional integer ms `>= MIN_WALL_MS` (one close timeout) | the run's wall clock. **NO DEFAULT, by ruling** — absent means time-unbounded *by explicit operator choice*, never by fallback (F45: a defaulted cap is a silent second ceiling). Enforcement is a BETWEEN-ROUND deadline, so the honest worst case is `maxWallMs + closeStages × closeTimeoutMs` — every stage of a staged close gets the FULL timeout — and all three numbers are reported (`loop.stop()` cannot cut an in-flight call — F61 measured 500ms→4,018ms). The `MIN_WALL_MS` floor is a ONE-stage number, so a spec with many stages can validate while its overshoot dwarfs its cap: the clock reports that honestly rather than the floor pretending to prevent it (stage-aware floor parked, PRD v1.39). Operator-only, tighten-only; adding or changing it changes the spec hash |
+| `maxWallMs` | optional integer ms `>= MIN_WALL_MS` (one close timeout) | the run's wall clock. **NO DEFAULT, by ruling** — absent means time-unbounded *by explicit operator choice*, never by fallback (F45: a defaulted cap is a silent second ceiling). Enforcement is a BETWEEN-ROUND deadline, so the honest worst case is `maxWallMs + closeStages × closeTimeoutMs` — every stage of a staged close gets the FULL timeout — and all three numbers are reported (`loop.stop()` cannot cut an in-flight call — F61 measured 500ms→4,018ms). The `MIN_WALL_MS` floor is a ONE-stage, un-autoset-default number, so a spec with many stages OR a raised/autoset `closeTimeoutMs` can validate while its overshoot dwarfs its cap: `runPlan` adds a RUN-START check (PRD item 27/M3) that refuses `wall-under-close-timeout` at $0 once the EFFECTIVE per-stage ceiling is known (autoset or signed), rather than a silent clamp. Operator-only, tighten-only; adding or changing it changes the spec hash |
+| `closeTimeoutMs` | optional integer ms `>= CLOSE_TIMEOUT_FLOOR_MS` (120,000 — hamr's arbiter floor, 2026-09-07) | PRD item 27/M3's SIGNED override for the close's own per-stage wall-clock cap. Absent (the normal case): the run autosets it from a $0 seed timing pass — `max(FLOOR, K × slowest measured stage)`, `K = 5` (hamr, 2026-09-07: "2 and 5 are fine"). Present: the operator's own number wins outright and may legally sit ABOVE *or below* the autoset estimate (the rates-passthrough shape, F113 — never tighten-only). Arbiter territory exactly like `budgetUsd`/`maxWallMs`/`close[].sha256`: the authoring pipeline's `assembleSpec` refuses a draft carrying it |
 | `model` | optional non-empty string, exact provider model id (e.g. `"claude-sonnet-5"`) | the WORKER's model, build-list #3. Absent means today's runner default; present it wins over a `--model` flag outright, and a flag naming a different id is refused (`resolveWorkerModel`, `src/job.js`) rather than silently overridden. Part of the signed hash like every other field. Worker only — the judge model stays library-pinned (`JUDGE_MODEL`) pending recalibration |
 | `writeScope` | array of contained globs | the operator's outer fence; the plan's own scopes must fit inside it, same containment code |
 | `steps` | RETIRED | operator-authored `steps[]` was deleted (PRD v1.32); a spec carrying it reds `shape-retired:steps` by name rather than half-running |
@@ -391,7 +392,7 @@ Append-only JSONL event emitter bound to one file. `seq` monotonic per spine, `t
 last. Consumers are pure listeners; nothing reads the file back. Returns each event as
 written.
 
-### `ralph({ middle, close?, judge?, capRuns?, ladder?, emit, redact?, closeTimeoutMs?, cwd?, expect?, judged?, gapKeep?, workerWrites? })` → `'green' | 'escalated'` — `src/ralph.js`
+### `ralph({ middle, close?, judge?, capRuns?, ladder?, emit, redact?, closeTimeoutMs?, cwd?, expect?, judged?, gapKeep?, workerWrites?, closeDir? })` → `'green' | 'escalated'` — `src/ralph.js`
 
 The dumb outer shell: `while close-red and not exhausted: run the middle`. **Exhaustion has
 two alternative rules and you supply exactly one** — `capRuns` (a fixed number of middle runs)
@@ -422,11 +423,23 @@ set the close's `gapKeep` (job-spec, arbiter territory) to a regex like `"^not o
 matching failure lines are preserved in a capped kept-failures block regardless of where
 they print (F28: the first real firing delivered a gap with zero failure names). The gap
 also combines stdout+stderr, so a stdout failure survives stderr noise.
-`closeTimeoutMs` caps the close's wall clock (default 120s) — shell/operator
-territory, inexpressible in any config. A faulted close is asked to leave with SIGTERM and,
-if it is still there 2s later, ended with SIGKILL: SIGTERM is a request a close can decline
-(its own handler, a trapping wrapper), and without a second deadline the wait never resolves.
-The verdict is untouched — the FIRST fault named the outcome and the kill only enforces it.
+`closeTimeoutMs` caps the close's wall clock (default 120s when nothing else supplies a
+value — `runClose`'s own bare default) — shell/operator territory, inexpressible in any
+config. A faulted close is asked to leave with SIGTERM and, if it is still there 2s later,
+ended with SIGKILL: SIGTERM is a request a close can decline (its own handler, a trapping
+wrapper), and without a second deadline the wait never resolves. The verdict is untouched —
+the FIRST fault named the outcome and the kill only enforces it. **As of PRD item 27/M3, a
+direct `ralph`/`runClose`/`runStages` caller still owns this number outright (`closeTimeoutMs
+?? 120_000`); the AUTOSET/override resolution lives one level up, in `runPlan`/`runJob`
+(see `resolveCloseTimeoutMs` below) — `ralph` itself never runs a timing pass.**
+
+`closeDir` (PRD item 27/M3 Part B, optional) is the close's own BOOKS DIRECTORY — pristine
+copies, calibration thresholds, logs — deliberately outside the patient tree (the worker
+must never read the arbiter's books, v1.12). Forwarded to every close invocation as the
+env var `BARELOOP_CLOSE_DIR` (set on a COPY of `process.env`, after `CLOSE_ENV_DENY`
+stripping — a `BARELOOP_` name matches none of that denylist's rules and is never stripped).
+A close script that reads this variable and gets none must instrument-stop itself; nothing
+in the runner invents a fallback directory.
 
 **The close child's environment is stripped of credential-shaped variables before it runs**
 (`CLOSE_ENV_DENY` in `src/ralph.js`: provider keys, `AWS_*`, any name ending
@@ -958,13 +971,33 @@ 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?, scout?, 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?, closeDir?, layerRoot?, readShim?, scout?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun?, resumable? })` → outcome — `src/run.js`
+
+**`closeTimeoutMs` (PRD item 27/M3) is now OPTIONAL for every real caller.** Omit it (both
+`src/cli.js`'s bundle runner and `scripts/run-u.mjs` do) and the run AUTOSETS the per-stage
+close ceiling from a $0 seed timing pass, or reads the job spec's own signed override —
+"guesstimate + loud sign + customer override", the same shape rates-passthrough already
+uses (F113). Passing an explicit value here still wins outright over both (kept for
+backward compatibility and test control) — see `resolveCloseTimeoutMs` further down.
+
+**`closeDir` (PRD item 27/M3 Part B, optional but effectively required for any
+hand-authored close that reads its own books)** — the close's own directory (pristine
+copies, calibration thresholds, logs), outside the patient tree. `src/cli.js` sets it to
+`<bundleDir>/runs/<runid>/close/`; `scripts/run-u.mjs` sets it to its existing `spineDir`. A
+close script whose source mentions `BARELOOP_CLOSE_DIR` and gets none here refuses the run
+at $0 (`close-dir-required`, before any provider call) — see `checkCloseDirRequired` below.
 
 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.
 Three of them are folds of a bound the operator SIGNED (money, wall, replans) and one is a
 readout seed (grades) — the distinction matters and is spelled out there.
 
+`resumable` (default `true`, PRD item 27(c)/F130) says whether THIS runner supports
+`--resume` at all — `run-u.mjs` leaves it at the default (byte-identical to before this
+flag existed); the exported bundle CLI (`src/cli.js`) passes `false` so the run's
+escalation tail says "resume is `run-u`-only in v1" instead of naming a flag it does not
+implement.
+
 The runner — the shell's top layer, and the ONE entry. It composes everything below it and
 interprets nothing itself. Sequence: **approval gate** (human-signs-always — refuses an
 unapproved spec before ANY provider call: `unapproved-spec`) → **primitive smoke** (litectx
@@ -1601,7 +1634,7 @@ package makes). Which runs open one is `doorOpens(job, reviewDoor)`:
   territory.
 
 **Answering one — `answerReviewDoor({ job, workdir, events, decision, text?, closeTimeoutMs?,
-registryDir?, name?, runid?, at?, now?, emit? })`** (`src/reviewdoor.js`). The answer arrives
+closeDir?, registryDir?, name?, runid?, at?, now?, emit? })`** (`src/reviewdoor.js`). The answer arrives
 after the run has ended, possibly days later and from another process, so it cannot ride the
 run's return path. This is that seam. It never throws and never conjures — a fourth door, an
 empty `rerun`, a run that opened no door (`no-door`), an expired one (`door-expired`), a tree
@@ -2481,7 +2514,9 @@ nothing here to check it against).
 
 Enforcement is **local only** — wired into `npm test` (see `package.json`'s `test`
 script), never into `.github/workflows/*` (CI already runs `npm test`, so the rule is
-enforced there without an ask-first CI edit). The check itself lives outside the
+enforced there without an ask-first CI edit). `npm test` itself now runs `node --test`
+through `scripts/hermetic.mjs`, which strips this machine's `HOME`/git identity so a
+test that leans on either fails locally instead of only on CI (F136). The check itself lives outside the
 published package, at `scripts/prompt-commit-check.mjs` (pure decision logic in
 `scripts/promptcommitlib.mjs`, `scripts/` is not in `package.json`'s `files`, so none of
 this ships):
@@ -2511,6 +2546,292 @@ 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/close-integrity.js` — close-absolute-path (M1) AND close-bytes signature (M2)
+
+Shared by `src/bundle.js` (export time) and a $0 run-start precheck inside `runPlan`
+(`src/planrun.js`) — every job, not only exported bundles, refuses at $0 (before the
+close-first precheck, before any provider call) when a close script's CONTENT bakes in an
+absolute path that exists on disk. Two spellings of the same rule is exactly how F129
+shipped an export-only guard while every non-exported job stayed exposed.
+
+**Scope (widened 2026-09-06, PRD item 27/M2, an orchestrator audit):** a close script is
+addressable — visible to `readCloseScripts`, `checkCloseAbsolutePaths`, the sha256
+fingerprint, and `signCloseScripts` — when its `cmd` is EITHER an interpreter
+(`node`/`sh`/`bash`/`python`/`python3`/`npx`) followed by a non-empty argv[1], OR a bare
+cmd whose argv[0] ITSELF is an absolute path (a `.sh`/other directly-executable close
+script, no interpreter prefix — e.g. `jobs/aurora-testgen-cold.json`'s close). A relative
+bare executable (`true`, `pytest`, `npm test`) names no file at all and stays out of
+scope, on both halves, exactly as before. The shape test itself
+(`closeScriptCandidateToken`, `src/validate.js`) is shared with `src/job.js`'s sha256
+demand so the demand and the detectors can never drift apart about which stages are in
+scope.
+
+| function | args → returns | notes |
+|---|---|---|
+| `absolutePathLiteralsOf(source)` | close script text → `string[]` | the scan itself (moved here from `src/bundle.js`, which now imports it) |
+| `readCloseScripts(spec, cwd)` | resolved job spec + cwd → `{ stage, path, bytes, sha256 }[]` | resolves every addressable `close[].cmd` (see scope above) to its absolute path and bytes off disk; a relative path resolves against `cwd`. Never throws — a missing/unreadable script reports `bytes: null`. `sha256` (M2, additive) is the stage's own signed field verbatim, or `null` |
+| `checkCloseAbsolutePaths(spec, cwd)` | resolved job spec + cwd → `{ ok: true } \| { ok: false, reds: { stage, path, literal }[] }` | the run-start check `runPlan` calls before the close-first precheck |
+| `hashCloseScriptBytes(text)` | script text → sha256 hex | the ONE formula every M2 consumer uses (minting, the run-start check, the runtime re-verify, the export mismatch check) — hashing the utf8-decoded text agrees with hashing the raw file bytes because a close script is always valid UTF-8 |
+| `checkCloseByteSignature(spec, cwd)` | resolved job spec + cwd → `{ ok: true } \| { ok: false, reds: { stage, path, expected, actual }[] }` | the $0 run-start integrity check (PRD item 27): every signed `close[].sha256` must match the script's bytes off disk RIGHT NOW. `runPlan` calls this alongside `checkCloseAbsolutePaths`, before the close-first precheck and before any provider call — a mismatch reds `close-tampered`. An unreadable signed script reads `actual: null` and is STILL a red (never silently "fine") |
+| `checkStageByteSignature(stages, cwd)` | a close stage chain + cwd → same shape as above | the narrower re-verify `runPlan`'s `runCloseStages` wrapper runs before EVERY close execution (precheck, preflight, check-passes, and the close-fix loop all go through this one seam) — a mismatch short-circuits to a `close-tampered` verdict in the same shape `runClose`/`runStages` render, so it rides out through the existing `CLOSE_FAULTS` machinery exactly like `crashed`/`timed-out`/`killed` |
+| `signCloseScripts(spec, cwd)` | resolved job spec + cwd → `{ ok, spec, changes: {stage,path,old,new}[], missing: {stage,path}[] }` | the PURE minting helper: fills `close[].sha256` from disk for every addressable stage. Never writes anything itself — `scripts/sign-close.mjs` is the thin CLI wrapper that gates on `--write`. A `closeDecl` spec (no script path to sign) returns `ok:false` unchanged |
+| `checkCloseDirRequired(spec, cwd, closeDir)` | resolved job spec + cwd + the runner's `closeDir` (or `null`) → `{ ok: true } \| { ok: false, reds: { stage, path }[] }` | PRD item 27/M3 Part B: scans the same addressable-script bytes `readCloseScripts` reads for the literal substring `BARELOOP_CLOSE_DIR` — a script that mentions it needs a real `closeDir` or it would run against `undefined`. A script that never mentions it carries no demand |
+| `CLOSE_DIR_ENV_VAR` | `'BARELOOP_CLOSE_DIR'` | the ONE spelling `checkCloseDirRequired`'s scan and `runClose`'s env-set (`src/ralph.js`) both use |
+
+#### `src/closetimeout.js` — close timeout: autoset + signed override (M3)
+
+hamr's ruling (2026-09-06): *"both … autoset and can be override, same like api pricing"*
+— the guesstimate-plus-loud-sign-plus-customer-override shape (F113), never a hidden
+defaulted knob. Arbiter constants, hamr 2026-09-07 verbatim: **floor = 120,000 ms; K = 5
+("2 and 5 are fine")** — never agent- or adopter-settable.
+
+| export | shape | notes |
+|---|---|---|
+| `CLOSE_TIMEOUT_FLOOR_MS` | `120_000` | the floor, hamr's arbiter constant |
+| `CLOSE_TIMEOUT_K` | `5` | the multiplier, hamr's arbiter constant |
+| `LIBRARY_DEFAULT_CLOSE_TIMEOUT_MS` | `120_000` | `runClose`'s own un-autoset default (`src/ralph.js`'s `timeoutMs = 120_000`) — named separately from the floor above even though the two numbers agree today, because they are different claims |
+| `TIMING_PREFLIGHT_CEILING_MS` | `600_000` (library default × K) | the GENEROUS provisional ceiling every stage runs under DURING the timing pass itself — never the autoset/override ceiling the run then uses, which is only known after the pass completes |
+| `timeCloseStages(stages, {cwd, redact})` | → `{ perStage: {name,ms,exitCode,timedOut}[], slowestMs, slowestName, anyTimedOut }` | runs EVERY stage once, ignoring verdicts (first-red-wins stays for the real verdict precheck) — a declared/kind stage (no `.cmd`) is skipped, contributing no reading rather than a false zero. A stage that never finishes within `TIMING_PREFLIGHT_CEILING_MS` reads `timedOut: true` |
+| `computeCloseTimeoutCeiling({slowestMs, overrideMs?})` | → `{ ceilingMs, source: 'estimated'\|'override' }` | `max(FLOOR, K × slowestMs)`, unless `overrideMs` is given, in which case it wins outright (may sit above OR below the estimate — not tighten-only) |
+| `resolveCloseTimeoutMs({job, stages, cwd, redact})` | → `{ closeTimeoutMs, source, timing, timedOut }` | the ONE resolver `src/planrun.js` and `scripts/run-u.mjs` BOTH call (never two independent spellings of this precedence): a signed `job.closeTimeoutMs` wins with NO timing pass run at all; absent, the pass runs and the ceiling autosets. `timedOut: true` means a stage never finished the pass — the caller reds `close-timing-red` rather than trusting any number |
+| `closeTimeoutBanner({ceilingMs, source, slowestMs?, slowestName?})` | → the printed line | ONE spelling for `estimated`/`override`/`explicit` (the last is the pre-M3 shell/test runtime-option escape hatch, never the signed field) — printed on every run so a silent default can never hide behind this feature the way the OLD 120s/900s defaults did |
+
+**`scripts/sign-close.mjs`** — `node scripts/sign-close.mjs <jobs/x.json> [--write]` or
+`--all` for every `jobs/*.json`. Prints the old→new `jobSpecHash` and each stage's
+old→new sha256; NEVER writes unless `--write` is passed (a dry run is the default). The
+agent never runs this with `--write` on its own authority — minting a close-bytes
+signature is arbiter territory exactly like a budget or a wall clock, the same as the
+authoring pipeline's own refusal (`src/authorjob.js`'s `assembleSpec`, which refuses a
+draft carrying `sha256` the same way it refuses `close`/`closeDecl`/`verdictType`).
+
+**`close[].sha256`** — a signed spec field (PRD item 27/M2): hex sha256 of the bytes of
+the script file the stage's `cmd` names (only for an addressable cmd, per the scope
+above). `validateJob` (`src/job.js`) demands it as `missing-required` on every addressable
+stage and shape-checks it (`invalid-value`, 64 lowercase hex chars) even where not
+demanded. It sits INSIDE the signed spec, so `jobSpecHash` covers it with no
+hash-function change — re-signing a job (minting or changing this field) moves the spec
+hash and needs re-approval, exactly like any other semantic edit.
+
+#### `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. **F132:** a stage carrying a signed `close[].sha256` gets it RE-SIGNED in the written `spec.json` over the RELOCATED bytes (post import-rewrite) it actually packs — not copied verbatim from the source spec. Without this, a script whose import gets rewritten (`../src/x.js` → `'bareloop'`) ships with a signature that covers the wrong bytes, and the bundle refuses itself as `close-tampered` at $0 on its very first run (the manifest hash and the spec signature disagree over two different byte strings for the same file) |
+| `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) AND `runPlan` (PRD item 27, every job) | a close script's source bakes in a quoted string literal that is an absolute POSIX path which `existsSync` finds real on this 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, `src/close-integrity.js`, for its named limits: string concatenation and cross-machine-only paths are invisible to it). `runPlan` reds this at run start, before the close-first precheck and before any provider call — $0, nothing spent |
+| `close-sha-mismatch` | `exportBundle` (PRD item 27/M2) | a `close[].sha256` the spec carries does not match the bytes of the script actually being packed into the bundle — the two signatures (this one, and `bundleHash`'s manifest hash over the rewritten script) cover the same bytes by two different paths and must never drift apart silently (N4's own hazard, one layer up). Only fires when a value is PRESENT and wrong; a spec with no sha256 at all reds `missing-required` upstream, at `validateJob` |
+| `close-tampered` | `runPlan` (PRD item 27/M2) | a close script's bytes no longer match its signed `sha256` — checked at run start (alongside `close-absolute-path`, before the close-first precheck and before any provider call) AND before EVERY close run thereafter (`runCloseStages`'s wrapper in `src/planrun.js`, the one seam the precheck/preflight/check-passes/close-fix-loop all share). Distinct from `close-red` (a judged "no" from a working close) and from `close-crashed`/`close-timeout`/`close-killed` (the close ran and hit an instrument fault): this is decided BEFORE the close is even spawned, and it means the close that ran would not have been the one the operator approved. Registered in `CLOSE_FAULTS` (`src/ralph.js`) so it rides out through the same forbidden-zone machinery as every other close fault — never retried, never fed back as a gap |
+| `close-dir-required` | `runPlan` (PRD item 27/M3 Part B) | a close script's source mentions `BARELOOP_CLOSE_DIR` (it reads its own books directory) but the runner was given no `closeDir` at all — `checkCloseDirRequired` (`src/close-integrity.js`) reuses the same `readCloseScripts` reader the other two integrity checks share. $0, run start, before the close-first precheck and before any provider call |
+| `close-timing-red` | `runPlan` (PRD item 27/M3) | the $0 timing preflight (`resolveCloseTimeoutMs`/`timeCloseStages`, `src/closetimeout.js`) ran every close stage once, ignoring verdicts, and at least one never finished within the provisional ceiling (`TIMING_PREFLIGHT_CEILING_MS`, the library default × K = 600s) — the close cannot run on this machine in a boundable time. Only reachable when NEITHER a signed `job.closeTimeoutMs` NOR a caller-passed runtime override is present (both skip the pass entirely) |
+| `wall-under-close-timeout` | `runPlan` (PRD item 27/M3) | `job.maxWallMs` is set and is under the EFFECTIVE per-stage close timeout just resolved (autoset or signed) — a budget under one close cannot fund its own close. `validateJob`'s own `MIN_WALL_MS` floor only bounds the un-autoset library default; this run-start check is the honest shape once the real ceiling is known, rather than a silent clamp |
+| `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.20.0",
-  "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.22.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,13 +11,16 @@
       "default": "./src/index.js"
     }
   },
+  "bin": {
+    "bareloop": "bin/bareloop.mjs"
+  },
   "license": "Apache-2.0",
   "author": "hamr0",
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --test && node scripts/prompt-commit-check.mjs --range origin/main..HEAD",
+    "test": "node scripts/hermetic.mjs && node scripts/prompt-commit-check.mjs --range origin/main..HEAD",
     "typecheck": "tsc --noEmit",
     "build:types": "tsc",
     "prepublishOnly": "npm run build:types"
@@ -38,6 +41,7 @@
   "homepage": "https://github.com/hamr0/bareloop#readme",
   "files": [
     "src/",
+    "bin/",
     "types/",
     "NOTICE",
     "bareloop.context.md",

package/src/authorjob.js

@@ -654,7 +654,21 @@ export async function authorCloseForJob({
 /** The fields `assembleSpec` writes, and therefore the fields a DRAFT must not
  * carry. Named as data so the refusal and the fold can never disagree about
  * which half of the spec is which. */
-export const AUTHORED_SPEC_FIELDS = Object.freeze(['close', 'closeDecl', 'verdictType']);
+// `sha256` (PRD item 27/M2) rides alongside `close`/`closeDecl`/`verdictType`:
+// it is arbiter territory exactly like a budget or a wall clock — the agent
+// never mints a close-bytes signature (only `signCloseScripts`/hamr's own
+// re-sign does), so a draft carrying the field at all is refused the same
+// way one carrying a raw `close` array is. A `closeDecl` spec has no script
+// path to sign in the first place (M1's own kind executor, never a shipped
+// script), so this can only ever fire on a smuggled/legacy-shaped draft —
+// named here anyway, because "arbiter fields are refused by name" is the
+// rule, not "arbiter fields that are currently reachable are refused".
+// `closeTimeoutMs` (PRD item 27/M3) joins the same list for the same reason:
+// it is arbiter territory exactly like the timeout floor/multiplier
+// themselves — the agent never mints a close-timeout override (only the
+// operator's own signed spec edit does), so a draft carrying it is refused
+// the same way one carrying a raw `close` array is.
+export const AUTHORED_SPEC_FIELDS = Object.freeze(['close', 'closeDecl', 'verdictType', 'sha256', 'closeTimeoutMs']);
 
 /**
  * Fold an authored close into the OPERATOR's own half of the spec.