bare-agent 0.21.1 → 0.23.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). 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), feeding the gap back with escalating temperature. 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`):
 
@@ -154,6 +154,7 @@ const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate, {
   actionTranslator: (toolName, args, ctx) => {
     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
     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.21.1 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.23.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.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)
 
@@ -37,6 +37,8 @@ Eight entry points:
 | Decompose a hard task into a verified tree (RLM) | recurse — decompose → fan-out → verify → synthesize in one call (**wire a gate**, cost is open by design) |
 | 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 |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |
 | Require human approval before dangerous actions | Checkpoint |
@@ -62,7 +64,7 @@ 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 files, list directories, run shell commands, grep | createShellTools + Loop({ policy }) |
+| 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 |
 | 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 })` |
@@ -384,15 +386,16 @@ Legacy `wrapTool` / `wrapTools` are retained as deprecation shims (one-shot cons
 ```javascript
 const { policy, onToolResult } = wireGate(gate, {
   actionTranslator: (toolName, args, ctx) => {
-    if (toolName === 'shell_exec') return { type: 'bash', args, _ctx: ctx };   // bareguard 0.4.1+ reads args.command
-    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_exec')  return { type: 'bash', args, _ctx: ctx };   // bareguard 0.4.1+ reads args.command
+    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)
     return { type: toolName, args, _ctx: ctx };          // fall through to defaultActionTranslator
   },
 });
 ```
 
-`onLlmResult` always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `defaultActionTranslator` is exported for composition.
+`onLlmResult` always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `defaultActionTranslator` is exported for composition. **A tool is NOT auto-gated by the fs/bash primitives without this translator** — e.g. `shell_write` runs the write but `fs.writeScope` only enforces once `shell_write` → `{type:'write', path}`; the default `{type:'shell_write'}` matches `tools.allow/denylist` only. Verified live: with the translator, `gate.check` ALLOWs `shell_run ["ls","/tmp"]` and DENYs `shell_read /etc/passwd` (`[deny: fs.readScope]`), and an out-of-scope `shell_write` is denied **before** `execute` (nothing touches disk).
 
 **Bounding tool rounds — use `limits.maxToolRounds` (bareguard 0.4.2+), not doubled `maxTurns`.** `limits.maxTurns` ticks on every `gate.record` (LLM + tool), so an "N LLM-tool round" cap is `maxTurns: N*2`. `limits.maxToolRounds: N` ticks only on non-`llm` records and gives the natural semantic — pairs cleanly with our split `onLlmResult` / `onToolResult` (the LLM side writes `{type:'llm'}` records which the counter skips). Halt severity, same shape as `maxTurns`, rebuilt from audit on cold-start.
 
@@ -629,6 +632,8 @@ if (out.incomplete) {
 console.log(out.receipts.spawned.length);          // RC-10 audit tree: parent→child lineage, per-node tokens/verdict
 ```
 
+> **Audit-safe by construction (since Unreleased).** You pass `provider` on `ctx`, and a wired gate records the per-run ctx VERBATIM as `action._ctx`. `recurse()` **strips the live provider** (and thus its `apiKey`) from the ctx at every governance boundary before it reaches `gate.record`/`gate.check`, so the key never lands in the audit JSONL — only the provider *name* does (identity, not secret). The provider still reaches the worker (it runs); only the audited copy is cleaned. (bareguard's own secret-redaction is opt-in and value/pattern-based, so do not rely on it to catch a key you put on `ctx` — but DO scrub any *other* secret-bearing field you thread on `ctx` yourself, or configure `gate` `secrets`.)
+
 **Control families (how the tree is shaped):**
 
 - **Family A — model-driven (default).** The worker is handed an in-process `spawn_child` tool and *decides* whether to split. `assessComplexity` is a **hint, not a gate** (only `simple → single-shot`, and the non-overridable `critical → force adversarial verify` safety floor). Nothing extra to set.
@@ -666,7 +671,18 @@ const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs'
 });
 ```
 
-**What a delegated child inherits (important — the setpoint is the TOP node's job):** when a worker delegates with `spawn_child`, the child runs a **fresh `recurse`** that inherits `tools`, `synthesize`, `maxDepth`, and `persona` — but the parent's **`contract`/`evaluate` are stripped** (and the forced `count`/`mode` + the corpus `retrieval` knobs). A slice is not graded against the *whole*-task definition-of-done (that verdict is the top node's, and a slice satisfying the whole DoD is the wrong question); only the top `recurse` verifies the synthesized result. The non-overridable `critical → force-verify` safety floor still fires per node (it keys on the task text, not the contract). So: set `contract`/`evaluate` once at the top; they do not — and should not — re-run per intermediate node.
+**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 the **retry temperature ESCALATES** (default `[0.2, 0.7, 1.0]` — load-bearing: a weak model at a flat temperature regenerates identical wrong code and ignores even crisp feedback). 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.
+
+```javascript
+const out = await recurse('Fix the failing function in calc.js', ctx, {
+  context: `project root: ${process.cwd()}\nresolve relative paths against it`,
+  refineLeaf: { sensor: (code) => runTestsAndGrade(code) },   // your deterministic test/compile close
+});
+```
+
+**What a delegated child inherits (important — the setpoint is the TOP node's job):** when a worker delegates with `spawn_child`, the child runs a **fresh `recurse`** that inherits `tools`, `synthesize`, `maxDepth`, `persona`, `context`, and `refineLeaf` — but the parent's **`contract`/`evaluate` are stripped** (and the forced `count`/`mode` + the corpus `retrieval` knobs). A slice is not graded against the *whole*-task definition-of-done (that verdict is the top node's, and a slice satisfying the whole DoD is the wrong question); only the top `recurse` verifies the synthesized result. The non-overridable `critical → force-verify` safety floor still fires per node (it keys on the task text, not the contract). So: set `contract`/`evaluate` once at the top; they do not — and should not — re-run per intermediate node.
 
 ## Wiring with Evaluator + refine (output-side verification)
 

package/examples/litectx-as-store.mjs

@@ -63,16 +63,23 @@ async function main() {
   } catch {
     console.log('\n[litectx] not installed — the swap is one line:');
     console.log("    import { LiteCtx, liteCtxAsStore } from 'litectx';");
-    console.log('    const lc = new LiteCtx({ dbPath: \'./agent.db\' }); await lc.ready();');
+    console.log('    const lc = new LiteCtx({ root: \'./agent-ctx\' }); await lc.ready();');
     console.log('    const memory = new Memory({ store: liteCtxAsStore(lc) });  // ← only this line changes');
     console.log('\n  Install it (`npm install litectx`) to run the litectx half of this example.');
     return;
   }
 
-  const lc = new LiteCtx({ dbPath: join(tmpdir(), `litectx-as-store-${process.pid}.db`) });
+  // litectx >= 0.21 takes a `root` DIRECTORY (it manages its own files under it), not a `dbPath` file —
+  // passing `{ dbPath }` throws on construction. Use a fresh temp dir per run.
+  const root = mkdtempSync(join(tmpdir(), `litectx-as-store-${process.pid}-`));
+  const lc = new LiteCtx({ root });
   if (typeof lc.ready === 'function') await lc.ready();
-  await hostWorkflow(new Memory({ store: liteCtxAsStore(lc) }), 'litectx (ranked, graph-aware)');
-  if (typeof lc.close === 'function') lc.close();
+  try {
+    await hostWorkflow(new Memory({ store: liteCtxAsStore(lc) }), 'litectx (ranked, graph-aware)');
+  } finally {
+    if (typeof lc.close === 'function') lc.close();
+    rmSync(root, { recursive: true, force: true });
+  }
 }
 
 main().catch((err) => { console.error(err); process.exit(1); });

package/examples/with-bareguard.mjs

@@ -6,9 +6,12 @@
 // Run:  OPENAI_API_KEY=... node examples/with-bareguard.mjs
 //
 // What this demonstrates:
-//   - Single-gate governance: every tool call traverses gate.check; every
-//     result reaches gate.record (via wrapTools).
-//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop.
+//   - Single-gate governance: every tool call traverses gate.check (policy); every
+//     result reaches gate.record (via onToolResult + onLlmResult — wrapTools is deprecated).
+//   - Primitive enforcement: a shell→primitive actionTranslator makes bash.allow + fs.readScope
+//     actually fire (the default translator leaves them dead — relayfact F7/BA-3).
+//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop (a HaltError,
+//     caught by the Loop as a clean exit — distinct from a per-action deny; see humanChannel below).
 //   - Audit log: one JSONL line per gated event at ./bareagent-audit.jsonl.
 //   - humanChannel: required by bareguard. Here we auto-deny asks; in real use
 //     wire it to a chat platform, terminal prompt, etc.
@@ -29,16 +32,40 @@ const gate = new Gate({
   audit:  { path: './bareagent-audit.jsonl' },
   // Required by bareguard: any ask/halt event flows through here.
   // Auto-deny is the safest default for headless use; in real apps, wire to
-  // a Telegram/Slack/terminal prompt and return { decision: 'allow' | 'deny' }.
+  // a Telegram/Slack/terminal prompt and return a decision.
+  //   • { decision: 'deny' }  → denies THIS ONE action only; the loop keeps running and the
+  //     model may try something else. deny does NOT stop the loop (relayfact F11/BA-6) — under a
+  //     retry wrapper like `refine` a denied-but-not-stopped loop can keep spending.
+  //   • { decision: 'terminate' } → the clean-halt path: surfaces as a HaltError the Loop catches
+  //     and exits on. Use this (or a budget/turn cap) when you mean "stop", not "skip this action".
   humanChannel: async (event) => {
-    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying`);
+    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying (this action only)`);
     return { decision: 'deny' };
   },
 });
 await gate.init();
 
-// 2. Wire the gate into Loop's policy slot and wrap tools so gate.record fires.
-const { policy, wrapTools } = wireGate(gate);
+// 2. Wire the gate. The DEFAULT translator emits `{ type: <toolName> }` — which matches bareguard's
+//    `tools.allowlist`/`tools.denylist` (they read `action.type`) but does NOT activate the `bash`/`fs`/`net`
+//    primitives: those fire only on `action.type ∈ {bash, read, write, edit}` and read `action.cmd`/`action.path`.
+//    So to make the `bash.allow` + `fs.readScope` config above actually enforce, we MUST translate the shell
+//    tools into those primitive shapes — otherwise the caps are silently dead (relayfact F7/BA-3).
+const actionTranslator = (toolName, args, ctx) => {
+  switch (toolName) {
+    // shell_run is argv (no shell); bareguard's bash.allow matches `cmd.startsWith(prefix)`, so join argv[0..].
+    case 'shell_run':  return { type: 'bash', cmd: (args?.argv || []).join(' '), args, _ctx: ctx ?? null };
+    case 'shell_exec': return { type: 'bash', cmd: args?.command, args, _ctx: ctx ?? null };
+    // shell_read / shell_grep are reads — gate them through fs.readScope.
+    case 'shell_read':
+    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 };
+    default:           return { type: toolName, args, _ctx: ctx ?? null };
+  }
+};
+// onToolResult + onLlmResult are the current wiring (wrapTools is deprecated — it loses _ctx and never sees
+// LLM cost, so the budget cap can't cover token-only rounds). policy gates pre-call; the result hooks record.
+const { policy, onToolResult, onLlmResult } = wireGate(gate, { actionTranslator });
 
 // 3. Standard bareagent setup.
 const provider = new OpenAI({
@@ -50,16 +77,19 @@ const { tools } = createShellTools();
 const loop = new Loop({
   provider,
   policy,
+  onToolResult,  // every tool result → gate.record (with _ctx in scope)
+  onLlmResult,   // every LLM round → gate.record so budget.maxCostUsd covers token-only spend
   onError: (err, meta) => console.error(`[onError ${meta.source}]`, err.message),
 });
 
-// 4. Run.
+// 4. Run. Pass the tools as-is — gating is via policy/onToolResult, not by wrapping execute().
 const result = await loop.run(
   [{ role: 'user', content: 'List the contents of /tmp using shell_run with argv ["ls", "/tmp"].' }],
-  wrapTools(tools),
+  tools,
 );
 
 console.log('---');
 console.log('text:', result.text);
-console.log('cost:', result.cost?.toFixed(6) ?? 'n/a');
+// Loop returns the meter under result.metrics (result.cost was removed); costUsd is null when unpriced.
+console.log('cost:', result.metrics?.costUsd != null ? result.metrics.costUsd.toFixed(6) : 'n/a (unpriced)');
 console.log('audit log → ./bareagent-audit.jsonl');

package/package.json

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

package/src/recurse.d.ts

@@ -23,7 +23,12 @@ export type RecurseCtx = {
      */
     depth?: number | undefined;
     /**
-     * - Optional event stream forwarded to each worker Loop (receipts substrate).
+     * - Optional event stream forwarded to each worker Loop (receipts substrate). This
+     * is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+     * `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+     * (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+     * the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+     * gate is wired) the bareguard audit.
      */
     stream?: object;
     /**
@@ -59,11 +64,51 @@ export type RecurseOptions = {
      * and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
      */
     persona?: string | undefined;
+    /**
+     * - (BA-9 / relayfact F19) An optional caller-supplied READ-ONLY working-context
+     * blob (e.g. "project root: /abs/path\nfiles are relative to it") prepended to EVERY worker's task message as
+     * a `Working context:` block, so a sliced child can LOCATE its artifact — the concrete context (absolute
+     * paths / cwd) the Planner strips when it paraphrases the parent goal into child subtasks. CARRIES DOWN the
+     * tree (preserved by `forChild`, like `persona`) and, when forced fan-out plans, is forwarded as the Planner's
+     * `info` so the slices themselves are path-aware. Also shown to the verifier (neutral FACTS, not a stance, so
+     * no anti-sycophancy concern — and an agentic critic needs the path to exercise the artifact). Distinct from
+     * `persona`: persona is a privileged SYSTEM-prompt stance; context is run-state facts on the USER message.
+     * Absent/blank ⇒ byte-identical to pre-BA-9 (backward-compatible). Validated live (`poc/ba9-context-thread.mjs`:
+     * a weak model went 0/3 → 3/3 at locating an unguessable file once the root was threaded).
+     * **SECURITY:** this becomes part of every worker's prompt (and the verifier's) — lower-privilege than
+     * `persona` (the USER message, not the SYSTEM prompt) but still a prompt-injection surface. Intended for
+     * TRUSTED run-state (paths/cwd); do NOT pass untrusted / end-user-controlled text here.
+     */
+    context?: string | undefined;
     /**
      * - 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.
      */
     tools?: import("../types").ToolDef[] | undefined;
+    /**
+     * (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
+     * returns a `Verdict`; on a non-pass its `critique` (the GAP, not the transcript) is fed FRESH into the next
+     * attempt (D6/A1 anti-anchoring) and the **retry temperature ESCALATES** (`temperatures`, default
+     * `[0.2,0.7,1.0]`) — the live-validated requirement 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). `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.
+     */
+    refineLeaf?: {
+        sensor: (result: any, ctx: {
+            task: string;
+            context: string | undefined;
+            contract: string | null;
+        }) => (Verdict | Promise<Verdict>);
+        maxIterations?: number;
+        temperatures?: number[];
+    } | undefined;
     /**
      * - Definition of done (A3). When present, the verifier grades against THIS,
      * not the loose task, and verification always runs.
@@ -172,6 +217,16 @@ export type RecurseNode = {
      * - The worker Loop's `metrics.tokens`.
      */
     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 passed
+     * (false = honest non-recovery, not a faked success).
+     */
+    refineLeaf?: {
+        iterations: number;
+        passed: boolean;
+        temperatures: number[];
+    } | undefined;
     model: string | null;
     /**
      * - (§10 step 7) the retrieval mode this node ran (`scan`/`search`/`exact`),
@@ -252,7 +307,12 @@ export type Slice = {
  *   and worker tokens are all real spend (BA1: never invisible).
  * @property {number} [depth] - The current recursion depth (0 at the top). Incremented on each self-call;
  *   threaded into `policy`. Callers normally omit it (defaults to 0).
- * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate).
+ * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate). This
+ *   is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+ *   `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+ *   (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+ *   the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+ *   gate is wired) the bareguard audit.
  * @property {{recall: Function}} [litectx] - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
  *   retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
  *   the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx
@@ -273,8 +333,35 @@ export type Slice = {
  *   **SECURITY:** this is a PRIVILEGED system-prompt seam — treat `persona` like a system prompt. Do NOT pass
  *   untrusted / end-user-controlled text here; a hostile persona is prepended ahead of the decomposition policy
  *   and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
+ * @property {string} [context] - (BA-9 / relayfact F19) An optional caller-supplied READ-ONLY working-context
+ *   blob (e.g. "project root: /abs/path\nfiles are relative to it") prepended to EVERY worker's task message as
+ *   a `Working context:` block, so a sliced child can LOCATE its artifact — the concrete context (absolute
+ *   paths / cwd) the Planner strips when it paraphrases the parent goal into child subtasks. CARRIES DOWN the
+ *   tree (preserved by `forChild`, like `persona`) and, when forced fan-out plans, is forwarded as the Planner's
+ *   `info` so the slices themselves are path-aware. Also shown to the verifier (neutral FACTS, not a stance, so
+ *   no anti-sycophancy concern — and an agentic critic needs the path to exercise the artifact). Distinct from
+ *   `persona`: persona is a privileged SYSTEM-prompt stance; context is run-state facts on the USER message.
+ *   Absent/blank ⇒ byte-identical to pre-BA-9 (backward-compatible). Validated live (`poc/ba9-context-thread.mjs`:
+ *   a weak model went 0/3 → 3/3 at locating an unguessable file once the root was threaded).
+ *   **SECURITY:** this becomes part of every worker's prompt (and the verifier's) — lower-privilege than
+ *   `persona` (the USER message, not the SYSTEM prompt) but still a prompt-injection surface. Intended for
+ *   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]
+ *   (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
+ *   returns a `Verdict`; on a non-pass its `critique` (the GAP, not the transcript) is fed FRESH into the next
+ *   attempt (D6/A1 anti-anchoring) and the **retry temperature ESCALATES** (`temperatures`, default
+ *   `[0.2,0.7,1.0]`) — the live-validated requirement 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). `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.
  * @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]
@@ -333,6 +420,9 @@ export type Slice = {
  * @property {boolean} incomplete
  * @property {boolean} halted
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
+ * @property {{iterations: number, passed: boolean, temperatures: number[]}} [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).
  * @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

@@ -28,6 +28,7 @@ const { Evaluator } = require('./evaluator');
 const { Planner } = require('./planner');
 const { runPlan } = require('./run-plan');
 const { assessComplexity, isCritical } = require('./complexity');
+const { refine } = require('./refine');
 const { HaltError } = require('./errors');
 const { DECOMPOSITION_POLICY, capabilityScrub } = require('./recurse-prompts');
 const { synthesize } = require('./recurse-synthesize');
@@ -51,6 +52,11 @@ const DEFAULT_FANOUT_CONCURRENCY = 4;
 // many parallel scan-workers a measured corpus needs. A calibratable knob (the §9.1 algorithm; corpus-specific),
 // not a discovered constant — overridable via `opts.workerBudget`. 100 items ≈ a worker doing ~25 scan windows.
 const DEFAULT_WORKER_BUDGET = 100;
+// BA-8 leaf-refine: temperature ESCALATES per retry. The live POC (poc/ba8-leaf-refine.mjs) found that at a flat
+// low temperature a weak model regenerates byte-identical wrong code and IGNORES even crisp deterministic
+// feedback (0/5 recovery); recovery only appears once retries are given room to vary (0/5 → 2-3/5). So escalation
+// is a DESIGN REQUIREMENT of the seam, not a tuning nicety. Overridable via `opts.refineLeaf.temperatures`.
+const DEFAULT_REFINE_TEMPS = [0.2, 0.7, 1.0];
 
 /**
  * Split an array into EXACTLY `n` contiguous, near-equal chunks (the data-partition for the §11 width path).
@@ -82,6 +88,23 @@ function workerPersonaPrefix(persona) {
   return p ? p + '\n\n' : '';
 }
 
+/**
+ * BA-9 (relayfact F19): prepend the caller's read-only working-context blob to a worker's task message, so a
+ * sliced child can LOCATE its artifact (absolute paths / cwd) — the concrete context the Planner otherwise
+ * strips when it paraphrases the parent goal into child subtasks. Distinct from `persona`: persona is a STANCE
+ * on the SYSTEM prompt (a privileged seam); context is neutral run-state FACTS on the USER message (the form
+ * the live POC `poc/ba9-context-thread.mjs` validated: no-context 0/3 → context 3/3 on a weak model). Absent/
+ * blank ⇒ the task message is byte-identical to pre-BA-9 (backward-compatible). Carries down the tree via
+ * `forChild` (a child of a worker rooted at `/proj` is still rooted at `/proj`), like `persona`.
+ * @param {string} task
+ * @param {unknown} context
+ * @returns {string}
+ */
+function withContext(task, context) {
+  const c = typeof context === 'string' ? context.trim() : '';
+  return c ? `Working context (read-only):\n${c}\n\n${task}` : task;
+}
+
 /**
  * The opts a delegated child inherits. Strips the parent's TOP-LEVEL SETPOINT — `contract`/`evaluate` grade
  * the WHOLE task's final answer; a child grading its own slice against the whole definition-of-done is wasted
@@ -91,9 +114,10 @@ function workerPersonaPrefix(persona) {
  * answered over the parent's corpus; a child has its own subtask and must not re-scan the parent's full corpus
  * (that would fan a whole-corpus count out under every child). The `critical → force-verify` SAFETY FLOOR is
  * unaffected — it keys on the task text via `isCritical`, not the contract, so a critical child still
- * self-verifies. Handle tools (`opts.tools`), `synthesize`, `maxDepth`, and **`persona`** carry down — the
- * persona is a DURABLE worker stance (a child of a "senior security engineer" is still one), unlike the
- * top-only `contract`/`evaluate` setpoint. It rides through the `...opts` spread (not in the strip list).
+ * self-verifies. Handle tools (`opts.tools`), `synthesize`, `maxDepth`, **`persona`**, and **`context`** (BA-9)
+ * carry down — the persona is a DURABLE worker stance (a child of a "senior security engineer" is still one)
+ * and the context is durable run-state (a child rooted at `/proj` is still rooted at `/proj`), unlike the
+ * top-only `contract`/`evaluate` setpoint. They ride through the `...opts` spread (not in the strip list).
  * @param {RecurseOptions} opts
  * @returns {RecurseOptions}
  */
@@ -111,6 +135,30 @@ function forChild(opts) {
   };
 }
 
+/**
+ * The ctx handed to a worker `Loop.run({ ctx })` or to a direct `ctx.policy(...)` checkpoint — i.e. the ctx
+ * that a wired gate records VERBATIM into the audit as `action._ctx` (see `defaultActionTranslator` in
+ * src/bareguard-adapter.js). It STRIPS the live `provider` instance, because that object carries the API key
+ * (`provider.apiKey`) and bareguard serializes `_ctx` to disk — so an un-stripped ctx writes the raw
+ * `sk-…` key into the plaintext audit log (F16/BA-1, confirmed by relayfact probe-03).
+ *
+ * Only the AUDITED copy is cleaned: the provider still rides in the recurse-internal ctx that is threaded into
+ * each child `recurse()` self-call (children need `ctx.provider` to run), and the worker Loop already receives
+ * the provider as a constructor option — `Loop.run` never reads `ctx.provider`. The provider's IDENTITY is not
+ * lost from the audit either: the meter records the provider NAME on the `{type:'llm'}` action's args.
+ *
+ * NB: this strips the provider only — the leak that was grounded. A caller that threads its OWN secret-bearing
+ * fields onto ctx is backstopped by bareguard-side redaction (BG-1), the defense-in-depth pair to this fix.
+ * @param {RecurseCtx} ctx
+ * @param {object} [overrides] - extra fields to set on the audited copy (e.g. `{ depth }`).
+ * @returns {object}
+ */
+function auditSafeCtx(ctx, overrides = {}) {
+  const safe = { ...(ctx || {}) };
+  delete (/** @type {any} */ (safe)).provider;
+  return { ...safe, ...overrides };
+}
+
 /**
  * @typedef {object} RecurseCtx
  * The per-run runtime blob — the wiring, threaded down the whole recursion tree (and forwarded to the worker
@@ -122,7 +170,12 @@ function forChild(opts) {
  *   and worker tokens are all real spend (BA1: never invisible).
  * @property {number} [depth] - The current recursion depth (0 at the top). Incremented on each self-call;
  *   threaded into `policy`. Callers normally omit it (defaults to 0).
- * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate).
+ * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate). This
+ *   is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+ *   `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+ *   (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+ *   the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+ *   gate is wired) the bareguard audit.
  * @property {{recall: Function}} [litectx] - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
  *   retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
  *   the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx
@@ -144,8 +197,35 @@ function forChild(opts) {
  *   **SECURITY:** this is a PRIVILEGED system-prompt seam — treat `persona` like a system prompt. Do NOT pass
  *   untrusted / end-user-controlled text here; a hostile persona is prepended ahead of the decomposition policy
  *   and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
+ * @property {string} [context] - (BA-9 / relayfact F19) An optional caller-supplied READ-ONLY working-context
+ *   blob (e.g. "project root: /abs/path\nfiles are relative to it") prepended to EVERY worker's task message as
+ *   a `Working context:` block, so a sliced child can LOCATE its artifact — the concrete context (absolute
+ *   paths / cwd) the Planner strips when it paraphrases the parent goal into child subtasks. CARRIES DOWN the
+ *   tree (preserved by `forChild`, like `persona`) and, when forced fan-out plans, is forwarded as the Planner's
+ *   `info` so the slices themselves are path-aware. Also shown to the verifier (neutral FACTS, not a stance, so
+ *   no anti-sycophancy concern — and an agentic critic needs the path to exercise the artifact). Distinct from
+ *   `persona`: persona is a privileged SYSTEM-prompt stance; context is run-state facts on the USER message.
+ *   Absent/blank ⇒ byte-identical to pre-BA-9 (backward-compatible). Validated live (`poc/ba9-context-thread.mjs`:
+ *   a weak model went 0/3 → 3/3 at locating an unguessable file once the root was threaded).
+ *   **SECURITY:** this becomes part of every worker's prompt (and the verifier's) — lower-privilege than
+ *   `persona` (the USER message, not the SYSTEM prompt) but still a prompt-injection surface. Intended for
+ *   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]
+ *   (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
+ *   returns a `Verdict`; on a non-pass its `critique` (the GAP, not the transcript) is fed FRESH into the next
+ *   attempt (D6/A1 anti-anchoring) and the **retry temperature ESCALATES** (`temperatures`, default
+ *   `[0.2,0.7,1.0]`) — the live-validated requirement 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). `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.
  * @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]
@@ -205,6 +285,9 @@ function forChild(opts) {
  * @property {boolean} incomplete
  * @property {boolean} halted
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
+ * @property {{iterations: number, passed: boolean, temperatures: number[]}} [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).
  * @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.
@@ -363,7 +446,7 @@ async function recurse(task, ctx = {}, opts = {}) {
         provider,
         window: opts.window,
         passes: opts.passes,
-        ctx: { ...ctx, depth },
+        ctx: auditSafeCtx(ctx, { depth }), // scan's Loop run ctx reaches the gate — strip provider (F16/BA-1)
         onLlmResult: ctx.onLlmResult,
         policy: ctx.policy,
       }));
@@ -372,6 +455,15 @@ async function recurse(task, ctx = {}, opts = {}) {
     if (Array.isArray(opts.corpus)) retrievalTools.push(buildExactTool(normalizeCorpus(opts.corpus)));
   }
   const handleTools = [...(Array.isArray(opts.tools) ? opts.tools : []), ...retrievalTools];
+
+  // BA-8 (opt-in): a DEFINITE leaf (no spawn offered — `simple` tier or at `maxDepth`) with a caller sensor runs
+  // as a bounded refine-with-escalation loop instead of a single pass, so a failed slice self-corrects. Gating on
+  // `!canSpawn` keeps it predictable (a node that may delegate is an orchestrator, not a leaf) and means the seam
+  // engages exactly at the leaves of a Family-A tree (it carries down via forChild). A no-op when unset.
+  if (!canSpawn && opts.refineLeaf && typeof opts.refineLeaf.sensor === 'function') {
+    return recurseRefineLeaf(task, ctx, opts, { provider, system, handleTools, depth, critical, node, sensor: opts.refineLeaf.sensor });
+  }
+
   // NB-3: collect each child's declared RESULT value (copy-on-return: the value, never its transcript) so the
   // reducer can aggregate them. Step-3's seam handed the receipts only, so a code-reduce could not see what to
   // combine — this closes that gap and is what Family B (step 5) will reduce over `runPlan` results[].
@@ -392,9 +484,13 @@ async function recurse(task, ctx = {}, opts = {}) {
   // Fresh message array = a true fresh window (RC-2 copy-on-return, IN side): the worker sees ONLY its task,
   // never a parent transcript. `ctx.depth` is threaded so bareguard's policy can enforce the depth cap (§6).
   const out = await loop.run(
-    [{ role: 'user', content: task }],
+    // BA-9: prepend the caller's read-only working-context (paths/cwd) so this worker can locate its artifact.
+    [{ role: 'user', content: withContext(task, opts.context) }],
     tools,
-    { ctx: { ...ctx, depth } },
+    // auditSafeCtx: the run ctx reaches the gate as `_ctx`; strip the key-bearing provider (F16/BA-1). The
+    // worker Loop already has `provider` as a constructor option, so stripping it from the run ctx is invisible
+    // to the worker and only cleans the audited copy.
+    { ctx: auditSafeCtx(ctx, { depth }) },
   );
 
   node.tokens = out.metrics ? out.metrics.tokens : null;
@@ -472,6 +568,96 @@ async function recurse(task, ctx = {}, opts = {}) {
   }
 }
 
+/**
+ * BA-8 leaf-refine — run a DEFINITE leaf as a bounded generate→sense→regenerate loop (relayfact F17). Reuses the
+ * existing `refine.js` primitive (the Outcomes iterate→grade→revise port): each attempt is a FRESH leaf Loop
+ * (fresh window = fresh-feedback, D6/A1) seeded with the working-context'd task + (on a retry) the prior GAP, run
+ * at an ESCALATING temperature — the live-validated requirement that lets a weak model escape a repeat-the-same-
+ * mistake rut (a flat temperature recovered 0/5 in `poc/ba8-leaf-refine.mjs`). The `sensor` is the caller's
+ * DETERMINISTIC close (test/compile/lint, not a model judge). Governance is bareguard's: every attempt is gate-
+ * checked (`ctx.policy`) and metered (`onLlmResult`); a HaltError mid-loop is a clean `{incomplete}`. Honest
+ * non-recovery is reported (`receipts.refineLeaf.passed=false`), never a faked pass. An optional rubric `verify`
+ * still runs on top when a `contract`/`evaluate`/critical applies (the sensor gates retries; the rubric grades).
+ * @param {string} task
+ * @param {RecurseCtx} ctx
+ * @param {RecurseOptions} opts
+ * @param {{provider: Provider, system: string, handleTools: ToolDef[], depth: number, critical: boolean, node: RecurseNode, sensor: Function}} state
+ * @returns {Promise<RecurseResult>}
+ */
+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 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;
+
+  // 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
+  // numeric, so we accrue field-wise (robust to extra/renamed numeric fields). The gate already sees each attempt
+  // via onLlmResult independently; this is the receipts mirror. Stays null until an attempt produces metrics.
+  /** @type {Record<string, number>|null} */
+  let tokensSum = null;
+  const accrueTokens = (/** @type {any} */ t) => {
+    if (!t || typeof t !== 'object') return;
+    tokensSum = tokensSum || {};
+    for (const [k, v] of Object.entries(t)) if (typeof v === 'number') tokensSum[k] = (tokensSum[k] || 0) + v;
+  };
+  // 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 loop = new Loop({
+      provider, system,
+      policy: ctx.policy || undefined,
+      onLlmResult: ctx.onLlmResult || undefined,
+      stream: ctx.stream || undefined,
+      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;
+    const out = await loop.run([{ role: 'user', content: userText }], handleTools, { ctx: auditSafeCtx(ctx, { depth }), temperature });
+    accrueTokens(out.metrics ? out.metrics.tokens : null);
+    if (typeof out.error === 'string' && out.error.startsWith('halt:')) throw new HaltError('refine-leaf attempt halted', { rule: out.error.slice('halt:'.length) });
+    if (out.error) throw new Error(out.error); // a non-halt worker fault → honest incomplete
+    return out.text;
+  };
+
+  try {
+    const outcome = await refine({
+      attempt,
+      evaluate: (result, c) => sensor(result, { task, context: opts.context, contract: c.contract }),
+      contract: typeof opts.contract === 'string' ? opts.contract : undefined,
+      maxIterations,
+    });
+    node.tokens = tokensSum;
+    node.refineLeaf = { iterations: outcome.iterations, passed: !!(outcome.verdict && outcome.verdict.pass), temperatures: temps.slice(0, outcome.iterations) };
+    const result = outcome.result;
+
+    // Optional rubric layer on top of the deterministic sensor (RC-7): forced for critical, or a contract/override.
+    const wantVerify = critical || typeof opts.contract === 'string' || typeof opts.evaluate === 'function';
+    if (wantVerify) {
+      const verdict = await verify(task, result, ctx, opts);
+      node.verdict = verdict;
+      return { result, verdict, receipts: node };
+    }
+    // No rubric layer ⇒ the sensor's final verdict IS the node verdict (a non-pass is surfaced, not hidden).
+    node.verdict = outcome.verdict || null;
+    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
+    if (err instanceof HaltError) {
+      node.halted = true;
+      node.incomplete = true;
+      return { incomplete: true, best: null, receipts: node };
+    }
+    node.incomplete = true;
+    return { incomplete: true, best: null, receipts: node };
+  }
+}
+
 /**
  * SCAN (§10 step 7 / §9.2.1) — the default retrieval mode for a "how many / all" task over a corpus. A
  * deterministic ORCHESTRATION, not a worker model call: every slice is processed, an isolated Loop LLM-judges
@@ -524,7 +710,7 @@ async function recurseScan(task, ctx, opts, state) {
       provider,
       window: opts.window,
       passes: opts.passes,
-      ctx: { ...ctx, depth: state.depth },
+      ctx: auditSafeCtx(ctx, { depth: state.depth }), // scan's Loop run ctx reaches the gate — strip provider (F16/BA-1)
       onLlmResult: ctx.onLlmResult,
       policy: ctx.policy,
     });
@@ -615,7 +801,7 @@ async function recursePartition(task, ctx, opts, state) {
     //     spends (bounds the burst to zero); a plain deny is advisory (allowlist-safe), same contract as fanout.
     if (typeof ctx.policy === 'function') {
       try {
-        await ctx.policy('recurse_partition', { width, size, depth }, { ...ctx, depth });
+        await ctx.policy('recurse_partition', { width, size, depth }, auditSafeCtx(ctx, { depth }));
       } catch (err) {
         if (err instanceof HaltError) throw err;
       }
@@ -715,7 +901,10 @@ async function recurseFanout(task, ctx, opts, state) {
     const planner = new Planner({ provider, onLlmResult: /** @type {any} */ (ctx.onLlmResult) || undefined });
     let steps;
     try {
-      steps = await planner.plan(task, { count });
+      // BA-9: forward the working-context as the Planner's `info` so the slices it writes are path-aware (a
+      // child still also receives `opts.context` directly via `forChild` — this just improves the split).
+      const planContext = typeof opts.context === 'string' && opts.context.trim() ? { count, info: opts.context } : { count };
+      steps = await planner.plan(task, planContext);
     } catch (err) {
       if (err instanceof HaltError) throw err;
       node.incomplete = true;
@@ -731,7 +920,7 @@ async function recurseFanout(task, ctx, opts, state) {
     //    descriptor — the load-bearing budget signal is the HaltError, on bareguard's existing contract.
     if (typeof ctx.policy === 'function') {
       try {
-        await ctx.policy('recurse_fanout', { count: steps.length, depth }, { ...ctx, depth });
+        await ctx.policy('recurse_fanout', { count: steps.length, depth }, auditSafeCtx(ctx, { depth }));
       } catch (err) {
         if (err instanceof HaltError) throw err;
         // non-halt policy error/deny → advisory; proceed (per-worker policy still gates each child below)
@@ -896,6 +1085,9 @@ function buildSpawnTool(ctx, opts, depth, maxDepth, node, childResults) {
  */
 function verify(task, result, ctx, opts) {
   const contract = typeof opts.contract === 'string' ? opts.contract : null;
+  // BA-9: the verifier sees the working-context too — neutral facts (not a stance, so no anti-sycophancy risk),
+  // and an agentic critic needs the path to exercise the artifact. A caller `evaluate` gets the RAW task (it owns
+  // its own context); only the default isolated grader is contextualized.
   if (typeof opts.evaluate === 'function') {
     return Promise.resolve(opts.evaluate(result, { contract, task }));
   }
@@ -905,7 +1097,7 @@ function verify(task, result, ctx, opts) {
     ? 'Judge whether the result satisfies the definition of done. Be strict and adversarial; cite the specific gap on any shortfall.'
     : 'Judge whether the result fully and correctly answers the goal. Be strict and adversarial; cite the specific gap on any shortfall.';
   return evaluator.evaluate(
-    task,
+    withContext(task, opts.context),
     result,
     { rubric, contract: contract || undefined },
     { onLlmResult: /** @type {any} */ (ctx.onLlmResult), policy: ctx.policy },

package/tools/shell.d.ts

@@ -1,4 +1,13 @@
-export type GrepArgs = {
+declare namespace _exports {
+    export { GrepArgs, RunArgvArgs, ExecCommandArgs, ToolDef };
+}
+declare namespace _exports {
+    export { createShellTools };
+    export { _grepCore };
+    export { writeFile as _writeFile };
+}
+export = _exports;
+type GrepArgs = {
     pattern: string;
     path: string;
     recursive?: boolean | undefined;
@@ -11,28 +20,28 @@ export type GrepArgs = {
      */
     timeout?: number | undefined;
 };
-export type RunArgvArgs = {
+type RunArgvArgs = {
     argv: string[];
     cwd?: string | undefined;
     timeout?: number | undefined;
     maxBuffer?: number | undefined;
     env?: Record<string, string> | undefined;
 };
-export type ExecCommandArgs = {
+type ExecCommandArgs = {
     command: string;
     cwd?: string | undefined;
     timeout?: number | undefined;
     maxBuffer?: number | undefined;
     env?: Record<string, string> | undefined;
 };
-export type ToolDef = import("../types").ToolDef;
+type ToolDef = import("../types").ToolDef;
 /**
  * Create the three shell tools. No options — configuration is per-call via tool args,
  * gating is the caller's responsibility via `new Loop({ policy })`.
  *
  * @returns {{tools: ToolDef[]}}
  */
-export function createShellTools(): {
+declare function createShellTools(): {
     tools: ToolDef[];
 };
 /**
@@ -54,7 +63,7 @@ export function createShellTools(): {
  * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
  * @param {GrepArgs} args
  */
-export function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
+declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
     hits: {
         file: string;
         line: number;
@@ -63,3 +72,17 @@ export function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags
     truncated: boolean;
     fileCount: number;
 }>;
+/**
+ * Write text to a file (the BA-2 first-class write primitive — a coding agent must edit files, and routing
+ * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
+ * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
+ * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
+ * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+declare function writeFile({ path: rawPath, content, append, maxBytes }: {
+    path: string;
+    content?: string;
+    append?: boolean;
+    maxBytes?: number;
+}): Promise<string>;

package/tools/shell.js

@@ -3,13 +3,30 @@
 /**
  * Pure-Node shell tools — cross-platform (linux, macOS, Windows), no external binaries.
  *
- * Three primitives:
+ * Primitives:
  *   shell_read  — read a file or list a directory
  *   shell_grep  — regex search across files (JS regex, no grep/rg/findstr)
- *   shell_exec  — run a shell command with timeout + max buffer
+ *   shell_write — write/overwrite (or append to) a file, creating parent dirs (no shell)
+ *   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
  *
- * All three run through Loop's policy hook when wired via `new Loop({ policy })`.
+ * All run through Loop's policy hook when wired via `new Loop({ policy })`.
  * Library ships zero baked-in allowlist — gating is the agent author's responsibility.
+ *
+ * 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).
+ *
+ * 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
+ * not caught — a `shell_write` through such a link can escape the scope. If untrusted input can create
+ * symlinks under your scope, canonicalize (`fs.realpath`) before the gate, or keep the scope on a root with
+ * no attacker-writable symlinks. This is bareguard's documented lexical-match contract, not specific to this tool.
  */
 
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -20,6 +37,7 @@ const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
 
 const DEFAULT_READ_MAX_BYTES = 256 * 1024;       // 256 KB
+const DEFAULT_WRITE_MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a sanity ceiling on a single write (LLM-authored)
 const DEFAULT_GREP_MAX_MATCHES = 200;
 const DEFAULT_GREP_TIMEOUT_MS = 5_000;           // hard ceiling on a single grep — bounds ReDoS
 const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
@@ -67,6 +85,31 @@ async function readEntry(rawPath, maxBytes) {
   return fs.readFile(resolved, 'utf8');
 }
 
+/**
+ * Write text to a file (the BA-2 first-class write primitive — a coding agent must edit files, and routing
+ * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
+ * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
+ * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
+ * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+async function writeFile({ path: rawPath, content = '', append = false, maxBytes }) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw new Error('shell_write requires a non-empty "path" string');
+  }
+  const text = content == null ? '' : String(content);
+  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > cap) {
+    throw new Error(`shell_write content is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
+  }
+  const resolved = path.resolve(expandHome(rawPath));
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  if (append) await fs.appendFile(resolved, text, 'utf8');
+  else await fs.writeFile(resolved, text, 'utf8');
+  return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
+}
+
 // Probe the first 1KB for NUL bytes to skip binary files in grep walks.
 /** @param {string} filePath */
 async function isProbablyText(filePath) {
@@ -373,6 +416,23 @@ function createShellTools() {
       },
       execute: async (/** @type {GrepArgs} */ args) => grepPath(args),
     },
+    {
+      name: 'shell_write',
+      description: 'Write text to a file (overwriting it), creating parent directories as needed. No shell — so an ' +
+        'fs.writeScope policy can gate it by path (translate to {type:"write"}). Use append:true to add to the end ' +
+        'instead of overwriting. Returns a "wrote N bytes to <path>" summary. Max 5MB per write by default.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Target file path. ~ expands to home. Parent dirs are created.' },
+          content: { type: 'string', description: 'The full text to write (UTF-8).' },
+          append: { type: 'boolean', description: 'Append to the file instead of overwriting it (default false).' },
+          maxBytes: { type: 'integer', description: 'Reject a write larger than this many bytes (default 5242880).' },
+        },
+        required: ['path', 'content'],
+      },
+      execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) => writeFile(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.',
@@ -413,4 +473,4 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools, _grepCore };
+module.exports = { createShellTools, _grepCore, _writeFile: writeFile };