bareloop 0.12.0 → 0.13.0

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/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";

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,117 @@
+/**
+ * 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}} [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.
+ */
+export function createReadShim({ cap, arm }?: {
+    cap?: number;
+    arm?: ReadShimArm;
+}): {
+    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;
+};
+/**
+ * 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;
+};

package/types/reuse.d.ts

@@ -364,6 +364,7 @@ export function resumeTreeGate({ head, seed, dirty }: {
  * @param {number} [opts.strikeLimit] forwarded (a plan step's strike ceiling)
  * @param {number} [opts.closeTimeoutMs] forwarded
  * @param {boolean} [opts.layerRoot] forwarded
+ * @param {boolean|'cap'|'diff'} [opts.readShim] the read shim's ARM (A0/A1/A2/A3), forwarded verbatim
  * @param {any} [opts.resume] RESUME (module C) — a `readResume` reading of the KILLED
  *   run's own spine. Its `approvalHash` must match this run's, or the run refuses:
  *   a resume continues ONE signed run, not any run.
@@ -397,6 +398,7 @@ export function runReuse(opts: {
     strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
     layerRoot?: boolean | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     resume?: any;
     runJob?: typeof shippedRunJob | undefined;
     now?: (() => number) | undefined;

package/types/run.d.ts

@@ -97,6 +97,19 @@
  *   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
@@ -128,7 +141,7 @@
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, readShim, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -159,6 +172,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         grantUsed?: boolean;
     } | null | undefined;
     resumeBranch?: string | null | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     layerRoot?: boolean | undefined;
     humanRuling?: {
         decision: string;

package/types/tools.d.ts

@@ -19,8 +19,24 @@ export function strategyFor(granted: string[]): string;
  *   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: any, workdir: string, emit: (type: string, data: object) => void): ({
+export function createCtxTools(lc: any, workdir: string, emit: (type: string, data: object) => void, { onStalePointer }?: {
+    onStalePointer?: ((req: {
+        file: string;
+        path: string;
+        startLine: number;
+        endLine: number;
+        detail: string;
+    }) => {
+        text: string;
+        outcome: string;
+    } | null) | null;
+}): ({
     name: string;
     description: string;
     parameters: {