bareloop 0.12.0 → 0.14.0

package/src/run.js

@@ -3,7 +3,7 @@
 // smoke, the ONE budget ledger (cap-not-estimate; unpriced is never free, F6),
 // and the decision-ready stops. It composes the plan flow below it and
 // interprets nothing itself.
-// Design record: docs/02-features/2026-07-12-n2-headless-loop-design.md.
+// Design record: docs/product/2026-07-12-n2-headless-loop-design.md.
 //
 // The legacy operator-authored `steps[]` path was DELETED 2026-07-26 (PRD
 // v1.32): the drafting call, config-v1, the per-step interpret loops and the
@@ -16,6 +16,7 @@ import { LiteCtx } from 'litectx';
 import { validateJob, jobSpecHash, checkApproval } from './job.js';
 import { runPlan } from './planrun.js';
 import { SMOKE_STORE, resolveHumanRuling } from './kinds.js';
+import { readShimArm } from './readshim.js';
 
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 
@@ -156,6 +157,19 @@ async function primitiveSmoke(workdir) {
  *   collision walk would mint a `-2` beside the work the resume exists to continue. The
  *   fold's precedent exactly: the chain's state is DECLARED, never re-derived. Forwarded
  *   verbatim to the plan flow; absent is the cold path.
+ * @param {boolean|'cap'|'diff'} [opts.readShim=false] THE READ SHIM (src/readshim.js) —
+ *        WHICH ARM to run, threaded to the plan flow. The Phase 2 pre-registration's four:
+ *          `false`  A0 — off (the default)
+ *          `'cap'`  A1 — cap + pointer + next-unseen-slice + G1, no diff
+ *          `'diff'` A2 — the diff lever alone: no cap, no pointer, no G1
+ *          `true`   A3 — every lever
+ *        Anything else THROWS below, before a token is spent: a mis-spelled arm coerced
+ *        by truthiness into A3 would run one treatment under another's label and be
+ *        invisible in the results afterwards.
+ *        OFF is byte-identical to the pre-shim run in every observable (G1 included): the
+ *        frozen A0 baseline arm has to be exactly today, so a guard firing under a disabled
+ *        shim would make the baseline a treatment arm. The default-flip belongs to a
+ *        paid contrast nobody has approved yet (the `layerRoot` precedent, F41).
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -187,7 +201,15 @@ async function primitiveSmoke(workdir) {
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, layerRoot = false, readShim = false, bridge = null, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null }) {
+  // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
+  // before the ledger, before the approval gate, before a byte of the spec is read.
+  // An unrecognised spelling throws here at zero cost instead of being coerced by
+  // truthiness into A3 and running a whole paid battery row under an arm label it
+  // never executed — a wrong result that looks like a fine one, which is the exact
+  // blind-instrument failure this programme keeps logging. Only the guard runs
+  // here; the flag itself is threaded onward to the plan flow as written.
+  readShimArm(readShim);
   // 0. the ledger's counters, declared FIRST so that every job-end — including
   // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
   // not a zero: a consumer reads `undefined` and either crashes or launders it
@@ -232,6 +254,15 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // outcome — keying on the outcome would floor the exact stop too, which is the same
   // dishonesty pointing the other way.
   let cutMidCall = false;
+  // F115 — did any worker call in this run absorb a transport-class retry
+  // (hamr's ruling: one retry, transport-only, planrun.js `withTransportRetry`)?
+  // The FIRST attempt of a retried call may already have been billed and threw
+  // before returning any usage figure — the same unknown a self-healed stall
+  // and a mid-call wall cut carry, so the same one-way floor applies even when
+  // the retry recovered and the run finishes green. Read off the `transport-retry`
+  // spine record's presence alone, never its `recovered` field: a recovered
+  // retry still hides the first attempt's possible spend.
+  let transportRetried = false;
   // The money on the terminal record, and whether the money is EXACT. `spentUsd`
   // is the accumulated sum of PRICED rounds ONLY — never an estimate derived
   // from tokens or averages (cap-not-estimate). When any round came back
@@ -241,7 +272,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // branch on field presence.
   // ONE spelling of the four causes, so the terminal and the in-flight money readout can
   // never disagree about whether the same run's figure is exact.
-  const spendComplete = () => !unpriced && !stalled && !cutMidCall && !priorFloor;
+  const spendComplete = () => !unpriced && !stalled && !cutMidCall && !priorFloor && !transportRetried;
   const spend = () => ({
     spentUsd,
     spendComplete: spendComplete(),
@@ -342,6 +373,10 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
     // One-way, and read by `spend()` — the run ends on this record either way, but the
     // between-rounds stop must keep its exact figure rather than inheriting a floor.
     if (type === 'wall-halt' && /** @type {any} */ (data)?.cutMidCall === true) cutMidCall = true;
+    // F115 — one-way, same lane as `stall`/`cutMidCall`: a transport retry's
+    // FIRST attempt threw before any usage figure came back, so the priced sum
+    // is a floor for the rest of the run regardless of `recovered`.
+    if (type === 'transport-retry') transportRetried = true;
     return emit(type, data);
   };
   const pricingRed = () => {
@@ -356,7 +391,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, layerRoot, readShim, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd,
       remainingUsd: () => Math.min(shellCapUsd, job.budgetUsd - spentUsd),
       isUnpriced: () => unpriced, // F6: let the plan flow bail in-flight, not just after it returns
       spendComplete, // …and let its money-halt readout say whether the remaining it quotes is exact

package/src/selection.js

@@ -1,5 +1,5 @@
 // Layer 3 — D3's DISPLAY half: the workflow LISTING, and the prompt that asks for a
-// pick (design record docs/02-features/2026-08-01-layer-3-reuse-design.md, D3).
+// pick (design record docs/product/2026-08-01-layer-3-reuse-design.md, D3).
 //
 // hamr's ruling, verbatim: *"i think there should be a listing for workflows names that
 // user can choose or auto-choose, or do we want llm to always decide (we still need to

package/src/tools.js

@@ -21,7 +21,7 @@ const require = createRequire(import.meta.url);
 const { createShellTools } = require('bare-agent/tools');
 // litectx's rank-tiered render — a free function, not a ctx method (its contract's
 // own recipe: the caller slices the chunk body, compress renders the signature tier)
-const { compress: compressNode } = require('litectx');
+const { compress: compressNode, StalePointerError } = require('litectx');
 
 import { extractArtifact, priceOf } from './text.js';
 // The isolate verbs write MODEL-AUTHORED text into `<workdir>/.litectx` — a file
@@ -243,8 +243,13 @@ const LINE_SPACE = 'Line numbers here are 0-BASED index positions from the repos
  *   RESULT is invisible cannot be judged: a `ctx_get` that silently reds (stale pointer,
  *   bad range) looks exactly like one that worked, and the worker's fallback to a
  *   whole-file read looks like a free choice instead of a forced one.
+ * @param {{onStalePointer?: ((req: {file: string, path: string, startLine: number, endLine: number, detail: string}) => {text: string, outcome: string}|null)|null}} [opts]
+ *   `onStalePointer`: the read shim's stale-pointer serve, wired ONLY by a capping
+ *   arm (see `createReadShim`). Absent — every caller today except that one — this
+ *   whole seam is byte-identical to what it was, which is what keeps A0 the
+ *   untouched baseline an experiment has already run against.
  */
-export function createCtxTools(lc, workdir, emit) {
+export function createCtxTools(lc, workdir, emit, { onStalePointer = null } = {}) {
   // ctx_get's failure contract, generalised to the palette (review 2026-07-31).
   // `emit` exists in this file because a verb whose RESULT is invisible cannot be
   // judged — and a THROWN call is the most invisible result there is: it looks
@@ -337,6 +342,33 @@ export function createCtxTools(lc, workdir, emit) {
           // StalePointerError: the file changed after indexing, so these lines now describe
           // DIFFERENT code. Its message IS the recovery instruction — hand it to the worker.
           const detail = String(/** @type {Error} */ (e)?.message || e);
+          // …and under a CAPPING read-shim arm, the recovery instruction is not
+          // enough. That arm's own strategy line steers the worker HERE for a whole
+          // function, and a worker that just edited the file it is working on — the
+          // normal case — gets a stale pointer and zero bytes for a paid round
+          // (measured: 5 of 10 ctx_get calls across the A1 arm's three green runs).
+          // So the shim serves the requested LINE RANGE from disk, labelled; see
+          // `serveStale`. The branch is on the TYPED error, never on the message
+          // prose — a prose sniff would fire on any failure whose wording happens
+          // to match, and litectx exports the class precisely so it need not.
+          if (onStalePointer && e instanceof StalePointerError) {
+            // The gate judged `resolve(workdir, expandHome(path))` for this call
+            // (toolAction, 'ctx_get'); the serve reads that same absolute path and
+            // no other, so it can never reach a byte the fence did not allow.
+            const served = onStalePointer({
+              file: resolve(workdir, expandHome(String(p))),
+              path: rel,
+              startLine: Number(startLine),
+              endLine: Number(endLine),
+              detail,
+            });
+            if (served && typeof served.text === 'string') {
+              // No `detail` on the event: the served TEXT is file content and the
+              // spine is append-only. Bytes and the outcome are what a reader needs.
+              emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: served.outcome, bytes: Buffer.byteLength(served.text) });
+              return served.text;
+            }
+          }
           emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'stale', bytes: 0, detail });
           return `stale pointer: ${detail}`;
         }

package/src/transport.js

@@ -0,0 +1,71 @@
+// hamr's ruling, verbatim: "one retry for transport layer failure and
+// reporting with the rest end of gate." (F115, docs/logs/FINDINGS.md.)
+//
+// A transport failure is fetch THROWING — the request never produced an HTTP
+// response at all (a TLS fault mid-record, a reset socket, a DNS/network
+// failure). That is a DIFFERENT unknown from an HTTP response the provider
+// DID send (4xx/5xx/429): a response means the provider answered, so
+// bare-agent's own retry policy for those stays exactly what it is — this
+// module never widens that. Retrying only the no-response case is the whole
+// point: a call that dies mid-read may already have been billed (retry can
+// pay twice), so the retry budget stays as tight as hamr authorized it —
+// exactly one extra attempt, never configurable upward from a job spec or
+// argv (tighten-only doctrine).
+//
+// Scope: this module wires ONE seam — the worker Loop built in
+// src/planrun.js's `newLoop` (~line 2239), which is the ONE factory behind
+// every scout/drafter/step/fix-worker call. It deliberately does NOT reach
+// the judge loops (src/judged.js), the native/CLI loop (src/planrun.js
+// ~2089), or the authoring scout (src/authorscout.js) — none of those are in
+// scope of hamr's ruling and each has its own transport story.
+
+/** The fixed retry budget: ONE extra attempt after the first transport
+ * throw. Never read from a job spec or CLI flag — raising it is arbiter
+ * territory (only a code change hamr signs, never a run-time knob). */
+export const TRANSPORT_RETRIES = 1;
+
+/** bare-agent's `Retry.call` counts ATTEMPTS, not retries. */
+export const TRANSPORT_MAX_ATTEMPTS = TRANSPORT_RETRIES + 1;
+
+/**
+ * Is `err` a transport-class failure — the request never produced an HTTP
+ * response? True for: a TLS fault mid-record ("bad record mac" and kin), a
+ * reset/broken/timed-out socket (ECONNRESET, EPIPE, ETIMEDOUT, ECONNREFUSED,
+ * ENETUNREACH — by code on the error itself or on `err.cause`), and
+ * `fetch failed` wrapping a network `cause`. False for anything carrying an
+ * HTTP status (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
+ * `err.retryable === false` — those are provider RESPONSES, not transport
+ * casualties, and bare-agent's own policy governs them unchanged.
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isTransportFailure(err) {
+  if (err == null) return false;
+  // An explicit HTTP response is never a transport casualty, no matter what
+  // its message says — the provider answered.
+  const status = err.status ?? err.statusCode;
+  if (typeof status === 'number') return false;
+  if (err.retryable === false) return false;
+
+  const codeOf = (e) => (e && typeof e.code === 'string' ? e.code : null);
+  const TRANSPORT_CODES = new Set(['ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ECONNREFUSED', 'ENETUNREACH', 'EAI_AGAIN']);
+  const code = codeOf(err) ?? codeOf(err.cause);
+  if (code && TRANSPORT_CODES.has(code)) return true;
+
+  const message = String(err.message ?? err ?? '');
+  if (/bad record mac/i.test(message)) return true;
+  if (TRANSPORT_CODES.has(message.trim())) return true;
+  for (const c of TRANSPORT_CODES) if (message.includes(c)) return true;
+  if (/fetch failed/i.test(message)) {
+    // "fetch failed" alone is Node's generic wrapper — it is only a
+    // transport casualty when its cause names a network fault, never on
+    // message text alone (a fetch can also fail on a non-network throw
+    // upstream, and that must not silently qualify).
+    const causeCode = codeOf(err.cause);
+    if (causeCode) return true;
+    const causeMsg = String(err.cause?.message ?? '');
+    if (/bad record mac/i.test(causeMsg) || [...TRANSPORT_CODES].some((c) => causeMsg.includes(c))) return true;
+    return false;
+  }
+  return false;
+}

package/types/behaviour.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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: Array<{
+    run_id?: string;
+    action?: {
+        type?: string;
+        path?: string;
+        args?: any;
+    };
+    decision?: string | null;
+}>, { runId }?: {
+    runId?: string;
+}): {
+    totalCalls: number;
+    byTool: Record<string, number>;
+    denied: number;
+    uniquePaths: number;
+    repeats: number;
+    repeatPct: number | 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: ReturnType<typeof runBehaviour>): string;

package/types/index.d.ts

@@ -9,8 +9,9 @@ export { runJob, ACCOUNTED_ROUND_TYPES } from "./run.js";
 export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists, QUARANTINED_VERDICTS, QUARANTINED_CODE, quarantinesCredit, newestEligibleVersion, reuseEligibility, recordDoor } from "./bridges.js";
 export { renderListing, selectionPrompt } from "./selection.js";
 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";
+export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES, VOUCHED_RATE_SOURCES, rateProvenance, spendProvenance } from "./ledger.js";
 export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE } from "./workbranch.js";
+export { createReadShim, wrapReadTool, readShimArm, readShimStrategy, READ_SHIM_CAP, READ_SHIM_STRATEGY, READ_SHIM_DIFF_STRATEGY, READ_SHIM_ARMS } from "./readshim.js";
 export { runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees, LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP, HUMAN_DECISIONS, SEED_EXEMPT_KINDS, JUDGED_FLOOR_KIND, normalizeHumanRuling, resolveHumanRuling, JUDGE_ATTEMPTS, MAX_JUDGED_PATHS, REVIEW_DOOR, DOOR_OPEN_OUTCOMES, REVIEW_DOOR_CLASSES, doorOpens, mechanicalStages } from "./kinds.js";
 export { answerReviewDoor, doorRecordOf, doorAgeGate } from "./reviewdoor.js";
 export { JUDGE_MODEL, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL, validateCard, validateFacts, locatePrompt, runLocate, decide, defaultJudgeLoop, CALIBRATION_SIZE, CASE_VERDICTS, validateCalibrationSet, validateJudgedArtifacts, expectedOf } from "./judged.js";
@@ -21,4 +22,5 @@ export { runAuthorScout, buildSeedListing, seedFileList, classifySurvey, AUTHOR_
 export { scrubRaw, RAW_PERSIST_MAX, RAW_TRIM_MARKER } from "./text.js";
 export { authorClose, authorPrompt, declarationSchema, makeLoopGenerate, MAX_REVISIONS, QUESTION_SETS, GREEN_QUESTIONS, SOFTGREEN_QUESTIONS, CLASS_STATEMENTS, questionsFor, requiredAnswersFor } from "./authorflow.js";
 export { validateCloseDecl, runDeclaredStages, declaredStages, isDeclaredClose, guardNames, closeGrade, DECLARED_GENRES, DECLARED_GAP_PREFIX, DECLARED_GAP_KEEP, DECLARED_CLOSE_CLASSES, CLOSE_DECL_FIELDS, HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS } from "./declaredclose.js";
+export { runBehaviour, formatBehaviour } from "./behaviour.js";
 export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind, GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS } from "./authorjob.js";

package/types/ledger.d.ts

@@ -48,8 +48,66 @@ export function updateLedger({ ledgerFile, spineFiles }: {
     appended: object[];
     fold: Record<string, FoldEntry>;
 };
+/**
+ * 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: any): "vouched" | "guessed" | "unpriced" | "unknown";
+/** @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: any[]): {
+    vouched: ProvenanceBucket;
+    guessed: ProvenanceBucket;
+    unpriced: ProvenanceBucket;
+    unknown: ProvenanceBucket;
+};
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES: readonly string[];
+/**
+ * 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: readonly string[];
+export type ProvenanceBucket = {
+    rounds: number;
+    usd: number;
+    unpricedRounds: number;
+};
 export type Sample = {
     spine: string;
     seq: number;

package/types/plan.d.ts

@@ -72,7 +72,7 @@ export function closeStagesOf(job: any): any[] | null;
  * 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
@@ -94,14 +94,23 @@ export function closeStagesOf(job: any): any[] | null;
  *   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: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks }?: {
+export function validatePlan(input: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks, readShim }?: {
     job?: any;
     maxStepRounds?: number;
     scopes?: string[];
     seedRed?: string[];
     priorChecks?: string[];
+    readShim?: boolean | "cap" | "diff";
 }): {
     ok: boolean;
     reds: Red[];
@@ -122,6 +131,14 @@ export const MAX_PLAN_STEPS: 8;
  * 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: readonly string[];
 /** P (design record 2026-07-28): the signed per-step model-tier menu. Closed by
  * construction — the agent picks a tier, never names an arbitrary model string
  * (the tier→model mapping and any effort params are the RUNNER's, per provider).

package/types/planrun.d.ts

@@ -78,6 +78,25 @@
  * @returns {string} the labelled block, or '' when there is nothing to show
  */
 export function closeGapBlock(gap: string | null | undefined): string;
+/**
+ * BA-21 — the WRITE side of the pricing-provenance signal (read side: `rateProvenance` /
+ * `spendProvenance` in src/ledger.js). bare-agent >=0.37 rides `rateSource` beside
+ * `pricing` on every metering payload; both metering callbacks below forward it onto the
+ * spine through THIS one helper, because two sites spelling one rule are two instruments
+ * (the ripgrep fix that landed in ci.yml but not publish.yml).
+ *
+ * Forwarded VERBATIM — the write side reports what upstream said, and src/ledger.js is
+ * the one place that decides what counts as a guess. And an ABSENT provenance stays
+ * absent: a payload carrying no `rateSource` (bare-agent <0.37, and every round already
+ * in the archive) emits no field at all, so a reader sees UNKNOWN rather than a label we
+ * invented. Never defaulted to `null` here — `null` is upstream saying "nothing was
+ * priced", which is a different fact from "nobody told us".
+ * @param {any} arg an `onLlmResult` / `onTurn` payload
+ * @returns {{rateSource?: string|null}} the field to spread into the spine record
+ */
+export function rateSourceFields(arg: any): {
+    rateSource?: string | null;
+};
 /**
  * What the NEXT attempt is told about the bound that cut the previous one.
  *
@@ -146,6 +165,10 @@ export function boundedNote(bounded: {
  *   REQUIREMENT the plan must meet, never a replacement for the goal: the signed goal and
  *   the signed close are unchanged, and what the person added is what the machine could
  *   not see.
+ * @param {boolean|'cap'|'diff'} [readShim] the read shim's ARM. Does it carry G1? Then G1
+ *   is STATED as well as enforced (the mailbox precedent again: a law only the validator
+ *   knows costs a redraft per draft). The arms without it — `false` and `'diff'` — render
+ *   byte-identically to the pre-shim prompt.
  */
 export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
     balanceUsd?: number | null;
@@ -154,7 +177,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
 }, startingDraft?: object | null, checkFacts?: {
     seedRed?: string[];
     priorChecks?: string[];
-}, doorNote?: string | null): string;
+}, doorNote?: string | null, readShim?: boolean | "cap" | "diff"): string;
 /**
  * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close).
  * Called by runJob after the approval gate, validation, and the smoke — this
@@ -203,6 +226,17 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
  *   reserved — a scout that spends every round on tools gets one toolless round to write its
  *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
+ * @param {boolean|'cap'|'diff'} [opts.readShim=false] THE READ SHIM (src/readshim.js) — the
+ *   ARM to run, one of the Phase 2 pre-registration's four: `false` (A0, off — the default),
+ *   `'cap'` (A1: cap + pointer + next-unseen-slice + G1), `'diff'` (A2: the diff lever alone,
+ *   no cap, no pointer, no G1), `true` (A3: every lever). Anything else THROWS at the entry
+ *   below rather than coercing into a truthy shim — a mis-spelled arm that silently ran A3
+ *   is a corrupted battery row, invisible afterwards.
+ *   OFF is byte-identical to the pre-shim run in every observable, G1 included: the frozen
+ *   A0 baseline arm must be exactly today's behaviour, and a guard firing under a disabled
+ *   shim would quietly make the baseline a treatment arm. The default-flip waits on a paid
+ *   contrast that has not been approved (the `layerRoot` precedent, F41 — an unproven lever
+ *   ships OFF and earns its default).
  * @param {boolean} [opts.layerRoot=false] Layer R — the within-run ratchet (src/root.js),
  *   scoped PER STEP's ralph loop (each micro-wheel is the Layer-1 atom). Shell-assembled from
  *   the step's own books: per-attempt write-sets from the F32 workerWrites audit (teed for
@@ -352,7 +386,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, readShim, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -371,6 +405,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     closeTimeoutMs?: number | undefined;
     maxStepRounds?: number | undefined;
     scoutRounds?: number | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     layerRoot?: boolean | undefined;
     bridge?: unknown;
     priorWallMs?: number | undefined;

package/types/readshim.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Resolve the `readShim` flag into its arm. THROWS on anything else — the BA-4
+ * param-guard class, and deliberately not a red.
+ *
+ * An unrecognised value is OPERATOR input, arriving before a single token is
+ * spent, and there is exactly one safe way to fail on it: loudly, at once. The
+ * failure this guard exists to prevent is `readShim: 'diff '` (or 'Diff', or
+ * 'cap+diff') coerced by truthiness into A3 — a battery row that RAN the wrong
+ * arm, recorded the arm it was asked for, and is invisible in the results
+ * afterwards. That is the blind-instrument class this programme keeps paying
+ * for, and it would corrupt the contrast rather than merely fail a run.
+ *
+ * A red was the alternative and is wrong here twice over: a red is a verdict on
+ * the AGENT's work (the plan, the artifact), and this is the operator's own
+ * argument; and a red would need a terminal outcome name, which is arbiter
+ * territory and out of this change's scope.
+ * @param {boolean|'cap'|'diff'|undefined} [flag]
+ * @returns {ReadShimArm}
+ */
+export function readShimArm(flag?: boolean | "cap" | "diff" | undefined): ReadShimArm;
+/**
+ * The persona line this arm is entitled to — empty when the arm changes nothing
+ * the worker can perceive. One arm, one line: the two are never concatenated,
+ * because a cap arm has no diff and a diff arm has no cap.
+ * @param {ReadShimArm} arm
+ * @returns {string}
+ */
+export function readShimStrategy(arm: ReadShimArm): string;
+/** @typedef {{file: string, path: string, startLine: number, endLine: number, detail: string}} StaleReq */
+/** @typedef {{text: string, outcome: 'stale-served'|'stale-absent'|'stale-past-eof'}} StaleServe */
+/**
+ * Create the shim: one delivery ledger, and the two seams that speak for it.
+ *
+ * `wrapRead` is the read tool's wrapper (the ledger's only writer). `serveStale`
+ * is the answer to a stale `ctx_get` pointer, and it deliberately holds NO
+ * reference to the ledger — see its own note. Both live in one object because
+ * they are one worker's shim: the read seam and the retrieval seam the cap
+ * steers a capped worker towards.
+ * @param {{cap?: number, arm?: ReadShimArm, onCount?: ((kind: 'pointered'|'capped', bytesWithheld: number) => void)|null}} [opts]
+ *   `cap`: delivery bound in bytes (the shipped value is `READ_SHIM_CAP`; the option
+ *   exists so the native path can pin the two bounds to one number rather than two
+ *   constants drifting apart). `arm`: which levers are live (`readShimArm`). Defaults to
+ *   ALL of them, so every caller written before the arms existed keeps the behaviour it
+ *   was written against. `onCount`: MEMORY-CACHE — fired once per pointer/capped-slice
+ *   response with exactly the bytes withheld on THAT response, for a caller (e.g.
+ *   `runPlan`) that sums several workers' shims into one run-level readout. Never called
+ *   for a diff response (L2 is its own lever, uncounted here) or a first read under the
+ *   cap (nothing was withheld).
+ */
+export function createReadShim({ cap, arm, onCount }?: {
+    cap?: number;
+    arm?: ReadShimArm;
+    onCount?: ((kind: "pointered" | "capped", bytesWithheld: number) => void) | null;
+}): {
+    arm: ReadShimArm;
+    cap: number;
+    wrapRead: (tool: {
+        name: string;
+        execute: (args: any) => Promise<any>;
+    }) => {
+        name: string;
+        execute: (args: any) => Promise<any>;
+    };
+    serveStale: ({ file, path, startLine, endLine, detail }: StaleReq) => StaleServe | null;
+    summary: () => {
+        pointered: number;
+        capped: number;
+        bytesWithheld: number;
+    };
+};
+/**
+ * The one-tool spelling, kept for every caller written before the shim became an
+ * object: wrap this read tool with its own private ledger and hand it back.
+ * @param {{name: string, execute: (args: any) => Promise<any>}} tool
+ * @param {{cap?: number, arm?: ReadShimArm}} [opts]
+ * @returns {{name: string, execute: (args: any) => Promise<any>}} the same tool
+ */
+export function wrapReadTool(tool: {
+    name: string;
+    execute: (args: any) => Promise<any>;
+}, opts?: {
+    cap?: number;
+    arm?: ReadShimArm;
+}): {
+    name: string;
+    execute: (args: any) => Promise<any>;
+};
+/** The delivery cap, in bytes. Equal to `NATIVE_READ_CAP` by construction — the
+ * native path's CLI display bound and this cap bound the SAME seam, so one
+ * number keeps them from double-truncating each other (see planrun's wiring). */
+export const READ_SHIM_CAP: number;
+/** The legal spellings, in one place so an error message cannot drift from the
+ * set it describes. */
+export const READ_SHIM_ARMS: readonly string[];
+/** F19 at the bound rather than the verb (the NATIVE_READ_STRATEGY precedent):
+ * a cap the worker does not know about is a worker that reads the same file
+ * three times wondering why it keeps starting over. It states the bound, what a
+ * re-read does, and the two verbs that read a symbol whole — the capability the
+ * cap makes mandatory (G1). */
+export const READ_SHIM_STRATEGY: "\nREAD LIMIT: a shell_read of a file over 24KB returns only the next 24KB of it, followed by a notice saying which bytes you got. This is NOT the whole file. Reading the same path again continues where the last read stopped, and once you hold all of it a re-read says so instead of re-sending the bytes. To read a function IN FULL, use ctx_recall(<symbol>) then ctx_get(<pointer>) \u2014 that returns the entire function however large its file is. To locate a line, use shell_grep(<pattern>). Never try to understand a large file by reading it whole.";
+/** The DIFF arm's own line. It says nothing about a 24KB limit and nothing about
+ * continuation reads, because under A2 neither exists — a persona describing
+ * machinery that is off is a lie to the worker, and a worker rationing its reads
+ * against an imaginary cap is a different treatment than the arm names.
+ *
+ * It does not repeat the steer at ctx_recall/ctx_get either: that steer is the
+ * CAP's compensation (G1's other half), and offering it here would import half
+ * of A1 into A2. The delivery itself carries `diffNotice`'s framing inline; this
+ * line exists so the first diff is not a surprise. */
+export const READ_SHIM_DIFF_STRATEGY: "\nRE-READS: if you shell_read a file you have already been shown in full and it has changed since, the result is a unified DIFF against the copy you already hold \u2014 not the file itself. It is labelled as one. Lines starting '-' were removed, '+' were added, ' ' are unchanged context; apply it to the copy you have and you hold the current file.";
+export type StaleReq = {
+    file: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    detail: string;
+};
+export type StaleServe = {
+    text: string;
+    outcome: "stale-served" | "stale-absent" | "stale-past-eof";
+};
+export type ReadShimArm = {
+    on: boolean;
+    cap: boolean;
+    pointer: boolean;
+    diff: boolean;
+    g1: boolean;
+};