bareloop 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.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/bareloop.context.md

@@ -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
@@ -1393,6 +1443,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,7 +2074,14 @@ 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.
 
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.12.0",
+  "version": "0.13.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",

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).

package/src/ledger.js

@@ -404,3 +404,105 @@ export function updateLedger({ ledgerFile, spineFiles }) {
   });
   return { appended, fold: foldLedger(rows.concat(appended)) };
 }
+
+// ── BA-21 pricing provenance: the READ side (REPORTING ONLY) ─────────────────
+// bare-agent >=0.37 rides `rateSource` beside `pricing` on every metering payload,
+// and the plan flow forwards it verbatim onto `worker-round`/`judge-round`/`worker-turn`
+// (`rateSourceFields`, src/planrun.js — the write side).
+//
+// NAMED rather than papered over: `judge-round`'s own payload (src/kinds.js's
+// `onJudgeCost({...})`) does not carry `rateSource` yet, so every judge round reads
+// UNKNOWN provenance today — correctly, by the same rule that governs the archive, and
+// the day that payload forwards the field the emit site already spreads it.
+//
+// `pricing` is UNCHANGED and still strictly two-valued ('priced'|'unpriced'). Nothing
+// below reads it, nothing below decides anything, and no new escalation category exists:
+// the `pricing-red` halt in src/run.js keys on cost alone and stays the ONLY pricing
+// signal with teeth. This is a READOUT — how much of a run's spend was priced by a rate
+// nobody vouched for — and coupling it to run control would be a new refusal, which is
+// arbiter territory.
+
+/**
+ * The two rate sources somebody VOUCHED for: `'provider'` (the provider reported its own
+ * authoritative cost, e.g. the claude CLI's `total_cost_usd`) and `'caller'` (we passed
+ * the rate in ourselves). Everything else bare-agent can report is a built-in guess.
+ *
+ * An ALLOW-LIST of vouched values, never a deny-list of guessed ones — this is the
+ * load-bearing line of the whole signal, for two reasons.
+ *
+ * First: BOTH of bareloop's production models resolve to `'tier'`, not to `'default'`
+ * (`claude-sonnet-5` and `claude-haiku-4-5-…` each match a recognized Claude tier by
+ * model-id substring, so bare-agent prices them off a hardcoded tier rate that could
+ * have drifted from Anthropic's). A "is this a guess?" test spelled
+ * `rateSource === 'default'` would therefore read EVERY normal bareloop round as
+ * confidently priced and see none of the population it exists to measure — this repo's
+ * blind-instrument class, seven recorded instances, and not becoming the eighth.
+ *
+ * Second: written this way, any value bare-agent adds later that we do not recognise
+ * reads as a GUESS rather than as vouched. The fail-safe direction, by construction.
+ */
+export const VOUCHED_RATE_SOURCES = Object.freeze(['provider', 'caller']);
+
+/**
+ * Read one spend record's rate PROVENANCE. Four-way, and the two absent-ish cases are
+ * deliberately distinct facts:
+ * - `'vouched'`  — a `VOUCHED_RATE_SOURCES` value: somebody stands behind the rate.
+ * - `'guessed'`  — a rate was used and nobody vouched for it (`'tier'`, `'default'`, or
+ *                  any future value we do not recognise).
+ * - `'unpriced'` — `rateSource: null`: nothing was priced, so there was no rate to have
+ *                  guessed. Upstream said so; we are not inferring it.
+ * - `'unknown'`  — the record carries no `rateSource` at all. Every round archived before
+ *                  this signal existed lands here and is NEVER backfilled: an absent label
+ *                  is reported as unknown, never reconstructed, and never rounded up to
+ *                  vouched (F6's unknown-is-never-zero, applied to provenance).
+ * @param {any} record a `worker-round` / `judge-round` / `worker-turn` spine record
+ * @returns {'vouched'|'guessed'|'unpriced'|'unknown'}
+ */
+export function rateProvenance(record) {
+  if (!record || typeof record !== 'object' || !('rateSource' in record)) return 'unknown';
+  const source = /** @type {any} */ (record).rateSource;
+  if (source === undefined) return 'unknown'; // a key carrying no value taught us nothing
+  if (source === null) return 'unpriced';
+  return VOUCHED_RATE_SOURCES.includes(source) ? 'vouched' : 'guessed';
+}
+
+/** The spend records a run's money is read from. `worker-round` and `judge-round` are the
+ * ACCOUNTED types — exactly `ACCOUNTED_ROUND_TYPES` in src/run.js, which is the ledger that
+ * enforces the budget (F12). `judge-round` is the softgreen rung's judged floor: the first
+ * spend a CLOSE has ever had, and a provenance readout that skipped it would be blind to the
+ * one seam whose rate nobody has audited. `worker-turn` is the native surface's per-turn
+ * attribution — unpriced by design, included so the readout covers every metering row the
+ * plan flow writes rather than only the ones carrying money. The attempt-level totals
+ * (`worker-result`, `worker-plan`) are ECHOES of these same rounds and are excluded, for
+ * the same reason the ledger in run.js excludes them: counting them double-counts.
+ *
+ * Re-spelled rather than imported (src/run.js imports this module's siblings and a cycle
+ * buys nothing here) — `tests/ledger.test.js` asserts the two spellings agree, because a
+ * spend-slicing instrument that misses a writer is the F45 class this list exists to avoid. */
+const SPEND_RECORD_TYPES = Object.freeze(['worker-round', 'judge-round', 'worker-turn']);
+
+/** @typedef {{rounds: number, usd: number, unpricedRounds: number}} ProvenanceBucket */
+
+/**
+ * How much of a run's spend was priced by a guess. Pure fold over one spine's events,
+ * REPORTING ONLY — it mints nothing, halts nothing and refuses nothing.
+ *
+ * `usd` sums only FINITE costs; a round whose cost is not a finite number is counted in
+ * `unpricedRounds` instead of being summed as $0 (F6 — unpriced is never free), so a
+ * bucket's `usd` is a FLOOR whenever its `unpricedRounds` is non-zero.
+ * @param {any[]} events one spine's parsed events
+ * @returns {{vouched: ProvenanceBucket, guessed: ProvenanceBucket, unpriced: ProvenanceBucket, unknown: ProvenanceBucket}}
+ */
+export function spendProvenance(events) {
+  /** @returns {ProvenanceBucket} */
+  const bucket = () => ({ rounds: 0, usd: 0, unpricedRounds: 0 });
+  const out = { vouched: bucket(), guessed: bucket(), unpriced: bucket(), unknown: bucket() };
+  for (const ev of events ?? []) {
+    if (!ev || !SPEND_RECORD_TYPES.includes(ev.type)) continue;
+    const b = out[rateProvenance(ev)];
+    b.rounds += 1;
+    if (typeof ev.costUsd === 'number' && Number.isFinite(ev.costUsd)) b.usd += ev.costUsd;
+    else b.unpricedRounds += 1;
+  }
+  return out;
+}

package/src/plan.js

@@ -27,6 +27,7 @@
 import { TOOL_MENU, LOCKED_TOOLS, WRITE_VERBS, checkMenu } from './job.js';
 import { declaredStages } from './declaredclose.js';
 import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals, hasNestedQuantifier } from './validate.js';
+import { READ_SHIM_CAP, readShimArm } from './readshim.js';
 
 /** the closed exit menu (PRD v1.12 §3 + decision 1's `check-passes`): the
  * shell evaluates every form with its own fixed code, never a command — the
@@ -49,6 +50,14 @@ export { WRITE_VERBS };
  * count. Shallow entries survive the cap (see `legalScopes`) because they are
  * the useful ones — a deep leaf is reachable via its parent. */
 export const MAX_SCOPE_MENU = 24;
+/** G1's pair (read shim only): the two verbs that can reach INTO a file the cap
+ * cut short — `recall` names where a symbol lives, `get` reads that symbol in
+ * full. Named here because the rule that needs them lives here; the cap that
+ * makes them mandatory lives in src/readshim.js.
+ * EXPORTED because `runPlan` refuses the same pair at $0 (see the G1 ceiling
+ * guard there): the rule and its pre-flight must read ONE spelling of which
+ * verbs count, never two that can drift apart. */
+export const RETRIEVAL_PAIR = Object.freeze(['recall', 'get']);
 
 /**
  * The MENU of legal `tree-changed` scopes — choose-don't-describe (design record
@@ -202,7 +211,7 @@ export function closeStagesOf(job) {
  * job spec. Never throws on JSON text or plain parsed data; every failure is
  * a named red. Returns the parsed plan on ok (single parse), null on any red.
  * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
- * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], seedRed?: string[], priorChecks?: string[] }} [opts] `job`: the
+ * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], seedRed?: string[], priorChecks?: string[], readShim?: boolean|'cap'|'diff' }} [opts] `job`: the
  *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
  *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
  *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
@@ -224,9 +233,23 @@ export function closeStagesOf(job) {
  *   only). Rule B — a redraft may not drop one (`check-shed`): exits without
  *   the check verify FORM alone, so a shed lets the run "green" unearned
  *   (u-msdsmkid mechanism b; the 3 archived sheds were all on step-red runs).
+ *   `readShim` (G1): the read shim's ARM for this run — `false` (default), `'cap'`,
+ *   `'diff'` or `true`. The arms that CAP (`'cap'`, `true`) add one rule: a step
+ *   granting `read` must also grant `recall` and `get` (`read-blind`), because a
+ *   capped read is only navigable with them. The arms that do not cap (`false`,
+ *   `'diff'`) render byte-identically to the pre-shim validator, so the frozen A0
+ *   baseline stays a baseline and A2 isolates the diff instead of importing an
+ *   admission rule with it. An unrecognised value THROWS (`readShimArm`) — a param
+ *   guard on the caller's own argument, never a plan red.
  * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
  */
-export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed, priorChecks } = {}) {
+export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed, priorChecks, readShim = false } = {}) {
+  // The one thing in here that throws, and it is not plan data: an unknown arm
+  // name is the CALLER's own argument, checked before a single plan field is
+  // read. The "never throws" contract above is about the agent's artifact —
+  // this is the operator's, and silently coercing it would run one arm under
+  // another's label (the BA-4 param-guard class; see `readShimArm`).
+  const shimArm = readShimArm(readShim);
   /** @type {Red[]} */
   const reds = [];
   /** @type {(code: string, path: string, detail?: string) => void} */
@@ -335,6 +358,24 @@ export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed,
         }
         writeStep = s.tools.some((/** @type {string} */ t) => WRITE_VERBS.includes(t));
         toolsParsed = true;
+        // G1 — the read shim's admission rule, and it only exists while the CAP
+        // does. The shim caps a read at READ_SHIM_CAP and hands back a steer;
+        // capping a worker whose grant holds no retrieval verb leaves it with no
+        // way to reach the rest of the file, which is BA-17 read-blinding on
+        // purpose. So the cap is what makes the pair mandatory — the two ship
+        // together or neither ships.
+        // Fires only inside the parsed branch (the mailbox precedent: a rule
+        // derived from an unknowable grant charges the ledger for a violation
+        // the agent never committed), and only per step, because the grant IS
+        // the step boundary. Keyed on the ARM's g1 flag, not on "is the shim on":
+        // the diff-only arm (A2) caps nothing, so there is nothing to be blind
+        // about, and firing here would narrow A2's admissible plan space on top
+        // of the lever it is meant to isolate.
+        if (shimArm.g1 && s.tools.includes('read') && !RETRIEVAL_PAIR.every((/** @type {string} */ v) => s.tools.includes(v))) {
+          const short = RETRIEVAL_PAIR.filter((v) => !ceiling.includes(v));
+          red('read-blind', `${at}.tools`, `a step granting "read" must also grant ${RETRIEVAL_PAIR.join(' and ')} — reads are capped at ${READ_SHIM_CAP} bytes and the rest of a big file is reachable only through the retrieval verbs; a capped worker without them is blind to it`
+            + (short.length ? ` (the signed ceiling [${ceiling.join(', ')}] offers no ${short.join('/')}: this plan cannot satisfy the rule — the spec needs re-signing with them, or the run needs the shim off)` : ''));
+        }
       }
 
       // rounds ≤ the shell cap (cap-not-estimate; the step bound IS maxTurns)