bareloop 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,195 @@ 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.
 
+## [Unreleased]
+
+## [0.15.0] — 2026-08-27
+
+### Added
+
+- **Generic run replay** (PRD build-list #6): `replayRun`/`formatReplay` (`src/replay.js`)
+  reconstruct one run's whole story from its spine JSONL + gate-audit sidecar. The single-run
+  report is a signed layout (hamr, 2026-08-25): a header block (`goal:`/`shape:`/`signed:`/
+  `branch:`/`outcome:`/`spent:`, absent fields printing the literal `none recorded`, never
+  blank or a fabricated `0`), a `TIMELINE (steps)` or `TIMELINE (iterations — loop-shape run)`
+  section with its own column-header row and per-row time/cost (wall, `$` — a `null` `costUsd`
+  anywhere in a row's window makes that row's spend `unknown (N unpriced rounds)`, never `0` or
+  a partial sum stamped exact) and a `↳ tripped:`/`↳ close:` line under any row an escalation or
+  close fell inside, a `CLOSE` section (never omitted — `none — the run ended before any close
+  ran` when nothing ever closed; picks the run's REAL final close by seq, never by record type —
+  an early `outer-close` precheck reading red must not shadow a LATER fix-loop close-verdict that
+  went satisfied), `ENDING` (last record + 3 before it, plus an out-of-window escalation), the
+  `BEHAVIOUR` block, and a `MEMORY-CACHE` line always printed (`not armed on this run` when
+  absent — absence is never silent). Stop reason is `category — decision — detail` off the last
+  escalation, so a run's actual failure text (a TLS "bad record mac", a specific mypy error)
+  rides onto the report instead of just the generic per-category decision prose. A step id that
+  recurs after a replan is split per OCCURRENCE, never merged into one pooled row. `--all <dir>`
+  is name-agnostic (a spine is identified by a `job-start`/`run-start` record in its content,
+  never a filename convention) and prints a fixed-column, ALIGNED table (never CSV) — `id job
+  shape outcome spend wall steps reason`, `reason` built from `detail` only (never `decision`,
+  cut at 60 chars) — flagging any non-spine `.jsonl` as `<name> not-a-spine` rather than dropping
+  it. A RESUMED run's `job-end.spentUsd` is a CHAIN total (prior legs folded in) that can never
+  equal this one file's own rounds (measured: `u-msf70nei` header `$5.3389` vs its own 55 rounds
+  summing to `$1.2127`) — the header now prints both, each labelled, plus a `resumed:` line
+  (keyed on `job-start.priorSpentUsd`, never on the narrower `resume-seed` record alone — 4 real
+  archived runs carry a real fold with no resume-seed record at all). A non-resumed run's own
+  spend disagreeing with its summed rounds is a genuine finding and prints as a `MISMATCH`, never
+  hidden (measured: 0 of the archive's non-resumed runs trip it). `--all` marks a resumed row
+  with a trailing `*` and one footnote line when the listing holds any. Reuses `runBehaviour`/the
+  `memory-cache` readout rather than reimplementing either. Reads only, mints no verdict, writes
+  nothing to the spine. `job-start` (`src/run.js`) now also carries `verdictType` (the spec's
+  required verdict class) and `model` (when the shell-owned provider binding itself carries one)
+  — PRD TODO #20, blessed verbatim by hamr the same day. The header prints `class:`/`model:`
+  right after `shape:` (`not recorded (pre-F117 spine)` / `not recorded` on an older archive or
+  a provider with no `.model`), and `--all` gains `class`/`model` columns (`model` kept FULL,
+  never truncated).
+- **Prompt-commit shape — a check, not convention** (PRD build-list #5, TODO #8, Q9 answered
+  by hamr 2026-08-25): a commit that changes a prompt register (a model-facing
+  system/strategy/instruction string a worker or judge reads) must now say, in its own
+  message, three labelled things — `Failure:` what caused the change, `Addresses:` what it
+  addresses, `Corrects:` what it corrects. `src/promptregisters.js` (`PROMPT_REGISTERS`,
+  `isPromptFile`, both exported from `bareloop`'s root) is the ONE inventory: 7 files carry
+  real prompt content (`src/authorscout.js`, `src/authorflow.js`, `src/judged.js`,
+  `src/cardauthor.js`, `src/readshim.js`, `src/tools.js`, `src/planrun.js`) — more than double
+  the 8 named consts a first grep found, once module-private consts and inline
+  template-literal prompt builders (`scoutPrompt()`, `cardCasesPrompt()`, `locatePrompt()`,
+  `strategyFor()`) are counted; the check is file-scoped precisely because a const-scoped one
+  would have silently missed those. Enforcement is LOCAL ONLY — wired into `npm test`
+  (`scripts/prompt-commit-check.mjs --range origin/main..HEAD`), never into any
+  `.github/workflows/*` file (ask-first, untouched); an unresolvable range (no `origin`, no
+  fetch) is a printed SKIP at exit 0, never a violation. Pure decision logic lives in
+  `scripts/promptcommitlib.mjs`, neither of which ships (`scripts/` is outside
+  `package.json`'s `files`). hamr's same-day addition: the `Failure:` line must also cite
+  the RUN that caused the change (`run <id>` / `run u-<id>`, `\brun\s+(u-)?[a-z0-9]{6,12}\b`
+  — alphabet/length measured against 231 real archived spine ids, every one exactly 8
+  lowercase-alnum chars), failing with a distinct message
+  (`FAILURE_NEEDS_RUN_REF`) when absent; format only, never checked against a real spine
+  file.
+- **Run→code stamp** (F118, the parked half of the same day's prompt-commit build, closed
+  same day on hamr's go): the prompt-commit check closes commit→run; this closes run→code.
+  `src/codeversion.js`'s `codeVersion()` is a pure, $0, no-shell reader — `version` from
+  bareloop's own `package.json`, `sha` from `.git/HEAD` (loose ref, falling back to
+  `packed-refs`) ONLY when a `.git` directory exists at the package root (a dev checkout;
+  an npm install has none), `dirty` always `null` (uncommitted-changes state cannot be
+  known without a shell — reported as unknown, never faked as `false`). `job-start`
+  (`src/run.js`) now also carries `code: {version, sha}`. `replayRun`/`formatReplay`
+  (`src/replay.js`) read it: a `code:` line right after `model:` — `bareloop 0.14.0 @
+  43f2812` / `@ sha unknown` / `not recorded (pre-F118 spine)`; no new `--all` column
+  (hamr's index is already full). The library never grows a shell seam to answer this —
+  `run` stays the one locked verb.
+- **Replay surfaces transport retries and floor reasons** (F119, live-proven the same day
+  a real run — `u-mt8yk53k` — fired the retry seam twice): `replayRun`/`formatReplay`
+  window `transport-retry` records into the step/iteration occurrence they fell inside
+  (same `seq` windowing as `worker-round`), printing `↳ transport retry ×N (recovered|not
+  recovered|partially recovered) — <error>` under that row; a retry outside every window
+  prints as `transport retries outside steps: N` under the `TIMELINE` header instead. The
+  header's `spent:` line, whenever `spendComplete:false`, now appends `· floor because:
+  <reason(s)>` — derived from the spine, never guessed: `transport retry ×N`, `unpriced
+  round(s)`, `cut mid-call`, `stall`, `prior leg floor`, every cause that shows real
+  evidence, or `floor (reason not in spine)` when none can be derived. `--all` adds no
+  column: a run carrying any retry gets ` ⟲N` appended to its outcome word (same posture
+  as the resumed `*`), with one footnote when the listing holds any. Report-only — reads
+  existing `transport-retry`/`wall-halt`/`stall`/`job-start` records, writes nothing.
+
+### Fixed
+
+- **Leaked tmp dirs from `npm test`** (same class that filled `/tmp` tmpfs on 2026-08-25 and
+  blocked a build): `tests/codeversion.test.js`'s real-worktree test tracked only the `wt`
+  subdirectory passed to `git worktree remove`, never the `mkdtemp`-created parent, so every run
+  left an empty `codeversion-worktree-*` dir behind; its `after()` now also prunes stale worktree
+  metadata when `remove` fails and `rmSync`s the tracked dir unconditionally, plus the mkdtemp
+  parent is now itself tracked and removed. `tests/ralph.test.js`'s cwd-threading test created a
+  `ralph-cwd-*` repo with no cleanup at all, and its cwd-relative-close test likewise leaked a
+  `close-cwd-*` and a `close-cwd-other-*` dir per run; added a per-test `after(() => rmSync(...))`
+  for each, matching the file's existing top-level cleanup pattern.
+- **`codeversion.test.js` false-red on PR checkouts** (F118 addendum): the HEAD-sha test's own
+  precondition assumed a symbolic ref, but `actions/checkout` leaves a PR checkout's HEAD
+  DETACHED at the merge commit, so the precondition threw before the module under test ever
+  ran — `src/codeversion.js` itself already handled the detached case correctly. Test-only fix:
+  the precondition now resolves a bare 40-hex `.git/HEAD` the same way `codeVersion()` does, plus
+  a new deterministic fake-package-root test that exercises the detached case without depending
+  on the checkout's own HEAD state.
+- **Review of PR #23 (2026-08-26), 7 items fixed**: (1) `replayRun`'s spend totals
+  (`src/replay.js`) counted only `worker-round`, silently dropping a close's own `judge-round`
+  spend and native `worker-turn` attribution out of every total — now filters on the canonical
+  `SPEND_RECORD_TYPES` (newly exported from `src/ledger.js`), including the per-step window,
+  which no longer requires a `.phase` match for records (like `judge-round`) that never carry
+  one. (2) `scripts/promptcommitlib.mjs`'s run-reference regex accepted plain prose ("run
+  failed" satisfied its `{6,12}` margin outright) — tightened to the measured exact shape
+  (`{8}`); a proposed additional per-id digit requirement was investigated and REJECTED (23 of
+  130 re-sampled real archived ids carry no digit, `msdsmkid` among them). (3)
+  `src/codeversion.js` read `sha: null` inside any real git worktree (`.git` there is a FILE,
+  `gitdir: <path>`, not a directory) — now resolves the pointer file and the worktree's
+  `commondir` to find HEAD/refs correctly. (4) `replayRun`'s `resumed` flag missed a genuine
+  $0-floor resume (`priorSpentUsd: 0` is still a real fold per `src/run.js:328`'s own doctrine)
+  — now keys on the field's presence, not `> 0`. (5) `scripts/run-replay.mjs --all` opened
+  every run's gate-audit sidecar despite never using the fields it feeds — no longer opens it
+  in `--all` mode (`--all` output on `aurora-u-bareloop` confirmed byte-identical before/after).
+  (6) the steps/iterations windowing logic in `replayRun` was duplicated inline twice — extracted
+  into one shared `buildOccurrenceMetrics` helper (replay output on `u-msdsmkid`, `u-msf70nei`,
+  `u-mt8yk53k` confirmed byte-identical before/after). (7) `npm test`'s prompt-commit check
+  (`origin/main..HEAD`) inspects NOTHING after a direct push to main, because the push itself
+  advances `origin/main` to match `HEAD` — `scripts/prompt-commit-check.mjs` now falls back to
+  `HEAD~1..HEAD` on that exact condition and prints that it did; a multi-commit direct push
+  still only re-covers the last commit (needs `github.event.before`, a `.github/` edit — out of
+  scope here, ask-first).
+- **Release-gate findings (2026-08-27)**: `scripts/prompt-commit-check.mjs`'s `--range` value
+  was passed to `git rev-list` positionally with no way to disambiguate it from an option — an
+  option-shaped value (e.g. `--output=<path>`) was parsed by git as its own flag (verified: a
+  `--` separator does NOT fix `rev-list`, unlike `show`/`diff-tree`, since it treats everything
+  after it as a path filter, not a revision range); the script now rejects any `--range` value
+  starting with `-` up front, before any git call runs. Also corrected the fallback's printed
+  limitation and code comment: on a MERGE commit, `HEAD~1` is the first parent, so
+  `HEAD~1..HEAD` covers the merge PLUS every commit unique to the merged branch (measured on
+  this repo's own `4904d76`: 10 commits, not 1) — the prior wording ("only re-covers the last
+  commit") was only accurate for a LINEAR multi-commit push, which is now stated explicitly.
+  (`src/replay.js`'s phase-less step-window filter was also reviewed and confirmed correct by a
+  new adversarial synthetic test — no code change there.)
+
+## [0.14.0] — 2026-08-25
+
+### Added
+
+- **One transport-class retry** (F115, hamr's ruling): the ONE worker-Loop seam in
+  `src/planrun.js` now retries exactly once on a transport-only throw (TLS fault,
+  `ECONNRESET`/`EPIPE`/`ETIMEDOUT`, `fetch failed` over a network cause — never an HTTP
+  4xx/5xx/429 response), classified by the new `src/transport.js` (`isTransportFailure`,
+  fixed `TRANSPORT_MAX_ATTEMPTS`, never operator-configurable). Emits a report-only
+  `transport-retry` spine record and forces `job-end.spendComplete: false` for the rest of the
+  run — the retried attempt's first throw may already have been billed — surfaced by
+  `scripts/run-u.mjs` as a `retries` line only when a retry occurred.
+- **provider-red joins the resumable set** (F115, PRD v1.80 TODO #4): when the one transport
+  retry also fails and a `run-u` run ends `provider-red`, its tail now prints an honest
+  readout — spend so far as a floor, "died in step X of Y" (or "before a plan was accepted"),
+  and the exact `--resume` command — and `--resume` re-enters at the recorded step with the
+  accepted plan, folding prior spend in. No cost/step threshold gates the offer (the operator
+  decides, every time); verdict terminals (`escalated`/`step-red`/`plan-red`) still refuse.
+  Folded from a local `scripts/run-u.mjs` widening into the library's own canonical
+  `CHECKPOINT_OUTCOMES` (`src/reuse.js`) so the two lists cannot drift.
+- **Run behaviour summary** (build-list item 2, agreed 2026-08-23): `runBehaviour(events, {
+  runId? })` and `formatBehaviour(summary)` in `src/behaviour.js`, plus
+  `scripts/behaviour-readout.mjs <gate-audit.jsonl> [run_id]`. A report-only text block —
+  "94 tool calls · 61 read, 28 grep, 5 recall" / "17 exact repeats (~18%)" — computed entirely
+  from a run's own gate-audit JSONL. Gates nothing, changes no verdict, writes nothing to the
+  spine. The exact-repeat key is the full recorded action (`type` + `path` + every `args` key),
+  never collapsed to `{type, path}` — sharper collapse would have merged different byte ranges
+  of the same file into false repeats.
+- **`memory-cache` end-of-run readout** for the read shim: `runPlan` emits one spine record
+  (`{pointered, capped, bytesWithheld, approxTokens}`) summing what L1's pointer and L4's cap
+  withheld across the whole run, only when the shim is armed. `scripts/run-u.mjs` prints it as
+  `MEMORY-CACHE  N re-reads answered from memory · M reads capped · X KB withheld (~Tk tokens
+  not re-sent)`; `scripts/behaviour-readout.mjs` prints the same line given the run's spine as
+  an optional third positional. No cost fields — report-only, not a spend record.
+
+### Fixed
+
+- **`scripts/readshim-battery.mjs`'s spend reader compared a resumed leg's own money against
+  the wrong job-end figure** (F116): `readSpend`'s `ledgerUsd` now reads
+  `job-end.engagementSpentUsd` (this leg's spend) when a spine carries one, falling back to
+  `job-end.spentUsd` only for a cold run — `spentUsd` on a resumed job-end is a CHAIN total,
+  not this spine's own spend. `chainUsd`/`priorUsd` are exposed as new, honest fields and never
+  folded into `accountedUsd`/`ledgerUsd`/`spendUsd`.
+
 ## [0.13.0] — 2026-08-23
 
 ### Fixed (2026-08-23 — the release round: a pointer that lied, a close with no home, a rule that charged for its own refusal)

package/README.md

@@ -162,7 +162,7 @@ package, and gaps get fixed upstream rather than shimmed.
 bareloop is the productization of **[adaptlearn](https://github.com/hamr0/adaptlearn)**, a
 closed experimental record on whether agent-authored workflows improve under an honest gate.
 The design laws it inherited, and the open questions it has not answered yet, are in
-[`docs/01-product/PRD.md`](docs/01-product/PRD.md).
+[`docs/product/PRD.md`](docs/product/PRD.md).
 
 ## License
 

package/bareloop.context.md

@@ -26,7 +26,7 @@
 > where `hitl` IS admitted, `human-confirms` IS live, and the three `hitl-*` terminals exist —
 > integrate against what is written here, and expect the class-level rename when the next rung
 > lands. Records: PRD Addendum v1.71 and
-> `docs/02-features/2026-08-17-softgreen-review-door-design.md` (repo-only, not shipped);
+> `docs/product/2026-08-17-softgreen-review-door-design.md` (repo-only, not shipped);
 > evidence F102–F105.
 
 ## What this is
@@ -1093,13 +1093,25 @@ raises it.
 of PRICED rounds ONLY — never an estimate from token counts or averages (cap-not-estimate) —
 and it is stated even on the pre-token reds, where the honest figure is a real `0`.
 `spendComplete` says whether that figure is EXACT; `false` means `spentUsd` is a FLOOR ("at
-least $X", true total unknowable) and must not be read as a total. Four things set it, all
+least $X", true total unknowable) and must not be read as a total. Five things set it, all
 the same class — a call whose cost is unknowable from here: a round that came back unpriced
 (F6); a run that ABSORBED a stall, because the fuse's silent reissue may pay twice for one
 answer and the flag is one-way whatever the outcome; a `wall-halt` that cut a call
-mid-flight (`cutMidCall`); and a RESUME whose fold was itself a floor
+mid-flight (`cutMidCall`); a RESUME whose fold was itself a floor
 (`priorSpendComplete: false` — an unknown does not heal by being carried forward, so every
-round of this attempt being priced repairs nothing about the one before it). A wall stop read BETWEEN iterations or steps has no call in flight,
+round of this attempt being priced repairs nothing about the one before it); and a
+**transport retry** (F115, hamr's ruling: "one retry for transport layer failure and
+reporting with the rest end of gate"). Every worker Loop (scout, drafter, each step, the fix
+worker — the ONE seam in `planrun.js`) gets exactly ONE extra attempt, and only for a
+transport-class throw — fetch itself throwing with no HTTP response at all (a TLS fault,
+`ECONNRESET`/`EPIPE`/`ETIMEDOUT`, `fetch failed` wrapping a network cause); an HTTP response
+(4xx/5xx/429) is never retried here and rides bare-agent's own unchanged policy. The budget is
+fixed (`TRANSPORT_MAX_ATTEMPTS` in `src/transport.js`) — never a job-spec or CLI knob, tighten-only
+doctrine. Each retry emits a report-only `transport-retry` spine record (`{phase, attempt, error,
+recovered}`, no cost field — the ledger is unaffected); the FIRST attempt threw before any usage
+figure came back, so **any** transport retry floors `spendComplete` for the rest of the run even
+when the retry recovers and the run finishes green — the same one-way flag class as `stalled`
+and `cutMidCall`. A wall stop read BETWEEN iterations or steps has no call in flight,
 so it stays exact. Both fields are present on all outcomes, so a consumer never branches on
 field presence and never has to launder a missing `spentUsd` into `$0`.
 
@@ -2084,6 +2096,364 @@ $0). `VOUCHED_RATE_SOURCES` is the frozen allow-list they key on. **Reporting on
 no class, no halt. CLI lands at N5; the
 panel reads the same file at N6.
 
+### `runBehaviour(events, { runId? })` / `formatBehaviour(summary)` — `src/behaviour.js`
+
+Build-list item 2 (agreed 2026-08-23): one report-only text block summarizing what a run
+DID with its tools, computed entirely from the run's own gate-audit JSONL. **Gates nothing,
+changes no verdict, writes NOTHING to the spine** — a pure function over records that already
+exist, same posture as `spendProvenance` above. `runBehaviour` counts and returns the summary
+object; `formatBehaviour` renders it as the printed block:
+
+```
+94 tool calls · 61 read, 28 grep, 5 recall
+17 exact repeats (~18%)
+```
+
+`llm` action rows are provider rounds, not tool calls, and are always excluded; only
+`decision: 'allow'` rows count toward the total (a `deny` is tallied separately as `N denied`,
+shown only when nonzero). **The exact-repeat key is the FULL recorded action — `type` + `path`
++ every key of `args`** (sorted, stably serialized), never collapsed to `{type, path}`: if the
+gate ever starts recording byte ranges or offsets, two different slices of one file must not
+read as the same repeated call. Repeat detection is therefore exactly as sharp as what the gate
+records, no sharper — a tool that reads identical bytes through two differently-shaped argument
+objects will not be caught by this. `scripts/behaviour-readout.mjs <gate-audit.jsonl> [run_id]`
+prints the block for one run or every run_id found in the file, skipping malformed lines with
+a count rather than throwing.
+
+```js
+import { runBehaviour, formatBehaviour } from 'bareloop';
+const events = fs.readFileSync(auditFile, 'utf8').trim().split('\n').map(JSON.parse);
+console.log(formatBehaviour(runBehaviour(events, { runId })));
+```
+
+#### `memory-cache` — the read shim's own end-of-run readout (`src/readshim.js`, `src/planrun.js`)
+
+A single spine record, emitted once by `runPlan` right before it returns (so it lands on the
+spine before the caller's `job-end`), reporting what the READ SHIM (L1 pointer + L4 cap) saved
+this run: `{pointered, capped, bytesWithheld, approxTokens}`. `pointered` counts re-reads of
+unchanged content answered with a pointer instead of the bytes; `capped` counts reads served as
+a bounded slice; `bytesWithheld` sums exactly the bytes NOT re-sent in both cases (never
+estimated) — the diff lever (L2) isn't counted, it's a different response shape. `approxTokens`
+is `Math.round(bytesWithheld / 4)`, a bytes→tokens ESTIMATE named accordingly so nothing reads
+it as measured. **Emitted only when the shim is armed** (any `readShim` arm but the off one) —
+an unarmed run emits no record at all, never a fabricated zero. It carries no cost fields, so it
+is not a spend record and no spend-slicing instrument needs to account for it.
+`scripts/run-u.mjs` prints it as a `MEMORY-CACHE` line right after `BEHAVIOUR` when armed
+(`no record` if the run ended before the summary could fire); `scripts/behaviour-readout.mjs`
+prints the same line when handed the run's spine file as its optional third positional.
+
+
+### `replayRun(spineEvents, auditEvents?, { runId? })` / `formatReplay(summary)` — `src/replay.js`
+
+PRD build-list item 6: today no failed run can be reconstructed in under five minutes — every
+byte is on disk (the spine JSONL + its gate-audit sidecar) but only hand-slicing JSONL reads it.
+`replayRun` is a report-only reader over BOTH files: **reads only, mints no verdict, writes
+NOTHING to the spine**, same posture as `runBehaviour` above, which it reuses rather than
+reimplements for the tool-call breakdown. It returns one plain object:
+
+```
+{ runId, job, goal, budgetUsd, specHash, branch, verdictType, model, code,
+  outcome, stopReason, spentUsd, spendComplete, wallMs, chainClock,
+  resumed, resumeSeed, thisFileSpend, spendMismatch,
+  timelineKind: 'steps'|'iterations', replans, close,
+  steps: [{ id, occurrence, outcome, rounds, toolCalls, checks: {passed, failed},
+    treeChanged, wallMs, spentUsd, unpricedRounds, tripped }],
+  iterations: [{ iteration, verdict, boundary, closeStage, rounds, toolCalls,
+    wallMs, spentUsd, unpricedRounds, tripped }],
+  ending: { record, before /* the 3 records before it */, escalation },
+  lastEscalation, behaviour, memoryCache, skipped }
+```
+
+**`verdictType`/`model`** (F117, PRD TODO #20 — hamr blessed the whole item verbatim, landed
+2026-08-25): `verdictType` reads `job-start.verdictType` (`src/run.js:303`) — a REQUIRED spec
+field (`src/job.js:552` reds `missing-required` before job-start ever fires), so `null` here
+means only "this spine predates the field" (measured: `u-msdsmkid`, an Aug-3 archived run),
+never "unset". `model` reads `job-start.model`, present only when the shell-owned provider
+binding itself carried a `.model` string at job-start time — `src/planrun.js:76`'s own comment
+documents bare-agent's Loop reading `baseProvider.model` directly off that same object, so it is
+a real, citable, synchronously-available property, not a guess; a native/clipipe call path (or
+any provider double with no such field — measured on `tests/helpers.js`'s `scriptedProvider`)
+legitimately has neither, and this reader reports that honestly rather than defaulting one in.
+`formatReplay` prints both right after `shape:` — `class:   softgreen` / `class:   not recorded
+(pre-F117 spine)`, `model:   claude-sonnet-5` / `model:   not recorded`
+(the two "not recorded" wordings are deliberately different: a missing `verdictType` is always
+an archive-age gap, a missing `model` can happen on any spine, old or new). `--all` gains a
+`class` column right after `shape` and a `model` column right after `class` (the verdict class /
+the model string, or `-`) — `model` is kept FULL, never truncated, unlike the compact `reason`
+column: a wrong or uncertain model reading is exactly the thing a directory-wide scan needs in
+full, not cut.
+
+**`code`** (F118, the run→code direction — the commit→run direction is the prompt-commit
+check's `Failure:` run-reference rule; the two are companion halves of one loop, built the
+same day). `codeVersion()` (`src/codeversion.js`) is a pure, $0, no-shell reader: `version`
+is bareloop's own `package.json` version (resolved off `import.meta.url`, never a hardcoded
+path — works whether this module is imported from `src/` or from an installed
+`node_modules/bareloop`); `sha` is read straight off `.git/HEAD` (following a symbolic ref
+to its loose ref file, falling back to `packed-refs` when the branch has been packed) **only
+when `.git` is a real directory at the package root** — a dev checkout has one, an
+npm-installed copy does not, and that absence reads as `sha: null`, honestly, never a guess.
+`dirty` is always `null`: whether the tree has uncommitted changes cannot be known without a
+shell, and this module NEVER shells out — `run` is the one locked verb (hamr's law targets
+what the agent can DO, not how it's written), and a report-only field is not a license for
+the library to grow a shell seam. `null` is reported here rather than a defaulted `false`,
+because a faked "clean" reading is a worse lie than an honest "don't know."
+
+`job-start` (`src/run.js:303`) carries `code: {version, sha}` alongside F117's
+`verdictType`/`model` (`dirty` is intentionally omitted from the spine — it is always
+`null`, and a spine field that can only ever hold one value is not worth a byte).
+`replayRun` reads it as `{version, sha}` or `null` (absent field, an archive older than this
+landing); `formatReplay` prints a `code:` line right after `model:` — `code:    bareloop
+0.14.0 @ 43f2812` on a spine with a real sha, `code:    bareloop 0.14.0 @ sha unknown` when
+`sha` is null (an npm-installed run), `code:    not recorded (pre-F118 spine)` when the
+whole field is absent. `--all` gains no new column for this — the row is already at hamr's
+named limit.
+
+**Unknown money/time is always `null`/`unknown` — never `0`, and a partial sum is never stamped
+exact** (F6's rule, carried through every level this module reports at): `spentUsd`/`wallMs` are
+`null` when the run's own `job-end` is absent or carries no figure; `spendComplete` reads `false`
+whenever `spentUsd` is `null`, regardless of what the record's own flag says. The SAME rule
+governs one occurrence/iteration's own `spentUsd`: it sums `worker-round.costUsd`
+(`src/planrun.js:2288-2297`) over records strictly inside that occurrence's own `seq` window —
+a single `null` `costUsd` anywhere in the window makes the WHOLE occurrence's `spentUsd` `null`
+(`unpricedRounds` names how many), never a partial sum. Zero rounds in the window is a real `$0`,
+not an unknown one.
+
+`stopReason` is `null` on a green/already-green outcome; otherwise `category — decision —
+detail` from the last `escalation` record, every part present that record actually carries
+(`category` dropped when it duplicates the outcome already shown beside it; `detail` trimmed at
+400 chars with an explicit `…[+N chars]` marker, never silent) — `decision` alone is the generic
+one-line prose every category shares ("the provider path failed mid-run…" fires for every
+transport casualty); **`detail` is what actually killed THIS run** (a TLS "bad record mac", a
+specific mypy error) and is the reason a stop is explained, never the decision prose alone.
+Falls back to the bare outcome string for a pre-escalation red (`plan-red`/`job-red`/
+`smoke-red`). `ending.escalation` carries that same last escalation record whenever it falls
+outside the fixed 3-before window (common on a run that keeps emitting bookkeeping records after
+its real failure) — never silently dropped. `lastEscalation` is the same raw record exposed
+unconditionally (not gated on the window check) — `summarizeForAllLine`'s `reason` column reads
+it directly rather than re-deriving from `ending`.
+
+**A step id can recur** (a replan re-executes the same step): each `step-start`..`step-end` pair
+is its own **occurrence** (`occurrence: 1, 2, …`), and every field on it — `rounds`, `toolCalls`,
+`checks`, `treeChanged`, `wallMs`, `spentUsd` — is scoped to records strictly between THAT pair's
+own `seq` (the spine's monotonic per-record counter, never `ts` — every record in one spine
+shares the same seq counter, so it is an exact ordering where two same-millisecond `ts` stamps
+are not), never pooled across every occurrence sharing the id. `rounds` counts real
+`worker-round` records (`phase === 'step:<id>'`), never the declared cap; `toolCalls` is the one
+thing still windowed by `ts` (the gate-audit carries no `step` or shared `seq`). `tripped` is the
+last `escalation` whose `seq` falls inside the occurrence's window — `{category, detail}`, with
+`detail` falling back to `decision` when the escalation site carries no `detail` at all (a
+ladder-exhaustion `cap-halt`, `src/ralph.js`, is the measured example — without the fallback the
+tripped line would print a bare category and hide the real reason).
+
+**A run whose spine carries no `step-start` at all** — the plan's only step was
+already-green-skipped on a resumed leg, or a genuinely loop-only shape (measured: `u-msf70nei`,
+a resumed leg whose one step was already proven and only the CLOSE-FIX loop ran) — has
+`timelineKind: 'iterations'` and `iterations[]` populated from `iteration-start`
+(`src/ralph.js:583`) instead: each row runs from one `iteration-start` to the next
+`close-verdict`/`run-end`/`escalation` (`src/ralph.js:674,577/657/676/698`), whichever comes
+first by `seq`. `steps`/`iterations` are never both populated — exactly one is non-empty. Each
+iteration's own `closeStage` (`{verdict, stages}`) is set when a `close-verdict` ended it, distinct
+from the run's FINAL `close` (below).
+
+**`close`** is the run's real, final close — resolved by picking the LAST (by `seq`) record
+among every `close-verdict` that carries an ARRAY `stages` field and every `outer-close`
+(`src/planrun.js:3296`). A `close-verdict` with NO `stages` came from a PLAN STEP's own
+micro-loop, judged by the exit evaluator instead of a command (`src/planrun.js:2907`) — never
+"the close". Picking by `seq` rather than preferring `outer-close`'s TYPE matters: `outer-close`
+is the PRECHECK against the real close, fired once before the fix loop even starts, so when it
+reads red the fix loop's own staged close-verdicts run strictly AFTER it — measured on
+`u-msf70nei`, whose `outer-close` (seq 14) reads `needs_revision` but whose fix loop's own final
+close-verdict (seq 97, LATER) reads `satisfied`, which is what the run actually ended on
+(`job-end.outcome:'green'`). A run that never reached ANY close (e.g. `u-msdsmkid`, stopped by a
+step-variance meter before `judgeClose()` ever fired) resolves `close: null`, printed as `none —
+the run ended before any close ran` — never omitted.
+
+`replans` prefers `plan-executed.replans` (`src/planrun.js:2688`) and falls back to counting
+`materials` records stamped `phase:'replan'` (`src/planrun.js:2520`) when that field is absent —
+an older archived spine can predate the field (measured on `u-msdsmkid`, an Aug-3 run). `branch`
+reads the last `work-branch.branch` (`src/planrun.js:1589`) or `null` when absent — also measured
+missing on the same era of archive, before the work-branch rung landed.
+
+`wallMs` is THIS FILE's own `job-start`→`job-end` span, labeled `(this file)` — on a RESUMED leg
+that is only the latest engagement, not the whole signed chain. `chainClock` is the other true
+number: the SIGNED wall read off the run's own clock record — `wall-halt` when present (the
+TERMINAL reading, taken at the moment the wall stopped the run; `src/planrun.js:1269`'s
+`emitWallHalt`), else the single `wall-clock` record every run emits near its start
+(`src/planrun.js:1203`) — both spread from `clock.report()` (`src/clock.js:235-247`: `bounded,
+requestedMs, closeStages, enforcedMs, elapsedMs, remainingMs`). `elapsedMs` on either is
+chain-scoped by construction (`createClock`'s `priorElapsedMs` fold, `src/clock.js:174`), so it
+can legitimately exceed this file's own `wallMs` on a resumed run. `wall-halt`'s reading is
+end-of-run-honest, so `formatReplay` states it plainly: `clock: 60m04s of 60m00s signed (chain,
+from wall-halt)`. `wall-clock`'s reading is taken at the TOP of the engagement (chain time
+already inherited, not this run's own duration) — printing that under the same template read as
+"this run took 0 seconds" on a cold run, so it gets its own honest wording instead: `clock: 30m00s
+signed · 0.0s inherited from prior legs at start (from wall-clock; no end-of-run reading in this
+file)`.
+
+**Money carries the identical split** (hamr, 2026-08-25): a RESUMED run's `job-end.spentUsd` is
+the CHAIN total (prior legs folded in — `src/run.js:227`'s `chainFoldUsd`, seeded from
+`job-start.priorSpentUsd`), which can never equal this ONE file's own rounds — measured on
+`u-msf70nei`: header `spentUsd` reads `$5.3389` while its own 55 `worker-round`s sum to exactly
+`$1.2127`. `resumed` reads `job-start.priorSpentUsd > 0` — the SAME condition `src/run.js` itself
+folds on — deliberately NOT `resume-seed`'s presence: `resume-seed` (`src/planrun.js:2622`) is a
+NARROWER record, fired only when a plan is actually reloaded mid-flight, and its absence does not
+mean "not resumed" — measured directly on 4 real archived runs (`litectx-maintainer-bareloop`'s
+`msx7xoe0`/`msx87qqs`/`msxf9129`/`msxf2mwi`) that carry a real `priorSpentUsd` fold with NO
+resume-seed record at all. `resumeSeed` (when present) supplies the DETAIL —
+`{phase, completed, skipping, divergence}` — printed as `resumed: yes — phase close, 1 of 1
+completed step(s) skipped`; a resumed leg with no resume-seed record still reads `resumed: yes
+(no resume-seed detail recorded)`, honestly, rather than falling back to `no`. `thisFileSpend`
+prefers `job-end.engagementSpentUsd` (F103, `src/run.js:284` — this engagement's own fold-out
+spend) when the record carries it, falling back to summing this file's own `worker-round.costUsd`
+when it does not (measured absent on `u-msf70nei` itself); an unpriced round anywhere in THIS
+FILE makes the figure `null` regardless of source (F6, never a partial sum stamped exact) — both
+figures print on the `spent:` line, each labeled with its source, never one silently standing in
+for the other. `spendMismatch` is the same-class check for a NON-resumed run: there is no fold to
+explain a gap, so `job-end.spentUsd` disagreeing with this file's own summed rounds by more than
+$0.0001 is a genuine finding, printed as `MISMATCH vs job-end`, never hidden — measured across
+every non-resumed run in the available archive (aurora-u, bareagent-u, litectx-maintainer): zero
+trip it. `--all`'s spend column stays the chain total (what a directory scan asks first) but
+marks a resumed row with a trailing `*` on its id, with one footnote line
+(`* resumed run — spend is the chain total, see detail`) printed once, only when the listing
+holds at least one such row.
+
+`formatReplay` renders the full page: a header block (`goal:`/`shape:`/`signed:`/`branch:`/
+`resumed:`/`outcome:`/`spent:`, every absent field printing the literal `none recorded` — never
+blank, never a fabricated `0`), a `TIMELINE (steps)` or `TIMELINE (iterations — loop-shape run)` section with
+its own column-header row (`#  step  result  rounds  tools  checks  tree  wall  spend`, or the
+iteration equivalent without `checks`/`tree`) and a `↳ tripped:`/`↳ close:` line under any row an
+escalation or close fell inside, a `CLOSE` section (never omitted — `none — the run ended before
+any close ran` when nothing ever closed; the failing stage, if any, prints FIRST with `✗`, the
+rest `name OK`), `ENDING` (last record + 3 before it, plus an out-of-window escalation), the
+`BEHAVIOUR` block, and a `MEMORY-CACHE` line **always printed** — the existing wording when the
+run carried a record, `not armed on this run` otherwise. An absent record is never silent.
+`RESULT` words are `GREEN`/`RED`/`UNKNOWN` — `satisfied`/`green`/`already-green` read GREEN,
+every other non-null value reads RED.
+
+`summarizeForAllLine(summary)` builds one `--all` row's raw fields (`id, job, shape, outcome,
+spend, wall, steps, reason`) — `shape` is `plan`/`loop` (from `timelineKind`, never the
+always-literal-`'plan'` `job-start.shape` field); `steps` is a bare count for a plan-shape run,
+`"N it"` for a loop-shape one; `reason` is `category — <first clause of detail, cut at 60 chars,
+plain "…", no [+N] marker>` off `lastEscalation` — **`detail` only, never `decision`** for this
+column specifically (unlike the full report's `↳ tripped:` line, which does fall back to
+`decision` — this compact row has no room for both and the coordinator's own ruling keeps
+`decision`'s generic per-category prose out of it); `-` on a green row; the distinct, literal
+`no job-end (killed mid-run)` when the spine never reached a `job-end` at all (`outcome` itself
+is `null`) — not folded into the ordinary escalation case. `formatAllLines(entries)` renders every
+row as a FIXED-COLUMN, ALIGNED table with a header row (never CSV — columns are padded, not
+delimited; the header's own label lengths count toward the column widths) plus any
+`<name>  not-a-spine` lines at their original position (unpadded — a filename carries no
+outcome/spend/wall of its own). No header prints when there are zero real spines in the listing.
+
+`scripts/run-replay.mjs <spine.jsonl>` resolves the sibling `-gate-audit.jsonl` automatically and
+prints the full report; `--all <dir>` is **name-agnostic** — the patient corpus does not agree on
+one filename convention (`u-<id>.jsonl`, `battery-A1-<id>.jsonl`, `l2accept-L1-<id>.jsonl`,
+`reuse-<id>.jsonl`, `types-screen-C-<id>.jsonl`, …), so a spine is identified by CONTENT: any
+`.jsonl` that is not a sidecar by name (`*-gate-audit.jsonl`, `*.lag.jsonl`) and whose records
+include a `job-start` (present on every real spine checked, nested wrappers included) or
+`run-start` (present on most, absent on a run that died before ralph's first iteration). A
+`.jsonl` matching neither is printed as `<name>  not-a-spine` — never silently dropped or
+misread as an empty run. Both modes mirror `scripts/behaviour-readout.mjs`'s own malformed-line
+handling (skip-and-count, never throw).
+
+**F117's PRD TODO #20 is now landed in full**: both the verdict CLASS and the worker MODEL
+name are surfaced (see `verdictType`/`model` above) — hamr blessed the item verbatim
+("1") on 2026-08-25, so the spine-WRITER change to `job-start` (`src/run.js`) that a
+report-only reader would not otherwise make on its own authority went in with his explicit
+word. `judgedCount` on a close-verdict was never a reliable stand-in for the class either way
+(it appears on plain green closes too, not only softgreen ones) — this reads the real
+declared field instead.
+
+**Transport retries and floor reasons (F119, live-proven 2026-08-25)**: every
+`transport-retry` record (`src/planrun.js:126`) whose `seq` falls inside a step's or
+iteration's own window prints a `↳ transport retry ×N (recovered|not recovered|partially
+recovered) — <first 80 chars of the error>` line under that row — the same open-interval
+`seq` windowing `windowSpend` already uses for rounds. A retry whose `seq` falls outside
+every occurrence window (e.g. during the scout/plan phase) is counted instead under the
+`TIMELINE` header as `transport retries outside steps: N`, printed only when that count is
+non-zero. The header's `spent:` line, whenever `spendComplete` is `false`, appends
+`· floor because: <reason(s)>` — derived from the spine, never guessed: `transport retry
+×N` (any `transport-retry` record), `unpriced round(s)` (a `worker-round`/`judge-round`
+with non-finite `costUsd`), `cut mid-call` (a `wall-halt` record with `cutMidCall:true`),
+`stall` (a `stall` record), `prior leg floor` (`job-start.priorSpendComplete === false`) —
+every cause that actually shows evidence prints, never just one; a floor with no derivable
+evidence on this spine (an older archive, or a resumed leg's floor inherited from a file not
+in hand) prints `· floor (reason not in spine)` instead. `--all` adds no new column: a run
+that carried any transport retry gets ` ⟲N` appended directly after its outcome word (same
+posture as the resumed `*` on `id`), with one footnote
+(`⟲N transport retry(ies), recovered inline — see the full replay for detail`) printed once
+when the listing holds at least one such row. Live-proven on `u-mt8yk53k` (F119): two
+recovered TLS `bad record mac` retries, both inside step `fix-mypy-strict`'s window —
+`floor because: transport retry ×2` and `green ⟲2` in `--all`, on a run that finished green.
+
+```js
+import { replayRun, formatReplay } from 'bareloop';
+const spine = fs.readFileSync(spineFile, 'utf8').trim().split('\n').map(JSON.parse);
+const audit = fs.readFileSync(auditFile, 'utf8').trim().split('\n').map(JSON.parse);
+console.log(formatReplay(replayRun(spine, audit, { runId: 'mszcthk1' })));
+```
+
+### `PROMPT_REGISTERS` / `isPromptFile(path)` — `src/promptregisters.js`, and the prompt-commit rule
+
+PRD build-list item 5 (TODO #8), Q9 answered (hamr, 2026-08-25): "a check". A commit that
+changes a **prompt register** — one of the model-facing system/strategy/instruction
+strings a worker or judge actually reads (`SCOUT_SYSTEM`, `AUTHOR_SYSTEM`,
+`PERSONA_TOOLS`, `READ_SHIM_STRATEGY`, and their neighbors — the full, verified list is
+`PROMPT_REGISTERS` in `src/promptregisters.js`) — must say, in its own message, three
+things: what failure caused the change, what it addresses, and what it corrects.
+Convention-only was rejected: doctrine already on record is "a frozen rule without a
+wired detector is prose." `isPromptFile(path)` is the pure predicate the check runs
+against; both are exported from `bareloop`'s root so the inventory has exactly one home.
+
+hamr's addition (2026-08-25, same day): the `Failure:` line must ALSO cite the **run**
+that caused the change — `run <id>` or `run u-<id>` (case-insensitive at the `run`
+keyword, multiple refs fine), matched by `\brun\s+(u-)?[a-z0-9]{8}\b` (tightened from an
+initial `{6,12}` margin after a PR #23 review found the margin loose enough to accept
+plain prose — "run failed" is 6 lowercase letters, satisfying `{6,12}` outright — to the
+measured exact shape: every real archived id is exactly 8 characters. A per-id digit
+requirement was proposed in that same review and rejected: 23 of 130 re-sampled real ids
+carry no digit at all, `msdsmkid` among them — a real archived run cited by name
+elsewhere in this repo — so requiring a digit would reject genuine citations). The commit
+points at the run; `replayRun`/`formatReplay` (above) close the loop the other way,
+turning that run id back into the whole story. A `Failure:` line with no run reference
+fails with a distinct message: `Failure: must cite the run that caused the change (e.g.
+"Failure: run mszcthk1 — ...")`. FORMAT ONLY — the check never verifies the cited run's
+spine file actually exists (a run's patient lives outside this repo entirely, so there is
+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
+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):
+
+```
+node scripts/prompt-commit-check.mjs --range origin/main..HEAD   # validates every commit
+                                                                    # in the range that
+                                                                    # touches a prompt file
+node scripts/prompt-commit-check.mjs --message-file .git/COMMIT_EDITMSG
+                                                                    # commit-msg hook mode:
+                                                                    # validates one message
+                                                                    # against staged files
+```
+
+A compliant message:
+
+```
+fix: tighten PERSONA_TOOLS
+
+Failure: run mszcthk1 — worker read the arbiter spine after being told it was denied
+Addresses: PERSONA_TOOLS did not name the spine file explicitly
+Corrects: spells the denied paths from ARBITER_BOOK_STORES
+```
+
+A commit that touches no prompt-register file is passed without inspecting its message.
+An unresolvable `--range` (no such ref — a fresh clone with no `origin`, a detached
+checkout that never fetched) is a **skip**, printed and exited 0: a missing baseline is
+not a rule violation, never a red.
+
+
 ## Architecture
 
 Three layers. An **outer shell** (dumb, permanent): per-run budget cap via bareguard,
@@ -2115,7 +2485,7 @@ is disclosed to the authoring agent; only admitted verbs are callable per job.
 ## Gotchas
 
 *TBD from real adopter friction; recorded here as they're found (repo-side friction goes
-to `docs/FINDINGS.md`).*
+to `docs/logs/FINDINGS.md`).*
 
 ## Constraints