bare-agent 0.28.0 → 0.30.0

package/README.md

@@ -94,7 +94,7 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 
 ### Recurse — break a hard task into a tree *(the RLM primitive)*
 
-`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. Give workers a stance with `opts.persona` (prepended to every worker, carries down the tree, deliberately kept out of the isolated verifier), and tell them *where they are* with `opts.context` (a read-only paths/cwd blob threaded to every worker so a sliced child can locate its artifact — facts, not a stance). For a leaf that should self-correct, pass `opts.refineLeaf` (opt-in): a definite leaf becomes a bounded generate→sense→regenerate loop driven by *your* deterministic sensor (test/compile/lint), feeding the gap back (with escalating temperature on models that accept it; on a temperature-fixed model like `claude-sonnet-5` the gap critique carries recovery, and the receipt records the effective temps). The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
+`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. Give workers a stance with `opts.persona` (prepended to every worker, carries down the tree, deliberately kept out of the isolated verifier), and tell them *where they are* with `opts.context` (a read-only paths/cwd blob threaded to every worker so a sliced child can locate its artifact — facts, not a stance). For a leaf that should self-correct, pass `opts.refineLeaf` (opt-in): a definite leaf becomes a bounded generate→sense→regenerate loop driven by *your* deterministic sensor (test/compile/lint — one that judges the *returned* result, never a worker side-effect it could game), feeding the gap back (with escalating temperature on models that accept it; on a temperature-fixed model like `claude-sonnet-5` the gap critique carries recovery, and the receipt records the effective temps). On a temperature-fixed model, `refineLeaf.rejectedBuffer` adds a second lever — it feeds the model's own prior *failed attempts* back verbatim ("write something structurally different"), the directed-diversity complement to temperature's random diversity (adaptive by default; the two are antagonistic, so it holds temperature flat when it engages). The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
 
 Over a corpus, context reaches a worker as a **handle routed by question shape** (`opts.retrieval`):
 
@@ -161,6 +161,7 @@ const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate, {
     if (toolName === 'shell_exec') return { type: 'bash', args, _ctx: ctx };
     if (toolName === 'shell_read') return { type: 'read', args, _ctx: ctx };
     if (toolName === 'shell_write') return { type: 'write', args, _ctx: ctx }; // gate by fs.writeScope
+    if (toolName === 'shell_edit')  return { type: 'edit',  args, _ctx: ctx }; // same fs.writeScope as write
     return defaultActionTranslator(toolName, args, ctx);
   },
 });

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.28.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.30.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -38,7 +38,7 @@ Eight entry points:
 | Count / answer "how many / all" over a corpus, honestly | recurse(task, ctx, `{ corpus, retrieval: 'scan' }`) — scans every slice, CODE-counts |
 | Give recurse workers a persona/role (senior-dev stance) | recurse(task, ctx, `{ persona }`) — prepended to every worker, carries down the tree; not applied to the verifier |
 | Tell recurse workers WHERE they are (paths/cwd) so a slice can find its file | recurse(task, ctx, `{ context }`) — read-only blob on every worker's task message + the Planner + verifier; carries down (facts, not a stance) |
-| Let a recurse LEAF retry its own failure with a deterministic check | recurse(task, ctx, `{ refineLeaf: { sensor } }`) — leaf becomes a bounded generate→sense→regenerate loop; your sensor (test/compile/lint), gap fed back, escalating temperature |
+| Let a recurse LEAF retry its own failure with a deterministic check | recurse(task, ctx, `{ refineLeaf: { sensor } }`) — leaf becomes a bounded generate→sense→regenerate loop; your sensor (test/compile/lint) judges the RETURNED result, gap fed back, escalating temperature; `rejectedBuffer` feeds prior failed attempts back on a temp-fixed model |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |
 | Require human approval before dangerous actions | Checkpoint |
@@ -65,7 +65,8 @@ Eight entry points:
 | Assess website privacy risk | createBrowsingTools + Loop (requires `npm install wearehere`) |
 | Control Android/iOS devices | createMobileTools + Loop |
 | Control mobile (token-efficient, disk-based) | `baremobile` CLI session — snapshots to `.baremobile/*.yml` |
-| Read/write files, list directories, run shell commands, grep | createShellTools (shell_read/grep/**write**/run/exec) + Loop({ policy }) — gate `shell_write` via `fs.writeScope` with an actionTranslator |
+| Read/write files, list directories, run shell commands, grep | createShellTools (shell_read/grep/**write**/**edit**/run/exec) + Loop({ policy }) — gate `shell_write`/`shell_edit` via `fs.writeScope` with an actionTranslator |
+| Change one span of a big file without re-emitting the whole thing | `shell_edit({path, oldText, newText})` — anchored exact-once replace; the surgical alternative to whole-file `shell_write` (BA-13). Gate it as `{type:'edit'}` |
 | Auto-discover MCP servers from IDE configs | createMCPBridge |
 | Gate MCP tools with allow/deny lists | createMCPBridge + `.mcp-bridge.json` |
 | Gate every tool call with one policy hook | `wireGate(gate).policy` → `Loop({ policy })` |
@@ -423,6 +424,7 @@ const { policy, onToolResult } = wireGate(gate, {
     if (toolName === 'shell_run')   return { type: 'bash', args, _ctx: ctx };   // reads args.argv → joins to cmd
     if (toolName === 'shell_read')  return { type: 'read',  args, _ctx: ctx };  // reads args.path
     if (toolName === 'shell_write') return { type: 'write', args, _ctx: ctx };  // gate by fs.writeScope (reads args.path)
+    if (toolName === 'shell_edit')  return { type: 'edit',  args, _ctx: ctx };  // same fs.writeScope as write (reads args.path)
     return { type: toolName, args, _ctx: ctx };          // fall through to defaultActionTranslator
   },
 });
@@ -706,7 +708,11 @@ const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs'
 
 **Worker context (`opts.context`, v0.23.0):** a read-only working-context string (paths/cwd) PREPENDED to every worker's TASK message as a `Working context:` block — so a sliced child can **locate its artifact** (the Planner paraphrases the goal into subtasks and drops absolute paths; without this, workers guess `.`/`~`/`/tmp` and get denied). Forwarded to the Planner as `info` (path-aware slices) and shown to the verifier too (neutral FACTS, not a stance — distinct from `persona`, which is a privileged SYSTEM-prompt stance). Carries down the tree. **Security:** it still becomes part of the prompt, so pass caller-trusted run-state only, never untrusted/end-user text (lower-privilege than `persona` — user message, not system — but still an injection surface). Absent ⇒ the task message is unchanged.
 
-**Leaf self-correction (`opts.refineLeaf`, v0.23.0, opt-in):** turn a **definite leaf** (a node offered no `spawn_child` — `simple` tier or at `maxDepth`) into a bounded generate→sense→regenerate loop instead of a single pass: `{ sensor, maxIterations?, temperatures? }`. `sensor(result, { task, context, contract }) → Verdict` is YOUR **deterministic** close (test/compile/lint — not a model judge); on a non-pass its `critique` (the gap, not the transcript) is fed FRESH into the next attempt and — **on models that accept `temperature`** — the **retry temperature ESCALATES** (default `[0.2, 0.7, 1.0]` — load-bearing there: a weak model at a flat temperature regenerates identical wrong code and ignores even crisp feedback). On a **temperature-fixed model** (e.g. `claude-sonnet-5`, which 400s any non-default temperature) the provider silently drops the param (see below), the escalation lever is inert, and the fed-back gap critique carries recovery alone; `receipts.refineLeaf.temperatures` then records the EFFECTIVE temps — a `null` marks an attempt that ran at the model's default (never the ignored requested value). Each attempt is gate-checked + metered; a HaltError mid-loop → clean `{ incomplete }`; honest non-recovery → `receipts.refineLeaf.passed === false` (never a faked pass); `receipts.tokens` sums all attempts. The error-keyed `recall` stays YOUR tool (`opts.tools`), keyed off the fed-back critique — bareagent stays litectx-agnostic. Carries down (engages at the leaves). Absent ⇒ a leaf is a single pass.
+**Leaf self-correction (`opts.refineLeaf`, v0.23.0, opt-in):** turn a **definite leaf** (a node offered no `spawn_child` — `simple` tier or at `maxDepth`) into a bounded generate→sense→regenerate loop instead of a single pass: `{ sensor, maxIterations?, temperatures?, rejectedBuffer? }`. `sensor(result, { task, context, contract }) → Verdict` is YOUR **deterministic** close (test/compile/lint — not a model judge); on a non-pass its `critique` (the gap, not the transcript) is fed FRESH into the next attempt and — **on models that accept `temperature`** — the **retry temperature ESCALATES** (default `[0.2, 0.7, 1.0]` — load-bearing there: a weak model at a flat temperature regenerates identical wrong code and ignores even crisp feedback). On a **temperature-fixed model** (e.g. `claude-sonnet-5`, which 400s any non-default temperature) the provider silently drops the param (see below), the escalation lever is inert, and the fed-back gap critique carries recovery alone; `receipts.refineLeaf.temperatures` then records the EFFECTIVE temps — a `null` marks an attempt that ran at the model's default (never the ignored requested value). Each attempt is gate-checked + metered; a HaltError mid-loop → clean `{ incomplete }`; honest non-recovery → `receipts.refineLeaf.passed === false` (never a faked pass); `receipts.tokens` sums all attempts. The error-keyed `recall` stays YOUR tool (`opts.tools`), keyed off the fed-back critique — bareagent stays litectx-agnostic. Carries down (engages at the leaves). Absent ⇒ a leaf is a single pass.
+
+> **Sensor integrity (`refineLeaf.sensor`):** the sensor must judge the **returned result** (tamper-proof — build/run the returned string in isolation), never a worker **side-effect** a worker with edit tools could game (writing a passing file then returning junk, or editing the failing test itself). The loop optimizes against whatever the sensor reads — keep the close outside what the worker can write. (RSI field lesson: reward-hacking appeared in every optimization loop with a gameable close.)
+
+> **`rejectedBuffer` (BA-14, v0.30.0):** a second lever for a **temperature-fixed** model, where escalation is inert. Instead of only the latest critique, it surfaces the model's OWN prior failed attempts VERBATIM — *"you wrote these, they failed X — write something STRUCTURALLY DIFFERENT."* This is **directed** diversity (attack the specific repeated mistake); escalation is **random** diversity, and the two are **antagonistic** — temperature monotonically degrades the buffer (`poc/ba14b`: flat-0.2 100% → 0.7 70% → 1.0 50%), so when the buffer engages the retry temperature is **held flat** at `temperatures[0]`, never escalated. Trigger: `true` = force on (also on temperature-accepting models); `false` = force off (pure BA-8 escalation); **unset = adaptive** — engage only once a prior attempt's temperature was dropped (i.e. a temp-fixed model where escalation is inert and the buffer is the sole lever). On a temperature-accepting model the default leaves behavior byte-identical. `receipts.refineLeaf.rejectedBuffer` reports whether it engaged. Efficacy is a **weak-model / fixation** phenomenon (live on `claude-sonnet-5` it engaged 6/6 but recovered no better than critique-only — cost-neutral, hence adaptive-not-always-on).
 
 ```javascript
 const out = await recurse('Fix the failing function in calc.js', ctx, {
@@ -1247,6 +1253,7 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 |---|---|
 | `shell_read` | Read a file (utf8, 256KB cap) or list a directory (tab-separated). `~` expands to home. |
 | `shell_write` | Write (or `append:true`) UTF-8 text to a file, creating parent dirs. 5MB cap. No shell, so it gates cleanly through `fs.writeScope` once translated to `{type:'write'}`. **`content` is REQUIRED** — see the truncation guard below. |
+| `shell_edit` | Anchored exact-string replace — the **surgical** alternative to whole-file `shell_write` (BA-13). `{path, oldText, newText}`: `oldText` must occur **exactly once** (quote surrounding lines to be unique); `newText` is spliced in **verbatim** (`""` deletes). Returns a compact `edited <path>: 1 replacement` receipt, never the body. 0 or 2+ matches → a refusal **returned as the tool result** (the model re-anchors; file untouched). Gates through `fs.writeScope` translated to `{type:'edit'}` — see the note below. |
 | `shell_grep` | JavaScript regex search across files. Walks directories, skips binary files, returns `{hits: [{file, line, text}], truncated, fileCount}`. |
 | `shell_run` | Run a command with an **argv array** via `child_process.execFile` (no shell, no metacharacter interpretation). Returns `{stdout, stderr, code, timedOut}`. **Use this when you need a policy allowlist.** |
 | `shell_exec` | Run a raw shell command string via `/bin/sh -c` (or `cmd.exe`). Returns the same shape. **Shell metacharacters are interpreted — naive allowlists are bypassable.** Use only when you genuinely need shell features (pipes, redirects, globs). |
@@ -1255,6 +1262,8 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 
 > **⚠️ `shell_write` requires `content` — and a gate cannot cover for it (v0.27+).** `content` used to default to `''`, so a tool call that OMITTED it silently overwrote the target with **zero bytes** and returned `"wrote 0 bytes to <path>"` as success. That is the ordinary shape of a model hitting its **output-token cap** mid-generation on a long file — observed live emptying a 1789-line source file. **No policy can catch it:** a 0-byte write is a *legal* write, and bareguard's `fs` primitive judges `{type:'write', path}` without inspecting the body (the gate correctly `allow`s it). `shell_write` now **rejects** an absent, `null`, or non-string `content` and leaves the file byte-identical; the error tells the model to retry with the full content. An explicit `content: ""` still empties the file — that one is deliberate.
 
+> **`shell_edit` — the surgical write (BA-13).** Changing one line of an 800-line file with `shell_write` forces the model to re-emit **all 800 lines** as tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every revision, and the maximal broken-tree surface (a truncated rewrite mangles the lines it never meant to touch — the BA-4/BA-6 class). `shell_edit({path, oldText, newText})` emits only the anchor + replacement. Semantics worth knowing: `oldText` must match **exactly once** (a 0/2+ match is a refusal *returned as the tool result*, so the loop continues and the model widens the anchor — not a throw, so a repeated-identical miss is bounded by maxTurns/budget, not the spin guard); missing/empty `oldText` or missing/non-string `newText` **throw** (BA-4 guards; `newText:""` is a legal deletion); the write is **atomic** (sibling temp + rename, mode preserved) so an fs failure never leaves a partial file; and `newText` is a **literal splice** (a `$&`/`$1` in it lands verbatim, unlike `String.replace`). Gate it exactly like `shell_write` but as `{type:'edit'}` — **bareguard gates `edit` by the same `fs.writeScope` as `write` with zero config** (its FS primitive's `FS_TYPES` already includes `edit`).
+
 > **⚠️ `shell_exec` injection caveat.** `"ls"` passes a base-command allowlist like `args.command.split(/\s+/)[0]`, but so does `"ls;rm -rf /tmp/x"` — the shell runs both. **A base-command allowlist is NOT safe for `shell_exec`.** For policy-gated use, prefer `shell_run({argv})` and allow-list on `args.argv[0]` — there is no shell in that path, so metacharacters are just literal argument bytes. Use `shell_exec` only when the agent needs pipes/redirects/globs, and gate it at a higher level (human approval, narrow intent).
 
 ```javascript

package/examples/with-bareguard.mjs

@@ -60,6 +60,8 @@ const actionTranslator = (toolName, args, ctx) => {
     case 'shell_grep': return { type: 'read', path: args?.path, args, _ctx: ctx ?? null };
     // shell_write is a write — gate it through fs.writeScope (add writeScope to the Gate config to enforce).
     case 'shell_write': return { type: 'write', path: args?.path, args, _ctx: ctx ?? null };
+    // shell_edit is an anchored edit — bareguard gates {type:'edit'} by the SAME fs.writeScope as write.
+    case 'shell_edit':  return { type: 'edit',  path: args?.path, args, _ctx: ctx ?? null };
     default:           return { type: toolName, args, _ctx: ctx ?? null };
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "files": [
     "index.js",
     "index.d.ts",

package/src/loop.js

@@ -701,6 +701,11 @@ class Loop {
         const generate = () => this.provider.generate(toSend, activeTools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
+        // A HaltError is a governance exit, not a provider failure — re-throw it (like every other seam) so it
+        // reaches the outer handler, which seals dangling tool_calls and returns error:`halt:<rule>`. Without
+        // this, throwOnError:false laundered a provider-surfaced HaltError into a generic `error:<message>`,
+        // indistinguishable from a real fault (the retry never retries it — DEFAULT_RETRY_ON is false for it).
+        if (err instanceof HaltError) throw err;
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
         // BA-5: a mid-run provider failure must not erase the work of the rounds that succeeded.

package/src/recurse.d.ts

@@ -94,13 +94,29 @@ export type RecurseOptions = {
      * (`temperatures`, default `[0.2,0.7,1.0]`) — the live-validated lever that lets a weak model escape a
      * repeat-the-same-mistake rut (`poc/ba8-leaf-refine.mjs`: 0/5 → 2-3/5; flat temp recovers 0/5). On a
      * temperature-fixed model (BA-10) the provider drops the param, `receipts.refineLeaf.temperatures` records
-     * `null`, and the fed-back gap critique carries recovery alone. `maxIterations` defaults to
+     * `null`, and the fed-back gap critique carries recovery alone — UNLESS the rejected-attempt buffer engages
+     * (below). `maxIterations` defaults to
      * `temperatures.length`; the REAL bound is bareguard (each attempt is gate-checked + metered). CARRIES DOWN the
      * tree (preserved by `forChild`), so it engages at the leaves of a Family-A decomposition. Recovery is PARTIAL
      * (a stubborn blind spot may persist) — `receipts.refineLeaf.passed` reports honestly. Does NOT apply to a node
      * that delegates (its children + the tree verify own quality), nor to the scan/fanout/partition dispatch paths.
      * Absent ⇒ a leaf is a single pass (byte-identical to pre-BA-8). An error-keyed `recall` is the CALLER's tool
      * (`opts.tools`) keyed off the fed-back critique — bareagent stays litectx-agnostic.
+     * **Sensor integrity (RSI-learnings #1/#5, "audit the close"):** the `sensor` MUST judge the RETURNED result
+     * (tamper-proof — e.g. build/run the returned string in an isolated context, as `poc/ba8-leaf-refine.mjs` does),
+     * NEVER a worker side-effect a worker with edit tools could GAME (writing a passing file then returning junk, or
+     * editing the failing test itself). A gameable close is the reward-hacking surface every RSI system in the field
+     * got bitten by; the loop optimizes against WHATEVER the sensor reads, so keep it outside what the worker can write.
+     * **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
+     * surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
+     * STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
+     * is RANDOM diversity; the two are ANTAGONISTIC (`poc/ba14b-temp-with-buffer.mjs`: temperature monotonically
+     * degrades the buffer, 100%→70%→50% across 0.2/0.7/1.0), so when the buffer engages the retry temperature is
+     * HELD at `temperatures[0]` (flat-low), never escalated. `true` = force on (also on temperature-accepting
+     * models); `false` = force off (pure BA-8 escalation); UNSET = ADAPTIVE — engage only once a prior attempt's
+     * temperature was dropped (a temperature-fixed model, BA-10, where escalation is inert and the buffer is the
+     * sole lever — `poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). `receipts.refineLeaf.rejectedBuffer`
+     * reports whether any iteration injected it. Bounded by `maxIterations` (the buffer never outgrows it).
      */
     refineLeaf?: {
         sensor: (result: any, ctx: {
@@ -110,6 +126,7 @@ export type RecurseOptions = {
         }) => (Verdict | Promise<Verdict>);
         maxIterations?: number;
         temperatures?: number[];
+        rejectedBuffer?: boolean;
     } | undefined;
     /**
      * - Definition of done (A3). When present, the verifier grades against THIS,
@@ -225,15 +242,20 @@ export type RecurseNode = {
      */
     tokens: object | null;
     /**
-     * - (BA-8) when this
-     * leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
+     * - (BA-8) when
+     * this leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
      * passed (false = honest non-recovery, not a faked success). `temperatures` are the EFFECTIVE per-attempt temps
      * (BA-10): a `null` marks an attempt the model ran at its DEFAULT because it rejected the requested temperature.
+     * `rejectedBuffer` (BA-14): whether any iteration injected the rejected-attempt buffer (prior failed attempts
+     * surfaced verbatim); when it engages the REQUESTED retry temperature is held flat at `temperatures[0]`, never
+     * escalated (ba14b antagonism) — but a temperature-fixed model still drops it, so the EFFECTIVE temp recorded
+     * above is `null`, not `temperatures[0]`.
      */
     refineLeaf?: {
         iterations: number;
         passed: boolean;
         temperatures: (number | null)[];
+        rejectedBuffer: boolean;
     } | undefined;
     model: string | null;
     /**
@@ -362,7 +384,7 @@ export type Slice = {
  *   TRUSTED run-state (paths/cwd); do NOT pass untrusted / end-user-controlled text here.
  * @property {ToolDef[]} [tools] - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
  *   `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
- * @property {{sensor: (result: any, ctx: {task: string, context: string|undefined, contract: string|null}) => (Verdict|Promise<Verdict>), maxIterations?: number, temperatures?: number[]}} [refineLeaf]
+ * @property {{sensor: (result: any, ctx: {task: string, context: string|undefined, contract: string|null}) => (Verdict|Promise<Verdict>), maxIterations?: number, temperatures?: number[], rejectedBuffer?: boolean}} [refineLeaf]
  *   (Opt-in, BA-8 / relayfact F17) Turn a DEFINITE LEAF (a node that is offered no `spawn_child` — `simple`
  *   tier or at `maxDepth`) into a bounded generate→sense→regenerate loop instead of a single pass, so a failed
  *   slice can self-correct. `sensor` is a DETERMINISTIC close (test/compile/lint — NOT a model judge, R-S8) that
@@ -371,13 +393,29 @@ export type Slice = {
  *   (`temperatures`, default `[0.2,0.7,1.0]`) — the live-validated lever that lets a weak model escape a
  *   repeat-the-same-mistake rut (`poc/ba8-leaf-refine.mjs`: 0/5 → 2-3/5; flat temp recovers 0/5). On a
  *   temperature-fixed model (BA-10) the provider drops the param, `receipts.refineLeaf.temperatures` records
- *   `null`, and the fed-back gap critique carries recovery alone. `maxIterations` defaults to
+ *   `null`, and the fed-back gap critique carries recovery alone — UNLESS the rejected-attempt buffer engages
+ *   (below). `maxIterations` defaults to
  *   `temperatures.length`; the REAL bound is bareguard (each attempt is gate-checked + metered). CARRIES DOWN the
  *   tree (preserved by `forChild`), so it engages at the leaves of a Family-A decomposition. Recovery is PARTIAL
  *   (a stubborn blind spot may persist) — `receipts.refineLeaf.passed` reports honestly. Does NOT apply to a node
  *   that delegates (its children + the tree verify own quality), nor to the scan/fanout/partition dispatch paths.
  *   Absent ⇒ a leaf is a single pass (byte-identical to pre-BA-8). An error-keyed `recall` is the CALLER's tool
  *   (`opts.tools`) keyed off the fed-back critique — bareagent stays litectx-agnostic.
+ *   **Sensor integrity (RSI-learnings #1/#5, "audit the close"):** the `sensor` MUST judge the RETURNED result
+ *   (tamper-proof — e.g. build/run the returned string in an isolated context, as `poc/ba8-leaf-refine.mjs` does),
+ *   NEVER a worker side-effect a worker with edit tools could GAME (writing a passing file then returning junk, or
+ *   editing the failing test itself). A gameable close is the reward-hacking surface every RSI system in the field
+ *   got bitten by; the loop optimizes against WHATEVER the sensor reads, so keep it outside what the worker can write.
+ *   **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
+ *   surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
+ *   STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
+ *   is RANDOM diversity; the two are ANTAGONISTIC (`poc/ba14b-temp-with-buffer.mjs`: temperature monotonically
+ *   degrades the buffer, 100%→70%→50% across 0.2/0.7/1.0), so when the buffer engages the retry temperature is
+ *   HELD at `temperatures[0]` (flat-low), never escalated. `true` = force on (also on temperature-accepting
+ *   models); `false` = force off (pure BA-8 escalation); UNSET = ADAPTIVE — engage only once a prior attempt's
+ *   temperature was dropped (a temperature-fixed model, BA-10, where escalation is inert and the buffer is the
+ *   sole lever — `poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). `receipts.refineLeaf.rejectedBuffer`
+ *   reports whether any iteration injected it. Bounded by `maxIterations` (the buffer never outgrows it).
  * @property {string} [contract] - Definition of done (A3). When present, the verifier grades against THIS,
  *   not the loose task, and verification always runs.
  * @property {(result: any, ctx: {contract: string|null, task: string}) => (Verdict|Promise<Verdict>)} [evaluate]
@@ -438,10 +476,14 @@ export type Slice = {
  * @property {string} [blocker] - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
  *   short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
- * @property {{iterations: number, passed: boolean, temperatures: (number|null)[]}} [refineLeaf] - (BA-8) when this
- *   leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
+ * @property {{iterations: number, passed: boolean, temperatures: (number|null)[], rejectedBuffer: boolean}} [refineLeaf] - (BA-8) when
+ *   this leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
  *   passed (false = honest non-recovery, not a faked success). `temperatures` are the EFFECTIVE per-attempt temps
  *   (BA-10): a `null` marks an attempt the model ran at its DEFAULT because it rejected the requested temperature.
+ *   `rejectedBuffer` (BA-14): whether any iteration injected the rejected-attempt buffer (prior failed attempts
+ *   surfaced verbatim); when it engages the REQUESTED retry temperature is held flat at `temperatures[0]`, never
+ *   escalated (ba14b antagonism) — but a temperature-fixed model still drops it, so the EFFECTIVE temp recorded
+ *   above is `null`, not `temperatures[0]`.
  * @property {string|null} model
  * @property {string|null} [retrieval] - (§10 step 7) the retrieval mode this node ran (`scan`/`search`/`exact`),
  *   or null/absent for a plain reasoning node.

package/src/recurse.js

@@ -216,7 +216,7 @@ function auditSafeCtx(ctx, overrides = {}) {
  *   TRUSTED run-state (paths/cwd); do NOT pass untrusted / end-user-controlled text here.
  * @property {ToolDef[]} [tools] - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
  *   `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
- * @property {{sensor: (result: any, ctx: {task: string, context: string|undefined, contract: string|null}) => (Verdict|Promise<Verdict>), maxIterations?: number, temperatures?: number[]}} [refineLeaf]
+ * @property {{sensor: (result: any, ctx: {task: string, context: string|undefined, contract: string|null}) => (Verdict|Promise<Verdict>), maxIterations?: number, temperatures?: number[], rejectedBuffer?: boolean}} [refineLeaf]
  *   (Opt-in, BA-8 / relayfact F17) Turn a DEFINITE LEAF (a node that is offered no `spawn_child` — `simple`
  *   tier or at `maxDepth`) into a bounded generate→sense→regenerate loop instead of a single pass, so a failed
  *   slice can self-correct. `sensor` is a DETERMINISTIC close (test/compile/lint — NOT a model judge, R-S8) that
@@ -225,13 +225,29 @@ function auditSafeCtx(ctx, overrides = {}) {
  *   (`temperatures`, default `[0.2,0.7,1.0]`) — the live-validated lever that lets a weak model escape a
  *   repeat-the-same-mistake rut (`poc/ba8-leaf-refine.mjs`: 0/5 → 2-3/5; flat temp recovers 0/5). On a
  *   temperature-fixed model (BA-10) the provider drops the param, `receipts.refineLeaf.temperatures` records
- *   `null`, and the fed-back gap critique carries recovery alone. `maxIterations` defaults to
+ *   `null`, and the fed-back gap critique carries recovery alone — UNLESS the rejected-attempt buffer engages
+ *   (below). `maxIterations` defaults to
  *   `temperatures.length`; the REAL bound is bareguard (each attempt is gate-checked + metered). CARRIES DOWN the
  *   tree (preserved by `forChild`), so it engages at the leaves of a Family-A decomposition. Recovery is PARTIAL
  *   (a stubborn blind spot may persist) — `receipts.refineLeaf.passed` reports honestly. Does NOT apply to a node
  *   that delegates (its children + the tree verify own quality), nor to the scan/fanout/partition dispatch paths.
  *   Absent ⇒ a leaf is a single pass (byte-identical to pre-BA-8). An error-keyed `recall` is the CALLER's tool
  *   (`opts.tools`) keyed off the fed-back critique — bareagent stays litectx-agnostic.
+ *   **Sensor integrity (RSI-learnings #1/#5, "audit the close"):** the `sensor` MUST judge the RETURNED result
+ *   (tamper-proof — e.g. build/run the returned string in an isolated context, as `poc/ba8-leaf-refine.mjs` does),
+ *   NEVER a worker side-effect a worker with edit tools could GAME (writing a passing file then returning junk, or
+ *   editing the failing test itself). A gameable close is the reward-hacking surface every RSI system in the field
+ *   got bitten by; the loop optimizes against WHATEVER the sensor reads, so keep it outside what the worker can write.
+ *   **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
+ *   surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
+ *   STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
+ *   is RANDOM diversity; the two are ANTAGONISTIC (`poc/ba14b-temp-with-buffer.mjs`: temperature monotonically
+ *   degrades the buffer, 100%→70%→50% across 0.2/0.7/1.0), so when the buffer engages the retry temperature is
+ *   HELD at `temperatures[0]` (flat-low), never escalated. `true` = force on (also on temperature-accepting
+ *   models); `false` = force off (pure BA-8 escalation); UNSET = ADAPTIVE — engage only once a prior attempt's
+ *   temperature was dropped (a temperature-fixed model, BA-10, where escalation is inert and the buffer is the
+ *   sole lever — `poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). `receipts.refineLeaf.rejectedBuffer`
+ *   reports whether any iteration injected it. Bounded by `maxIterations` (the buffer never outgrows it).
  * @property {string} [contract] - Definition of done (A3). When present, the verifier grades against THIS,
  *   not the loose task, and verification always runs.
  * @property {(result: any, ctx: {contract: string|null, task: string}) => (Verdict|Promise<Verdict>)} [evaluate]
@@ -293,10 +309,14 @@ function auditSafeCtx(ctx, overrides = {}) {
  * @property {string} [blocker] - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
  *   short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
- * @property {{iterations: number, passed: boolean, temperatures: (number|null)[]}} [refineLeaf] - (BA-8) when this
- *   leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
+ * @property {{iterations: number, passed: boolean, temperatures: (number|null)[], rejectedBuffer: boolean}} [refineLeaf] - (BA-8) when
+ *   this leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
  *   passed (false = honest non-recovery, not a faked success). `temperatures` are the EFFECTIVE per-attempt temps
  *   (BA-10): a `null` marks an attempt the model ran at its DEFAULT because it rejected the requested temperature.
+ *   `rejectedBuffer` (BA-14): whether any iteration injected the rejected-attempt buffer (prior failed attempts
+ *   surfaced verbatim); when it engages the REQUESTED retry temperature is held flat at `temperatures[0]`, never
+ *   escalated (ba14b antagonism) — but a temperature-fixed model still drops it, so the EFFECTIVE temp recorded
+ *   above is `null`, not `temperatures[0]`.
  * @property {string|null} model
  * @property {string|null} [retrieval] - (§10 step 7) the retrieval mode this node ran (`scan`/`search`/`exact`),
  *   or null/absent for a plain reasoning node.
@@ -608,10 +628,25 @@ async function recurse(task, ctx = {}, opts = {}) {
 async function recurseRefineLeaf(task, ctx, opts, state) {
   const { provider, system, handleTools, depth, critical, node, sensor } = state;
   node.model = provider.model || null;
-  const cfg = /** @type {{maxIterations?: number, temperatures?: number[]}} */ (opts.refineLeaf || {});
+  const cfg = /** @type {{maxIterations?: number, temperatures?: number[], rejectedBuffer?: boolean}} */ (opts.refineLeaf || {});
   const temps = Array.isArray(cfg.temperatures) && cfg.temperatures.length ? cfg.temperatures : DEFAULT_REFINE_TEMPS;
   const maxIterations = Number.isInteger(cfg.maxIterations) && /** @type {number} */ (cfg.maxIterations) > 0
     ? /** @type {number} */ (cfg.maxIterations) : temps.length;
+  // BA-14 rejected-attempt buffer: surface the model's OWN prior failed attempts verbatim ("you wrote these,
+  // they failed X — write something DIFFERENT") — a SkillOpt-shaped directed-diversity lever. `rejectedBuffer`:
+  // `true` = force on (also on temperature-accepting models); `false` = force off; unset = ADAPTIVE (engage only
+  // once a prior attempt's temperature was DROPPED, i.e. a temperature-fixed model where BA-8 escalation is inert
+  // and the buffer is the only lever — ba14 D>C). Escalation and the buffer are ANTAGONISTIC (ba14b: temp
+  // monotonically degrades the buffer 100→70→50% across 0.2/0.7/1.0), so when the buffer engages we HOLD temps[0].
+  const bufferForced = cfg.rejectedBuffer === true;
+  const bufferDisabled = cfg.rejectedBuffer === false;
+  let bufferUsed = false; // receipt: did any iteration actually inject the ledger?
+  const LEDGER_ENTRY_CAP = 600, LEDGER_WHY_CAP = 400;
+  const formatLedger = (/** @type {Array<{result: any, verdict: any}>} */ history) => history.map((h, i) => {
+    const code = String(h.result == null ? '' : h.result).replace(/```[a-zA-Z]*\n?/g, '').trim().slice(0, LEDGER_ENTRY_CAP);
+    const why = h.verdict && typeof h.verdict.critique === 'string' ? h.verdict.critique.slice(0, LEDGER_WHY_CAP) : '';
+    return `--- Rejected attempt ${i + 1} (already failed — do NOT reproduce) ---\n${code}${why ? `\nFailed: ${why}` : ''}`;
+  }).join('\n\n');
 
   // A refine leaf runs N Loops, so its receipts.tokens SUMS every attempt's spend (not just the last) — the
   // honest cost of the node. The 4-tier tokens object (`{input,output,cacheCreation,cacheRead}`, loop.js) is flat
@@ -632,8 +667,16 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
   const effectiveTemps = [];
   // One attempt = a fresh leaf Loop (no spawn tool: a retry is a direct correction, not a re-decomposition) at the
   // iteration's temperature, with the GAP fed forward as fresh feedback. A governance halt → throw so refine stops.
-  const attempt = async ({ iteration, critique }) => {
-    const temperature = temps[Math.min(iteration, temps.length - 1)];
+  const attempt = async ({ iteration, critique, history }) => {
+    const hist = Array.isArray(history) ? history : [];
+    // ADAPTIVE trigger: a prior attempt whose temperature the model rejected (BA-10) records `null` in
+    // effectiveTemps → escalation is inert on this (temperature-fixed) model, so engage the buffer. Forced-on
+    // engages regardless (incl. temperature-accepting models). Needs ≥1 prior attempt to have something to buffer.
+    const tempDropped = effectiveTemps.some((t) => t === null);
+    const useBuffer = hist.length > 0 && !bufferDisabled && (bufferForced || tempDropped);
+    // ba14b: temperature is antagonistic to the buffer's directed diversity — HOLD temps[0] when it engages;
+    // otherwise escalate (BA-8, the no-memory lever). On a temperature-fixed model both collapse to the default.
+    const temperature = useBuffer ? temps[0] : temps[Math.min(iteration, temps.length - 1)];
     const loop = new Loop({
       provider, system,
       policy: ctx.policy || undefined,
@@ -642,9 +685,15 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
       throwOnError: false,
     });
     const base = withContext(task, opts.context);
-    const userText = critique
-      ? `${base}\n\nYour previous attempt FAILED these checks:\n${critique}\n\nReturn a corrected result that passes ALL of them.`
-      : base;
+    let userText;
+    if (useBuffer) {
+      bufferUsed = true;
+      userText = `${base}\n\nYou have already tried the following and each FAILED. Do NOT reproduce them — write a STRUCTURALLY DIFFERENT result that passes ALL checks:\n\n${formatLedger(hist)}`;
+    } else if (critique) {
+      userText = `${base}\n\nYour previous attempt FAILED these checks:\n${critique}\n\nReturn a corrected result that passes ALL of them.`;
+    } else {
+      userText = base;
+    }
     const out = await loop.run([{ role: 'user', content: userText }], handleTools, { ctx: auditSafeCtx(ctx, { depth }), temperature });
     // `temperatureDropped` is set on the Loop result only when the model rejected the requested temperature
     // (BA-10); it's absent on the error/halt return shapes, so read it through a narrow cast.
@@ -667,7 +716,7 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
     // `temperatures` = the EFFECTIVE temps (BA-10): a `null` marks an attempt whose requested temperature the
     // model rejected and ran at its default — so the receipt never claims a value the model ignored. On a
     // temperature-accepting model this equals the requested `temps.slice(0, iterations)` (byte-identical receipt).
-    node.refineLeaf = { iterations: outcome.iterations, passed: !!(outcome.verdict && outcome.verdict.pass), temperatures: effectiveTemps.slice(0, outcome.iterations) };
+    node.refineLeaf = { iterations: outcome.iterations, passed: !!(outcome.verdict && outcome.verdict.pass), temperatures: effectiveTemps.slice(0, outcome.iterations), rejectedBuffer: bufferUsed };
     const result = outcome.result;
 
     // Optional rubric layer on top of the deterministic sensor (RC-7): forced for critical, or a contract/override.
@@ -682,6 +731,11 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
     return { result, verdict: outcome.verdict || null, receipts: node };
   } catch (err) {
     node.tokens = tokensSum; // record whatever attempts DID spend, on both the halt and fault paths
+    // The refineLeaf receipt must ride EVERY terminating path, not just the clean one (same invariant as BA-10's
+    // `temperatureDropped`): a leaf that ran attempts then halted/faulted still spent tokens and may have engaged
+    // the buffer. `effectiveTemps[iteration]` is set BEFORE each attempt's throw, so it reflects every attempt
+    // made; `passed:false` because the catch is only reached on a throw (a pass returns from the try above).
+    node.refineLeaf = { iterations: effectiveTemps.length, passed: false, temperatures: effectiveTemps.slice(), rejectedBuffer: bufferUsed };
     if (err instanceof HaltError) {
       node.halted = true;
       node.incomplete = true;

package/src/refine.d.ts

@@ -1,15 +1,25 @@
 export type Verdict = import("./evaluator").Verdict;
 export type RefineOptions = {
     /**
-     *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
-     *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
-     *   transcript — anchoring on a wrong answer defeats the independent verifier.
+     *   Build one generation. On iteration 0, `lastResult`/`critique` are null and `history` is empty. Fresh-feedback
+     *   (D6/A1) is the consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the
+     *   failed transcript — anchoring on a wrong answer defeats the independent verifier. `history` is a fresh
+     *   shallow COPY of every prior `{result, verdict}` in order (a SkillOpt rejected-attempt buffer, BA-14): a
+     *   consumer MAY surface the failed attempts verbatim ("you already wrote these, they failed X — write something
+     *   different"), the lever that recovers a temperature-fixed model's fixation rut where escalation is inert
+     *   (`poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). *Structurally* mutating the copy (push/splice/reorder)
+     *   is safe; the `{result, verdict}` entries are SHARED references into refine's internal history (and the returned
+     *   `outcome.history`), so treat them as READ-ONLY — deep-mutating an entry corrupts the outcome.
      */
     attempt: (args: {
         iteration: number;
         lastResult: any;
         critique: string | null;
         contract: string | null;
+        history: Array<{
+            result: any;
+            verdict: Verdict;
+        }>;
     }) => any;
     /**
      *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
@@ -56,10 +66,16 @@ export type RefineOutcome = {
 /** @typedef {import('./evaluator').Verdict} Verdict */
 /**
  * @typedef {object} RefineOptions
- * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null}) => any} attempt
- *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
- *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
- *   transcript — anchoring on a wrong answer defeats the independent verifier.
+ * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null, history: Array<{result: any, verdict: Verdict}>}) => any} attempt
+ *   Build one generation. On iteration 0, `lastResult`/`critique` are null and `history` is empty. Fresh-feedback
+ *   (D6/A1) is the consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the
+ *   failed transcript — anchoring on a wrong answer defeats the independent verifier. `history` is a fresh
+ *   shallow COPY of every prior `{result, verdict}` in order (a SkillOpt rejected-attempt buffer, BA-14): a
+ *   consumer MAY surface the failed attempts verbatim ("you already wrote these, they failed X — write something
+ *   different"), the lever that recovers a temperature-fixed model's fixation rut where escalation is inert
+ *   (`poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). *Structurally* mutating the copy (push/splice/reorder)
+ *   is safe; the `{result, verdict}` entries are SHARED references into refine's internal history (and the returned
+ *   `outcome.history`), so treat them as READ-ONLY — deep-mutating an entry corrupts the outcome.
  * @property {(result: any, ctx: {iteration: number, contract: string|null}) => (Verdict | Promise<Verdict>)} evaluate
  *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
  * @property {string} [contract] - The shared definition of done (A3/D10), forwarded to BOTH `attempt` and

package/src/refine.js

@@ -4,10 +4,16 @@
 
 /**
  * @typedef {object} RefineOptions
- * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null}) => any} attempt
- *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
- *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
- *   transcript — anchoring on a wrong answer defeats the independent verifier.
+ * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null, history: Array<{result: any, verdict: Verdict}>}) => any} attempt
+ *   Build one generation. On iteration 0, `lastResult`/`critique` are null and `history` is empty. Fresh-feedback
+ *   (D6/A1) is the consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the
+ *   failed transcript — anchoring on a wrong answer defeats the independent verifier. `history` is a fresh
+ *   shallow COPY of every prior `{result, verdict}` in order (a SkillOpt rejected-attempt buffer, BA-14): a
+ *   consumer MAY surface the failed attempts verbatim ("you already wrote these, they failed X — write something
+ *   different"), the lever that recovers a temperature-fixed model's fixation rut where escalation is inert
+ *   (`poc/ba14-rejected-buffer.mjs`: flat-temp 50%→100%). *Structurally* mutating the copy (push/splice/reorder)
+ *   is safe; the `{result, verdict}` entries are SHARED references into refine's internal history (and the returned
+ *   `outcome.history`), so treat them as READ-ONLY — deep-mutating an entry corrupts the outcome.
  * @property {(result: any, ctx: {iteration: number, contract: string|null}) => (Verdict | Promise<Verdict>)} evaluate
  *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
  * @property {string} [contract] - The shared definition of done (A3/D10), forwarded to BOTH `attempt` and
@@ -49,7 +55,7 @@ async function refine(options) {
   let lastVerdict = null;
 
   for (let iteration = 0; iteration < maxIterations; iteration++) {
-    const result = await attempt({ iteration, lastResult, critique: lastVerdict ? lastVerdict.critique : null, contract });
+    const result = await attempt({ iteration, lastResult, critique: lastVerdict ? lastVerdict.critique : null, contract, history: history.slice() });
     const verdict = await evaluate(result, { iteration, contract });
     history.push({ result, verdict });
     lastResult = result;

package/tools/shell.d.ts

@@ -5,6 +5,7 @@ declare namespace _exports {
     export { createShellTools };
     export { _grepCore };
     export { writeFile as _writeFile };
+    export { editFile as _editFile };
 }
 export = _exports;
 type GrepArgs = {
@@ -97,3 +98,41 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
     append?: boolean;
     maxBytes?: number;
 }): Promise<string>;
+/**
+ * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
+ * Changing one line of an 800-line file with `shell_write` forces the model to EMIT all 800 lines as
+ * tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every
+ * revision, and the maximal broken-tree surface (a truncated rewrite mangles the 799 lines it never meant
+ * to touch — the BA-4/BA-6 truncation class). `shell_edit` emits only the anchor and its replacement.
+ *
+ * TWO error classes, deliberately split:
+ *   - ANCHOR failures (`oldText` matches 0 or 2+ times) RETURN a refusal string as a normal tool RESULT —
+ *     the loop continues and the model re-anchors, and the refusal names the count so the retry is a DISTINCT
+ *     call. (Tradeoff, chosen with eyes open: a result does NOT feed the Loop's `maxIdenticalToolErrors` spin
+ *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
+ *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
+ *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
+ *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *
+ * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
+ * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
+ * absent param is the truncated-call signature, never a silent default). Explicit `newText:""` is a legal
+ * deletion; an absent `newText` is not.
+ *
+ * ATOMIC: read → splice in memory → write a sibling temp (same filesystem, so `rename` is atomic) carrying
+ * the original's mode → rename over the original. Any throw before the rename leaves the original
+ * byte-identical and cleans the temp up, so a reader never sees a partial file, and an edit can't silently
+ * drop the executable bit.
+ *
+ * LITERAL splice, NOT `String.replace`: `.replace(oldText, newText)` interprets `$&`/`$1`/`` $` `` patterns in
+ * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
+ * `newText` lands verbatim.
+ * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
+    path: string;
+    oldText: string;
+    newText: string;
+    maxBytes?: number;
+}): Promise<string>;

package/tools/shell.js

@@ -7,6 +7,7 @@
  *   shell_read  — read a file or list a directory
  *   shell_grep  — regex search across files (JS regex, no grep/rg/findstr)
  *   shell_write — write/overwrite (or append to) a file, creating parent dirs (no shell)
+ *   shell_edit  — anchored exact-string replace: change one span without rewriting the whole file
  *   shell_run   — run a command via an argv array (no shell, allowlist-friendly on argv[0])
  *   shell_exec  — run a raw shell command with timeout + max buffer
  *
@@ -16,11 +17,13 @@
  * GATING WITH bareguard's fs/bash PRIMITIVES: these tools carry tool-named actions by default
  * (`{ type:'shell_write' }`), which match `tools.allowlist`/`tools.denylist` but do NOT activate the
  * `fs`/`bash` primitives — those need `action.type ∈ {read,write,edit,bash}` with `action.path`/`action.cmd`.
- * To gate `shell_write` by `fs.writeScope` (so a write outside the allowed root is denied BEFORE it touches
- * disk), translate it at the gate — see `examples/with-bareguard.mjs` for the `wireGate(gate, { actionTranslator })`
- * mapping (`shell_write` → `{ type:'write', path }`, `shell_read`/`shell_grep` → `{ type:'read', path }`,
- * `shell_run`/`shell_exec` → `{ type:'bash', cmd }`). A write tool alone is NOT auto-gated — validated by
- * poc/ba2-write-tool-gate.mjs (without the translator the out-of-scope write leaks).
+ * To gate `shell_write`/`shell_edit` by `fs.writeScope` (so a write outside the allowed root is denied BEFORE it
+ * touches disk), translate it at the gate — see `examples/with-bareguard.mjs` for the `wireGate(gate, { actionTranslator })`
+ * mapping (`shell_write` → `{ type:'write', path }`, `shell_edit` → `{ type:'edit', path }`, `shell_read`/`shell_grep`
+ * → `{ type:'read', path }`, `shell_run`/`shell_exec` → `{ type:'bash', cmd }`). bareguard gates `edit` by
+ * `fs.writeScope` identically to `write` (its FS primitive's `FS_TYPES` includes `edit`), so a consumer that
+ * fences `write` gets `edit` fenced by the same scope with ZERO extra config. A write/edit tool alone is NOT
+ * auto-gated — validated by poc/ba2-write-tool-gate.mjs (without the translator the out-of-scope write leaks).
  *
  * CAVEAT (applies to read AND write scopes): bareguard's `fs` primitive matches paths LEXICALLY (no
  * `realpath`/symlink resolution), so a symlink that lives INSIDE the allowed scope but points OUTSIDE it is
@@ -33,6 +36,7 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
 
@@ -127,6 +131,101 @@ async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
   return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
 }
 
+/**
+ * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
+ * Changing one line of an 800-line file with `shell_write` forces the model to EMIT all 800 lines as
+ * tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every
+ * revision, and the maximal broken-tree surface (a truncated rewrite mangles the 799 lines it never meant
+ * to touch — the BA-4/BA-6 truncation class). `shell_edit` emits only the anchor and its replacement.
+ *
+ * TWO error classes, deliberately split:
+ *   - ANCHOR failures (`oldText` matches 0 or 2+ times) RETURN a refusal string as a normal tool RESULT —
+ *     the loop continues and the model re-anchors, and the refusal names the count so the retry is a DISTINCT
+ *     call. (Tradeoff, chosen with eyes open: a result does NOT feed the Loop's `maxIdenticalToolErrors` spin
+ *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
+ *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
+ *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
+ *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *
+ * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
+ * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
+ * absent param is the truncated-call signature, never a silent default). Explicit `newText:""` is a legal
+ * deletion; an absent `newText` is not.
+ *
+ * ATOMIC: read → splice in memory → write a sibling temp (same filesystem, so `rename` is atomic) carrying
+ * the original's mode → rename over the original. Any throw before the rename leaves the original
+ * byte-identical and cleans the temp up, so a reader never sees a partial file, and an edit can't silently
+ * drop the executable bit.
+ *
+ * LITERAL splice, NOT `String.replace`: `.replace(oldText, newText)` interprets `$&`/`$1`/`` $` `` patterns in
+ * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
+ * `newText` lands verbatim.
+ * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw new Error('shell_edit requires a non-empty "path" string');
+  }
+  if (typeof oldText !== 'string' || oldText.length === 0) {
+    throw new Error(
+      'shell_edit requires a non-empty "oldText" string to anchor the edit — refusing to edit, the file is unchanged. '
+      + `Got ${oldText === undefined ? 'no oldText argument' : oldText === '' ? 'an empty string' : `oldText of type ${oldText === null ? 'null' : typeof oldText}`}.`,
+    );
+  }
+  if (typeof newText !== 'string') {
+    throw new Error(
+      'shell_edit requires a "newText" string (pass newText:"" to delete the anchored text) — refusing to edit, the file is unchanged. '
+      + `Got ${newText === undefined ? 'no newText argument' : `newText of type ${newText === null ? 'null' : typeof newText}`}`
+      + '. If your output was cut short, retry with the full newText.',
+    );
+  }
+
+  const resolved = path.resolve(expandHome(rawPath));
+  // fs-layer errors (ENOENT for a missing file, EISDIR for a directory) throw — same surface as shell_read.
+  const content = await fs.readFile(resolved, 'utf8');
+
+  // Literal, non-overlapping occurrence count (split on a string does no regex interpretation).
+  const occurrences = content.split(oldText).length - 1;
+  if (occurrences === 0) {
+    return `shell_edit: oldText not found in ${resolved} — no change made. Quote the exact text to replace `
+      + `(check whitespace and indentation), or read the file to re-anchor.`;
+  }
+  if (occurrences > 1) {
+    return `shell_edit: oldText occurs ${occurrences}× in ${resolved} — the anchor must match exactly once. `
+      + `Widen it with surrounding lines so it is unique. No change made.`;
+  }
+
+  const idx = content.indexOf(oldText);
+  const patched = content.slice(0, idx) + newText + content.slice(idx + oldText.length);
+
+  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+  const bytes = Buffer.byteLength(patched, 'utf8');
+  if (bytes > cap) {
+    throw new Error(`shell_edit result is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
+  }
+
+  // Atomic replace: a sibling temp (same dir → same filesystem → rename is atomic) with the original's mode.
+  const stat = await fs.stat(resolved);
+  const tmp = `${resolved}.shell_edit-${crypto.randomBytes(9).toString('hex')}.tmp`;
+  try {
+    // flag 'wx' (O_CREAT|O_EXCL) — never follow or clobber a pre-planted file/symlink at the temp path; a
+    // colliding name fails the write instead. Create owner-only (0o600) so the patched body — which may hold
+    // a secret from a sensitive source file — is never briefly world-readable in the window before chmod sets
+    // the original's real mode. (This temp pattern is new to shell_edit, so it carries its own hardening.)
+    await fs.writeFile(tmp, patched, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    await fs.chmod(tmp, stat.mode & 0o777);
+    await fs.rename(tmp, resolved);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+
+  const removed = oldText.split('\n').length - 1;
+  const added = newText.split('\n').length - 1;
+  return `edited ${resolved}: 1 replacement (-${removed}/+${added} lines)`;
+}
+
 // Probe the first 1KB for NUL bytes to skip binary files in grep walks.
 /** @param {string} filePath */
 async function isProbablyText(filePath) {
@@ -453,6 +552,30 @@ function createShellTools() {
       execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) =>
         writeFile(/** @type {any} */ (args)),
     },
+    {
+      name: 'shell_edit',
+      description: 'Replace an exact, unique text span in a file — the surgical alternative to shell_write, which ' +
+        'rewrites the ENTIRE file. Give oldText (the exact text to replace — it must occur EXACTLY ONCE, so quote ' +
+        'enough surrounding lines to be unique) and newText (its replacement; pass "" to delete). Matched literally ' +
+        '(no regex; whitespace and indentation are significant). Returns a compact "edited <path>: 1 replacement" ' +
+        'receipt, never the file body. If oldText matches 0 or 2+ times the file is left unchanged and the reason is ' +
+        'returned so you can re-anchor. The file must already exist. No shell — gate by path with an fs.writeScope ' +
+        'policy (translate to {type:"edit"}).',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File to edit. ~ expands to home. The file must already exist.' },
+          oldText: { type: 'string', description: 'Exact text to find — must occur exactly once. Quote surrounding lines to disambiguate. Matched literally (no regex); whitespace and indentation are significant.' },
+          newText: { type: 'string', description: 'Replacement text, inserted verbatim (a literal splice — $ is not special). Pass "" to delete the anchored text. Required — a call without it is REJECTED, not treated as a deletion.' },
+          maxBytes: { type: 'integer', description: 'Reject if the resulting file would exceed this many bytes (default 5242880).' },
+        },
+        required: ['path', 'oldText', 'newText'],
+      },
+      // The args are model-authored and UNTRUSTED — oldText/newText may be absent (an output-token-capped
+      // generation), so the boundary type stays loose and editFile enforces the BA-4 contract at runtime.
+      execute: async (/** @type {{path: string, oldText?: string, newText?: string, maxBytes?: number}} */ args) =>
+        editFile(/** @type {any} */ (args)),
+    },
     {
       name: 'shell_run',
       description: 'Run a command with an argv array (no shell, no interpolation) and return {stdout, stderr, code, timedOut}. Use this when a policy allowlist needs to match on argv[0] — no shell metacharacter injection is possible. Default timeout 30s, max output 1MB.',
@@ -493,4 +616,4 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools, _grepCore, _writeFile: writeFile };
+module.exports = { createShellTools, _grepCore, _writeFile: writeFile, _editFile: editFile };