bareloop 0.2.0 → 0.4.0

package/src/interpret.js

@@ -12,25 +12,164 @@
 
 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}} CategorizedError the failure map's carrier: ralph relays by `category` */
+/** @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) */
 
 // consecutive close reds that count as a stall; one revision per run
 export const STALL_REDS = 2;
 
 const require = createRequire(import.meta.url);
 const { Loop, wireGate, HaltError } = require('bare-agent');
+const { createShellTools } = require('bare-agent/tools');
 
-import { stripFences } from './text.js';
+import { extractArtifact, priceOf } from './text.js';
 
 /** @typedef {{body?: string|null, text?: string|null}} RecallHit litectx recall hit — body present only with `{body: true}` */
 
 const PERSONA = 'You are a senior engineer. Reply with ONLY the complete contents of the requested JavaScript file — no markdown fences, no commentary. ESM.';
+// The tool persona states the LOOP CONTRACT (F16): the worker is one attempt inside
+// `while close-red and under-cap`, not a one-shot. Without knowing that, a model does
+// the rational one-shot thing — read everything, be certain, then act — and the real
+// run spent its ENTIRE budget on 12 rounds of reading without one write, never once
+// reaching the close. Every round re-pays for every earlier tool result, so reads
+// 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. '
+  + '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.';
+
+// ---- 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']);
+
+/**
+ * The retrieval pair (F19). `shell_read` cannot seek — it starts at byte zero — so a
+ * pointer at a symbol was inert and the worker paged whole files to reach one function.
+ * `ctx_recall` hands back a POINTER (no body: a search index returns pointers, and bodies
+ * on every hit rebuild the bloat — measured, a 5-hit recall dumps ~15k tokens unbidden);
+ * `ctx_get` trades that pointer for ONE chunk. A chunk starts at its doc-comment, so the
+ * body arrives WITH the docstring that says what it was supposed to do.
+ * @param {any} lc the run's LiteCtx (rooted at workdir)
+ * @param {string} workdir
+ * @param {(type: string, data: object) => void} emit the spine — a retrieval verb whose
+ *   RESULT is invisible cannot be judged: a `ctx_get` that silently reds (stale pointer,
+ *   bad range) looks exactly like one that worked, and the worker's fallback to a
+ *   whole-file read looks like a free choice instead of a forced one.
+ */
+function createCtxTools(lc, workdir, emit) {
+  return [
+    {
+      name: 'ctx_recall',
+      description: 'Search the repository index for a symbol or phrase. Returns POINTERS (path, symbol, line range) — not code. '
+        + 'Pass a pointer to ctx_get to read that one function. Search finds what you can NAME: it will not find a bug from a failing '
+        + "test's output (the symptom and the cause live in different files) — read the failing test first, then recall the function it calls.",
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Symbol name or phrase, e.g. "keywords" or "stopword filter".' },
+          n: { type: 'integer', description: 'Max pointers to return (default 5, max 20).' },
+        },
+        required: ['query'],
+      },
+      execute: async (/** @type {{query: string, n?: number}} */ { query, n }) => {
+        const hits = await lc.recall(String(query), { kind: 'code', n: Math.min(Math.max(Number(n) || 5, 1), 20) });
+        const out = hits.length
+          ? hits.map((/** @type {any} */ h) => (h.chunk
+            ? `${h.path}\t${h.chunk.symbol ?? '(anonymous)'}\t${h.chunk.nodeType}\tlines ${h.chunk.startLine}-${h.chunk.endLine}`
+            : `${h.path}\t(whole file — no chunk)`)).join('\n')
+          : 'no hits';
+        emit('ctx-tool', { tool: 'ctx_recall', query: String(query), hits: hits.length, paths: hits.map((/** @type {any} */ h) => h.path), bytes: Buffer.byteLength(out) });
+        return out;
+      },
+    },
+    {
+      name: 'ctx_get',
+      description: 'Read ONE function by the line range ctx_recall gave you — code plus its doc-comment, without the rest of the file. '
+        + 'The line range is a HANDLE you copy from ctx_recall, never one you compute: a range that is not a chunk boundary is refused, '
+        + 'and a file edited since it was indexed is refused (re-run ctx_recall for a fresh pointer).',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Repository-relative path, exactly as ctx_recall printed it.' },
+          startLine: { type: 'integer', description: 'From ctx_recall.' },
+          endLine: { type: 'integer', description: 'From ctx_recall.' },
+        },
+        required: ['path', 'startLine', 'endLine'],
+      },
+      execute: async (/** @type {{path: string, startLine: number, endLine: number}} */ { path: p, startLine, endLine }) => {
+        // The path is spelled as recall printed it (repo-relative); the gate judges the
+        // resolved absolute path, exactly as toolAction resolves it. Boundary-aware
+        // prefix (workdir + sep, the line-247 pattern): bare startsWith would garble a
+        // sibling like `${workdir}-backup/x` into `ackup/x` — the gate independently
+        // denies such a path before execute() runs, so this is defense in depth only.
+        const rel = String(p).startsWith(workdir + sep) ? String(p).slice(workdir.length + 1) : String(p);
+        try {
+          const item = lc.get(rel, { startLine: Number(startLine), endLine: Number(endLine) });
+          if (!item?.text) {
+            emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'no-chunk', bytes: 0 });
+            return `no chunk at ${startLine}-${endLine} in "${rel}" — copy a line range from ctx_recall, do not compute one`;
+          }
+          emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'ok', bytes: Buffer.byteLength(item.text) });
+          return item.text;
+        } catch (e) {
+          // StalePointerError: the file changed after indexing, so these lines now describe
+          // DIFFERENT code. Its message IS the recovery instruction — hand it to the worker.
+          const detail = String(/** @type {Error} */ (e)?.message || e);
+          emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'stale', bytes: 0, detail });
+          return `stale pointer: ${detail}`;
+        }
+      },
+    },
+  ];
+}
+
+// The load-bearing containment line (2b POC, scenario B): bare-agent's built-in
+// tools are deliberately ungated and their action type is their own NAME, which
+// never trips bareguard's fs primitives — this translator maps them onto
+// write/read actions so the SAME fence text mode enforces manually governs
+// every tool call. Paths resolve exactly as the tools resolve them
+// (path.resolve(expandHome(p)), POC scenario F) so the gate judges the same
+// file the tool would touch; a relative spelling resolves against the process
+// cwd and reds at the fence, and the deny reason teaches the retry.
+/** @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) => {
+  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
+  // the replacement's size so the audit can read the edit economy (a 40-byte splice
+  // vs an 8KB rewrite is the variable BA-13 exists to move — F18 blindness rule).
+  if (name === 'shell_edit') return { type: 'edit', path: resolve(expandHome(String(args?.path ?? ''))), args: { bytes: String(args?.newText ?? '').length } };
+  // `tool` rides the action so the AUDIT can tell the read tools apart. Without it every
+  // read tool collapses to {type:'read', path} and a whole-file shell_read is
+  // indistinguishable from a bounded ctx_get chunk — the ledger cannot see the one
+  // variable the retrieval arm exists to test (the F18 blindness, repeated).
+  if (name === 'shell_read' || name === 'shell_grep') return { type: 'read', path: resolve(expandHome(String(args?.path ?? ''))), args: { tool: name } };
+  // The retrieval verbs are READS and are judged as reads by the SAME fence (F14/F19):
+  // ctx_get names a file, so the gate judges that file — the deny list (gate audit,
+  // primitive smoke, the litectx store itself) applies to a chunk read exactly as it
+  // applies to shell_read, or the worker would read the arbiter's books through the
+  // other door. ctx_recall names no file: it is a read OF THE INDEX, judged against the
+  // run directory, so it is contained by readScope and cannot reach outside the repo.
+  if (name === 'ctx_get') return { type: 'read', path: resolve(String(workdir ?? ''), expandHome(String(args?.path ?? ''))), args: { tool: name } };
+  if (name === 'ctx_recall') return { type: 'read', path: resolve(String(workdir ?? '')), args: { tool: name } };
+  return { type: name, args };
+};
 
 /**
  * Execute a workflow config against one task under the dumb shell.
@@ -38,13 +177,26 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
  * @param {object|string} configRaw schema v1 config (object or raw JSON text)
  * @param {object} opts
  * @param {string} opts.task implement instruction shown to the worker
- * @param {string} opts.target absolute path the artifact is written to
+ * @param {string} [opts.target] absolute path the artifact is written to —
+ *        required in text mode; unused in tool mode (the worker writes through
+ *        the gated tools, wherever the fence allows)
  * @param {string[]} opts.close argv whose exit code is truth (shell-owned)
+ * @param {number} [opts.closeExpect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.closeJudged] the signed spec's
+ *   judgment-rendered signal — proof the close actually judged something before
+ *   its exit code is believed in EITHER direction (PRD v1.11; the drafted config
+ *   cannot express it, and must not: it is the arbiter's own honesty check)
+ * @param {string} [opts.closeGapKeep] the signed spec's kept-failures pattern (F28):
+ *   close-output lines matching it survive the gap bound, so a large suite's
+ *   `not ok` names reach the worker instead of being elided into "N fail" — also
+ *   arbiter territory, inexpressible in the drafted config
  * @param {string} opts.workdir run directory (litectx root, gate audit, scope base)
  * @param {number} opts.capRuns shell iteration budget; the config may tighten via loop.maxIterations, never exceed
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
- * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {number} [opts.shellCapUsd=2] the shell's USD cap; a config budgetUsd above it REDS at validation (bounds — no silent clamping)
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap, threaded to the shell
+ *        (shell/operator territory — the workflow config cannot express it)
  * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
  *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
  *        every workflow scope must fit inside it (scope-escape config-red otherwise),
@@ -56,9 +208,32 @@ const PERSONA = 'You are a senior engineer. Reply with ONLY the complete content
  *        (arbiter-touch / cap-touch revision-reds otherwise; the run continues on the old
  *        config). Revisor spend rides the run's own gate handlers — same budget axis as
  *        the worker.
+ * @param {string} [opts.closeState] the close's CURRENT output on the tree as it stands
+ *        (the shell's pre-token close check, F13) — shown to the first attempt only, and
+ *        never framed as an attempt: the worker cannot run the close itself (`run` is a
+ *        locked verb), so without this it is asked to fix a failure it cannot see
+ * @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 }) {
+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,
+  // so nothing downstream catches it before writeFileSync(undefined)).
+  if (mode === 'text' && (typeof target !== 'string' || !target)) {
+    throw new TypeError('interpret: text mode requires target (the absolute artifact path)');
+  }
   // Normalize ONCE: a trailing slash or a relative spelling must mean the same
   // directory everywhere below — the enforcement belt compares string prefixes,
   // and "/run/" vs "/run" would false-red every legal scope (release review).
@@ -87,41 +262,397 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
     emit('run-end', { outcome: 'config-red', iterations: 0 });
     return 'config-red';
   }
+  // The attempt's round bound — ONE number for the Gate's run-wide maxTurns and the
+  // per-attempt cutoff below (two literals here once drifted apart in kind: the
+  // advertised/enforced class). 24→40 on hamr's word 2026-07-16 (TESTGEN amendment
+  // 2026-07-16e): the curve measured that prompting cannot buy readability at 24 —
+  // the read-first prelude eats the window before the first write.
+  const TURNS_PER_ATTEMPT = mode === 'tools' ? 40 : 8;
   const gate = new Gate({
     // bareguard fs.writeScope is prefix-containment, not glob (adaptlearn F4); globToPrefix
     // is the ONE transform shared with the validator's legality rule — mid-path wildcards
     // and workdir-escaping scopes were already rejected up front (adaptlearn F9, law #1).
-    fs: { writeScope: resolvedScopes },
+    // Tool mode adds readScope: the worker's reads stay inside the run directory —
+    // the stray-read secrets channel (~/.ssh, /etc) closes with one field (2b POC D).
+    // Tool mode adds readScope (the stray-read secrets channel, 2b POC D) AND
+    // deny (F14): readScope is the whole workdir, which CONTAINS the run's own
+    // machinery — the gate's audit ledger, the primitive-smoke store, the litectx
+    // memory store. The real run's worker read its own gate audit and spine. The
+    // emergent middle does not author the arbiter, and it does not get to read the
+    // arbiter's books either: that is an invitation to fit-to-pass and it fills the
+    // context with the run's own bookkeeping instead of the repository's code.
+    fs: {
+      writeScope: resolvedScopes,
+      ...(mode === 'tools'
+        ? { readScope: [workdir], deny: [join(workdir, 'gate-audit.jsonl'), join(workdir, '.smoke'), join(workdir, '.litectx')] }
+        : {}),
+    },
     budget: { maxCostUsd: config.gate.budgetUsd },
-    limits: { maxTurns: 8 * (capRuns + 1) },
+    // 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
   });
   await gate.init();
-  const { policy, onLlmResult } = wireGate(gate);
-  const loop = new Loop({ provider, system: PERSONA, policy, onLlmResult });
+  // The crash-attribution instrument (F32): which files has the worker written this
+  // run? Answered from the arbiter's OWN books — the gate audit's allow-decision
+  // write lines, run_id-scoped because the audit file appends across steps and runs.
+  // Both middles land here: tool-mode writes are policy-checked, text-mode writes go
+  // through gate.check. Read on demand (only ever at a crashed verdict) and
+  // fail-closed: an unreadable audit attributes nothing, so the crash escalates
+  // 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();
+      for (const line of readFileSync(auditPath, 'utf8').split('\n')) {
+        if (!line) continue;
+        let rec;
+        try { rec = JSON.parse(line); } catch { continue; }
+        if (rec.run_id === gate.runId && rec.phase === 'gate' && rec.decision === 'allow'
+            && (rec.action?.type === 'write' || rec.action?.type === 'edit')
+            && typeof rec.action.path === 'string') paths.add(rec.action.path);
+      }
+      return [...paths];
+    } catch { return []; }
+  };
+  // 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
+  // halted attempt and the job ledger reported $0.0048. `onLlmResult` is the one
+  // seam that sees every round, and it fires BEFORE the gate records the round —
+  // so even the round that trips the cap lands on the spine. Emitted first, then
+  // forwarded verbatim: the gate's own accounting is never altered. costUsd/
+  // pricing ride AS-IS (a null is the honest unknown, never $0 — F6).
+  /** @type {number|undefined} the attempt a round belongs to (display only) */
+  let roundIteration;
+  // F20 — THE ATTEMPT HAD NO BOUND, so ralph never ralphed. `limits.maxTurns` is bareguard's,
+  // and the Gate is constructed ONCE for the whole RUN: it is a run-wide HALT, not a
+  // per-attempt cap. Nothing else ended an attempt — a tool-mode attempt ran until the model
+  // CHOSE to stop calling tools. A worker that has never been told it is wrong does not stop:
+  // measured, attempt #1 ran 55 rounds, spent the entire $1.50 budget, and the close NEVER RAN
+  // ONCE (zero verdicts, zero gaps, zero writes). The loop's whole premise — a cheap wrong
+  // attempt corrected by the next round — was unreachable, and the persona's promise ("a test
+  // suite runs and you are called again") was a lie the shell never kept.
+  // `loop.stop()` breaks at the round boundary and — since bare-agent 0.27.0 (BA-3/BA-5) —
+  // returns the transcript with `error: null` and the produced text preserved, so the attempt
+  // ends cleanly, its summary stands, and the close renders the verdict that feeds the next
+  // attempt. (Before 0.27.0 stop() fell through to a HARD_ROUND_LIMIT return carrying a bogus
+  // error, which bareloop had to un-lie behind a `stoppedByBound` flag — the upgrade removed
+  // both the lie and the shim; see ask().) Per-attempt, because each attempt is a FRESH
+  // conversation (the context resets), which is what keeps four bounded attempts inside a
+  // budget one unbounded attempt exhausts.
+  /** rounds spent inside the CURRENT attempt (reset per attempt, unlike the gate's run-wide tick) */
+  let roundsThisAttempt = 0;
+  /** @type {number|undefined} the attempt that was cut short by the bound (spine + gap note) */
+  let attemptBounded;
+  /** true while the REVISOR holds the metered handler: its rounds are real money on
+   * the run's axis (F12) but they are not the WORKER's rounds, and charging them to
+   * the per-attempt bound silently handed the worker 40−R turns while the prompt
+   * still advertised 40 (advertised == enforced, PRD; a revisor that burned the whole
+   * bound stopped the worker loop before its first tool call) */
+  let inRevisor = false;
+  // `tokens` alone cannot answer the question the ledger exists to answer.
+  // bare-agent's `inputTokens` is the UNCACHED prompt remainder — re-sent context
+  // is billed as a cache READ and never appears in it. So a round that re-pays for
+  // half the repo and a round that reads it fresh can carry the same `tokens`, at
+  // very different cost. Record the four tiers the provider actually prices
+  // separately, and record the `kind` (a summarizer fold is an LLM call too, and
+  // must never hide inside the worker's own numbers).
+  /** @param {{costUsd?: number|null, pricing?: string|null, usage?: any, kind?: string}} arg */
+  const meteredOnLlmResult = async (arg) => {
+    const u = arg?.usage ?? {};
+    emit('worker-round', {
+      iteration: roundIteration,
+      kind: arg?.kind ?? 'turn',
+      costUsd: arg?.costUsd ?? null,
+      pricing: arg?.pricing ?? null,
+      tokens: (u.inputTokens ?? 0) + (u.outputTokens ?? 0),
+      usage: {
+        inputTokens: u.inputTokens ?? 0,
+        outputTokens: u.outputTokens ?? 0,
+        cacheReadTokens: u.cacheReadTokens ?? 0,
+        cacheCreationTokens: u.cacheCreationTokens ?? 0,
+      },
+    });
+    // The attempt's own bound (F20). A summarizer fold is an LLM call but not a worker
+    // ROUND — counting it would let a fold shorten the attempt that paid for it. The
+    // revisor is the same case wearing `kind: 'turn'`: metered above, never charged here.
+    if ((arg?.kind ?? 'turn') === 'turn' && mode === 'tools' && !inRevisor) {
+      roundsThisAttempt += 1;
+      if (roundsThisAttempt >= TURNS_PER_ATTEMPT) {
+        // Clean stop at the round boundary: since 0.27.0 (BA-3/BA-5) run() returns the
+        // transcript with error=null and the text preserved, so this is an attempt that
+        // ENDED, not one that FAILED. The close now runs and its verdict becomes the next
+        // attempt's gap — which is the entire point.
+        attemptBounded = roundIteration;
+        emit('attempt-bounded', { iteration: roundIteration, rounds: roundsThisAttempt, cap: TURNS_PER_ATTEMPT });
+        loop.stop();
+      }
+    }
+    return onLlmResult(arg);
+  };
+  // The offered tools ARE the grant (2b decision #2): an ungranted tool is never
+  // in the menu the model sees — a call to it is "unknown tool", not a deny.
+  const toolDefs = mode === 'tools'
+    ? await (async () => {
+      const granted = new Set((tools ?? Object.keys(TOOL_BY_VERB)).map((v) => /** @type {Record<string, string>} */ (TOOL_BY_VERB)[v]));
+      const shell = createShellTools().tools.filter((/** @type {{name: string}} */ t) => granted.has(t.name));
+      const ctx = CTX_TOOLS.some((t) => granted.has(t))
+        ? createCtxTools(lc, workdir, emit).filter((t) => granted.has(t.name))
+        : [];
+      // A retrieval verb with no index is a tool that always answers "no hits". Index is
+      // incremental (unchanged files skipped) and BM25-only: measured on the real repo, the
+      // semantic tier costs 26s of embedding and does NOT find a symbol the lexical tier
+      // misses (for code it only RE-RANKS a BM25-gated pool — it cannot nominate), and it
+      // demoted the exact-symbol hit from rank 1 to rank 4. Lexical is the better instrument here.
+      if (ctx.length) await lc.index();
+      return [...shell, ...ctx];
+    })()
+    : [];
+
+  // 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({
+    provider,
+    system: mode === 'tools' ? PERSONA_TOOLS + (usesEdit ? EDIT_STRATEGY : '') + (usesCtx ? RETRIEVAL_STRATEGY : '') : PERSONA,
+    policy,
+    onLlmResult: meteredOnLlmResult,
+    onToolResult: onToolOutcome,
+  });
 
   /** @param {string} slot */
   const slotOps = (slot) => config.hooks?.[slot] ?? [];
   /** @param {{kinds?: string[]}} op */
   const recallKinds = (op) => op.kinds ?? config.memory.recall?.kinds ?? ['fact'];
 
-  /** @param {string} prompt */
-  async function ask(prompt) {
+  /**
+   * @param {string} prompt
+   * @param {typeof toolDefs} [defs] the tool menu for THIS call — defaults to the
+   *   step's grant; the plan-only call passes [] (its own prompt says "no code",
+   *   and the menu is the grant: a tool it isn't offered cannot be called)
+   */
+  async function ask(prompt, defs = toolDefs) {
     let r;
     try {
-      r = await loop.run([{ role: 'user', content: prompt }]);
+      // cacheMessages (BA-1, bare-agent 0.27.0): roll an Anthropic cache breakpoint onto the
+      // transcript so a tool loop stops re-buying its whole growing history at full price every
+      // round — F18 measured 754k full-price tokens, $1.55, and the job died at the cap without
+      // one write. Opt-in and provider-routed (loop.run forwards options to generate): a
+      // non-Anthropic binding ignores it, and it is safe because bareloop wires no trim/compaction
+      // fold — the one interaction (a fold that rewrites the cached prefix) that would defeat it.
+      // maxTokens (F30): the provider's 4096 default cannot hold a whole-file
+      // shell_write of a real source file — the API cuts the round, BA-6 surfaces
+      // `truncated:max_tokens`, and doctrine reads it provider-red: run over.
+      // Battery pass 1 lost 3/3 rows to exactly this. Output budget is shell
+      // territory (never the config's); 32k fits any single-file write the
+      // writeScope admits, and output tokens are only paid when generated.
+      r = await loop.run([{ role: 'user', content: prompt }], defs, { cacheMessages: true, maxTokens: 32000 });
     } catch (e) {
-      if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt'; // belt: bare-agent's contract could change
-      throw e;
+      const err = /** @type {CategorizedError} */ (e);
+      // A throw OUT OF loop.run() is provider/loop territory by definition — the
+      // interpreter's own code is not on that stack. The real run died `read
+      // ENETUNREACH` mid-call and was filed interpreter-red ("fix the middle"),
+      // when the honest decision was "the network failed — retry" (F11). A
+      // governance halt keeps its own category; everything else is provider-red,
+      // the same class the drafting path already names.
+      err.category = e instanceof HaltError ? 'cap-halt' : (err.category ?? 'provider-red');
+      throw err;
     }
     // bare-agent NEVER throws HaltError out of run() — a governance halt comes
     // back as an error RETURN ({text: '', error: 'halt:<rule>'}; loop.js: "no
     // throw even when throwOnError: true"). Read it, or the failure map goes
     // blind and a cap story masquerades as a worker result (design law #8).
+    // A denial streak ('denied:<tool>', BA-11) is a governance deny, not a
+    // broken interpreter — gate-red, same category as text mode's fence deny.
+    // A TRUNCATED round ('truncated:max_tokens', BA-6, bare-agent 0.27.0) is the
+    // API cutting the generation off at the output cap — not a middle fault. It is
+    // provider-red (retry), the same class as an ENETUNREACH transport failure
+    // (F11): no verdict exists and the failed round's spend is only partly known.
+    // Before 0.27.0 this round was laundered into a clean finish with error:null
+    // (F25) — every prior sonnet arm ran on that bug; the fix surfaces it as its
+    // own error, so the middle can escalate instead of scoring an empty attempt.
+    // OUR OWN stop is not a fault (F20), and since 0.27.0 (BA-3/BA-5) `loop.stop()`
+    // returns `error: null` with the run's text preserved — so a bounded attempt
+    // lands on the clean-return path below with no special-casing (the 0.26.2
+    // `stoppedByBound` shim that un-lied the HARD_ROUND_LIMIT return is gone).
     if (r.error) {
       const err = /** @type {CategorizedError} */ (new Error(`worker loop: ${r.error}`));
-      err.category = r.error.startsWith('halt:') ? 'cap-halt' : 'interpreter-red';
+      err.category = r.error.startsWith('halt:') ? 'cap-halt'
+        : r.error.startsWith('denied:') ? 'gate-red'
+        : r.error.startsWith('truncated:') ? 'provider-red'
+        : 'interpreter-red';
+      // Attribute at the THROW site, where the owner is known, instead of
+      // leaving the ledger to sniff the prose downstream: this error came out
+      // of bare-agent's loop, whatever words it happens to carry. A litectx
+      // hook throw (runOps) reaches the same escalation with no lib field and
+      // keeps its verb→lib mapping. Review 2026-07-18: prose-sniffing billed a
+      // transport failure to litectx whenever the text said "recall".
+      err.lib = 'bare-agent';
       throw err;
     }
     return r;
@@ -141,7 +672,10 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
         }
         context.text = hits.map((h) => h.body ?? h.text ?? '').filter(Boolean).join('\n');
         context.level = null;
-        emit('hook-op', { slot, op: 'recall', hits: hits.length, iteration });
+        // paths ride on the event: a recall whose CONTENT is invisible blinds every
+        // downstream instrument to what the worker was handed (F33 — P5's green looked
+        // like an impossible sight-unseen edit until recall_log forensics explained it)
+        emit('hook-op', { slot, op: 'recall', hits: hits.length, paths: hits.map((h) => /** @type {any} */ (h).path).filter(Boolean), iteration });
       } else if (op.op === 'compress') {
         const level = op.level ?? config.memory.compressLevel ?? 'verbatim';
         if (context.text) context.text = await compress({ text: context.text, format: 'js' }, { level });
@@ -150,7 +684,11 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
         if (gap) lc.stash(`gap-${iteration}`, gap);
         emit('hook-op', { slot, op: 'stash', iteration });
       } else if (op.op === 'remember') {
-        await lc.remember(`green-${iteration ?? 'final'}-${target.split('/').at(-1)}`, readFileSync(target, 'utf8'), { kind: op.kind ?? 'fact' });
+        // tool mode has no single target to read back — the green's retained
+        // form is the worker's own change summary (its final loop text), which
+        // is what a future recall can actually use
+        const content = mode === 'tools' ? (lastText ?? '') : readFileSync(/** @type {string} */ (target), 'utf8');
+        await lc.remember(`green-${iteration ?? 'final'}-${mode === 'tools' ? 'tools' : /** @type {string} */ (target).split('/').at(-1)}`, content, { kind: op.kind ?? 'fact' });
         emit('hook-op', { slot, op: 'remember' });
       }
     }
@@ -182,11 +720,22 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
   /** @type {string[]} */
   const gaps = [];
   let revised = false;
+  /** @type {string|undefined} set on artifact-red, consumed by the next attempt's prompt */
+  let artifactNote;
+  /** @type {string|undefined} tool mode: the last attempt's summary text (retention source) */
+  let lastText;
   /**
    * @param {number} iteration
    * @param {string} [gap]
    */
   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 });
@@ -196,41 +745,108 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
         // the run's own gate handlers ride along: revisor spend hits the same
         // budget axis as the worker; a budget halt mid-revision is a cap story,
         // not a revision bug
-        rv = await revisor({ config, gaps: [...gaps], policy, onLlmResult });
+        // the METERED handler: revisor rounds are real money on the same axis (F12)
+        inRevisor = true;
+        rv = await revisor({ config, gaps: [...gaps], policy, onLlmResult: meteredOnLlmResult });
       } catch (e) {
         if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt';
         throw e;
+      } finally {
+        // `finally`, not a trailing assignment: a revisor that throws (cap-halt is
+        // the expected one) must not leave the worker's rounds uncounted for the
+        // rest of the run — that would turn this fix into an unbounded attempt.
+        inRevisor = false;
       }
       const rr = acceptRevision(rv.candidate);
       if (rr.red) {
-        emit('revision-red', { iteration, ...rr.red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? 0 });
+        // `?? null`, never `?? 0`: an unpriced revisor's spend is UNKNOWN, and
+        // the spine is the permanent record (F6 — the cap is governed honestly
+        // by the metered worker-round path, but $0 on the record is a lie).
+        emit('revision-red', { iteration, ...rr.red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? null });
       } else {
-        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rr.config), costUsd: rv.costUsd ?? 0 });
+        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rr.config), costUsd: rv.costUsd ?? null });
         config = rr.config;
       }
     }
     if (gap) await runOps('after-red', { iteration, gap, context: {} });
     const context = {};
     await runOps('before-attempt', { iteration, context });
-    const parts = [task, context.text && `Possibly relevant notes:\n${context.text}`, gap && `Previous attempt failed the test suite:\n${gap}`];
+    // F10 (first real-model run): a tool-mode worker must be TOLD where the
+    // repository is. The persona demands absolute paths, but bare-agent's shell
+    // tools resolve relative paths against the PROCESS cwd — not the workdir —
+    // so a worker with no root is working blind: the real run groped for the repo
+    // (/home/hamr, the runner's own directory, then /) and the fence denied every
+    // guess until the denial streak stopped it. Containment held; the task was
+    // impossible. Text mode is told nothing: it has no tools to point anywhere,
+    // and the shell alone chooses its one target.
+    // (parts[0] stays the task: the plan shape re-orders around it)
+    const parts = [
+      task,
+      mode === 'tools' && `Repository root (absolute): ${workdir}\nEvery path you pass to a tool MUST be absolute and inside this root — a relative path resolves against a different directory and will be denied by the gate.`,
+      // F13: what the close says about the tree RIGHT NOW — the state a human
+      // maintainer reads first. Given only until an attempt of our own exists
+      // (then `gap` is the truer, attributable evidence). The real run withheld
+      // this on the grounds that "no attempt has happened", and the worker — which
+      // cannot run the suite itself, the `run` verb being locked — groped through
+      // the repository and burned the entire cap without one write. Attributing an
+      // 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
+      // the next attempt investigating exactly as far and stopping exactly as short.
+      attemptBounded !== undefined && attemptBounded === iteration - 1
+        && `Your previous attempt was CUT OFF after ${TURNS_PER_ATTEMPT} tool rounds without making a change. Reading is bounded; writing is not. `
+          + `Form a hypothesis EARLY and make the edit — a wrong cheap edit is corrected by the next round, but an attempt that never writes teaches this loop nothing.`];
 
     if (config.loop.shape === 'plan') {
       // plan-then-execute: one call to decompose, one to implement following the plan
-      const p = await ask([`Produce a SHORT numbered implementation plan (2-4 steps) for this task. Plan only, no code.`, ...parts.slice(1), parts[0]].filter(Boolean).join('\n\n'));
-      emit('worker-plan', { iteration, costUsd: p.metrics?.costUsd ?? p.cost ?? null }); // metrics.costUsd carries the honest null when unpriced; cost sums priced rounds only
+      // Plan only, no code — so no tools either: the menu IS the grant (2b), and a
+      // plan call offered shell_write can mutate the tree before the implement
+      // round exists (release review 2026-07-19; unexercised combination until then)
+      const p = await ask([`Produce a SHORT numbered implementation plan (2-4 steps) for this task. Plan only, no code.`, ...parts.slice(1), parts[0]].filter(Boolean).join('\n\n'), []);
+      emit('worker-plan', { iteration, ...priceOf(p) }); // priceOf: the ONE honest-null cost read (F6)
       parts.push(`Follow this plan:\n${p.text}`);
     }
     const r = await ask(parts.filter(Boolean).join('\n\n'));
-    emit('worker-result', { iteration, costUsd: r.metrics?.costUsd ?? r.cost ?? null, tokens: r.usage?.outputTokens ?? null });
+    emit('worker-result', { iteration, ...priceOf(r), toolCalls: r.metrics?.toolCalls ?? 0, tokens: r.usage?.outputTokens ?? null });
+
+    // Tool mode: the worker already wrote through the gated tools (every call
+    // policy-checked against the fence); its final text is a change summary,
+    // not an artifact — there is nothing to extract and artifact-red genuinely
+    // does not exist here (2b decision #3). The close judges the tree as-is.
+    if (mode === 'tools') {
+      lastText = r.text ?? '';
+      return;
+    }
 
-    const decision = await gate.check({ type: 'write', path: target, args: { bytes: r.text.length } });
+    // Fence-robust extraction BEFORE the gate: what gets written is the
+    // artifact, not the response (F2 #2). A response with no artifact reds on
+    // its OWN axis — artifact-red — and writes nothing: the close will red
+    // against the stale/missing target, but the spine names the true cause,
+    // so the contrast evidence stays clean (F21's instrument caveat).
+    const ex = extractArtifact(r.text);
+    if (ex.red) {
+      emit('artifact-red', { iteration, category: 'artifact-red', reason: ex.red });
+      artifactNote = `your response was rejected as a non-artifact (${ex.red}) — emit ONLY the code artifact`;
+      return; // retryable: the next attempt carries the note; ralph's cap still governs
+    }
+    artifactNote = undefined;
+    const code = /** @type {string} */ (ex.code); // non-null: ex.red was checked above
+    const t = /** @type {string} */ (target); // text mode contract: target is required
+    const decision = await gate.check({ type: 'write', path: t, args: { bytes: code.length } });
     if (decision.outcome !== 'allow') {
-      const err = /** @type {CategorizedError} */ (new Error(`gate ${decision.outcome} write to ${target} (${decision.rule ?? 'no rule'})`));
+      const err = /** @type {CategorizedError} */ (new Error(`gate ${decision.outcome} write to ${t} (${decision.rule ?? 'no rule'})`));
       err.category = decision.severity === 'halt' ? 'cap-halt' : 'gate-red';
       throw err;
     }
-    writeFileSync(target, stripFences(r.text));
-    emit('artifact-written', { iteration, path: target });
+    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 });
   };
 
   // the config may tighten the shell's iteration budget, never exceed it (mirrors budgetUsd)
@@ -241,7 +857,14 @@ export async function interpret(configRaw, { task, target, close, workdir, capRu
   // pass a shape detection reds (a git close echoing a ghp_ token was the gap).
   // Injected here (the layer that owns bareguard) so ralph stays stdlib-only and
   // the scrub is a fixed shell primitive, not an emergent component (V4 holds).
-  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit, redact: (/** @type {string} */ s) => redact(s, { patterns: SECRET_PATTERNS }) });
+  // cwd: workdir — the close judges the tree the work happened in (F8). A close
+  // is a repository command (`npm test`); run from anywhere else it silently
+  // judges another repo and exit-code-is-truth stops being true.
+  // expect/judged/gapKeep are the SIGNED spec's, threaded verbatim — the drafted
+  // config cannot express any of them (they are arbiter territory, PRD v1.11; F28
+  // for gapKeep, which keeps a large suite's failure NAMES in the gap the worker
+  // sees instead of letting the bound elide them into a bare "N fail").
+  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit, closeTimeoutMs, cwd: workdir, expect: closeExpect, judged: closeJudged, gapKeep: closeGapKeep, workerWrites, redact: (/** @type {string} */ s) => redact(s, { patterns: SECRET_PATTERNS }) });
   if (outcome === 'green') {
     // The close already passed — a retention hiccup must not un-green a real
     // green (it would corrupt the learning curve). It degrades loudly: