bareloop 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,89 @@ 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.4.0] — 2026-07-21
+
+### Added
+
+- **Layer R — the root, the within-run ratchet (`src/root.js`; design record
+  `docs/plans/2026-07-19-layer-r-design.md`, interview-locked 2026-07-19).** The shell
+  mechanically detects fixation — consecutive attempts rewriting the same file(s)
+  without moving the close's kept-failure set — and injects an escalating note into the
+  next attempt's prompt: a capped summary first, then the worker's own prior failed
+  edit content verbatim (the BA-14 rejected-edit-buffer shape, rewritten for our
+  attempt loop). Fixation-gated (inert when not stuck — RSI §3.3: the lift is a
+  fixation phenomenon, an honest null on a strong unstuck model), shell-authored (the
+  worker authors nothing, gains no verb), within-run only (state dies with the run;
+  inheritance stays verdict-gated). Red-set comparison strips the spec-reporter's
+  per-run duration stamps (POC-measured: kept lines are never byte-stable) —
+  comparison-only, the delivered gap is untouched. Spine event `root-injected` carries
+  stage/mode/streak/paths, never content (append-only law). Ships **OFF by default**
+  (`layerRoot: false` on `runJob`/`interpret`; pass `true` for the ON/experimental arm) —
+  decided 2026-07-21: fixation is extinct on every current job (F41), so ON has never won
+  its own A/B; the default flip to `true` defers to the first Layer 2 job that produces
+  natural fixation (see `docs/01-product/LAYERS.md` Layer R note).
+
+### Fixed
+
+- **F44 — fresh whole-branch review: three correctness bugs + cleanups, all validated and
+  mutation-proven.** (1) A casualty job-end laundered unknown spend as complete: `1b0720c`
+  put `spentUsd` on every path, so a provider-red TRANSPORT THROW reported
+  `spendComplete: true` (F6 violation — the failed call's cost is unknown) and the battery
+  scripts' `spentUsd == null` casualty-STOP never fired. Fixed both sides: the transport
+  provider-red now reports `spendComplete: false` (the metered draft-truncation keeps
+  `true`), and the frozen battery/probe scripts key their STOP on
+  `spendComplete === false || spentUsd == null`. (2) Layer R's outcome probe mislabeled a
+  missed-anchor edit as "landed" when its `newText` appeared elsewhere (substring
+  false-positive) — now discriminated by the tool result, exact-equality for writes, one
+  read not two. (3) Layer R false-fired on a progressing text-mode worker with no gapKeep
+  (write-overlap is constant-true when the single target is rewritten every attempt) — a
+  `writesInformative` flag now requires a known-unmoved red-set when writes carry no
+  information. Cleanups: double redaction, unbounded `attempts` retention, a dead ternary.
+  (2) and (3) are latent behind the OFF-by-default `layerRoot`.
+
+- **Layer R settled its note on the gate's allow, which is written BEFORE the tool runs
+  (F43).** An `allow` record states INTENT, never that bytes reached a file:
+  `shell_edit` returns an anchor miss as a refusal *result* and a byte-cap overflow as a
+  throw, both leaving the file untouched with the allow already on the audit. The
+  verbatim note could therefore present content to the worker as "your own previous
+  changes — they landed" while that text was provably absent from the file it named
+  (reproduced end-to-end: 3 allowed edits, 0 bytes changed). Fixed by splitting the two
+  axes rather than merging them — the DETECTOR keeps reading intent (an edit that never
+  applied is still repetition; a tree-diff detector measured blind to it on every
+  attempt), while the NOTE settles on the observed file through `Loop`'s
+  `onToolResult` seam. An unapplied repeat now names the missed anchor instead, which is
+  the mechanical gap genre (F38). `commitWrite` is replaced by `settleWrite(landed)`.
+- **Guarded the `maxTurns` LLM-round invariant (F43 follow-up).** bareguard's `maxTurns`
+  ticks on every `gate.record`; our cap means "LLM rounds" only because the sole record
+  path is the LLM one (tool calls take `gate.check`, which does not tick). That was
+  correct but unguarded — wiring tool results into `gate.record` would silently halve the
+  LLM budget (the F37 lower-silent-ceiling class). Added a guard test pinning "every
+  `gate.record` is `type:llm`" (mutation-proven: wiring tool records turns it red) and a
+  config comment marking the invariant load-bearing. No behavior change; no upstream ask —
+  bareguard already offers the correct counters.
+- **F41 — the disposition: armed-and-inert, field read deferred.** Before any ON/OFF
+  battery spent money, two cheap reads measured the disease's base rate: the archive
+  sweep (`poc/layer-r-base-rate.mjs`, $0 — every surviving spine is OFF-arm by
+  construction) read 0 fixated in 10 pairs on jobs #2/#4; two frozen probes on a
+  rebuilt job #1 patient (`scripts/run-probe-layer-r.mjs`, $10.12 total) read 0
+  fixated in 4 pairs — including against a three-plant tree (three subsystems, one fix
+  cannot green) that forced a full 8→4→green ladder across three judged attempts.
+  Every pair was healthy navigation. F21's fixation was a broken-loop symptom, cured
+  by the F20/F21/F30/BA-13 fixes. Because ON has therefore never won its own A/B,
+  Layer R ships **OFF by default** (decided 2026-07-21; `layerRoot: true` is the ON
+  arm) — measured cost-free when enabled and healthy (zero injections across all
+  probe runs); the repetition-drop ON/OFF read, and the default-flip decision, defer
+  to the first run whose spine records `root-injected`. No learning claim is minted.
+
+### Changed
+
+- **`jobs/litectx-maintainer.json` `budgetUsd` 1.5 → 4.5** (probe 2, re-signed): $1.50
+  funded exactly ONE judged attempt on the real patient — a run could red at attempt 1
+  and die at the gate mid-attempt-2, structurally unable to produce across-attempt
+  evidence. The advertised budget must fund the attempts the cap promises.
+
 ## [0.3.0] — 2026-07-19
 
 ### Fixed

package/README.md

@@ -13,7 +13,7 @@
 <p align="center">
   <img src="https://img.shields.io/github/package-json/v/hamr0/bareloop?label=version&color=2a4f8c" alt="version (auto from package.json)">
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
-  <img src="https://img.shields.io/badge/status-N2%20%C2%B7%20headless%20loop-2a6d3a" alt="status: N2, headless loop">
+  <img src="https://img.shields.io/badge/status-Layer%20R%20%C2%B7%20ratchet%20armed-2a6d3a" alt="status: Layer R, ratchet armed">
 </p>
 
 **"Automate this job — I don't know the best workflow."** For tasks that are **repeated,
@@ -25,10 +25,15 @@ inheritance with ledger-counted attribution.
 The pitch in one line: **workflows that earn their own design, with receipts** — every
 inherited rule carries the green that minted it and the contrast that attributed it.
 
-> **Status: N2 — the headless loop is real.** `runJob()` takes a signed job spec through
-> draft → per-step worker loops → close verdicts → draft PR, under one budget the agent
-> can only tighten. Rungs N0–N2 have landed (roadmap below); next is executed
-> inheritance (N3), where the ladder's kill-switch question gets its answer.
+> **Status: Layer R — the within-run ratchet is built and armed.** `runJob()` takes a
+> signed job spec through draft → per-step worker loops → close verdicts → draft PR,
+> under one budget the agent can only tighten; the shell now also detects a worker
+> stuck repeating itself and feeds back its own failed attempts (escalating
+> summary→verbatim). Two frozen probes found the disease in remission under the current
+> loop (F41: 0 fixated pairs in 14, jobs #1/#2/#4), so the ratchet ships inert-by-
+> measurement with its field read deferred to the first run that trips it. Next is
+> Layer 2 (plan-v1 micro-wheels), then executed inheritance (N3) — the ladder's
+> kill-switch question.
 
 ## Quick start
 
@@ -98,6 +103,8 @@ ladder, and the stop is a result.
 | **N0** ✅ | Port + outer shell + spine (token-free) — v0.1.0 |
 | **N1** ✅ | Job/close schema + validator — v0.2.0 |
 | **N2** ✅ | Single-job headless loop — job #1 minimal (review→fix→PR, hard greens only) — v0.3.0 |
+| **Layer R** ✅ | Within-run ratchet: shell-side fixation detector (intent) + rejected-edit feedback (outcome), **shipped OFF by default** (F41: fixation in remission, so ON has never won its A/B; F43 split the two axes; field read + default decision defer to Layer 2) — v0.4.0 |
+| **Layer 2** | plan-v1 micro-wheels — the road: bounded steps with in-run verifiable exits (the F39-measured semantic converter) |
 | **N3** | Executed inheritance + contrast-bit extractor — **kill-switch: rules must transmit across non-identical runs** |
 | **N4** | Verdict classes complete (soft/HITL minting) |
 | **N5** | Scheduler + budget ops |

package/bareloop.context.md

@@ -285,7 +285,32 @@ the close judges the tree; on-green `remember` retains the worker's change summa
 Worker-caused close crashes feed back as `worker-crash` gaps via the gate audit (F32 —
 see `ralph` above).
 
-### `runJob(spec, { approvals, workdir, provider, emit, target?, capRuns?, shellCapUsd?, closeTimeoutMs?, execCmd? })` → outcome — `src/run.js`
+**Layer R — the within-run ratchet (`layerRoot`, default `false`; design record
+2026-07-19).** The shell mechanically detects fixation across attempts — consecutive
+attempts that rewrote the same file(s) without moving the close's kept-failure set
+(`closeGapKeep` lines, duration stamps stripped before comparing; without a gapKeep the
+detector degrades to write-overlap alone and the spine event names the mode) — and
+injects an escalating note into the next prompt: first a capped summary naming the
+repeated files, then (if still stuck) the worker's OWN prior failed edit content
+verbatim, scrubbed and capped with trims announced. Inert unless stuck; the worker
+authors nothing and gains no verb. Two axes, deliberately separate (F43): the DETECTOR
+reads INTENT (the gate audit's allow-set — an edit whose anchor missed is still the
+worker reaching for that file again, and a tree-diff detector measured blind to exactly
+that), while the NOTE's claims about file contents read OUTCOME (settled post-execution
+through `Loop`'s `onToolResult`). So a repeat that never applied is told its anchor
+missed, and only content actually in the file is ever described as having landed. Spine event `root-injected` carries
+`{stage, mode, streak, paths, redSetSize}` — counts and paths only, NEVER content (the
+spine is append-only). State dies with the run: this is within-run scratch, not
+across-run memory. `layerRoot: true` (on `interpret` and `runJob`) is the ON/experimental
+arm; the default is OFF. Status (F41): the ratchet is MEASURED inert on every current
+job — two frozen probes + an archive sweep read 0 fixated pairs in 14 (the F21 repetition
+disease was a broken-loop symptom, since cured). Because ON has therefore never won its
+own A/B, it ships **OFF by default (decided 2026-07-21)** — armed and correct, but not
+default-enabled until a stuck job (Layer 2, or a manufactured-fixation probe) shows ON
+beats OFF. Flip the default to `true` the day that evidence lands; a `root-injected` event
+on your spine (when you pass `layerRoot: true`) is a signal worth reading, not noise.
+
+### `runJob(spec, { approvals, workdir, provider, emit, target?, capRuns?, shellCapUsd?, closeTimeoutMs?, execCmd?, layerRoot? })` → outcome — `src/run.js`
 
 The N2 runner — the shell's top layer; composes everything below it and interprets
 nothing itself. Sequence: **approval gate** (human-signs-always — refuses an unapproved
@@ -312,7 +337,15 @@ round the API cut off mid-generation (`truncated:max_tokens`, bare-agent 0.27.0/
 before which it laundered into a clean finish, F25); in both cases no verdict exists and the
 failed round's spend is only partly known (F6). `cap-halt` is drafting spend consuming the whole job budget before a
 valid config existed. Both are decision-ready escalations with a terminal `job-end`:
-the spine never dangles. A text-mode job invoked without `opts.target` is a `job-red`
+the spine never dangles. **Every `job-end` carries the money, on every path**:
+`{ outcome, spentUsd, spendComplete }` (plus `step`/`cause`/`detail` where the outcome has
+them). `spentUsd` is the accumulated sum 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 one or more rounds came back unpriced (F6), so `spentUsd` is a FLOOR
+("at least $X", true total unknowable) and must not be read as a total. 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`. A text-mode job invoked without `opts.target` is a `job-red`
 before ANY provider call (and `interpret` itself throws a TypeError for direct
 callers) — reds-before-tokens applies to the call, not just the spec.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",

package/src/interpret.js

@@ -12,12 +12,14 @@
 
 import { createRequire } from 'node:module';
 import { writeFileSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { Gate, redact } from 'bareguard';
 import { LiteCtx, compress } from 'litectx';
 import { validateConfig, diffPaths, globToPrefix, SECRET_PATTERNS } from './validate.js';
 import { ralph } from './ralph.js';
+import { createRoot } from './root.js';
 
 /** @typedef {Error & {category?: string, lib?: string}} CategorizedError the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose) */
 
@@ -213,11 +215,18 @@ const toolAction = (name, args, workdir) => {
  * @param {'text'|'tools'} [opts.mode] middle mode (2b): 'text' (default) writes the ONE
  *        target from the response artifact; 'tools' gives the worker Gate-governed file
  *        tools — SPEC-side territory (the step declares it; the config cannot express it)
+ * @param {boolean} [opts.layerRoot=false] Layer R (the within-run ratchet, src/root.js):
+ *        shell-assembled fixation detection over the run's own books, injecting an
+ *        escalating summary→verbatim note when consecutive attempts rewrite the same
+ *        files without moving the reds. Inert when the worker is not stuck (RSI §3.3).
+ *        Defaults OFF (decided 2026-07-21): fixation is extinct on every current job
+ *        (F41), so ON is unproven — the field read defers to Layer 2. `true` is the
+ *        ON/experimental arm; never a worker-visible knob
  * @param {string[]} [opts.tools] the spec's tool grant (subset of read|grep|write,
  *        job-v1 validated); defaults to the full menu in tool mode
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, jobWriteScope, revisor, closeTimeoutMs, mode = 'text', tools, closeState, closeExpect, closeJudged, closeGapKeep }) {
+export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, jobWriteScope, revisor, closeTimeoutMs, mode = 'text', tools, closeState, closeExpect, closeJudged, closeGapKeep, layerRoot = false }) {
   // Reds-before-tokens: text mode writes ONE artifact — a missing target is a
   // caller bug that must be loud NOW, not a TypeError after a paid worker call
   // that ralph would misfile as interpreter-red (the gate skips an absent path,
@@ -279,7 +288,17 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
         : {}),
     },
     budget: { maxCostUsd: config.gate.budgetUsd },
-    // text mode is ~1-2 rounds per attempt; tool mode is N rounds (read→write→…)
+    // text mode is ~1-2 rounds per attempt; tool mode is N rounds (read→write→…).
+    // maxTurns ticks on every gate.RECORD (bareguard limits.js:88), and this
+    // number means "LLM rounds" ONLY because the sole record path is the LLM one
+    // (onLlmResult → gate.record{type:'llm'}); tool calls take gate.CHECK, which
+    // does not tick. That invariant is load-bearing: wiring wireGate's own
+    // onToolResult into gate.record would silently start ticking maxTurns on
+    // tools and halve the LLM budget (the F37 lower-silent-ceiling class). It is
+    // pinned by the "every record is type:llm" guard test — do not wire tool
+    // records without switching this bound (bareguard offers no llm-only counter;
+    // it has maxTurns=all and maxToolRounds=tools-only, neither of which is
+    // llm-only once tools also record). Cap semantics are arbiter territory.
     limits: { maxTurns: TURNS_PER_ATTEMPT * (capRuns + 1) },
     audit: { path: join(workdir, 'gate-audit.jsonl') },
     humanChannel: async () => ({ decision: 'terminate' }), // no human mid-run: a tripped cap terminates → decision-ready escalation
@@ -294,6 +313,13 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
   // exactly as it did before F32 — attribution can only ADD a recovery path, never
   // swallow an instrument stop.
   const auditPath = join(workdir, 'gate-audit.jsonl');
+  // NOTE (Finding 4, deferred): this re-reads and re-parses the whole audit each
+  // call. That is O(1) reads when Layer R is OFF (called only at the rare crashed
+  // verdict), but O(attempts) when Layer R is ON, and the audit can accumulate
+  // across steps/runs. An incremental byte-cursor reader would make it O(total)
+  // — deferred as cleanup-tier (only bites the OFF-by-default arm) until it can
+  // carry its own multi-path-accumulation tests; the simple full-parse is kept
+  // because it is obviously correct.
   const workerWrites = () => {
     try {
       const paths = new Set();
@@ -308,7 +334,135 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
       return [...paths];
     } catch { return []; }
   };
-  const { policy, onLlmResult } = wireGate(gate, mode === 'tools' ? { actionTranslator: (/** @type {string} */ n, /** @type {any} */ a) => toolAction(n, a, workdir) } : {});
+  // Layer R — the root (within-run ratchet, design record 2026-07-19). Shell-
+  // assembled from the arbiter's own books: per-attempt write-sets come from
+  // the SAME workerWrites audit read (allow-decision only, so a denied write is
+  // never counted), red-sets from the close's kept-failure lines. The verbatim
+  // stage needs the content the audit deliberately does not keep (bytes-only),
+  // so it is teed below at the one seam that sees it — memory-only, scrubbed,
+  // never the spine.
+  const root = layerRoot ? createRoot({ gapKeep: closeGapKeep, redact: (/** @type {string} */ s) => redact(s, { patterns: SECRET_PATTERNS }), writesInformative: mode === 'tools' }) : null;
+  // The tee rides the translator and resolves paths exactly as toolAction does,
+  // so tee keys match audit paths byte-for-byte. The translator fires BEFORE the
+  // gate decides (wireGate calls translate() inside its policy, then awaits
+  // gate.check), so it can only STAGE: the audit-path filter downstream is not
+  // enough on its own, because the tee is last-write-wins PER PATH and a path the
+  // audit legitimately lists as allowed can end the attempt holding the content
+  // of a LATER write the gate rejected — the verbatim note would then swear that
+  // code landed when it is not in the file (Finding 6, 2026-07-20). Settlement
+  // is split across the two seams that actually know (Finding 7): the gate
+  // verdict can only DISCARD (a deny means the tool never runs), and the
+  // post-execution seam supplies the outcome an allow cannot — see `policy` and
+  // `onToolOutcome` below.
+  /** @param {string} n @param {any} a */
+  const teeingTranslator = (n, a) => {
+    // Classify ONCE and decide by the action TYPE, not a hardcoded name list — a
+    // third enumeration of the write verbs (workerWrites already filters on
+    // action.type write|edit) would let a future granted write-class verb enter
+    // the gate audit but silently bypass the tee (the recurring blind-instrument
+    // class). Reuse act.path so the tee key matches the audit path byte-for-byte
+    // (both from this same resolution). Content is read off the RAW args and never
+    // put on the action object — the gate audit stays bytes-only (the secrets law:
+    // what an append-only log captures, it captures forever).
+    const act = toolAction(n, a, workdir);
+    if (root && (act.type === 'write' || act.type === 'edit')) {
+      // act.path is always present on the write/edit branch (cast: toolAction's
+      // object literals widen `type` to string, so tsc cannot narrow the union)
+      const path = /** @type {string} */ (act.path);
+      const content = String((act.type === 'edit' ? a?.newText : a?.content) ?? '');
+      root.stageWrite(path, content);
+      // Finding 7 — the OUTCOME probe. The gate's allow is an INTENT record
+      // written before the tool runs; shell_edit returns an anchor miss as a
+      // refusal RESULT (bare-agent tools/shell.js:190) and a byte-cap overflow
+      // as a throw (:204), both leaving the file untouched with the allow
+      // already on the audit. Snapshot the file hash HERE (pre-execution) so the
+      // post-execution seam can settle the note against ground truth. Carry the
+      // action TYPE: for the file-unchanged case, a write and an edit answer
+      // "did it land?" differently (Finding 2). Raw content, never the scrubbed
+      // copy — the comparison is against real bytes; transient, never on a
+      // prompt, the spine, or the audit.
+      pendingProbe = { path, content, type: act.type, before: fileHash(path) };
+    }
+    return act;
+  };
+  /**
+   * Content hash of a file, or null when it does not exist / cannot be read —
+   * null is the honest unknown here, and a missing file BEFORE a write is the
+   * normal new-file case (it compares unequal to the hash after, which is
+   * exactly right: the write landed).
+   * @param {string} p
+   */
+  const fileHash = (p) => {
+    try { return createHash('sha256').update(readFileSync(p)).digest('hex'); } catch { return null; }
+  };
+  /** @type {{path: string, content: string, type: string, before: string|null}|null} the write-class action awaiting its OUTCOME */
+  let pendingProbe = null;
+  const { policy: gatePolicy, onLlmResult } = wireGate(gate, mode === 'tools' ? { actionTranslator: teeingTranslator } : {});
+  // Settle the stage on the verdict. wireGate's policy returns true on allow,
+  // a string on deny, and THROWS HaltError on halt — and bare-agent processes
+  // tool calls strictly sequentially (`for (const tc of result.toolCalls) { …
+  // await this.policy(…) }`, loop.js), so at most one stage is ever in flight.
+  // The catch discards and RE-THROWS: cap-halt routing reads that throw, and a
+  // swallowed halt would launder a tripped budget into a plain deny. A non-write
+  // action stages nothing, so both settlements are no-ops for it.
+  const policy = root && mode === 'tools'
+    ? async (/** @type {string} */ n, /** @type {any} */ a, /** @type {any} */ c) => {
+      try {
+        const verdict = await gatePolicy(n, a, c);
+        // A DENY is settled here and only here: the tool never executes, so the
+        // outcome seam below never fires for it. An ALLOW is deliberately NOT
+        // settled — the bytes have not been written yet, and settling on the
+        // verdict is precisely the Finding 7 defect (validated 2026-07-20: three
+        // allowed edits, zero bytes changed, and the note swore they landed).
+        if (verdict !== true) { root.discardWrite(); pendingProbe = null; }
+        return verdict;
+      } catch (e) {
+        root.discardWrite();
+        pendingProbe = null;
+        throw e;
+      }
+    }
+    : gatePolicy;
+  /**
+   * Finding 7 — settle the staged write on what the tool ACTUALLY did. Fires
+   * after every `tool.execute` (bare-agent loop.js:986), success or error, and
+   * bare-agent processes tool calls strictly sequentially, so exactly one probe
+   * is ever in flight. A probe that never reaches here (the BA-12 spin-guard
+   * early return, or a HaltError out of a tool body) leaves the stage pending
+   * and unsettled — correct, because in both cases nothing landed, and the
+   * attempt boundary drops it.
+   *
+   * NOT wired: `wireGate`'s own `onToolResult`, which would start feeding
+   * `gate.record` per-tool records. That changes what `limits.maxTurns` /
+   * `maxToolRounds` count and therefore when a run halts (the guarded
+   * llm-only-turns invariant at the Gate config above) — cap semantics are
+   * arbiter territory, so it is deliberately not wired here.
+   * @param {{result?: any}} [info] the tool's return value (bare-agent loop.js:988)
+   */
+  const onToolOutcome = async (info) => {
+    if (!root || !pendingProbe) return;
+    const { path: p, content, type, before } = pendingProbe;
+    pendingProbe = null;
+    // ONE read serves both the after-hash and the content check (Finding 5: the
+    // old path read the file twice). null = unreadable/absent.
+    let after = null;
+    try { after = readFileSync(p, 'utf8'); } catch { /* absent → after stays null */ }
+    let landed = after !== null && createHash('sha256').update(after, 'utf8').digest('hex') !== before;
+    if (!landed && after !== null) {
+      // The bytes did not change — but the action may still have left `content`
+      // in the file, and write vs edit answer that differently (Finding 2):
+      //   - write: a whole-file write always writes; identical bytes means the
+      //     content genuinely IS the file (exact equality, never a substring —
+      //     substring false-positived when newText appeared elsewhere).
+      //   - edit: a no-byte-change edit is EITHER an idempotent apply (newText===
+      //     oldText, "edited …: 1 replacement") OR a missed anchor ("shell_edit:
+      //     … no change made") — indistinguishable on disk, so the tool RESULT is
+      //     the only honest signal. An anchor miss is NOT landed.
+      if (type === 'write') landed = after === content;
+      else landed = typeof info?.result === 'string' && info.result.startsWith('edited ');
+    }
+    root.settleWrite(landed);
+  };
   // Money is metered as it is SPENT — per ROUND, not per attempt (F12). A
   // multi-round attempt that halts (or throws) never returns, so its rounds
   // never reach `worker-result`: the real run bought $1.4375 of tokens inside a
@@ -428,6 +582,7 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
     system: mode === 'tools' ? PERSONA_TOOLS + (usesEdit ? EDIT_STRATEGY : '') + (usesCtx ? RETRIEVAL_STRATEGY : '') : PERSONA,
     policy,
     onLlmResult: meteredOnLlmResult,
+    onToolResult: onToolOutcome,
   });
 
   /** @param {string} slot */
@@ -576,6 +731,11 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
   const middle = async (iteration, gap) => {
     roundIteration = iteration; // stamps every round of this attempt (F12)
     roundsThisAttempt = 0;      // the bound is PER ATTEMPT — a fresh conversation, a fresh budget (F20)
+    // Layer R: finalize the previous attempt from the books and ask the ratchet.
+    // Inert (null) unless consecutive attempts rewrote the same files without
+    // moving the reds; the event carries stage/paths/counts, NEVER content.
+    const rootInj = root ? root.observe({ iteration, gap, writes: workerWrites() }) : null;
+    if (rootInj) emit('root-injected', rootInj.event);
     if (gap) gaps.push(gap);
     if (revisor && !revised && gaps.length >= STALL_REDS) {
       emit('stall-detected', { iteration, consecutiveReds: gaps.length });
@@ -632,6 +792,9 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
       // attempt and describing the tree are different claims; this is the second.
       !gap && closeState && `The close is currently failing. This is its output on the tree as it stands (not an attempt of yours):\n${closeState}`,
       context.text && `Possibly relevant notes:\n${context.text}`, gap && `Previous attempt failed the test suite:\n${gap}`,
+      // Layer R: the ratchet note rides directly after the gap it qualifies —
+      // same channel discipline as the gap itself (bounded, trims announced)
+      rootInj && rootInj.note,
       artifactNote && `Previous attempt never reached the close:\n${artifactNote}`,
       // F20: a bounded attempt must SAY it was bounded. Otherwise the worker reads its own
       // truncated transcript as a finished one, learns nothing from being cut off, and spends
@@ -682,6 +845,7 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
       throw err;
     }
     writeFileSync(t, code);
+    root?.noteWrite(t, code); // Layer R tee, text mode: same seam role as the translator's
     emit('artifact-written', { iteration, path: t });
   };
 

package/src/ralph.js

@@ -143,6 +143,12 @@ const GAP_HEAD = 400, GAP_TAIL = 1500;
 // matches it says so with an explicit marker — silent truncation is the disease
 // this whole fix cures (F28), never a cure that truncates silently in turn.
 const GAP_KEEP_MAX_LINES = 50, GAP_KEEP_MAX_BYTES = 8192;
+// The exact phrase the trim announcement carries when kept failures are dropped
+// by the cap above. Exported so Layer R's detector (src/root.js) keys off the
+// SAME string the shell emits — a magic string on the reading side would drift
+// silently the day this wording changes (the blind-instrument class). Reference
+// only: the shell's behavior is unchanged, the label below is byte-identical.
+export const GAP_KEEP_TRIM_MARKER = 'more elided by the';
 
 /**
  * Bound an over-long close stream to a head sample + elided middle + tail. When
@@ -173,7 +179,7 @@ function boundGap(s, keepPattern) {
     bytes += line.length + 1;
   }
   if (!matched.length) return `${base}\n${tail}`; // pattern matched nothing — behave as the plain bound
-  const label = `kept failures matching /${keepPattern}/ (${matched.length}${trimmed ? `, ${trimmed} more elided by the ${GAP_KEEP_MAX_LINES}-line/${GAP_KEEP_MAX_BYTES}-byte cap` : ''})`;
+  const label = `kept failures matching /${keepPattern}/ (${matched.length}${trimmed ? `, ${trimmed} ${GAP_KEEP_TRIM_MARKER} ${GAP_KEEP_MAX_LINES}-line/${GAP_KEEP_MAX_BYTES}-byte cap` : ''})`;
   return `${base}\n── ${label} ──\n${matched.join('\n')}\n── end kept failures ──\n${tail}`;
 }
 

package/src/root.js

@@ -0,0 +1,305 @@
+// Layer R — the root: the within-run ratchet (LAYERS.md item 2; design record
+// docs/plans/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.
+//
+// Ownership: the SHELL authors the root, mechanically, from the arbiter's own
+// books — per-attempt write-sets (the gate audit, via the F32 workerWrites
+// seam) and the close's kept-failure lines. The worker authors nothing and
+// gains no verb; delivery is injection into the next attempt's prompt, so the
+// adaptlearn-F6 write-only-decoy class is structurally excluded.
+//
+// Engagement is FIXATION-GATED (RSI-LEARNINGS §3.3: the rejected-edit buffer's
+// lift is a fixation phenomenon and an honest null on a strong model when not
+// stuck — pay only when stuck). Content ESCALATES: first detection injects a
+// capped mechanical summary; a second consecutive detection injects the
+// worker's own prior failed edit content verbatim ("write something
+// STRUCTURALLY DIFFERENT" — the BA-14 mechanism, 50%→100% under fixation).
+// Both stages fire on DIFFERENT attempts, so every stuck episode yields a
+// per-stage read for the acceptance battery.
+//
+// Scope: within-run scratch, discarded at run end — NEVER across-run memory
+// (only a green mints that, and this module touches no inheritance channel).
+// Spine events carry counts and paths only, never content: verbatim edit text
+// is worker-authored and the spine is append-only (what a log captures, it
+// captures forever).
+
+// The shell's kept-failures trim announcement (ralph): its presence in a gap means
+// failures were dropped past the gap cap, so the visible kept lines are an
+// UNRELIABLE red-set for comparison. Imported (never re-spelled) so the detector
+// keys off the exact string the shell emits — a magic string here would drift.
+import { GAP_KEEP_TRIM_MARKER } from './ralph.js';
+
+/**
+ * Strip a trailing duration stamp from a kept-failure line. Real `node --test`
+ * spec-reporter lines are NEVER byte-stable across runs (`✖ multiplies
+ * (1.738ms)` vs `(1.637ms)` — POC 2026-07-19), so naive equality reads every
+ * attempt as "reds moved" and the detector never fires. COMPARISON-ONLY: the
+ * gap the worker sees is never rewritten.
+ * @param {string} line
+ */
+export const normalizeRedLine = (line) => line.replace(/ \(\d+(?:\.\d+)?m?s\)\s*$/, '');
+
+// Bounds — every trim is ANNOUNCED in the note (F28: silent truncation is the
+// disease; a cure that truncates silently is the same disease).
+/**
+ * A teed write: the content the worker emitted, plus whether it actually reached
+ * the file. `landed` is the OUTCOME axis (Finding 7) — the gate's allow is an
+ * intent record written before the tool runs, and a shell_edit whose anchor
+ * misses returns a refusal RESULT with the file untouched (bare-agent
+ * tools/shell.js:190). A note that says "these are your changes" is a claim
+ * about the file's contents and must be true, so it reads this flag, never the
+ * audit. The DETECTOR deliberately does not: see `observe`.
+ * @typedef {{content: string, trimmed: boolean, landed: boolean}} TeeEntry
+ */
+
+const TEE_CAP_BYTES = 2000;   // per-file content retained for the verbatim stage
+const VERBATIM_MAX_FILES = 3; // files surfaced per verbatim injection
+const SUMMARY_MAX_PATHS = 10; // paths named in the summary line
+
+/**
+ * The root collector. One per run; state dies with the run.
+ *
+ * Call order (wired by the interpreter's middle):
+ *   observe({iteration: 1, writes})            → null (nothing to compare)
+ *   stageWrite(path, content)                  → stage, before the tool runs
+ *   settleWrite(landed) | discardWrite()       → the outcome, after it ran
+ *   noteWrite(path, content)                   → stage+settle, text mode (which
+ *                                                writes before it reports)
+ *   observe({iteration: N, gap, writes})       → null | {stage, note, event}
+ * `writes` is the CUMULATIVE allow-decision write/edit path list from the gate
+ * audit (the F32 instrument); the per-attempt set is the delta between calls —
+ * so a gate-DENIED write is never counted (the tool never ran at all).
+ *
+ * Finding 7 — the two axes, deliberately NOT merged. An allow-decision records
+ * what the worker REACHED FOR, which is the right instrument for "is it
+ * repeating itself"; whether those bytes reached the file is a different
+ * question, and only the note (a claim about file contents) needs it. Collapsing
+ * them either way is a bug: settling the note on the allow makes it lie, and
+ * running the detector off the file makes it blind to a worker re-firing an
+ * identical edit whose anchor never matches — measured null on every attempt.
+ *
+ * @param {{gapKeep?: string, redact?: (s: string) => string, writesInformative?: boolean}} [opts]
+ *   the signed spec's kept-failures pattern (the red-set source; without it the
+ *   detector degrades to write-overlap alone and the event says so), the shell's
+ *   secret scrubber (verbatim content is scrubbed before it rides a prompt), and
+ *   `writesInformative` (Finding 3, default true): whether the per-attempt
+ *   write-set carries information. In TOOL mode the worker CHOOSES which files to
+ *   write, so re-writing the same file is a real repetition signal; in TEXT mode
+ *   the one target is rewritten every attempt by construction, so write-overlap
+ *   is constant-true and carries none — with no red-set to compare, the detector
+ *   cannot tell repetition from progress and must stay inert (it would otherwise
+ *   steer a progressing worker off course, violating "inert when not stuck").
+ */
+export function createRoot({ gapKeep, redact = (s) => s, writesInformative = true } = {}) {
+  const keepRe = gapKeep ? new RegExp(gapKeep, 'm') : null;
+  /**
+   * The comparable red-set, or null when it CANNOT be trusted — one clean UNKNOWN
+   * covering three cases, so the detector honestly degrades to write-overlap alone
+   * rather than making the strong "reds unchanged" claim off a blind instrument:
+   *   - no gapKeep pattern at all (no red-set instrument);
+   *   - a TRIMMED window (ralph dropped failures past the cap): failures beyond the
+   *     window can move while the visible lines stay identical (Finding 5);
+   *   - zero matches on a judged gap: an empty kept-set is UNKNOWN, not "zero
+   *     failures" — [] === [] would false-read as "reds unchanged" (Finding 2).
+   * @param {string} gap @returns {string[]|null} normalized kept lines, or null when untrustworthy
+   */
+  const keptSet = (gap) => {
+    if (!keepRe || gap.includes(GAP_KEEP_TRIM_MARKER)) return null;
+    const lines = [...new Set(gap.split('\n').filter((l) => keepRe.test(l)).map(normalizeRedLine))].sort();
+    return lines.length ? lines : null;
+  };
+
+  /** @type {{writes: string[], reds: string[]|null, tee: Map<string, TeeEntry>}[]} finalized attempts */
+  const attempts = [];
+  /** @type {Set<string>} cumulative audit write-set at the last observe */
+  let prevCumulative = new Set();
+  /** @type {Map<string, TeeEntry>} tee for the attempt currently running */
+  let tee = new Map();
+  /** @type {{path: string, entry: TeeEntry}|null} the write awaiting its outcome */
+  let pending = null;
+  let streak = 0;
+
+  /**
+   * Capture a write/edit's content as PENDING — staged against the gate verdict
+   * that has not been rendered yet (Finding 6). Scrub at CAPTURE, BEFORE
+   * truncating (repo doctrine: secrets scrub at the source, and staging IS the
+   * source — a staged secret must be scrubbed even if the write is later
+   * discarded). Every SECRET_PATTERN is a prefix+min-length shape (sk-…{16,}),
+   * so a secret straddling the cap would lose the bytes that make it match and a
+   * partial token would ride the note unredacted — redact the FULL content
+   * first, then cap the already-scrubbed string.
+   * @param {string} path @param {string} content
+   */
+  const stageWrite = (path, content) => {
+    const scrubbed = redact(content);
+    const trimmed = scrubbed.length > TEE_CAP_BYTES;
+    pending = { path, entry: { content: scrubbed.slice(0, TEE_CAP_BYTES), trimmed, landed: false } };
+  };
+
+  return {
+    stageWrite,
+
+    /**
+     * The staged write RAN — record what it actually did (Finding 7). Retained
+     * either way: an attempted-but-unapplied edit is still the worker reaching
+     * for the same file, which is what the detector measures, and dropping it
+     * here would blind the ratchet to the purest fixation there is (a worker
+     * re-firing an identical edit whose anchor never matches — measured null on
+     * every attempt under a tree-diff detector, 2026-07-20). Only the NOTE's
+     * wording turns on `landed`. Last write per path wins (the tree's final
+     * state for that attempt is what failed the close).
+     * @param {boolean} landed whether the content is now in the file
+     */
+    settleWrite(landed) {
+      if (pending) tee.set(pending.path, { ...pending.entry, landed });
+      pending = null;
+    },
+
+    /**
+     * The staged write was DENIED or HALTED: it is not in the file, so it must
+     * never be surfaced as "your own change that landed". Drops the stage and
+     * leaves whatever DID land for that path untouched.
+     */
+    discardWrite() { pending = null; },
+
+    /**
+     * Stage and commit in one call — the post-allow write site (text mode
+     * gate-checks and writes before it calls this, so the verdict is already in).
+     * @param {string} path @param {string} content
+     */
+    noteWrite(path, content) {
+      stageWrite(path, content);
+      if (pending) tee.set(pending.path, { ...pending.entry, landed: true });
+      pending = null;
+    },
+
+    /**
+     * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
+     * gap. Finalizes that attempt from the books, runs the detector, and
+     * returns the injection for the attempt about to run — or null (inert).
+     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
+     */
+    observe({ iteration, gap, writes }) {
+      const cumulative = new Set(writes);
+      if (!gap) { // first attempt: nothing judged yet, nothing to compare
+        prevCumulative = cumulative;
+        tee = new Map();
+        pending = null;
+        return null;
+      }
+      // finalize the attempt that just failed: its writes are the audit delta
+      const delta = [...cumulative].filter((p) => !prevCumulative.has(p));
+      // an edit to a file already written in an earlier attempt is not in the
+      // delta — the tee saw it, and a teed landed path IS this attempt's work
+      for (const p of tee.keys()) if (cumulative.has(p) && !delta.includes(p)) delta.push(p);
+      // `gap` is guaranteed truthy here (the `if (!gap) return` guard above handled
+      // the empty case); reds === null comes only from keptSet's own UNKNOWN logic.
+      attempts.push({ writes: delta, reds: keptSet(gap), tee });
+      // The detector only ever compares the last two finalized attempts, so older
+      // ones (and their teed content) are dead state — keep just the two (Finding 7).
+      if (attempts.length > 2) attempts.shift();
+      prevCumulative = cumulative;
+      tee = new Map();
+      // a stage whose verdict never arrived (the attempt ended mid-flight) is not
+      // a landed write and must not survive into the next attempt's tee
+      pending = null;
+
+      if (attempts.length < 2) return null;
+      const [prev, last] = attempts.slice(-2);
+      const overlap = last.writes.filter((p) => prev.writes.includes(p));
+      // Both UNKNOWN → no trustworthy red-set either side: write-overlap alone
+      // decides (writes-only mode, named below). One known and one UNKNOWN → the
+      // red-set is not provably the same, so it counts as MOVEMENT, never a fire
+      // (a real red-set followed by a crash/empty gap is new information, not
+      // repetition). Both known → the honest set comparison.
+      const redsSame = last.reds === null && prev.reds === null ? null
+        : last.reds === null || prev.reds === null ? false
+        : JSON.stringify(last.reds) === JSON.stringify(prev.reds);
+      // Finding 3: when writes carry no information (text mode — the one target is
+      // rewritten every attempt regardless of progress), write-overlap alone can
+      // never establish fixation; only a KNOWN-unmoved red-set can. So the
+      // degraded writes-only path (redsSame === null) is available to fire only
+      // when writes ARE informative (tool mode). With informative writes the prior
+      // behavior stands: overlap + reds-not-known-to-have-moved.
+      const redsGate = writesInformative ? redsSame !== false : redsSame === true;
+      const fixated = overlap.length > 0 && redsGate;
+      if (!fixated) { streak = 0; return null; }
+      streak += 1;
+
+      const stage = streak === 1 ? 'summary' : 'verbatim';
+      const mode = redsSame === null ? 'writes-only' : 'reds+writes';
+      const shownPaths = overlap.slice(0, SUMMARY_MAX_PATHS);
+      const morePaths = overlap.length - shownPaths.length;
+      const event = {
+        iteration, stage, mode, streak,
+        paths: shownPaths, ...(morePaths > 0 ? { pathsElided: morePaths } : {}),
+        redSetSize: last.reds ? last.reds.length : null,
+      };
+
+      // Finding 7: what the worker REACHED FOR fired the detector; what it
+      // ACHIEVED decides the wording. Only paths this attempt actually teed can
+      // answer the outcome question — a path known solely from the audit is
+      // unattributable, so it falls back to the neutral (landed) phrasing rather
+      // than guessing.
+      const attempted = overlap.filter((p) => last.tee.has(p));
+      const noneApplied = attempted.length > 0
+        && attempted.every((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+
+      if (stage === 'summary') {
+        const redsClause = mode === 'reds+writes'
+          ? 'and the set of failing tests did not change at all'
+          : 'with no visible progress';
+        // The unapplied case is the MECHANICAL genre (F38: gaps that name a wall
+        // convert; semantic ones stall) — naming the missed anchor is strictly
+        // more actionable than "form a different hypothesis", because the
+        // hypothesis may have been right and only the anchor wrong.
+        const body = noneApplied
+          ? `Your last two attempts both tried to change ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} and NEITHER EDIT APPLIED — `
+            + 'the text you anchored on was not found in the file, so nothing changed. '
+            + 'Re-read the file and quote the exact text (whitespace and indentation included) before editing again.'
+          : `Your last two attempts both rewrote ${shownPaths.join(', ')}`
+            + `${morePaths > 0 ? ` (and ${morePaths} more)` : ''} ${redsClause}. `
+            + 'Do NOT retry the same change — form a DIFFERENT hypothesis before your next edit.';
+        return { stage, event, note: `RATCHET: you are repeating yourself. ${body}` };
+      }
+      // verbatim: surface the worker's own last content for the repeated paths —
+      // scrubbed, capped, every trim announced. Grouped by OUTCOME, because the
+      // two groups need opposite advice: content that landed and failed must not
+      // be written again, while content that never applied may have been the
+      // right change aimed at the wrong anchor — telling that worker to "write
+      // something structurally different" would steer it away from a correct fix.
+      const files = attempted.slice(0, VERBATIM_MAX_FILES);
+      const moreFiles = attempted.length - files.length;
+      /** @param {string} p */
+      const block = (p) => {
+        const t = /** @type {TeeEntry} */ (last.tee.get(p));
+        // t.content was already scrubbed by redact() in stageWrite before storage
+        // (Finding 6): re-redacting here is redundant work over already-masked text.
+        return `--- ${p}${t.trimmed ? ` (truncated to first ${TEE_CAP_BYTES} chars)` : ''} ---\n${t.content}`;
+      };
+      const landedFiles = files.filter((p) => /** @type {TeeEntry} */ (last.tee.get(p)).landed);
+      const unappliedFiles = files.filter((p) => !(/** @type {TeeEntry} */ (last.tee.get(p)).landed));
+      const sections = [];
+      if (landedFiles.length) {
+        sections.push('These are your OWN previous changes — they landed, and they did NOT fix the failing set:\n'
+          + landedFiles.map(block).join('\n')
+          + '\nDo not write these again. Write something STRUCTURALLY DIFFERENT, or change a different file.');
+      }
+      if (unappliedFiles.length) {
+        sections.push('This is text you tried to write, and it did NOT apply — the anchor was not found, '
+          + 'so the file is UNCHANGED and none of this is in it:\n'
+          + unappliedFiles.map(block).join('\n')
+          + '\nRe-read the file and copy the exact text you mean to replace, character for character, before editing again.');
+      }
+      return {
+        stage, event,
+        note: `RATCHET: you are STILL repeating yourself. ${sections.join('\n\n')}`
+          + (moreFiles > 0 ? `\n(and ${moreFiles} more repeated file${moreFiles > 1 ? 's' : ''}, elided)` : ''),
+      };
+    },
+  };
+}

package/src/run.js

@@ -183,6 +183,12 @@ async function openDraftPr({ workdir, branch, title, body, addPaths, exec }) {
  * boundary — the Gate still caps within a step, but an unpriced result cannot
  * be summed, so the run stops rather than counting it $0 (F6).
  *
+ * EVERY terminal `job-end` states the money: `spentUsd` (the sum of PRICED
+ * rounds only — never an estimate; a real 0 on the pre-token reds) plus
+ * `spendComplete`, false when any round came back unpriced and the figure is
+ * therefore a FLOOR, not the total. Both are always present, so a consumer
+ * never branches on field presence nor launders a blank into $0.
+ *
  * @param {object|string} rawSpec the job spec (job-v1), text or parsed
  * @param {object} opts
  * @param {unknown} opts.approvals `{ specHash, signer, ts }` records (from OUTSIDE the spec)
@@ -194,21 +200,41 @@ async function openDraftPr({ workdir, branch, title, body, addPaths, exec }) {
  * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
  * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
  * @param {ExecCmd} [opts.execCmd] process runner for the hitl PR mechanics
- *        (shell-owned seam, same doctrine as the provider binding)
+ * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
+ *        territory, threaded to every predicate step's interpreter. Defaults OFF
+ *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
+ *        ON has never won its own A/B — the acceptance read defers to Layer 2 (or
+ *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
+ *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
+ *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'escalated' | 'unapproved-spec' |
  *   'job-red' | 'smoke-red' | 'config-red' | 'pricing-red' | 'provider-red' |
  *   'cap-halt' | 'close-unsupported' | `step-red:<id>`
  */
-export async function runJob(rawSpec, { approvals, workdir, target, provider, emit, capRuns = 3, shellCapUsd = 2, closeTimeoutMs, execCmd = defaultExec }) {
+export async function runJob(rawSpec, { approvals, workdir, target, provider, emit, capRuns = 3, shellCapUsd = 2, closeTimeoutMs, execCmd = defaultExec, layerRoot = false }) {
+  // 0. the ledger's counters, declared FIRST so that every job-end — including
+  // the pre-token reds below — can state a real figure. An omitted `spentUsd` is
+  // not a zero: a consumer reads `undefined` and either crashes or launders it
+  // into $0 (F12's class, at the terminal record instead of mid-attempt).
+  let spentUsd = 0;
+  let unpriced = 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
+  // unpriced (F6) that sum is a FLOOR, not the total, and `spendComplete: false`
+  // says so machine-readably instead of dressing a floor up as exact. Emitted on
+  // EVERY job-end (true when everything was priced) so no consumer ever has to
+  // branch on field presence.
+  const spend = () => ({ spentUsd, spendComplete: !unpriced });
   // 1. human-signs-always — before ANY provider call (N1 decision #1)
   if (!checkApproval(rawSpec, approvals)) {
-    emit('job-end', { outcome: 'unapproved-spec', detail: 'no approval record matches this exact spec version' });
+    emit('job-end', { outcome: 'unapproved-spec', detail: 'no approval record matches this exact spec version', ...spend() });
     return 'unapproved-spec';
   }
   const jv = validateJob(rawSpec, { shellCapUsd });
   if (!jv.ok) {
     for (const r of jv.reds) emit('job-red', r);
-    emit('job-end', { outcome: 'job-red' });
+    emit('job-end', { outcome: 'job-red', ...spend() });
     return 'job-red';
   }
   const job = /** @type {any} */ (jv.job);
@@ -218,7 +244,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   if ((typeof target !== 'string' || !target)
       && job.steps.some((/** @type {any} */ s) => s.close.type === 'predicate' && (s.mode ?? 'text') === 'text')) {
     emit('job-red', { code: 'missing-required', path: 'opts.target', detail: 'text-mode steps write ONE artifact — pass opts.target (reds-before-tokens)' });
-    emit('job-end', { outcome: 'job-red' });
+    emit('job-end', { outcome: 'job-red', ...spend() });
     return 'job-red';
   }
   emit('job-start', { job: job.job, specHash: jobSpecHash(job), budgetUsd: job.budgetUsd, steps: job.steps.map((/** @type {any} */ s) => s.id) });
@@ -228,14 +254,12 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   emit('primitive-smoke', smoke);
   if (!smoke.ok) {
     emit('escalation', { category: 'smoke-red', decisionReady: true, decision: `The ${smoke.primitive} primitive failed its known-answer check — no run verdict is trustworthy on a degraded primitive.`, options: ['fix the primitive/store', 'abandon the run'], detail: smoke.detail });
-    emit('job-end', { outcome: 'smoke-red' });
+    emit('job-end', { outcome: 'smoke-red', ...spend() });
     return 'smoke-red';
   }
 
   // 3. the ONE ledger. Unpriced is never free (F6): a null cost can't be
   // summed, so it flags a stop instead of accumulating $0.
-  let spentUsd = 0;
-  let unpriced = false;
   /** @param {number|null|undefined} c */
   const account = (c) => { if (typeof c === 'number' && Number.isFinite(c)) spentUsd += c; else unpriced = true; };
   /** @type {(type: string, data?: object) => object} */
@@ -256,7 +280,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   };
   const pricingRed = () => {
     emit('escalation', { category: 'pricing-red', decisionReady: true, decision: 'A provider result carried no priced cost — the hard cap cannot govern spend it cannot see (unpriced is never free, F6).', options: ['bind a priced provider/model', 'abandon the run'], spentUsd });
-    emit('job-end', { outcome: 'pricing-red' });
+    emit('job-end', { outcome: 'pricing-red', ...spend() });
     return 'pricing-red';
   };
 
@@ -294,7 +318,11 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
   };
   const providerRed = () => {
     emit('escalation', { category: 'provider-red', decisionReady: true, decision: 'The provider path threw before a result existed — spend for the failed call is unknown (F6), and no drafting verdict exists.', options: ['fix the provider binding', 'retry the run', 'abandon the run'], detail: transportRed, spentUsd });
-    emit('job-end', { outcome: 'provider-red' });
+    // A transport THROW never returned a usage figure, so the floor is NOT the total
+    // (F6): spendComplete must be false — spend()'s `!unpriced` only knows about priced
+    // rounds that came back unpriced, not a call that never returned at all. Leaving it
+    // true would have the job-end contradict the escalation's own "spend … is unknown".
+    emit('job-end', { outcome: 'provider-red', ...spend(), spendComplete: false });
     return 'provider-red';
   };
   const capNow = () => Math.min(shellCapUsd, job.budgetUsd - spentUsd);
@@ -345,7 +373,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
       // not on trial. Mirrors the worker path (interpret.js) and the human's options: the round
       // was metered, so this is a fault with a known cost, not a spend-unknown transport throw.
       emit('escalation', { category: 'provider-red', decisionReady: true, decision: 'The drafting round was truncated at the output cap (BA-6) — the API cut the config off mid-generation, so no valid config exists. Not the drafter\'s competence (never a config-red), and not silently retried.', options: ['raise the drafting cap and rerun', 'retry the run', 'abandon the run'], detail: draftTruncated, spentUsd });
-      emit('job-end', { outcome: 'provider-red' });
+      emit('job-end', { outcome: 'provider-red', ...spend() });
       return 'provider-red';
     }
     if (unpriced) return pricingRed();
@@ -355,11 +383,11 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
         // the honest stop is a cap story, never a config-red blaming the drafter
         emit('cap-halt', { category: 'cap-halt', meaning: 'not under cap — not "can\'t"', spentUsd, budgetUsd: job.budgetUsd });
         emit('escalation', { category: 'cap-halt', decisionReady: true, decision: `Drafting spend ($${spentUsd.toFixed(4)}) consumed the job budget ($${job.budgetUsd}) before a valid config existed.`, options: ['raise the job budget and rerun', 'abandon the run'], spentUsd });
-        emit('job-end', { outcome: 'cap-halt' });
+        emit('job-end', { outcome: 'cap-halt', ...spend() });
         return 'cap-halt';
       }
       for (const r of cv.reds) emit('config-red', r);
-      emit('job-end', { outcome: 'config-red' });
+      emit('job-end', { outcome: 'config-red', ...spend() });
       return 'config-red';
     }
     config = cv.config;
@@ -402,14 +430,14 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
       // baseline — loud, and never allowed to un-open a real PR
       if (pr.strandedOn) emit('workdir-red', { step: step.id, branch: pr.strandedOn, detail: 'the run could not return the checkout to its starting branch — the next run would build on this one' });
       emit('escalation', { category: 'hitl-close', decisionReady: true, step: step.id, prompt: step.close.prompt, spentUsd, decision: step.close.prompt, options: ['approve', 'reject'], pr: { url: pr.url, branch, error: pr.red?.detail ?? null } });
-      emit('job-end', { outcome: 'escalated', step: step.id, spentUsd });
+      emit('job-end', { outcome: 'escalated', step: step.id, ...spend() });
       return 'escalated'; // by design: the human acts outside the run, forever
     }
     if (step.close.type !== 'predicate') {
       // honest refusal: gold/rubric EXECUTION lands with the verdict classes
       // (N4); a fake verdict here would poison every contrast downstream
       emit('escalation', { category: 'close-unsupported', decisionReady: true, step: step.id, decision: `Step "${step.id}" has a ${step.close.type} close — N2 executes predicate and hitl closes only.`, options: ['restate the close as a predicate', 'wait for the verdict-classes rung'] });
-      emit('job-end', { outcome: 'close-unsupported', step: step.id });
+      emit('job-end', { outcome: 'close-unsupported', step: step.id, ...spend() });
       return 'close-unsupported';
     }
     emit('step-start', { step: step.id, remainingUsd: job.budgetUsd - spentUsd, spentUsd, mode: step.mode ?? 'text' });
@@ -436,7 +464,7 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
     const fault = Object.hasOwn(CLOSE_FAULTS, pre.verdict) ? CLOSE_FAULTS[pre.verdict] : undefined;
     if (fault) {
       emit('escalation', { category: fault.category, decisionReady: true, step: step.id, decision: fault.decision, options: fault.options, detail: pre.detail, spentUsd });
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: fault.category, spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: fault.category, ...spend() });
       return `step-red:${step.id}`;
     }
     // The precheck's gap goes to the worker as what it IS: the close's output on
@@ -458,21 +486,22 @@ export async function runJob(rawSpec, { approvals, workdir, target, provider, em
         // arbiter territory (PRD v1.11; F28 for gapKeep).
         mode: step.mode ?? 'text', tools: step.tools,
         closeExpect: step.close.expect, closeJudged: step.close.judged, closeGapKeep: step.close.gapKeep,
+        layerRoot,
       });
     } catch (e) {
       // ralph belts throws INSIDE the loop; this belts the interpreter's own
       // setup (gate.init, store ctor) — the spine must terminate, never dangle
       emit('escalation', { category: 'interpreter-red', decisionReady: true, step: step.id, decision: 'The interpreter broke outside the loop — no harness verdict is trustworthy until it is fixed.', options: ['fix the interpreter/run directory', 'abandon the run'], detail: String(/** @type {Error} */ (e)?.message ?? e), spentUsd });
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: 'interpreter-red', spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: 'interpreter-red', ...spend() });
       return `step-red:${step.id}`;
     }
     emit('step-end', { step: step.id, outcome, spentUsd });
     if (unpriced) return pricingRed();
     if (outcome !== 'green') {
-      emit('job-end', { outcome: 'step-red', step: step.id, cause: outcome, spentUsd });
+      emit('job-end', { outcome: 'step-red', step: step.id, cause: outcome, ...spend() });
       return `step-red:${step.id}`;
     }
   }
-  emit('job-end', { outcome: 'green', spentUsd });
+  emit('job-end', { outcome: 'green', ...spend() });
   return 'green';
 }

package/types/interpret.d.ts

@@ -42,11 +42,18 @@
  * @param {'text'|'tools'} [opts.mode] middle mode (2b): 'text' (default) writes the ONE
  *        target from the response artifact; 'tools' gives the worker Gate-governed file
  *        tools — SPEC-side territory (the step declares it; the config cannot express it)
+ * @param {boolean} [opts.layerRoot=false] Layer R (the within-run ratchet, src/root.js):
+ *        shell-assembled fixation detection over the run's own books, injecting an
+ *        escalating summary→verbatim note when consecutive attempts rewrite the same
+ *        files without moving the reds. Inert when the worker is not stuck (RSI §3.3).
+ *        Defaults OFF (decided 2026-07-21): fixation is extinct on every current job
+ *        (F41), so ON is unproven — the field read defers to Layer 2. `true` is the
+ *        ON/experimental arm; never a worker-visible knob
  * @param {string[]} [opts.tools] the spec's tool grant (subset of read|grep|write,
  *        job-v1 validated); defaults to the full menu in tool mode
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep }: {
+export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep, layerRoot }: {
     task: string;
     target?: string | undefined;
     close: string[];
@@ -75,6 +82,7 @@ export function interpret(configRaw: object | string, { task, target, close, wor
     }>) | undefined;
     closeState?: string | undefined;
     mode?: "text" | "tools" | undefined;
+    layerRoot?: boolean | undefined;
     tools?: string[] | undefined;
 }): Promise<"green" | "escalated" | "config-red">;
 /** @typedef {Error & {category?: string, lib?: string}} CategorizedError the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose) */

package/types/ralph.d.ts

@@ -134,6 +134,7 @@ export function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cw
     gapKeep?: string | undefined;
     workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+export const GAP_KEEP_TRIM_MARKER: "more elided by the";
 /**
  * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the
  * close rendered NO JUDGMENT — so it is not a verdict, it never feeds a gap

package/types/root.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The root collector. One per run; state dies with the run.
+ *
+ * Call order (wired by the interpreter's middle):
+ *   observe({iteration: 1, writes})            → null (nothing to compare)
+ *   stageWrite(path, content)                  → stage, before the tool runs
+ *   settleWrite(landed) | discardWrite()       → the outcome, after it ran
+ *   noteWrite(path, content)                   → stage+settle, text mode (which
+ *                                                writes before it reports)
+ *   observe({iteration: N, gap, writes})       → null | {stage, note, event}
+ * `writes` is the CUMULATIVE allow-decision write/edit path list from the gate
+ * audit (the F32 instrument); the per-attempt set is the delta between calls —
+ * so a gate-DENIED write is never counted (the tool never ran at all).
+ *
+ * Finding 7 — the two axes, deliberately NOT merged. An allow-decision records
+ * what the worker REACHED FOR, which is the right instrument for "is it
+ * repeating itself"; whether those bytes reached the file is a different
+ * question, and only the note (a claim about file contents) needs it. Collapsing
+ * them either way is a bug: settling the note on the allow makes it lie, and
+ * running the detector off the file makes it blind to a worker re-firing an
+ * identical edit whose anchor never matches — measured null on every attempt.
+ *
+ * @param {{gapKeep?: string, redact?: (s: string) => string, writesInformative?: boolean}} [opts]
+ *   the signed spec's kept-failures pattern (the red-set source; without it the
+ *   detector degrades to write-overlap alone and the event says so), the shell's
+ *   secret scrubber (verbatim content is scrubbed before it rides a prompt), and
+ *   `writesInformative` (Finding 3, default true): whether the per-attempt
+ *   write-set carries information. In TOOL mode the worker CHOOSES which files to
+ *   write, so re-writing the same file is a real repetition signal; in TEXT mode
+ *   the one target is rewritten every attempt by construction, so write-overlap
+ *   is constant-true and carries none — with no red-set to compare, the detector
+ *   cannot tell repetition from progress and must stay inert (it would otherwise
+ *   steer a progressing worker off course, violating "inert when not stuck").
+ */
+export function createRoot({ gapKeep, redact, writesInformative }?: {
+    gapKeep?: string;
+    redact?: (s: string) => string;
+    writesInformative?: boolean;
+}): {
+    stageWrite: (path: string, content: string) => void;
+    /**
+     * The staged write RAN — record what it actually did (Finding 7). Retained
+     * either way: an attempted-but-unapplied edit is still the worker reaching
+     * for the same file, which is what the detector measures, and dropping it
+     * here would blind the ratchet to the purest fixation there is (a worker
+     * re-firing an identical edit whose anchor never matches — measured null on
+     * every attempt under a tree-diff detector, 2026-07-20). Only the NOTE's
+     * wording turns on `landed`. Last write per path wins (the tree's final
+     * state for that attempt is what failed the close).
+     * @param {boolean} landed whether the content is now in the file
+     */
+    settleWrite(landed: boolean): void;
+    /**
+     * The staged write was DENIED or HALTED: it is not in the file, so it must
+     * never be surfaced as "your own change that landed". Drops the stage and
+     * leaves whatever DID land for that path untouched.
+     */
+    discardWrite(): void;
+    /**
+     * Stage and commit in one call — the post-allow write site (text mode
+     * gate-checks and writes before it calls this, so the verdict is already in).
+     * @param {string} path @param {string} content
+     */
+    noteWrite(path: string, content: string): void;
+    /**
+     * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
+     * gap. Finalizes that attempt from the books, runs the detector, and
+     * returns the injection for the attempt about to run — or null (inert).
+     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
+     */
+    observe({ iteration, gap, writes }: {
+        iteration: number;
+        gap?: string;
+        writes: string[];
+    }): null | {
+        stage: "summary" | "verbatim";
+        note: string;
+        event: object;
+    };
+};
+export function normalizeRedLine(line: string): string;
+/**
+ * A teed write: the content the worker emitted, plus whether it actually reached
+ * the file. `landed` is the OUTCOME axis (Finding 7) — the gate's allow is an
+ * intent record written before the tool runs, and a shell_edit whose anchor
+ * misses returns a refusal RESULT with the file untouched (bare-agent
+ * tools/shell.js:190). A note that says "these are your changes" is a claim
+ * about the file's contents and must be true, so it reads this flag, never the
+ * audit. The DETECTOR deliberately does not: see `observe`.
+ */
+export type TeeEntry = {
+    content: string;
+    trimmed: boolean;
+    landed: boolean;
+};

package/types/run.d.ts

@@ -17,6 +17,12 @@
  * boundary — the Gate still caps within a step, but an unpriced result cannot
  * be summed, so the run stops rather than counting it $0 (F6).
  *
+ * EVERY terminal `job-end` states the money: `spentUsd` (the sum of PRICED
+ * rounds only — never an estimate; a real 0 on the pre-token reds) plus
+ * `spendComplete`, false when any round came back unpriced and the figure is
+ * therefore a FLOOR, not the total. Both are always present, so a consumer
+ * never branches on field presence nor launders a blank into $0.
+ *
  * @param {object|string} rawSpec the job spec (job-v1), text or parsed
  * @param {object} opts
  * @param {unknown} opts.approvals `{ specHash, signer, ts }` records (from OUTSIDE the spec)
@@ -28,12 +34,18 @@
  * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
  * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
  * @param {ExecCmd} [opts.execCmd] process runner for the hitl PR mechanics
- *        (shell-owned seam, same doctrine as the provider binding)
+ * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
+ *        territory, threaded to every predicate step's interpreter. Defaults OFF
+ *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
+ *        ON has never won its own A/B — the acceptance read defers to Layer 2 (or
+ *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
+ *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
+ *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'escalated' | 'unapproved-spec' |
  *   'job-red' | 'smoke-red' | 'config-red' | 'pricing-red' | 'provider-red' |
  *   'cap-halt' | 'close-unsupported' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd, layerRoot }: {
     approvals: unknown;
     workdir: string;
     target?: string | undefined;
@@ -43,6 +55,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, target, p
     shellCapUsd?: number | undefined;
     closeTimeoutMs?: number | undefined;
     execCmd?: ExecCmd | undefined;
+    layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {
     code: string;