bareloop 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.13.0",
+  "version": "0.15.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",
@@ -17,13 +17,13 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test && node scripts/prompt-commit-check.mjs --range origin/main..HEAD",
     "typecheck": "tsc --noEmit",
     "build:types": "tsc",
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.36.0",
+    "bare-agent": "^0.39.0",
     "bareguard": "^0.13.0",
     "litectx": "^0.32.0"
   },

package/src/behaviour.js

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

package/src/bridges.js

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

package/src/calibrate.js

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

package/src/cardauthor.js

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

package/src/codeversion.js

@@ -0,0 +1,155 @@
+// F118 (parked half) — the run→code direction. The commit→run direction
+// (prompt-commit-check's `Failure:` line citing a run id) landed same-day;
+// this is the other half: a run's own spine never recorded which version of
+// bareloop's code it ran under, so a replay could not tell which prompts
+// were in force. Report-only, $0, no shell — same posture as the F117
+// verdictType/model stamp this rides beside (src/run.js:303).
+//
+// NEVER shells out to git: `run` is the one locked verb (hamr's law), and a
+// library growing a shell seam just to read a report field is exactly the
+// kind of capability creep that doctrine exists to block. Everything below
+// is a plain file read of `.git`'s own on-disk layout.
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// this module lives at <pkgRoot>/src/codeversion.js
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * `.git` at a package root can be a FILE, not a directory — `git worktree
+ * add` makes every worktree's own `.git` a one-line pointer file
+ * (`gitdir: <path>`, absolute or relative to the worktree root) at the
+ * per-worktree git dir living under the main checkout's `.git/worktrees/
+ * <name>/` (measured directly: `git worktree add <tmp> HEAD --detach`
+ * against this repo). Resolves that file to the real per-worktree git dir;
+ * returns the plain `.git` directory path unchanged when it already is one,
+ * and `null` when `.git` is absent (an npm install) or the pointer file
+ * can't be read/parsed.
+ * @param {string} pkgRoot
+ * @returns {string|null}
+ */
+function resolveGitDir(pkgRoot) {
+  const dotGit = join(pkgRoot, '.git');
+  if (!existsSync(dotGit)) return null;
+  const st = statSync(dotGit);
+  if (st.isDirectory()) return dotGit;
+  if (!st.isFile()) return null;
+  const contents = readFileSync(dotGit, 'utf8').trim();
+  const m = /^gitdir:\s*(.+)$/.exec(contents);
+  if (!m) return null;
+  const target = m[1].trim();
+  return target.startsWith('/') ? target : join(pkgRoot, target);
+}
+
+/**
+ * A worktree's own git dir (from {@link resolveGitDir}) holds HEAD but never
+ * refs — branches/`packed-refs` are shared, and live in the MAIN checkout's
+ * `.git`, whose path is this worktree git dir's own `commondir` file (one
+ * line, a path RELATIVE TO THIS GIT DIR — measured directly: this repo's own
+ * worktree fixture wrote `../..`, which from `.git/worktrees/<name>/`
+ * resolves back to the repo's real `.git`). A normal (non-worktree) git dir
+ * carries no `commondir` file at all and IS already the common dir.
+ * @param {string} gitDir
+ * @returns {string}
+ */
+function resolveCommonDir(gitDir) {
+  const commondirPath = join(gitDir, 'commondir');
+  if (!existsSync(commondirPath)) return gitDir;
+  try {
+    const rel = readFileSync(commondirPath, 'utf8').trim();
+    if (!rel) return gitDir;
+    return rel.startsWith('/') ? rel : join(gitDir, rel);
+  } catch {
+    return gitDir;
+  }
+}
+
+/**
+ * Resolve a ref name (e.g. "refs/heads/main") to a sha by reading the loose
+ * ref file, falling back to `packed-refs` when the branch has been packed
+ * (measured: this repo's own `.git/packed-refs` carries `main` but not every
+ * branch — a loose ref can legitimately be absent while the branch is real).
+ * @param {string} gitDir
+ * @param {string} refName
+ * @returns {string|null}
+ */
+function resolveRef(gitDir, refName) {
+  const loose = join(gitDir, refName);
+  if (existsSync(loose)) {
+    try {
+      const sha = readFileSync(loose, 'utf8').trim();
+      return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+    } catch {
+      return null;
+    }
+  }
+  const packed = join(gitDir, 'packed-refs');
+  if (!existsSync(packed)) return null;
+  try {
+    const lines = readFileSync(packed, 'utf8').split('\n');
+    for (const line of lines) {
+      if (line.startsWith('#')) continue;
+      const [sha, ref] = line.trim().split(' ');
+      if (ref === refName && sha && /^[0-9a-f]{40}$/.test(sha)) return sha;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Report-only stamp of the bareloop code this process is running as. Never
+ * throws — an unreadable package.json or absent `.git` reads as `null`,
+ * honestly, rather than crashing a caller over a report field.
+ * @returns {{ version: string|null, sha: string|null, dirty: null }}
+ */
+export function codeVersion() {
+  let version = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+    version = typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    version = null;
+  }
+
+  let sha = null;
+  try {
+    // only a dev checkout carries a `.git` at all (directory OR the
+    // `gitdir:` pointer file a worktree checkout leaves instead) — an
+    // npm-installed copy has neither, and this reads that absence as
+    // "unknown", never fakes one
+    const gitDir = resolveGitDir(PKG_ROOT);
+    if (gitDir !== null) {
+      const headPath = join(gitDir, 'HEAD');
+      const head = readFileSync(headPath, 'utf8').trim();
+      const m = /^ref:\s*(\S+)$/.exec(head);
+      if (m) {
+        // branches/packed-refs are shared across worktrees and live in the
+        // COMMON git dir, never the per-worktree one HEAD itself came from
+        sha = resolveRef(resolveCommonDir(gitDir), m[1]);
+      } else if (/^[0-9a-f]{40}$/.test(head)) {
+        // detached HEAD: a bare 40-hex sha directly in the file
+        sha = head;
+      }
+    }
+  } catch {
+    sha = null;
+  }
+
+  // dirty: uncommitted-changes state cannot be known without a shell
+  // (`git status`/`git diff`) — reported as unknown, never faked as false.
+  return { version, sha, dirty: null };
+}
+
+/**
+ * First 8 characters of a sha, or null. Mirrors the short-sha convention
+ * `replay.js` already uses for `specHash` (`s.specHash.slice(0, 8)`).
+ * @param {string|null|undefined} sha
+ * @returns {string|null}
+ */
+export function shortSha(sha) {
+  return typeof sha === 'string' && sha.length > 0 ? sha.slice(0, 8) : null;
+}

package/src/index.js

@@ -228,6 +228,17 @@ export {
   HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS,
 } from './declaredclose.js';
 export { closeStagesOf } from './plan.js';
+// Build-list item 2 (2026-08-23) — the run behaviour summary: a report-only
+// read of a run's gate-audit records. Gates nothing, mints no verdict,
+// writes nothing to the spine; `runBehaviour` computes, `formatBehaviour`
+// renders the printable block.
+export { runBehaviour, formatBehaviour } from './behaviour.js';
+// PRD build-list item 6 — generic run replay: point it at a run's spine (+
+// its gate-audit sidecar) and get the whole story back as one object
+// (`replayRun`) or one printable page (`formatReplay`). Reads only, mints no
+// verdict, writes nothing to the spine — reuses `runBehaviour` rather than
+// re-implementing the tool-call count.
+export { replayRun, formatReplay } from './replay.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.
 // `prepareSigning` returns the resolved spec's HASH and the seed evidence; it
 // never signs — the approvals array and the human's word are unchanged.
@@ -235,3 +246,9 @@ export {
   runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind,
   GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS,
 } from './authorjob.js';
+// PRD build-list item 5 (TODO #8) — the prompt-register inventory: every file
+// known to carry model-facing prompt/instruction text, and the predicate a
+// commit-message check (`scripts/prompt-commit-check.mjs`) uses to decide
+// whether a changed file is one. The ONE place this list lives; exported so
+// bareloop.context.md can point an adopter here instead of re-deriving it.
+export { PROMPT_REGISTERS, isPromptFile } from './promptregisters.js';

package/src/job.js

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

package/src/judged.js

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

package/src/ledger.js

@@ -1,5 +1,5 @@
 // The upstream ledger (module 4) — reactive lib/primitive incident monitoring.
-// Design record: docs/02-features/2026-07-11-upstream-ledger-design.md (adaptlearn
+// Design record: docs/product/2026-07-11-upstream-ledger-design.md (adaptlearn
 // POC'd spec) + its 2026-07-13 addendum: the bareloop event mapping. One
 // append-only JSONL both the consumer (the panel, N6) and the maintainer read;
 // the A1/A2/A3 upstream-ask flow, mechanized — evidence in, human judgment out.
@@ -479,7 +479,7 @@ export function rateProvenance(record) {
  * 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']);
+export const SPEND_RECORD_TYPES = Object.freeze(['worker-round', 'judge-round', 'worker-turn']);
 
 /** @typedef {{rounds: number, usd: number, unpricedRounds: number}} ProvenanceBucket */
 

package/src/planrun.js

@@ -42,9 +42,101 @@ import {
   REVIEW_DOOR, doorOpens, mechanicalStages,
 } from './kinds.js';
 import { workBranchName, prepareWorkBranch } from './workbranch.js';
+import { TRANSPORT_MAX_ATTEMPTS, isTransportFailure } from './transport.js';
 
 const require = createRequire(import.meta.url);
-const { Loop, wireGate, HaltError } = require('bare-agent');
+const { Loop, Retry, wireGate, HaltError } = require('bare-agent');
+
+// F115 — hamr's ruling verbatim: "one retry for transport layer failure and
+// reporting with the rest end of gate." TRANSPORT_MAX_ATTEMPTS is fixed
+// (src/transport.js — never a job-spec/argv knob); `retryOn` is bare-agent's
+// own extension seam (node_modules/bare-agent/src/retry.js), constrained to
+// ONLY the no-HTTP-response transport class so a provider RESPONSE (4xx/5xx/
+// 429) still rides bare-agent's own unchanged policy. One instance: `Retry`
+// carries no per-call state, so it is safe to share across every worker.
+// timeout:0 disables Retry's own per-attempt race (this run already has its
+// own timing authority — the stall watchdog and the wall clock, src/stall.js
+// / src/clock.js — and a second racing 60s clock here would just be a second,
+// disagreeing one; bare-agent's own BA-18 idle-socket timeout is what
+// actually bounds a hung call, and that is exactly one of the errors this
+// retry is FOR). `backoff` is deliberately left unset: bare-agent's
+// constructor does `options.backoff || 'exponential'`, so a literal `0` is
+// falsy and would silently fall through to the same exponential default
+// anyway — passing it would read as "no pause" while doing the opposite.
+// With `maxAttempts:2` there is only ever ONE delay to compute (attempt 1),
+// so the default exponential backoff's own formula (`2**0 * 1000`, capped at
+// 30s) is a flat ~1s pause before the one retry — named here, not hidden
+// behind a knob that lies about what it does.
+const transportRetry = new Retry({ maxAttempts: TRANSPORT_MAX_ATTEMPTS, retryOn: isTransportFailure, timeout: 0 });
+
+/**
+ * Wrap a Loop provider's `generate` so a single transport-class throw (fetch
+ * itself throwing — no HTTP response was ever produced) gets ONE retry via
+ * `transportRetry`, and the outcome is reported once the retry is settled.
+ * Every other property of `baseProvider` (`.name`, `.model`, `.ownsCycle`,
+ * `.policy`) passes through unchanged — bare-agent's Loop reads those
+ * directly (src/loop.js).
+ *
+ * F64 carve-out: a wall-DERIVED timeout (bare-agent's own `ETIMEDOUT`/
+ * `EDEADLINE`, thrown because `clock.callTimeoutMs()` told the provider to
+ * cut the call — `isWallTimeout`, src/clock.js) is doctrine's governance
+ * stop, never a transport casualty, and retrying it would both mis-spend a
+ * round the operator's clock already ended and corrupt `categorize`'s own
+ * classification (which reads the SAME error a moment later). So the
+ * per-call `retryOn` here is `isTransportFailure(err) && !isWallTimeout(err,
+ * clock)` — the clock's verdict always wins over the transport shape.
+ *
+ * Scope note: this wraps the ONE seam that builds every worker Loop
+ * (scout/drafter/step-worker/fix-worker, planrun.js `newLoop` ~line 2240) —
+ * and ONLY its Loop-driven (anthropic-api-shaped) provider branch. The judge
+ * loops (src/judged.js), the native/CLI session path (this file, `mkWorker`'s
+ * NATIVE branch above `ask`/`askFrom`, AND the toolless native/claude-json
+ * branch of `newLoop`'s own `loopProvider` — a retried native session
+ * re-spends a subscription turn, a different failure/cost model entirely),
+ * and the authoring scout (src/authorscout.js) are each a distinct call site
+ * outside hamr's ruling and are deliberately left unwrapped.
+ * @param {any} baseProvider
+ * @param {string} phase
+ * @param {(type: string, data?: object) => any} emit
+ * @param {(s: string) => string} scrub
+ * @param {import('./clock.js').Clock} clock
+ */
+function withTransportRetry(baseProvider, phase, emit, scrub, clock) {
+  return new Proxy(baseProvider, {
+    get(target, prop, receiver) {
+      if (prop !== 'generate') return Reflect.get(target, prop, receiver);
+      return async (...args) => {
+        let attempts = 0;
+        let firstErr = null;
+        const fn = async () => {
+          attempts += 1;
+          try {
+            return await target.generate(...args);
+          } catch (err) {
+            if (attempts === 1) firstErr = err;
+            throw err;
+          }
+        };
+        // `recovered` is knowable only once the retried attempt has settled
+        // (succeeded or exhausted the budget) — emit exactly once, here,
+        // after the outcome is known, never speculatively before it.
+        const report = (recovered) => {
+          if (attempts <= 1) return; // no retry happened — nothing to report
+          const message = String(firstErr?.message ?? firstErr ?? '').slice(0, 200);
+          emit('transport-retry', { phase, attempt: 1, error: scrub(message), recovered });
+        };
+        try {
+          const result = await transportRetry.call(fn, { retryOn: (err) => isTransportFailure(err) && !isWallTimeout(err, clock) });
+          report(true);
+          return result;
+        } catch (err) {
+          report(false);
+          throw err;
+        }
+      };
+    },
+  });
+}
 const { createShellTools } = require('bare-agent/tools');
 
 /** the scout's hard round bound — read-only survey, never a worker (v1.12 §1) */
@@ -714,6 +806,14 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
 export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, maxStepRounds = 40, layerRoot = false, readShim = false, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null }) {
+  // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
+  // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
+  // worker) — one accumulator closed over by all of them, because the shim's ledger
+  // is deliberately per-worker (F-class reset boundary) while this readout is
+  // per-run. `wrapRead`'s call sites feed it via `onCount`; nothing here re-derives
+  // a count, it only sums what the shim already measured. Read, never written, by
+  // anything outside the `finally` below.
+  const memoryCacheCounts = { pointered: 0, capped: 0, bytesWithheld: 0 };
   workdir = resolve(workdir);
   // The read shim's ARM, resolved at the door — before the workdir is read, before
   // the scout, before a single token. An unrecognised spelling throws HERE, where
@@ -744,6 +844,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       throw new TypeError(`readShim: this arm caps reads, so a step granting "read" must also grant ${RETRIEVAL_PAIR.join(' and ')} — but the signed ceiling [${signedCeiling.join(', ')}] offers no ${short.join('/')}, so no legal plan exists and every draft would red as "read-blind". Re-sign the spec with ${short.join(' and ')}, or run with the shim off.`);
     }
   }
+  // MEMORY-CACHE's own `try`: everything from here on is a run that actually
+  // BEGAN (both $0 refusals above — the unknown-arm throw and the G1 throw —
+  // already happened and never touch this block), so `finally` below is the
+  // one place the accumulated counts are read out, no matter which of the
+  // paths below this point returns or throws.
+  try {
   // ONE spelling of the redaction, housed next to the inventory it reads
   // (src/validate.js) — the same helper the isolate verbs scrub the litectx store
   // with. Two hand-spelled copies of "what a secret looks like" is exactly how
@@ -1961,7 +2067,16 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // are one shim because the cap creates the second problem — its strategy line
     // sends a capped worker to ctx_recall/ctx_get for a whole function, and a stale
     // pointer there is the cap's own dead end, not litectx's.
-    const shim = createReadShim({ arm: shimArm });
+    const shim = createReadShim({
+      arm: shimArm,
+      // MEMORY-CACHE: this worker's shim reports into the RUN-level accumulator
+      // declared at the top of `runPlan` — one shim per worker, one sum per run.
+      onCount: (kind, bytes) => {
+        if (kind === 'pointered') memoryCacheCounts.pointered++;
+        else memoryCacheCounts.capped++;
+        memoryCacheCounts.bytesWithheld += bytes;
+      },
+    });
     const rdTool = shell.find((/** @type {{name: string}} */ t) => t.name === TOOL_BY_VERB.read);
     // F48: on native, bound shell_read below the CLI's tool-result display cap and hand back a
     // TRUSTED truncation notice steering to ctx_get — the CLI's own truncation blinds the worker
@@ -2111,9 +2226,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // claude-json TEXT path reports a real per-call cost that the Loop's
     // onLlmResult meters exactly like an API round, so the drafter's spend is
     // never invisible (F6/F44). The gate policy is wired but idle (no tools).
+    // F115's retry wraps ONLY the API-shaped branch — a native/claude-json session
+    // (below) has its own failure and cost model (a retried native session
+    // re-spends a subscription turn, not a metered fetch) and is out of scope.
     const loopProvider = native
       ? /** @type {any} */ (nativeProvider)({ policy, maxTurns, hasTools: false })
-      : (workerProvider ?? provider);
+      : withTransportRetry(workerProvider ?? provider, phase, emit, scrub, clock);
     // F66 — the stall watchdog. bare-agent's `timeoutMs` bounds socket INACTIVITY,
     // not call duration (provider-http.js `req.setTimeout` resets on every byte),
     // so a connection that stays alive while producing nothing is invisible to it:
@@ -3490,4 +3608,23 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
   // the verdict was arrived at.
   if (fixOutcome === 'green') await emitReviewDoor('green', lastCloseVerdict);
   return fixOutcome === 'green' ? 'green' : 'escalated';
+  } finally {
+    // Emitted on EVERY exit (return or throw) — `finally` fires exactly once,
+    // right before this call returns to `runJob`, which is where every other
+    // caller's `job-end` lands next. Armed-only: an unarmed run leaves no trace
+    // (absence reported as absence, never a fabricated zero line, PRD antigen).
+    // No cost fields — this is not a spend record and spend-slicing instruments
+    // are unaffected by it (F6/F12's ACCOUNTED_ROUND_TYPES list is untouched).
+    if (readShimArm(readShim).on) {
+      emit('memory-cache', {
+        pointered: memoryCacheCounts.pointered,
+        capped: memoryCacheCounts.capped,
+        bytesWithheld: memoryCacheCounts.bytesWithheld,
+        // bytes→tokens is an ESTIMATE (÷4, the same rough conversion used
+        // elsewhere) — the field is named `approx…` so no consumer reads it
+        // as measured the way `bytesWithheld` itself is.
+        approxTokens: Math.round(memoryCacheCounts.bytesWithheld / 4),
+      });
+    }
+  }
 }