bareloop 0.3.0 → 0.5.0

package/src/exits.js

@@ -0,0 +1,163 @@
+// Layer 2: the exit evaluator — the SHELL's own fixed code for the closed
+// exit menu (PRD v1.12 §3). An exit is declarative data; nothing here ever
+// executes agent-authored text. Doctrine wired in, not promised:
+//
+//   - exits verify FORM, not truth: progress gates only; the operator's close
+//     stays the one arbiter (checks decide nothing, mint nothing).
+//   - `tree-changed` reads OUTCOME — real bytes vs a pre-step snapshot taken
+//     by `snapshotScope` — never git status (always shows the planted bug,
+//     F45) and never gate intent (the F43 identical-refire trap: an allowed
+//     write that lands the same bytes is NOT a change).
+//   - a failing exit's detail is a MECHANICAL gap (a named wall, a count) —
+//     the genre that converts (F38/F46); details carry names and counts only,
+//     never file bodies (they ride the spine, which is append-only forever).
+//   - `check-passes` delegates through the `runCheck` seam the runner wires
+//     to the full runClose machinery; the evaluator itself never spawns. An
+//     unwired or throwing check fails CLOSED (the broken-close class: an
+//     unrunnable check is a stop, never a silent pass).
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { globToPrefix } from './validate.js';
+
+/** The check gap is ALREADY bounded upstream by runClose's boundGap (head +
+ * gapKeep block ≤ 8192 + tail ≈ 10KB, with the failing-test NAMES preserved).
+ * The evaluator must NOT re-truncate it: a 400-char clamp deletes exactly those
+ * `not ok`/`FAILED` names — the mechanical gap the F46 conversion mechanism
+ * feeds the worker (F28 reintroduced). This cap is a defensive backstop above
+ * boundGap's own envelope: a normal bounded gap passes through intact, and only
+ * a pathological seam that returned an unbounded gap would ever be trimmed. */
+const CHECK_GAP_MAX = 12000;
+
+/** @typedef {{ type: string, pass: boolean, detail?: string, fault?: string }} ExitResult
+ * `fault` present means the INSTRUMENT could not judge (unwired snapshot/seam,
+ * a check in runClose's forbidden zone) — it carries the runClose verdict name
+ * ('failed'|'timed-out'|'killed'|'crashed') so the micro-loop escalates through
+ * the same CLOSE_FAULTS taxonomy instead of feeding a fake gap to the worker.
+ * A plain pass:false with no fault is honest worker feedback. */
+
+/**
+ * Snapshot the file state under a scope prefix — the "before" side of
+ * `tree-changed`. Content hashes, not mtimes: only real bytes count as
+ * outcome. A scope directory that does not exist yet snapshots empty (the
+ * step creating it IS the change). Never throws on a missing dir.
+ * @param {string} dir absolute workdir (the run directory)
+ * @param {string} scope a validated scope glob (e.g. `tests/**`)
+ * @returns {Promise<Map<string, string>>} relative path → sha256
+ */
+export async function snapshotScope(dir, scope) {
+  const prefix = globToPrefix(scope);
+  /** @type {Map<string, string>} */
+  const snap = new Map();
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = /** @type {string[]} */ (await readdir(join(dir, prefix), { recursive: true, encoding: 'utf8' }));
+  } catch {
+    return snap; // missing scope dir = empty snapshot, never a throw
+  }
+  for (const rel of entries) {
+    const full = join(dir, prefix, rel);
+    let body;
+    try { body = await readFile(full); } catch { continue; } // directories and vanished files skip
+    snap.set(`${prefix}/${rel.replaceAll('\\', '/')}`, createHash('sha256').update(body).digest('hex'));
+  }
+  return snap;
+}
+
+/**
+ * Evaluate a step's exits — AND-only (decision 8): the step passes iff EVERY
+ * listed exit passes. All exits are evaluated (never short-circuit): the gap
+ * must name every wall, not the first one hit.
+ * @param {Array<Record<string, any>>} exits validated exit items
+ * @param {{ dir: string, snapshot?: Map<string, string>, runCheck?: (name: string) => Promise<{pass: boolean, gap?: string}> }} ctx
+ *   `dir`: the run directory; `snapshot`: the pre-step `snapshotScope` result
+ *   (required by tree-changed — absent fails closed); `runCheck`: the runner's
+ *   runClose-backed seam (required by check-passes — absent fails closed).
+ * @returns {Promise<{ pass: boolean, results: ExitResult[] }>}
+ */
+export async function evalExits(exits, { dir, snapshot, runCheck }) {
+  /** @type {ExitResult[]} */
+  const results = [];
+  for (const e of exits) {
+    results.push(await evalOne(e, { dir, snapshot, runCheck }));
+  }
+  return { pass: results.every((r) => r.pass), results };
+}
+
+/**
+ * @param {Record<string, any>} e
+ * @param {{ dir: string, snapshot?: Map<string, string>, runCheck?: (name: string) => Promise<{pass: boolean, gap?: string}> }} ctx
+ * @returns {Promise<ExitResult>}
+ */
+async function evalOne(e, { dir, snapshot, runCheck }) {
+  if (e.type === 'artifact-written') {
+    let body;
+    try { body = await readFile(join(dir, e.path), 'utf8'); } catch {
+      return { type: e.type, pass: false, detail: `${e.path} was not written (does not exist)` };
+    }
+    if (body.length === 0) return { type: e.type, pass: false, detail: `${e.path} is empty — a zero-byte artifact is not progress` };
+    if (e.pattern !== undefined && !new RegExp(e.pattern, 'm').test(body)) {
+      return { type: e.type, pass: false, detail: `${e.path} exists but does not match the declared pattern ${e.pattern}` };
+    }
+    return { type: e.type, pass: true };
+  }
+
+  if (e.type === 'tree-changed') {
+    if (!(snapshot instanceof Map)) {
+      // fail CLOSED as a FAULT: without the before-side this instrument is
+      // blind — it must never read "changed" (F45) and never feed the miss to
+      // the worker as if it were inaction
+      return { type: e.type, pass: false, fault: 'failed', detail: `no pre-step snapshot for ${e.scope} — the tree-changed instrument is unwired (instrument fault, not worker inaction)` };
+    }
+    const now = await snapshotScope(dir, e.scope);
+    // deletions count only WITHIN this exit's own scope: the step's `snapshot`
+    // is merged across every tree-changed scope, so an unscoped keys() walk
+    // would read a SIBLING scope's files (absent from this re-scan) as deletions
+    // and pass an unchanged scope by borrowing the other's change.
+    const prefix = globToPrefix(e.scope);
+    const underScope = (/** @type {string} */ p) => p === prefix || p.startsWith(`${prefix}/`);
+    let changed = 0;
+    for (const [path, hash] of now) if (snapshot.get(path) !== hash) changed++;
+    for (const path of snapshot.keys()) if (underScope(path) && !now.has(path)) changed++; // deletions are real changes
+    if (changed === 0) {
+      return { type: e.type, pass: false, detail: `0 files changed under ${e.scope} — the tree is byte-identical to the step start (an identical re-write is not a change)` };
+    }
+    return { type: e.type, pass: true, detail: `${changed} file(s) changed under ${e.scope}` };
+  }
+
+  if (e.type === 'json-valid') {
+    let body;
+    try { body = await readFile(join(dir, e.path), 'utf8'); } catch {
+      return { type: e.type, pass: false, detail: `${e.path} was not written (does not exist)` };
+    }
+    try { JSON.parse(body); } catch (err) {
+      return { type: e.type, pass: false, detail: `${e.path} is not valid JSON: ${String(/** @type {Error} */ (err).message).slice(0, 200)}` };
+    }
+    return { type: e.type, pass: true };
+  }
+
+  if (e.type === 'check-passes') {
+    if (typeof runCheck !== 'function') {
+      return { type: e.type, pass: false, fault: 'failed', detail: `check "${e.name}" cannot run — runCheck is not wired (instrument fault: an unrunnable check is a stop, never a silent pass)` };
+    }
+    try {
+      const r = await runCheck(e.name);
+      if (r.pass) return { type: e.type, pass: true };
+      // the seam's fault (a runClose forbidden-zone verdict) rides through by
+      // NAME: 'crashed' keeps its F32 routing (worker-crash after writes —
+      // the F46 broken-test mechanism), 'timed-out' keeps its own decision
+      if (typeof (/** @type {any} */ (r).fault) === 'string') {
+        return { type: e.type, pass: false, fault: /** @type {any} */ (r).fault, detail: `check "${e.name}": ${(r.gap ?? '').slice(0, CHECK_GAP_MAX)}` };
+      }
+      return { type: e.type, pass: false, detail: `check "${e.name}" red: ${(r.gap ?? '').slice(0, CHECK_GAP_MAX)}` };
+    } catch (err) {
+      return { type: e.type, pass: false, fault: 'failed', detail: `check "${e.name}" crashed the seam: ${String(/** @type {Error} */ (err).message).slice(0, 200)}` };
+    }
+  }
+
+  // belt — the validator already reds unknown types; the evaluator must not
+  // silently pass what it cannot judge
+  return { type: String(e.type), pass: false, fault: 'failed', detail: `unknown exit type "${e.type}" — the evaluator cannot judge it (fail closed)` };
+}

package/src/index.js

@@ -16,7 +16,13 @@ export { makeSpine } from './spine.js';
 // exports map admits only ".", so a deep import cannot reach them).
 export { ralph, runClose, CLOSE_FAULTS } from './ralph.js';
 export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS } from './job.js';
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
+// Layer 2: the plan-v1 validator — the agent-authored plan doc's gate; the
+// two-doc split's third validator never happens (plan-v1 gates the PLAN, the
+// job spec stays the arbiter's only home).
+export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from './plan.js';
+export { snapshotScope, evalExits } from './exits.js';
+export { runPlan } from './planrun.js';
 export { interpret, STALL_REDS } from './interpret.js';
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';
 export { runJob } from './run.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) */
 
@@ -41,18 +43,38 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
 // compound: that run's context grew 2k → 121k tokens and its last round cost $0.25.
 // Telling the worker it will be re-run with the close's verdict makes an early,
 // cheap, wrong attempt the rational move — which is exactly what the loop wants.
-const PERSONA_TOOLS = 'You are a senior engineer working in a repository through file tools. '
+export const PERSONA_TOOLS = 'You are a senior engineer working in a repository through file tools. '
   + 'ALWAYS use absolute paths — relative paths resolve against the process, not the repository, and will be denied. '
   + 'You are ONE attempt inside an automated loop: when you finish, a test suite runs and, if it still fails, you are called again with its output. '
   + 'So do not try to be certain before acting. Read only what you need to form your best hypothesis, make the change with the write tool, and stop. '
   + 'A wrong cheap attempt is corrected by the next round; exhaustive reading is not — every file you read is re-sent on every later round and the run has a hard budget it can exhaust before you ever write. '
   + 'Make the required changes with the write tool, then reply with a short summary of what you changed. Never put file contents in your reply.';
 
+// The retrieval verbs only pay if the worker reaches for them INSTEAD of paging a file.
+// F18 measured the failure they exist to fix: the worker read one 117 KB file NINE times
+// and dragged 1.37 MB of source through context to reach an 8-line function. The tool
+// descriptions carry the mechanics; the persona has to carry the STRATEGY, or a model
+// with a familiar `read` and an unfamiliar `recall` will simply keep reading.
+// (Module-level + exported since Layer 2: the plan-step worker shares the SAME
+// personas/strategies — two spellings of the loop contract would drift, F16.)
+export const RETRIEVAL_STRATEGY = '\nYou also have a repository index. To read a function, do NOT read its whole file: '
+  + 'call ctx_recall with the function name to get a pointer, then ctx_get with that pointer to read that function alone '
+  + '(it comes with its doc-comment, which states what the function is SUPPOSED to do — compare it against what the code does). '
+  + 'Reserve shell_read for whole files that are genuinely small, and for files you cannot name a symbol in yet. '
+  + 'Search only finds what you can NAME: a failing test names the symptom, not the cause, so read the failing test first, '
+  + 'see which function it calls, and recall THAT.';
+// BA-13: like retrieval, the edit verb only pays if the worker reaches for it INSTEAD
+// of a whole-file rewrite. F31 measured the default: 4 of 5 big-file whole-writes
+// broke the tree, and every one was a rewrite to change ~one line. The tool
+// description carries the mechanics; the persona carries the strategy.
+export const EDIT_STRATEGY = '\nPrefer the edit tool over whole-file writes: quote the EXACT text to change (it must match exactly once) and its replacement. '
+  + 'Rewriting a whole file to change one line is how trees get broken and budgets get burned — reserve the write tool for genuinely new files.';
+
 // ---- tool mode (2b): the spec-side grant menu mapped to the underlying tools ----
 // read/grep/write are bare-agent's shell tools; recall/get are litectx's retrieval
 // verbs (F19), composed from the SAME LiteCtx the memory hooks already use.
-const TOOL_BY_VERB = Object.freeze({ read: 'shell_read', grep: 'shell_grep', write: 'shell_write', edit: 'shell_edit', recall: 'ctx_recall', get: 'ctx_get' });
-const CTX_TOOLS = Object.freeze(['ctx_recall', 'ctx_get']);
+export const TOOL_BY_VERB = Object.freeze({ read: 'shell_read', grep: 'shell_grep', write: 'shell_write', edit: 'shell_edit', recall: 'ctx_recall', get: 'ctx_get' });
+export const CTX_TOOLS = Object.freeze(['ctx_recall', 'ctx_get']);
 
 /**
  * The retrieval pair (F19). `shell_read` cannot seek — it starts at byte zero — so a
@@ -68,7 +90,7 @@ const CTX_TOOLS = Object.freeze(['ctx_recall', 'ctx_get']);
  *   bad range) looks exactly like one that worked, and the worker's fallback to a
  *   whole-file read looks like a free choice instead of a forced one.
  */
-function createCtxTools(lc, workdir, emit) {
+export function createCtxTools(lc, workdir, emit) {
   return [
     {
       name: 'ctx_recall',
@@ -146,7 +168,7 @@ function createCtxTools(lc, workdir, emit) {
 /** @param {string} p */
 const expandHome = (p) => (p === '~' || p.startsWith('~/')) ? join(homedir(), p.slice(1)) : p;
 /** @param {string} name @param {any} args @param {string} [workdir] */
-const toolAction = (name, args, workdir) => {
+export const toolAction = (name, args, workdir) => {
   if (name === 'shell_write') return { type: 'write', path: resolve(expandHome(String(args?.path ?? ''))), args: { bytes: String(args?.content ?? '').length } };
   // shell_edit (BA-13) is judged as bareguard's own 'edit' action type — the SAME
   // fs.writeScope fence as write, decided upstream (bareguard FS_TYPES). `bytes` is
@@ -213,11 +235,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 +308,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 +333,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 +354,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
@@ -404,23 +578,6 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
     })()
     : [];
 
-  // The retrieval verbs only pay if the worker reaches for them INSTEAD of paging a file.
-  // F18 measured the failure they exist to fix: the worker read one 117 KB file NINE times
-  // and dragged 1.37 MB of source through context to reach an 8-line function. The tool
-  // descriptions carry the mechanics; the persona has to carry the STRATEGY, or a model
-  // with a familiar `read` and an unfamiliar `recall` will simply keep reading.
-  const RETRIEVAL_STRATEGY = '\nYou also have a repository index. To read a function, do NOT read its whole file: '
-    + 'call ctx_recall with the function name to get a pointer, then ctx_get with that pointer to read that function alone '
-    + '(it comes with its doc-comment, which states what the function is SUPPOSED to do — compare it against what the code does). '
-    + 'Reserve shell_read for whole files that are genuinely small, and for files you cannot name a symbol in yet. '
-    + 'Search only finds what you can NAME: a failing test names the symptom, not the cause, so read the failing test first, '
-    + 'see which function it calls, and recall THAT.';
-  // BA-13: like retrieval, the edit verb only pays if the worker reaches for it INSTEAD
-  // of a whole-file rewrite. F31 measured the default: 4 of 5 big-file whole-writes
-  // broke the tree, and every one was a rewrite to change ~one line. The tool
-  // description carries the mechanics; the persona carries the strategy.
-  const EDIT_STRATEGY = '\nPrefer the edit tool over whole-file writes: quote the EXACT text to change (it must match exactly once) and its replacement. '
-    + 'Rewriting a whole file to change one line is how trees get broken and budgets get burned — reserve the write tool for genuinely new files.';
   const usesCtx = toolDefs.some((/** @type {{name: string}} */ t) => CTX_TOOLS.includes(t.name));
   const usesEdit = toolDefs.some((/** @type {{name: string}} */ t) => t.name === 'shell_edit');
   const loop = new Loop({
@@ -428,6 +585,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 +734,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 +795,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 +848,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 });
   };