bareloop 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,145 @@ 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.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)
+
+- **The pointer no longer lies about a file emptied since it was read.** `src/readshim.js`'s
+  pointer branch tested `start >= total` alone, so `0 >= 0` held with **no ledger entry at all** —
+  the first read of an empty file and a re-read of a file TRUNCATED TO EMPTY since delivery were
+  indistinguishable, and both answered "you already hold all 0 bytes". A worker would have gone on
+  believing in content that was gone. The guard now requires a ledger entry whose hash still
+  matches. This is precisely the untruthful-pointer class the module exists to prevent, found
+  inside the module built to prevent it, and reproduced live before the fix.
+- **`judge-round` carries its rate provenance.** The judged floor made it the first spend a CLOSE
+  has ever had, and `src/ledger.js` documented the write side as forwarding `rateSource` onto it —
+  but the emit never spread the field, so every judge round would have read UNKNOWN forever. NOT
+  rounded up: `src/kinds.js`'s `onJudgeCost` payload still does not carry the field, so it reads
+  UNKNOWN today, and both the emit and the ledger header now say so plainly.
+- **A torn spine line stops reading as exact spend.** `scripts/run-battery-readshim.mjs` marked
+  unparseable lines `__corrupt` "never guessed at", then counted them, dropped them, and reported
+  the row's spend as EXACT while `corruptLines` reached no readout. `spendComplete` now goes false
+  when any line was unreadable (spend renders `>=`) and the audit prints the count per row.
+- **G1's ceiling half is refused at $0 instead of after the drafter is paid.** `validatePlan` reds
+  `read-blind` when a capped step grants `read` without the retrieval pair — but a step cannot
+  grant what the SIGNED CEILING does not offer, so against a spec whose `tools` lack `recall`/`get`
+  **every** draft red identically and the drafter was paid for each doomed cycle. `runPlan` now
+  throws at the same $0 door as the arm guard, in the same class: an operator param-guard
+  `TypeError`, never a model-output red — nothing the agent authored is wrong when the operator
+  asks for a shim the signature cannot satisfy. Tighten-only; the only configuration it rejects
+  already failed 100% of the time, just later and for money. `RETRIEVAL_PAIR` is now exported from
+  `src/plan.js` rather than respelled, so the rule and its pre-flight cannot drift apart.
+
+### Changed (2026-08-23)
+
+- **The aurora close moved to a tree development cannot mutate** (`jobs/aurora-u-spawner-types.json`,
+  F110). Its stages had pointed at a scratch worktree, which was removed during ordinary branch
+  work — every stage silently became `node: cannot find module`. The home before that was a shared
+  working checkout, where a close landing mid-edit dies as an instrument fault rather than a
+  verdict. Neither is a home: a checkout is *supposed* to go dirty and a scratch worktree is
+  *supposed* to be removable. **A close is the arbiter's instrument, so its host must have the
+  arbiter's lifetime.** Now a worktree pinned at a release tag, never edited, with its own
+  dependencies. Re-signing was required and given in-turn.
+
+### Added (2026-08-18 — the read shim, flag-gated OFF)
+
+- **`src/readshim.js` — a per-worker delivery ledger over the read tool**, off unless the new
+  `readShim` flag is set on `runJob`/`runPlan`. A read over 24KB (`READ_SHIM_CAP`) delivers its
+  next unseen slice plus a trusted steer at `ctx_recall`/`ctx_get`; a re-read of a file the
+  worker holds WHOLE and unchanged returns a short pointer instead of the bytes; a re-read of
+  a file it holds only PART of returns the next slice, never a pointer; any content change
+  re-delivers from the start. Measured on a $0 replay of 1,844 real `shell_read` actions from
+  143 archived gate audits: 48% of reads re-read unchanged bytes, and cap+pointer keyed on what
+  was DELIVERED saved 65.6% of read payload with **zero** untruthful responses — where the
+  naive path+hash key saved 8.2 points more by telling **250 lies**, median 73,348 bytes hidden
+  each (BA-17 read-blinding, reproduced).
+- **G1 at the validation gate (`read-blind`)**: under the shim, a plan step granting `read` must
+  also grant `recall` and `get`. Capping a worker with no retrieval verb is BA-17 on purpose —
+  the cap is what makes the pair mandatory. Stated in the drafting prompt as well as enforced
+  (the mailbox precedent).
+- **One flag, four ARMS, default OFF** (the `layerRoot` precedent, F41). `readShim` names which
+  levers run, one value per row of the frozen Phase 2 pre-registration: `false` = A0 (off),
+  `'cap'` = A1 (cap + pointer + next-unseen-slice + G1), `'diff'` = A2 (the diff lever alone — no
+  cap, no pointer, no G1), `true` = A3 (every lever). The two booleans mean exactly what they
+  meant before the arms existed, so nothing written against them changed meaning. With the shim
+  off every observable — validator reds, persona, delivered bytes — is byte-identical to the
+  pre-shim run: the frozen A0 arm has to be exactly today, and a guard firing under a disabled
+  shim would make the baseline a treatment arm. Each arm's persona line describes only the
+  machinery actually installed (A2 is never told about a 24KB limit that is not in force). An
+  unrecognised value THROWS at the entry (`readShimArm`) rather than coercing into a truthy
+  shim — a mis-spelled arm would run one treatment under another's label and be invisible in the
+  results afterwards. The default-flip is not in this change: it waits on a paid contrast.
+- **A stale `ctx_get` pointer serves the requested line range from disk** (2026-08-19), under a
+  CAPPING arm only. The cap's own strategy line steers a capped worker at `ctx_recall` →
+  `ctx_get` for a whole function; `ctx_get` is content-hash gated and throws `StalePointerError`
+  the moment the file changed after indexing — which is the normal case for a worker that just
+  EDITED the file it is working on. Measured on the A1 arm's three green runs: 10 `ctx_get`
+  calls, 5 stale, 0 bytes each, every one a just-written file. A paid round returning nothing,
+  down a path the cap itself chose. The serve hands back the requested 0-based inclusive line
+  range read fresh from disk, under TRUSTED framing that says the pointer was stale, that the
+  range may now hold DIFFERENT code than the symbol asked for, which lines arrived, and that
+  nothing was recorded as delivered. litectx refuses to slice a drifted range itself because an
+  UNLABELLED slice can silently be another symbol's body — the label is what makes it legal.
+  Detection is on the exported `StalePointerError` CLASS, never on message prose. A vanished
+  file or a range now entirely past the end is a refusal RESULT naming what happened, never a
+  throw. It **never touches the delivery ledger**: a slice is not the file, and a ledger that
+  recorded one would answer the next read with "you already have it" to a worker holding 90
+  lines of 900 — the untruthful-pointer failure the shim exists to prevent. The cost of that is
+  a later `shell_read` may re-deliver bytes the serve already showed; the shim over-delivers
+  rather than lies. A0 and A2 are untouched: with no capping arm the hook is not wired and
+  `ctx_get`'s contract is byte-identical.
+- On the native surface the shim REPLACES the `NATIVE_READ_CAP` wrapper rather than layering over
+  it (both bound the same seam at the same 24KB, and a shim outside the native wrapper would
+  ledger already-truncated text as a whole file — the exact lie it exists to prevent). L2
+  (diff-on-change) is deliberately not built: it never fired on the real corpus.
+
 ## [0.12.0] — 2026-08-23
 
 ### Added (N4 slice 2 — the softgreen rung: a close that JUDGES, and a signer who has the last word)

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
@@ -918,7 +918,7 @@ Reserved spine vocabulary (V7, machinery-free until job #1 surfaces one):
 `coordination-red` — a failure between units (scope contention, step order, store
 races), never to be folded into worker/interpreter reds.
 
-### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
+### `runJob(spec, { approvals, workdir, provider, nativeProvider?, providerFor?, emit, capRuns?, strikeLimit?, shellCapUsd?, closeTimeoutMs?, layerRoot?, readShim?, bridge?, priorSpentUsd?, priorSpendComplete?, priorWallMs?, resumeSeed?, resumeGrades?, resumeReplans?, resumeBranch?, humanRuling?, heldRuling?, reviewDoor?, doorRerun? })` → outcome — `src/run.js`
 
 The last seven are the RESUME fold and are documented under *Resuming a killed run* below; they
 default to `0` / `true` / `0` / `null` / `[]` / `null` / `null`, so a fresh run passes none of them.
@@ -937,6 +937,56 @@ plan-red | check-red | close-red | close-unsupported | recipe-stale | branch-red
 provider-red | interpreter-red | cap-halt | wall-halt | step-stalled | hitl-pause |
 hitl-decision-red | step-red:<id>`.
 
+**`readShim` (default `false`) — the capped read seam, per ARM.** The value names which levers
+run — the four arms of the frozen Phase 2 pre-registration:
+
+| value | arm | cap + next-unseen-slice | pointer | diff on a changed re-read | G1 (`read-blind`) | persona line |
+|---|---|---|---|---|---|---|
+| `false` *(default)* | A0 | — | — | — | — | none |
+| `'cap'` | A1 | ✓ | ✓ | — | ✓ | `READ_SHIM_STRATEGY` |
+| `'diff'` | A2 | — | — | ✓ | — | `READ_SHIM_DIFF_STRATEGY` |
+| `true` | A3 | ✓ | ✓ | ✓ | ✓ | `READ_SHIM_STRATEGY` |
+
+Anything else **throws** (`readShimArm`) at `runJob`/`runPlan`/`validatePlan` before a token is
+spent — a mis-spelled arm coerced by truthiness would run one treatment under another's label and
+be invisible in the results afterwards.
+
+A **capping arm against a signed ceiling that offers no `recall`/`get` also throws at that same
+$0 door**, and for the same reason: G1 below requires the retrieval pair on any step granting
+`read`, but a step cannot grant what `spec.tools` does not offer — so every draft would red
+`read-blind` identically while the drafter was paid for each doomed cycle. The message names the
+missing verbs and both exits (re-sign the spec with them, or run with the shim off). Like the arm
+throw, it is an **operator param-guard `TypeError`, never a model-output red**: nothing the agent
+authored is wrong when the operator asks for a shim the signature cannot satisfy. It narrows
+nothing that works — the only configuration it rejects already failed 100% of the time, later and
+for money. `RETRIEVAL_PAIR` is exported from `src/plan.js` so the rule and this pre-flight read one
+spelling of which verbs count.
+
+Under a CAPPING arm (A1/A3) the shim also answers a **stale `ctx_get` pointer**: the cap steers the
+worker at `ctx_recall`/`ctx_get`, and `ctx_get` refuses a file that changed after indexing — the
+normal case once the worker has edited it. Instead of nothing, the shim serves that pointer's
+0-based inclusive line range read fresh from disk, capped the same way, under a trusted notice
+saying the pointer was stale, that the range may now hold DIFFERENT code than the symbol asked
+for, and that nothing was recorded as delivered. A vanished file or a range past the end is a
+refusal result, never a throw. The serve never writes the delivery ledger, so it can never mint a
+"you already hold it" pointer for bytes the read seam did not hand over. A0 and A2 do not wire it
+and `ctx_get` behaves exactly as it always did.
+
+`false` is the shipped behaviour and is byte-identical to a run without the flag, guards included;
+`true` means exactly what it meant before the arms existed, so nothing written against the boolean
+changed meaning. Where the CAP runs, `shell_read` delivers at most `READ_SHIM_CAP` (24KB) per call
+with a trusted steer at `ctx_recall`/`ctx_get`; a re-read continues from where the last one
+stopped, and once the worker holds the whole unchanged file a re-read returns a pointer instead of
+the bytes (keyed on what was DELIVERED — a partly-seen file NEVER gets a pointer, which is the
+measured correctness point); and `validatePlan` reds `read-blind` on any step granting `read`
+without `recall` and `get`. Where only the DIFF runs, nothing is capped (a first read delivers
+whole, whatever the size), an unchanged re-read re-delivers rather than pointing, and G1 does not
+exist — G1 is the cap's compensation, and an arm that caps nothing has nothing to compensate for.
+The ledger is per worker, so it resets with every step. On the native (clipipe) surface a CAPPING
+arm replaces the CLI-display cap rather than stacking on it; a non-capping arm leaves that wrapper
+installed *inside* the shim, so native never loses its bound. Default-flip pending a paid contrast;
+see CHANGELOG for the replay numbers behind it.
+
 **The two hitl terminals (N4 slice 1, doors re-cut 2026-08-18)** are the class's whole surface
 at this layer, and each is a CLEAN exit (`spendComplete` stays true — only the two casualties floor). `hitl-pause` is a
 decision-ready CHECKPOINT: the close reached a stage no machine can render, so the run stops
@@ -1043,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`.
 
@@ -1393,6 +1455,53 @@ reserved round bound, with the LAST round reserved for a toolless summary: the b
 a scout mid-tool-use, and text is its only deliverable, so without that reservation it
 spends its whole allowance exploring and reports nothing (F59 — measured on 15 of 18 runs).
 
+**Every cost figure bareloop reports is an ESTIMATE, not a billed amount (BA-21).** No
+vanilla LLM API returns a price — providers report TOKENS — so `spentUsd`, every
+`worker-round` cost, every halt readout and every ledger dollar is a token count
+multiplied by a RATE, never a provider invoice. Expect it to read somewhat high, and do
+not reconcile it against a bill expecting a match. There is deliberately **no per-model
+price table** behind it, and the reason is worth knowing before you decide how far to
+trust the number: a hand-curated table is a treadmill that rots SILENTLY — a price moves
+or a new model ships, the row goes stale, and the figure under-reports with no detector to
+say so. bare-agent instead matches a recognized Claude TIER (haiku / sonnet) by model id,
+and falls back to a conservative ceiling rate for anything it does not recognize. Both
+deliberately OVER-report rather than under-report, which is the fail-safe direction for a
+cap: a run halts slightly early rather than overspending unnoticed. **The consequence
+bites at the budget, and it is not softened here:** `budgetUsd` and `shellCapUsd` are
+enforced against these estimates, so an inaccurate rate is a cap that binds earlier or
+later than you intended. The cap is exact about the number it holds; the number is a
+guess.
+
+**If you need accuracy, pass your own rates — the supported path, not a workaround.**
+bare-agent's `Loop` takes `rates: {in, out, cacheReadMult?, cacheWriteMult?}` — USD per 1K
+tokens, the two multipliers applying to the input rate for the cache-read and cache-write
+tiers (defaulting to Anthropic's 0.1× / 1.25×). A caller-supplied rate is recorded as
+VOUCHED rather than as a guess, and it silences bare-agent's own guesstimate warning.
+**Named, not papered over:** `runJob`/`runPlan` construct their own `Loop` and do not yet
+accept a `rates` passthrough, so today that option is reachable only by a caller driving
+bare-agent directly — a bareloop-run job is priced by the guesstimate, full stop. The
+passthrough is an open follow-up, and until it lands every paragraph above describes the
+only pricing a `runJob` adopter gets.
+
+**The provenance is on the record, per round (`rateSource`).** The field arrives with
+bare-agent **>= 0.37**; under the pinned `^0.36.0` no provider payload carries it yet, so
+every priced round this library writes today reads UNKNOWN provenance — correctly, and by
+the same rule that governs the archive. (The one exception is the native per-turn
+`worker-turn`, whose `null` is bareloop's OWN statement rather than a forwarded one: that
+surface prices the SESSION, so a turn had no rate to guess.) Once the pin moves, every `worker-round` /
+`worker-turn` the plan flow writes carries bare-agent's own label beside `pricing`:
+`'provider'` (the provider reported its own authoritative cost — the native CLI surface)
+and `'caller'` (you passed the rate) are VOUCHED; `'tier'` (a recognized Claude tier,
+where **both** of bareloop's own production models land) and `'default'` (the blind
+ceiling) are GUESSES; `null` means nothing was priced, so there was no rate to have
+guessed. An ABSENT field is UNKNOWN provenance — every round archived before this signal
+existed, and it is never backfilled, never reconstructed, and never rounded up to vouched.
+Read it with `rateProvenance(record)` and `spendProvenance(events)` (`src/ledger.js`),
+whose predicate is an ALLOW-LIST of the two vouched values: anything else, including a
+value a future bare-agent adds, reads as a GUESS. **Reporting only** — `pricing` stays
+strictly two-valued (`'priced'`|`'unpriced'`), the `pricing-red` halt still keys on cost
+alone, and nothing about provenance decides, halts or refuses anything.
+
 **What the worker is told (tool mode):** the absolute repository root (F10 — bare-agent's
 shell tools resolve relative paths against the PROCESS cwd, so a worker with no root is
 blind), the close's CURRENT output as the tree's state (F13 — never framed as "your previous
@@ -1977,9 +2086,62 @@ the same refusal emits, so counting the escalation too would double every refusa
 `suggestedAsk` on every row is a template seed for an upstream ask — filing stays human;
 status rows (`open → filed → fixed → consumed`) are human-appended, and the fold shows
 the latest per key. Pure pieces exported for custom folds: `classifyIncidents(events,
-{spine?})`, `foldLedger(rows)`, `ledgerDeltas(fold, occurrences)`. CLI lands at N5; the
+{spine?})`, `foldLedger(rows)`, `ledgerDeltas(fold, occurrences)`. Riding with them,
+and deliberately NOT a ledger class: `rateProvenance(record)` → `vouched|guessed|unpriced|unknown`
+and `spendProvenance(events)` → per-provenance `{rounds, usd, unpricedRounds}` buckets answer
+"how much of this run's spend was priced by a rate nobody vouched for" (BA-21 — see *Every cost
+figure bareloop reports is an ESTIMATE* above). A bucket's `usd` sums FINITE costs only and is a
+FLOOR whenever its `unpricedRounds` is non-zero (F6 — an unknown cost is counted, never summed as
+$0). `VOUCHED_RATE_SOURCES` is the frozen allow-list they key on. **Reporting only**: no incident,
+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.
+
 ## Architecture
 
 Three layers. An **outer shell** (dumb, permanent): per-run budget cap via bareguard,
@@ -2011,7 +2173,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.36.0",
+    "bare-agent": "^0.39.0",
     "bareguard": "^0.13.0",
     "litectx": "^0.32.0"
   },

package/src/behaviour.js

@@ -0,0 +1,150 @@
+// The run behaviour summary (PRD build-list §2, agreed 2026-08-23): ONE
+// report-only text block computed entirely from a run's gate-audit JSONL.
+// It gates NOTHING, mints no verdict, writes NOTHING to the spine — a pure
+// read of records that already exist. "We can see what a run cost, never
+// what it wasted" is the gap this closes; item 4's five-minute-replay test
+// gets this as its cheap first slice.
+//
+// Gate-audit rows this reads (observed shape, this repo's real archive):
+//   {ts, seq, run_id, phase, action: {type, path?, args?}, decision, ...}
+// `action.type` is one of `llm` (a provider round, NOT a tool call — always
+// excluded), `read`, `edit`, `ctx_remember`. `action.args.tool` names the
+// concrete tool for read-shaped actions (`shell_read`, `shell_grep`,
+// `ctx_recall`, `ctx_get`, `ctx_recent`, `ctx_impact`, `ctx_related`);
+// edit/ctx_remember rows carry no `args.tool`. `decision` is `allow` for a
+// gated tool call, `null` for an llm row, or `deny`.
+
+/**
+ * Stable JSON — keys sorted at every level — so two calls with the same
+ * arguments in a different insertion order (or a different property visit
+ * order out of JSON.parse) hash to the same string. Used only to build the
+ * exact-repeat key below; it is not a general-purpose canonicalizer.
+ * @param {any} v
+ * @returns {string}
+ */
+function stableStringify(v) {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(v).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+}
+
+/**
+ * The exact-repeat key for one tool-call action: `type` + `path` + a stable
+ * serialization of the WHOLE `args` object.
+ *
+ * Load-bearing, and deliberately not `{type, path}`: this repo's own history
+ * is a blind-instrument catalogue of collapsed keys reading two DIFFERENT
+ * things as the same thing (a ledger that summed input+output with no cache
+ * tiers, a gate audit that collapsed reads to `{type,path}`, `git status` as
+ * "did it write?"). If the gate ever starts recording byte ranges or offsets
+ * in `args`, two different slices of the same file must NOT count as a
+ * repeat — dropping `args` from the key would silently manufacture that
+ * exact confound here. This detector is exactly as sharp as what the gate
+ * records, no sharper: a tool that reads the same bytes through two
+ * differently-shaped argument objects will not be caught, and that is an
+ * honest limit, not a bug.
+ * @param {{type?: string, path?: string, args?: any}} action
+ * @returns {string}
+ */
+function repeatKey(action) {
+  return `${action?.type ?? ''} ${action?.path ?? ''} ${stableStringify(action?.args ?? null)}`;
+}
+
+/**
+ * The display label for one tool-call breakdown row. Kept SEPARATE from the
+ * counting key (`args.tool || action.type`, computed inline in
+ * {@link runBehaviour}): the summary object stores the raw tool name so a
+ * consumer can trace a count back to its source, and only {@link
+ * formatBehaviour} shortens it for the printed line — the agreed shape reads
+ * "read"/"grep"/"recall", not "shell_read"/"shell_grep"/"ctx_recall".
+ * @param {string} key
+ * @returns {string}
+ */
+function displayLabel(key) {
+  return key.replace(/^shell_/, '').replace(/^ctx_/, '');
+}
+
+/**
+ * Summarize what a run DID with its tools, from its gate-audit records
+ * alone. Pure and read-only: no IO, no spine writes, no verdict.
+ *
+ * Counting rules:
+ *   - `llm` rows are provider rounds, never tool calls — always excluded.
+ *   - a tool call counts toward `totalCalls`/`byTool`/`uniquePaths`/repeats
+ *     only when `decision === 'allow'`; a `deny` is tallied separately in
+ *     `denied` and touches nothing else (denied ≠ done).
+ *   - `byTool` is keyed by `action.args.tool` when present, else
+ *     `action.type` (an edit or ctx_remember has no `args.tool`).
+ *   - exact repeats: see {@link repeatKey}. A first occurrence of an action
+ *     is not itself a "repeat" — only the 2nd, 3rd, ... occurrences count,
+ *     so `repeats` can never exceed `totalCalls - byTool-group-count`.
+ * @param {Array<{run_id?: string, action?: {type?: string, path?: string, args?: any}, decision?: string|null}>} events
+ * @param {{runId?: string}} [opts]
+ * @returns {{totalCalls: number, byTool: Record<string, number>, denied: number,
+ *   uniquePaths: number, repeats: number, repeatPct: number|null}}
+ */
+export function runBehaviour(events, { runId } = {}) {
+  const list = Array.isArray(events) ? events : [];
+  const scoped = runId === undefined ? list : list.filter((e) => e?.run_id === runId);
+
+  const byTool = /** @type {Record<string, number>} */ ({});
+  const paths = new Set();
+  const keyCounts = new Map();
+  let totalCalls = 0;
+  let denied = 0;
+
+  for (const e of scoped) {
+    const action = e?.action ?? {};
+    if (action.type === 'llm') continue; // a provider round, never a tool call
+    if (e?.decision === 'deny') { denied += 1; continue; }
+    if (e?.decision !== 'allow') continue; // neither allow nor deny: not a counted call
+
+    totalCalls += 1;
+    const tool = action.args?.tool ?? action.type ?? 'unknown';
+    byTool[tool] = (byTool[tool] ?? 0) + 1;
+    if (action.path) paths.add(action.path);
+
+    const k = repeatKey(action);
+    keyCounts.set(k, (keyCounts.get(k) ?? 0) + 1);
+  }
+
+  let repeats = 0;
+  for (const count of keyCounts.values()) if (count > 1) repeats += count - 1;
+
+  return {
+    totalCalls,
+    byTool,
+    denied,
+    uniquePaths: paths.size,
+    repeats,
+    repeatPct: totalCalls > 0 ? Math.round((repeats / totalCalls) * 100) : null,
+  };
+}
+
+/**
+ * Render a {@link runBehaviour} summary as the agreed printable block
+ * (2–4 short lines). A zero-call run formats plainly ("0 tool calls") rather
+ * than a NaN-laced percentage — an empty run is a complete, reportable
+ * answer, not a division error.
+ * @param {ReturnType<typeof runBehaviour>} summary
+ * @returns {string}
+ */
+export function formatBehaviour(summary) {
+  const { totalCalls, byTool, denied, repeats, repeatPct } = summary; // uniquePaths: data-only, not in the agreed printed shape
+  const lines = [];
+
+  if (totalCalls === 0) {
+    lines.push('0 tool calls');
+  } else {
+    const breakdown = Object.entries(byTool)
+      .sort((a, b) => b[1] - a[1])
+      .map(([tool, n]) => `${n} ${displayLabel(tool)}`)
+      .join(', ');
+    lines.push(`${totalCalls} tool call${totalCalls === 1 ? '' : 's'} · ${breakdown}`);
+    lines.push(`${repeats} exact repeat${repeats === 1 ? '' : 's'} (~${repeatPct}%)`);
+  }
+  if (denied > 0) lines.push(`${denied} denied`);
+
+  return lines.join('\n');
+}

package/src/bridges.js

@@ -1,5 +1,5 @@
 // Layer 3 — the REUSE registry (design record:
-// docs/02-features/2026-08-01-layer-3-reuse-design.md, D1/D2/D6, frozen 2026-08-01).
+// docs/product/2026-08-01-layer-3-reuse-design.md, D1/D2/D6, frozen 2026-08-01).
 //
 // A BRIDGE is the plan a green actually executed, kept so the next run of the same
 // SHAPE starts from it instead of cold. This module is the box and the label on it:

package/src/calibrate.js

@@ -1,5 +1,5 @@
 // THE CALIBRATION GATE — softgreen module 5 (design record
-// docs/02-features/2026-08-17-softgreen-review-door-design.md §4.4, the
+// docs/product/2026-08-17-softgreen-review-door-design.md §4.4, the
 // 2026-08-18 threshold addendum rulings 1–3, and the second same-day addendum's
 // rulings 1 and 3).
 //

package/src/cardauthor.js

@@ -1,5 +1,5 @@
 // THE TWO SIGNED ARTIFACTS — softgreen module 4 (design record
-// docs/02-features/2026-08-17-softgreen-review-door-design.md §4.3 and §4.4,
+// docs/product/2026-08-17-softgreen-review-door-design.md §4.3 and §4.4,
 // plus the 2026-08-18 threshold addendum).
 //
 // Module 1 built the judged floor's core, module 2 wired the stage into a close,

package/src/index.js

@@ -82,7 +82,12 @@ export { renderListing, selectionPrompt } from './selection.js';
 // credit it has no way to release. STORAGE ONLY — nothing here selects, promotes or reuses
 // a bridge; those stay parked on `layer-3-reuse`.
 export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate, CHECKPOINT_OUTCOMES, PAUSE_TTL_MS, checkpointAgeGate, applyDoorDecision, writeRunGreenRow } from './reuse.js';
-export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from './ledger.js';
+// BA-21 pricing provenance rides out with the ledger because it is the same job: reading
+// a run's own spend record honestly. `rateProvenance`/`spendProvenance` answer "how much of
+// this was priced by a rate nobody vouched for" — REPORTING ONLY, no halt, no refusal.
+// Exported because an adopter enforcing a budget against these numbers is entitled to know
+// which of them are guesses (see bareloop.context.md, "Every cost figure … is an ESTIMATE").
+export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES, VOUCHED_RATE_SOURCES, rateProvenance, spendProvenance } from './ledger.js';
 // THE WORK BRANCH (PRD v1.57 §3). `workBranchName` is exported so an operator runner can
 // SHOW, before the approval gate, which branch the run will work on — the same reason the
 // resolved per-try hash is printed there: a bound the human is agreeing to should not be
@@ -91,6 +96,16 @@ export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASS
 // still there before spending anything. The runner applies the rule itself either way —
 // neither export is a way to opt out of it.
 export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from './workbranch.js';
+// THE READ SHIM (arm-gated, OFF by default via `runJob`'s `readShim`). The cap is exported
+// because bareloop.context.md names it, and documented-but-unexported is a false contract;
+// the wrapper goes with it so a caller building its own worker seam wraps the SAME ledger
+// rather than reimplementing the one rule that matters (a pointer keys on what was
+// DELIVERED, never on path+hash).
+//
+// `readShimArm` is exported for the same reason the cap is: a battery driver has to be able
+// to name and check the arm it is about to run BEFORE it launches, and the legal set living
+// only inside a runner would leave the driver guessing at spellings the guard will reject.
+export { createReadShim, wrapReadTool, readShimArm, readShimStrategy, READ_SHIM_CAP, READ_SHIM_STRATEGY, READ_SHIM_DIFF_STRATEGY, READ_SHIM_ARMS } from './readshim.js';
 // ── CLOSE AUTHORING v1 (gate 4) — the user declares what done means ──────────
 // The public surface is settled ONCE, here, at M4 (M2's header flagged the
 // naming collision and deferred it rather than exporting piecemeal).
@@ -213,6 +228,11 @@ export {
   HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS,
 } from './declaredclose.js';
 export { closeStagesOf } from './plan.js';
+// Build-list item 2 (2026-08-23) — the run behaviour summary: a report-only
+// read of a run's gate-audit records. Gates nothing, mints no verdict,
+// writes nothing to the spine; `runBehaviour` computes, `formatBehaviour`
+// renders the printable block.
+export { runBehaviour, formatBehaviour } from './behaviour.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.
 // `prepareSigning` returns the resolved spec's HASH and the seed evidence; it
 // never signs — the approvals array and the human's word are unchanged.

package/src/job.js

@@ -1,5 +1,5 @@
 // Job-spec validator — the OPERATOR-owned half of the config story (N1,
-// design record: docs/02-features/2026-07-12-n1-job-close-schema-design.md).
+// design record: docs/product/2026-07-12-n1-job-close-schema-design.md).
 // A job spec is the arbiter's rulebook: the close chain, the budget, the
 // outer write fence, the escalation route. It is pure declarative data —
 // no freeform code is expressible anywhere in it — and it validates

package/src/judged.js

@@ -1,5 +1,5 @@
 // THE JUDGED FLOOR'S CORE — softgreen module 1 (design record
-// docs/02-features/2026-08-17-softgreen-review-door-design.md §4, plus the
+// docs/product/2026-08-17-softgreen-review-door-design.md §4, plus the
 // 2026-08-18 threshold addendum). POC: poc/softgreen-judge/poc.mjs — validated
 // logic, rewritten here, never copied (graduation is a rewrite).
 //