bareloop 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [Unreleased]
+
+## [0.14.0] — 2026-08-25
+
+### Added
+
+- **One transport-class retry** (F115, hamr's ruling): the ONE worker-Loop seam in
+  `src/planrun.js` now retries exactly once on a transport-only throw (TLS fault,
+  `ECONNRESET`/`EPIPE`/`ETIMEDOUT`, `fetch failed` over a network cause — never an HTTP
+  4xx/5xx/429 response), classified by the new `src/transport.js` (`isTransportFailure`,
+  fixed `TRANSPORT_MAX_ATTEMPTS`, never operator-configurable). Emits a report-only
+  `transport-retry` spine record and forces `job-end.spendComplete: false` for the rest of the
+  run — the retried attempt's first throw may already have been billed — surfaced by
+  `scripts/run-u.mjs` as a `retries` line only when a retry occurred.
+- **provider-red joins the resumable set** (F115, PRD v1.80 TODO #4): when the one transport
+  retry also fails and a `run-u` run ends `provider-red`, its tail now prints an honest
+  readout — spend so far as a floor, "died in step X of Y" (or "before a plan was accepted"),
+  and the exact `--resume` command — and `--resume` re-enters at the recorded step with the
+  accepted plan, folding prior spend in. No cost/step threshold gates the offer (the operator
+  decides, every time); verdict terminals (`escalated`/`step-red`/`plan-red`) still refuse.
+  Folded from a local `scripts/run-u.mjs` widening into the library's own canonical
+  `CHECKPOINT_OUTCOMES` (`src/reuse.js`) so the two lists cannot drift.
+- **Run behaviour summary** (build-list item 2, agreed 2026-08-23): `runBehaviour(events, {
+  runId? })` and `formatBehaviour(summary)` in `src/behaviour.js`, plus
+  `scripts/behaviour-readout.mjs <gate-audit.jsonl> [run_id]`. A report-only text block —
+  "94 tool calls · 61 read, 28 grep, 5 recall" / "17 exact repeats (~18%)" — computed entirely
+  from a run's own gate-audit JSONL. Gates nothing, changes no verdict, writes nothing to the
+  spine. The exact-repeat key is the full recorded action (`type` + `path` + every `args` key),
+  never collapsed to `{type, path}` — sharper collapse would have merged different byte ranges
+  of the same file into false repeats.
+- **`memory-cache` end-of-run readout** for the read shim: `runPlan` emits one spine record
+  (`{pointered, capped, bytesWithheld, approxTokens}`) summing what L1's pointer and L4's cap
+  withheld across the whole run, only when the shim is armed. `scripts/run-u.mjs` prints it as
+  `MEMORY-CACHE  N re-reads answered from memory · M reads capped · X KB withheld (~Tk tokens
+  not re-sent)`; `scripts/behaviour-readout.mjs` prints the same line given the run's spine as
+  an optional third positional. No cost fields — report-only, not a spend record.
+
+### Fixed
+
+- **`scripts/readshim-battery.mjs`'s spend reader compared a resumed leg's own money against
+  the wrong job-end figure** (F116): `readSpend`'s `ledgerUsd` now reads
+  `job-end.engagementSpentUsd` (this leg's spend) when a spine carries one, falling back to
+  `job-end.spentUsd` only for a cold run — `spentUsd` on a resumed job-end is a CHAIN total,
+  not this spine's own spend. `chainUsd`/`priorUsd` are exposed as new, honest fields and never
+  folded into `accountedUsd`/`ledgerUsd`/`spendUsd`.
+
 ## [0.13.0] — 2026-08-23
 
 ### Fixed (2026-08-23 — the release round: a pointer that lied, a close with no home, a rule that charged for its own refusal)

package/README.md

@@ -162,7 +162,7 @@ package, and gaps get fixed upstream rather than shimmed.
 bareloop is the productization of **[adaptlearn](https://github.com/hamr0/adaptlearn)**, a
 closed experimental record on whether agent-authored workflows improve under an honest gate.
 The design laws it inherited, and the open questions it has not answered yet, are in
-[`docs/01-product/PRD.md`](docs/01-product/PRD.md).
+[`docs/product/PRD.md`](docs/product/PRD.md).
 
 ## License
 

package/bareloop.context.md

@@ -26,7 +26,7 @@
 > where `hitl` IS admitted, `human-confirms` IS live, and the three `hitl-*` terminals exist —
 > integrate against what is written here, and expect the class-level rename when the next rung
 > lands. Records: PRD Addendum v1.71 and
-> `docs/02-features/2026-08-17-softgreen-review-door-design.md` (repo-only, not shipped);
+> `docs/product/2026-08-17-softgreen-review-door-design.md` (repo-only, not shipped);
 > evidence F102–F105.
 
 ## What this is
@@ -1093,13 +1093,25 @@ raises it.
 of PRICED rounds ONLY — never an estimate from token counts or averages (cap-not-estimate) —
 and it is stated even on the pre-token reds, where the honest figure is a real `0`.
 `spendComplete` says whether that figure is EXACT; `false` means `spentUsd` is a FLOOR ("at
-least $X", true total unknowable) and must not be read as a total. Four things set it, all
+least $X", true total unknowable) and must not be read as a total. Five things set it, all
 the same class — a call whose cost is unknowable from here: a round that came back unpriced
 (F6); a run that ABSORBED a stall, because the fuse's silent reissue may pay twice for one
 answer and the flag is one-way whatever the outcome; a `wall-halt` that cut a call
-mid-flight (`cutMidCall`); and a RESUME whose fold was itself a floor
+mid-flight (`cutMidCall`); a RESUME whose fold was itself a floor
 (`priorSpendComplete: false` — an unknown does not heal by being carried forward, so every
-round of this attempt being priced repairs nothing about the one before it). A wall stop read BETWEEN iterations or steps has no call in flight,
+round of this attempt being priced repairs nothing about the one before it); and a
+**transport retry** (F115, hamr's ruling: "one retry for transport layer failure and
+reporting with the rest end of gate"). Every worker Loop (scout, drafter, each step, the fix
+worker — the ONE seam in `planrun.js`) gets exactly ONE extra attempt, and only for a
+transport-class throw — fetch itself throwing with no HTTP response at all (a TLS fault,
+`ECONNRESET`/`EPIPE`/`ETIMEDOUT`, `fetch failed` wrapping a network cause); an HTTP response
+(4xx/5xx/429) is never retried here and rides bare-agent's own unchanged policy. The budget is
+fixed (`TRANSPORT_MAX_ATTEMPTS` in `src/transport.js`) — never a job-spec or CLI knob, tighten-only
+doctrine. Each retry emits a report-only `transport-retry` spine record (`{phase, attempt, error,
+recovered}`, no cost field — the ledger is unaffected); the FIRST attempt threw before any usage
+figure came back, so **any** transport retry floors `spendComplete` for the rest of the run even
+when the retry recovers and the run finishes green — the same one-way flag class as `stalled`
+and `cutMidCall`. A wall stop read BETWEEN iterations or steps has no call in flight,
 so it stays exact. Both fields are present on all outcomes, so a consumer never branches on
 field presence and never has to launder a missing `spentUsd` into `$0`.
 
@@ -2084,6 +2096,52 @@ $0). `VOUCHED_RATE_SOURCES` is the frozen allow-list they key on. **Reporting on
 no class, no halt. CLI lands at N5; the
 panel reads the same file at N6.
 
+### `runBehaviour(events, { runId? })` / `formatBehaviour(summary)` — `src/behaviour.js`
+
+Build-list item 2 (agreed 2026-08-23): one report-only text block summarizing what a run
+DID with its tools, computed entirely from the run's own gate-audit JSONL. **Gates nothing,
+changes no verdict, writes NOTHING to the spine** — a pure function over records that already
+exist, same posture as `spendProvenance` above. `runBehaviour` counts and returns the summary
+object; `formatBehaviour` renders it as the printed block:
+
+```
+94 tool calls · 61 read, 28 grep, 5 recall
+17 exact repeats (~18%)
+```
+
+`llm` action rows are provider rounds, not tool calls, and are always excluded; only
+`decision: 'allow'` rows count toward the total (a `deny` is tallied separately as `N denied`,
+shown only when nonzero). **The exact-repeat key is the FULL recorded action — `type` + `path`
++ every key of `args`** (sorted, stably serialized), never collapsed to `{type, path}`: if the
+gate ever starts recording byte ranges or offsets, two different slices of one file must not
+read as the same repeated call. Repeat detection is therefore exactly as sharp as what the gate
+records, no sharper — a tool that reads identical bytes through two differently-shaped argument
+objects will not be caught by this. `scripts/behaviour-readout.mjs <gate-audit.jsonl> [run_id]`
+prints the block for one run or every run_id found in the file, skipping malformed lines with
+a count rather than throwing.
+
+```js
+import { runBehaviour, formatBehaviour } from 'bareloop';
+const events = fs.readFileSync(auditFile, 'utf8').trim().split('\n').map(JSON.parse);
+console.log(formatBehaviour(runBehaviour(events, { runId })));
+```
+
+#### `memory-cache` — the read shim's own end-of-run readout (`src/readshim.js`, `src/planrun.js`)
+
+A single spine record, emitted once by `runPlan` right before it returns (so it lands on the
+spine before the caller's `job-end`), reporting what the READ SHIM (L1 pointer + L4 cap) saved
+this run: `{pointered, capped, bytesWithheld, approxTokens}`. `pointered` counts re-reads of
+unchanged content answered with a pointer instead of the bytes; `capped` counts reads served as
+a bounded slice; `bytesWithheld` sums exactly the bytes NOT re-sent in both cases (never
+estimated) — the diff lever (L2) isn't counted, it's a different response shape. `approxTokens`
+is `Math.round(bytesWithheld / 4)`, a bytes→tokens ESTIMATE named accordingly so nothing reads
+it as measured. **Emitted only when the shim is armed** (any `readShim` arm but the off one) —
+an unarmed run emits no record at all, never a fabricated zero. It carries no cost fields, so it
+is not a spend record and no spend-slicing instrument needs to account for it.
+`scripts/run-u.mjs` prints it as a `MEMORY-CACHE` line right after `BEHAVIOUR` when armed
+(`no record` if the run ended before the summary could fire); `scripts/behaviour-readout.mjs`
+prints the same line when handed the run's spine file as its optional third positional.
+
 ## Architecture
 
 Three layers. An **outer shell** (dumb, permanent): per-run budget cap via bareguard,
@@ -2115,7 +2173,7 @@ is disclosed to the authoring agent; only admitted verbs are callable per job.
 ## Gotchas
 
 *TBD from real adopter friction; recorded here as they're found (repo-side friction goes
-to `docs/FINDINGS.md`).*
+to `docs/logs/FINDINGS.md`).*
 
 ## Constraints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build:types"
   },
   "dependencies": {
-    "bare-agent": "^0.36.0",
+    "bare-agent": "^0.39.0",
     "bareguard": "^0.13.0",
     "litectx": "^0.32.0"
   },

package/src/behaviour.js

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

package/src/bridges.js

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

package/src/calibrate.js

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

package/src/cardauthor.js

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

package/src/index.js

@@ -228,6 +228,11 @@ export {
   HUMAN_PAUSE, HITL_PAUSE, HITL_DECISION_RED, HUMAN_CHECKPOINTS,
 } from './declaredclose.js';
 export { closeStagesOf } from './plan.js';
+// Build-list item 2 (2026-08-23) — the run behaviour summary: a report-only
+// read of a run's gate-audit records. Gates nothing, mints no verdict,
+// writes nothing to the spine; `runBehaviour` computes, `formatBehaviour`
+// renders the printable block.
+export { runBehaviour, formatBehaviour } from './behaviour.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.
 // `prepareSigning` returns the resolved spec's HASH and the seed evidence; it
 // never signs — the approvals array and the human's word are unchanged.

package/src/job.js

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

package/src/judged.js

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

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.

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),
+      });
+    }
+  }
 }

package/src/readshim.js

@@ -332,13 +332,18 @@ const stalePastEofNotice = (path, startLine, endLine, lines, detail) =>
  * 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.
+ * @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 = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
+export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL, onCount = null } = {}) {
   /** path → what the worker has been handed of the CURRENT content. `full` is
    * the delivered text itself, kept ONLY while the worker holds the whole file
    * (null otherwise) because that is the only state a diff is legal from.
@@ -354,6 +359,22 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
    * @type {Map<string, {hash: string, total: number, delivered: number, full: string|null}>} */
   const ledger = new Map();
 
+  // MEMORY-CACHE counters (this worker's own ledger, summed by a caller across
+  // workers for a run-level readout — see `onCount` above). Counted only where
+  // it is EXACT, never estimated: a pointer withholds exactly `total` bytes (the
+  // whole delivery it replaces) and a capped slice withholds exactly `total - end`
+  // (the tail this call did not send) — both numbers the ledger already computes
+  // for its own bookkeeping below, read here rather than re-derived.
+  let pointered = 0;
+  let capped = 0;
+  let bytesWithheld = 0;
+  /** @param {'pointered'|'capped'} kind @param {number} bytes */
+  const count = (kind, bytes) => {
+    if (kind === 'pointered') pointered++; else capped++;
+    bytesWithheld += bytes;
+    if (onCount) onCount(kind, bytes);
+  };
+
   /**
    * THE STALE-POINTER SERVE. When `ctx_get` throws `StalePointerError` — the file
    * changed on disk after indexing — hand back the REQUESTED LINE RANGE read
@@ -510,6 +531,9 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
       // slice path and is delivered (as nothing) truthfully.
       if (arm.pointer && seen && seen.hash === hash && start >= total) {
         ledger.set(path, { hash, total, delivered: total, full: r });
+        // Withheld = the whole delivery this pointer replaces: `total` bytes the
+        // worker asked to be re-sent and was not, because it already holds them.
+        count('pointered', total);
         return pointer(path, total);
       }
       ledger.set(path, { hash, total, delivered: end, full: end === total ? r : null });
@@ -518,12 +542,20 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL } = {}) {
       // no notice, no reframing. That is the overwhelming majority of reads, and
       // it keeps the shim invisible where it buys nothing.
       if (start === 0 && end === total) return slice;
+      // Withheld = the tail beyond this slice (`total - end`), not the slice
+      // itself — the slice IS what was sent; the remainder is what was not.
+      if (end < total) count('capped', total - end);
       return slice + (end < total ? capNotice(start, end, total) : doneNotice(start, total));
     };
     return tool;
   };
 
-  return { arm, cap, wrapRead, serveStale };
+  /** MEMORY-CACHE: this worker's own counts, exact — never re-derived, never
+   * estimated. `bytesWithheld` sums only the `pointered`/`capped` cases above;
+   * the diff lever (L2) is a different response shape and is not counted here. */
+  const summary = () => ({ pointered, capped, bytesWithheld });
+
+  return { arm, cap, wrapRead, serveStale, summary };
 }
 
 /**

package/src/reuse.js

@@ -1,5 +1,5 @@
 // Layer 3 — the D7 ENVELOPE and the REUSE RUNNER (design record
-// docs/02-features/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
+// docs/product/2026-08-01-layer-3-reuse-design.md, D3/D5/D6/D7 + R1).
 //
 // hamr's sentence is the whole specification of this file, verbatim:
 //
@@ -115,8 +115,30 @@ export const REUSE_GRADED_RED = Object.freeze(['escalated']);
  * how they would come to disagree about which member is which: the first three are
  * allowances the loop's remaining tries are meant to spend against, and the human
  * ones are the stop no further try can change (see `hardStop`).
+ *
+ * `provider-red` folded in 2026-08-25 (PRD v1.80 TODO #4, F115 "Ruled: one transport
+ * retry"; hamr's ruling verbatim: *"joins resume anyways and you decide but you are
+ * given an honest readout and with 1 retry"*). It is a MACHINE halt, not a human one
+ * — it does NOT go into `HUMAN_CHECKPOINTS` — but it is a checkpoint by the same
+ * test every other member here passes: the close never got the say it was asked
+ * for (no verdict was rendered, so it is not a graded red — see `REUSE_GRADED_RED`
+ * above), and the scout+draft and every finished step it bought stand on disk
+ * exactly like a cap-halt or a wall-halt. The one transport retry
+ * (`src/planrun.js`'s `withTransportRetry`) already covers the common case; when
+ * that retry ALSO fails, throwing the run away because the transport hiccuped
+ * twice is throwing away real work for no reason a machine can judge. Deliberately
+ * NO cost/step threshold gates this: a threshold is a number picked from a small
+ * observed sample (F115 logged exactly 7 rows), which is arbiter territory
+ * reserved for hamr — the operator decides case by case, every time, off the
+ * honest readout `scripts/run-u.mjs` prints.
+ *
+ * This entry was built 2026-08-24 as a LOCAL widening in `scripts/run-u.mjs`
+ * (`RESUMABLE_HALTS = [...CHECKPOINT_OUTCOMES, 'provider-red']`) because this file
+ * sat outside that pass's scope — the fold here is the follow-up, so this repo
+ * does not end up with two lists that can drift, which is the exact failure this
+ * constant exists to end (see the paragraph above).
  */
-export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', ...HUMAN_CHECKPOINTS]);
+export const CHECKPOINT_OUTCOMES = Object.freeze(['cap-halt', 'wall-halt', 'step-stalled', 'provider-red', ...HUMAN_CHECKPOINTS]);
 
 /**
  * v1's definition of "the same KIND of recipe" — and it is the LOAD GATE's own: the

package/src/root.js

@@ -1,5 +1,5 @@
 // Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
-// docs/02-features/2026-07-19-layer-r-design.md). One state that survives attempts
+// docs/product/2026-07-19-layer-r-design.md). One state that survives attempts
 // inside ONE run so a never-green run stops repeating itself (F21). Role is
 // CONTINUITY ONLY — F39 measured that hand-delivered state buys no conversion;
 // the semantic converter is Layer 2's job, not this module's.

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
@@ -254,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
@@ -263,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(),
@@ -364,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 = () => {

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

@@ -22,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/readshim.d.ts

@@ -36,15 +36,21 @@ export function readShimStrategy(arm: ReadShimArm): string;
  * 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.
+ * @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 }?: {
+export function createReadShim({ cap, arm, onCount }?: {
     cap?: number;
     arm?: ReadShimArm;
+    onCount?: ((kind: "pointered" | "capped", bytesWithheld: number) => void) | null;
 }): {
     arm: ReadShimArm;
     cap: number;
@@ -56,6 +62,11 @@ export function createReadShim({ cap, arm }?: {
         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

package/types/reuse.d.ts

@@ -589,6 +589,28 @@ export const REUSE_GRADED_RED: readonly string[];
  * how they would come to disagree about which member is which: the first three are
  * allowances the loop's remaining tries are meant to spend against, and the human
  * ones are the stop no further try can change (see `hardStop`).
+ *
+ * `provider-red` folded in 2026-08-25 (PRD v1.80 TODO #4, F115 "Ruled: one transport
+ * retry"; hamr's ruling verbatim: *"joins resume anyways and you decide but you are
+ * given an honest readout and with 1 retry"*). It is a MACHINE halt, not a human one
+ * — it does NOT go into `HUMAN_CHECKPOINTS` — but it is a checkpoint by the same
+ * test every other member here passes: the close never got the say it was asked
+ * for (no verdict was rendered, so it is not a graded red — see `REUSE_GRADED_RED`
+ * above), and the scout+draft and every finished step it bought stand on disk
+ * exactly like a cap-halt or a wall-halt. The one transport retry
+ * (`src/planrun.js`'s `withTransportRetry`) already covers the common case; when
+ * that retry ALSO fails, throwing the run away because the transport hiccuped
+ * twice is throwing away real work for no reason a machine can judge. Deliberately
+ * NO cost/step threshold gates this: a threshold is a number picked from a small
+ * observed sample (F115 logged exactly 7 rows), which is arbiter territory
+ * reserved for hamr — the operator decides case by case, every time, off the
+ * honest readout `scripts/run-u.mjs` prints.
+ *
+ * This entry was built 2026-08-24 as a LOCAL widening in `scripts/run-u.mjs`
+ * (`RESUMABLE_HALTS = [...CHECKPOINT_OUTCOMES, 'provider-red']`) because this file
+ * sat outside that pass's scope — the fold here is the follow-up, so this repo
+ * does not end up with two lists that can drift, which is the exact failure this
+ * constant exists to end (see the paragraph above).
  */
 export const CHECKPOINT_OUTCOMES: readonly string[];
 /**

package/types/transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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: any): boolean;
+/** 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: number;