bare-agent 0.12.0 → 0.12.2

package/examples/README.md

@@ -0,0 +1,14 @@
+# examples
+
+Runnable reference scripts for bare-agent. Each is self-contained — the top-of-file docstring documents flags and required env vars. These ship in the npm package, so you can copy them straight out of `node_modules/bare-agent/examples/`.
+
+| Example | What it shows |
+|---------|---------------|
+| [`with-bareguard.mjs`](with-bareguard.mjs) | End-to-end Loop + bareguard wiring: budget cap, fs scope, bash allowlist, audit log, humanChannel. The canonical governed-loop reference. |
+| [`mcp-bridge-poc.js`](mcp-bridge-poc.js) | Auto-discover MCP servers from your IDE configs and expose them as bareagent tools. First run writes `.mcp-bridge.json` (edit to deny tools). |
+| [`mcp-bridge-concurrent.js`](mcp-bridge-concurrent.js) | Soak test: fan out concurrent `barebrowse_browse` calls against real domains (Amazon, Wikipedia, GitHub, a dead host) and verify resilience. |
+| [`orchestrator/`](orchestrator/) | Multi-agent dispatch via `spawn`. Three configs, one system prompt — no orchestrator class, no role types. Roles are JSON files. See its [README](orchestrator/README.md). |
+| [`wake.sh`](wake.sh) + [`wake.md`](wake.md) | Reference cron + jq script for firing deferred actions. The runtime half of `createDeferTool` — bareagent emits, `wake.sh` fires. |
+| [`replay-job.js`](replay-job.js) | Supervised replay POC: record a browser task once with the LLM driving, then replay against fresh snapshots with the LLM as locator-only. Falls back to full reasoning when the locator misses, and patches the trace. |
+
+For wiring recipes and API details see the [Integration Guide](../bareagent.context.md); for usage patterns and design philosophy see the [Usage Guide](../docs/02-features/usage-guide.md).

package/examples/mcp-bridge-concurrent.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Concurrent MCP stress test — real domains, real payloads, varying complexity.
+ *
+ * Usage:
+ *   node examples/mcp-bridge-concurrent.js
+ */
+
+const { readFileSync } = require('node:fs');
+const { createMCPBridge } = require('../src/mcp-bridge');
+
+async function main() {
+  console.log('Connecting to barebrowse...');
+  const bridge = await createMCPBridge({ servers: ['barebrowse'], timeout: 15000 });
+
+  if (bridge.servers.length === 0) {
+    console.error('No servers connected');
+    process.exit(1);
+  }
+
+  const browse = bridge.tools.find(t => t.name === 'barebrowse_browse');
+
+  const tasks = [
+    {
+      label: 'Amazon NL — 2.5 inch HDD SATA case',
+      args: { url: 'https://www.amazon.nl/s?k=2.5+inch+hdd+sata+case', maxChars: 3000 },
+      verify: (r) => /amazon/i.test(r) || /hdd|sata|case|behuizing/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Wikipedia — Phoenician language',
+      args: { url: 'https://en.wikipedia.org/wiki/Phoenician_language', maxChars: 3000 },
+      verify: (r) => /phoenician/i.test(r) || /semitic|canaanite/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Dead domain — should fail or timeout',
+      args: { url: 'https://this-domain-does-not-exist-xyz-999.com/page', maxChars: 1000 },
+      verify: () => true, // any response is fine, we just want to see it doesn't hang or crash others
+      shouldFail: true,
+    },
+    {
+      label: 'GitHub — bare-agent repo',
+      args: { url: 'https://github.com/nicobailon/bareagent', maxChars: 2000 },
+      verify: (r) => /bare.?agent|orchestration|lightweight/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Slow static page — archive.org',
+      args: { url: 'https://web.archive.org/web/2024/https://example.com/', maxChars: 2000 },
+      verify: (r) => /example|wayback|archive/i.test(r),
+      shouldFail: false,
+    },
+  ];
+
+  console.log(`\nFiring ${tasks.length} concurrent browse calls...\n`);
+
+  const t0 = Date.now();
+  const results = await Promise.allSettled(
+    tasks.map(t => browse.execute(t.args))
+  );
+  const elapsed = Date.now() - t0;
+
+  let passed = 0;
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    const r = results[i];
+    const status = r.status === 'fulfilled' ? 'OK' : 'FAIL';
+    const value = r.status === 'fulfilled' ? r.value : r.reason.message;
+    let text = typeof value === 'string' ? value : JSON.stringify(value);
+    // If barebrowse saved to disk, read the file to verify actual content
+    const fileMatch = text.match(/saved to (.+\.yml)/);
+    if (fileMatch) {
+      try { text += '\n' + readFileSync(fileMatch[1], 'utf8'); } catch {}
+    }
+    const correct = r.status === 'fulfilled' && task.verify(text);
+
+    console.log(`[${i + 1}] ${task.label}`);
+    if (task.shouldFail) {
+      const handled = r.status === 'rejected' || (r.status === 'fulfilled' && /error|fail|not|ERR_/i.test(text.slice(0, 500)));
+      console.log(`    Status: ${status} | Error handled gracefully: ${handled ? 'YES' : 'NO'}`);
+      console.log(`    Preview: ${(r.status === 'rejected' ? r.reason.message : text).slice(0, 120)}...`);
+      console.log();
+      if (handled) passed++;
+    } else {
+      console.log(`    Status: ${status} | Routed correctly: ${correct ? 'YES' : 'NO'}`);
+      console.log(`    Size: ${text.length} chars`);
+      console.log(`    Preview: ${text.slice(0, 120)}...`);
+      console.log();
+      if (correct) passed++;
+    }
+  }
+
+  console.log(`--- Result: ${passed}/${tasks.length} routed correctly in ${elapsed}ms ---`);
+  console.log(passed === tasks.length ? 'PASS' : 'FAIL');
+
+  await bridge.close();
+  console.log('Closed.');
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/mcp-bridge-poc.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * MCP Bridge POC — auto-discover MCP servers, expose as bareagent tools, run Loop.
+ *
+ * First run: discovers servers from IDE configs, writes .mcp-bridge.json (all tools allowed).
+ * Edit .mcp-bridge.json to deny tools. Changes survive refresh.
+ *
+ * Usage:
+ *   OPENAI_API_KEY=sk-... node examples/mcp-bridge-poc.js Go to example.com and describe it
+ *   ANTHROPIC_API_KEY=sk-... node examples/mcp-bridge-poc.js --provider anthropic What tools do you have?
+ *   node examples/mcp-bridge-poc.js --refresh                     # force re-discovery
+ */
+
+const { Loop } = require('../src/loop');
+const { createMCPBridge } = require('../src/mcp-bridge');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse flags
+  const providerFlag = args.includes('--provider') ? args.splice(args.indexOf('--provider'), 2)[1] : 'openai';
+  const refresh = args.includes('--refresh') ? (args.splice(args.indexOf('--refresh'), 1), true) : false;
+
+  // Everything left is the prompt
+  const prompt = args.join(' ') || 'List all your available tools and describe what each one does.';
+
+  // Provider
+  let provider;
+  if (providerFlag === 'anthropic') {
+    const { AnthropicProvider } = require('../src/provider-anthropic');
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) { console.error('Set ANTHROPIC_API_KEY'); process.exit(1); }
+    provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-4-20250514' });
+  } else {
+    const { OpenAIProvider } = require('../src/provider-openai');
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) { console.error('Set OPENAI_API_KEY'); process.exit(1); }
+    provider = new OpenAIProvider({ apiKey, model: 'gpt-4.1-mini' });
+  }
+
+  // Bridge — reads .mcp-bridge.json if it exists, discovers on first run or TTL expiry
+  const bridge = await createMCPBridge({ refresh, timeout: 20000 });
+
+  if (bridge.servers.length === 0) {
+    console.error('No MCP servers found. Check your .mcp.json or ~/.claude/mcp_servers.json');
+    process.exit(1);
+  }
+
+  console.log();
+  console.log(`Prompt: ${prompt}`);
+  console.log('---');
+
+  const loop = new Loop({
+    provider,
+    maxRounds: 5,
+    system: `You are a helpful assistant with access to MCP tools. Use them to accomplish the user\'s request. Be concise.\n\n${bridge.systemContext}`,
+    onToolCall: (name, args) => console.log(`[tool] ${name}(${JSON.stringify(args)})`),
+    onText: (text) => console.log(`[response] ${text}`),
+  });
+
+  try {
+    const result = await loop.run(
+      [{ role: 'user', content: prompt }],
+      bridge.tools,
+    );
+    console.log('---');
+    console.log('Done.', { usage: result.usage, cost: result.cost ? `$${result.cost.toFixed(4)}` : 'n/a' });
+  } catch (err) {
+    console.error('Loop error:', err.message);
+  } finally {
+    await bridge.close();
+  }
+}
+
+main();

package/examples/orchestrator/README.md

@@ -0,0 +1,53 @@
+# orchestrator/
+
+Reference pattern for multi-agent dispatch. **Three configs and a system
+prompt — no orchestrator class, no role types, no DAG runner.** The LLM
+itself is the dispatcher; the only primitive is `spawn(config, input)`.
+
+```
+orchestrator/
+├── orchestrator.json     # the parent agent — picks a specialist per job
+└── specialists/
+    ├── summarizer.json   # specialist: summarise text given as input
+    └── researcher.json   # specialist: shell_grep + shell_read across cwd
+```
+
+## Run it
+
+```bash
+cd examples/orchestrator
+OPENAI_API_KEY=... echo '{"content":"Summarise the README in this repo."}' \
+  | bare-agent --config orchestrator.json
+```
+
+The orchestrator's system prompt tells the model:
+
+> You receive a job. Decide which specialist handles it (summarizer or
+> researcher), `spawn` that specialist with the relevant input, and return
+> the specialist's result.
+
+The model picks `spawn(config: 'specialists/researcher.json', input: ...)`,
+the researcher reads the README via `shell_read`, returns its summary, the
+orchestrator returns that to stdout.
+
+## What's gated
+
+Both `orchestrator.json` and `specialists/*.json` declare a `gate` block
+that wires bareguard. Defaults:
+
+- `budget.maxCostUsd: 0.50` — hard cap on the *family* (parent + children
+  share via `BAREGUARD_BUDGET_FILE`).
+- `limits.maxTurns: 20`, `limits.maxChildren: 3`, `limits.maxDepth: 2` —
+  spawn-tree shape bounds.
+- `spawn.ratePerMinute: 5`, `defer.ratePerMinute: 10` — bareguard 0.2 rate
+  caps.
+- `bash.allow` and `fs.readScope` scoped per specialist.
+
+## Why this isn't a framework
+
+There's no `class Orchestrator`, no `dispatch_to_specialist()`, no shared
+state object. Roles are *configs*, not types. Adding a new specialist is
+adding one JSON file — no code change to bareagent or the orchestrator.
+
+The "intelligence" is the orchestrator's system prompt. Substitute a
+better-written prompt and the same primitives handle a 5-specialist team.

package/examples/orchestrator/orchestrator.json

@@ -0,0 +1,14 @@
+{
+  "systemPrompt": "You are an orchestrator. You receive a job (the user's first message), decide which specialist handles it, then spawn that specialist with the relevant input and return its result.\n\nAvailable specialists (config paths relative to cwd):\n  - specialists/summarizer.json — summarises text content given via input.content\n  - specialists/researcher.json — searches and reads files in the project\n\nUse the spawn tool: spawn({ config: '<path>', input: { ...whatever the specialist expects... } }). The result.text from spawn is the specialist's final answer — return it verbatim or with a one-line preface.\n\nDo not attempt the work yourself; you are a router. If no specialist fits, say so plainly.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": ["spawn"],
+  "gate": {
+    "budget": { "maxCostUsd": 0.50 },
+    "limits": { "maxTurns": 20, "maxChildren": 3, "maxDepth": 2 },
+    "spawn":  { "ratePerMinute": 5 },
+    "defer":  { "ratePerMinute": 10 },
+    "tools":  { "allowlist": ["spawn"] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/orchestrator/specialists/researcher.json

@@ -0,0 +1,12 @@
+{
+  "systemPrompt": "You are a researcher. You have shell_read and shell_grep tools scoped to the current working directory. The user's message describes what to find or read. Use shell_grep to locate matches and shell_read to read whole files. Return a concise summary of what you found (3-8 sentences). Do not invent file contents; if you can't find something, say so.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": ["shell_read", "shell_grep"],
+  "gate": {
+    "limits": { "maxTurns": 10 },
+    "fs":     { "readScope": ["."] },
+    "tools":  { "allowlist": ["shell_read", "shell_grep"] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/orchestrator/specialists/summarizer.json

@@ -0,0 +1,11 @@
+{
+  "systemPrompt": "You are a summarizer. The user's message contains text to summarise. Produce a concise (3-5 sentence) summary capturing the main points. Return the summary as your final response — no tool calls needed unless the input is malformed.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": [],
+  "gate": {
+    "limits": { "maxTurns": 5 },
+    "tools":  { "allowlist": [] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/replay-job.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Replay-job POC — supervised replay of a recorded browser task.
+ *
+ * The idea: record once with the LLM driving (full reasoning), then on every
+ * subsequent run replay the recorded *intents* against a fresh snapshot, with
+ * the LLM acting as a locator/supervisor — not a planner. If the locator
+ * can't find a match for a step, fall back to full Loop reasoning from that
+ * point and overwrite the trace. That's the self-healing path.
+ *
+ * Why this isn't a barebrowse feature: barebrowse stays dumb (URL → snapshot,
+ * ref → action). The "job" concept (trace storage, replay supervisor, scheduler
+ * hookup) is composed from bareagent primitives.
+ *
+ * Usage:
+ *   # First run — record:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --record demo-job \
+ *     "Go to example.com and click the 'More information' link"
+ *
+ *   # Subsequent runs — replay:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --replay demo-job
+ *
+ *   # Cron'd:
+ *   *\/15 * * * * node /path/to/replay-job.js --replay demo-job
+ *
+ * What's deliberately NOT in this POC (next steps, in order):
+ *   1. Fingerprint fast-path: hash selector+role+text per step, try direct
+ *      match before calling the locator LLM. Brings per-step cost to ~0 on
+ *      stable UIs (Gmail, IG).
+ *   2. PostState assertion: after each step, ask the LLM "does this snapshot
+ *      reflect the expected outcome?" Without this, replay can silently drift
+ *      on subtly-changed UIs.
+ *   3. Trace confidence: rolling success rate per step; below a threshold,
+ *      re-derive the whole trace instead of patching one entry.
+ *   4. Scheduler integration: wrap as a Scheduler trigger so cron is a config
+ *      line instead of an OS cron entry.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Loop } = require('../src/loop');
+
+const JOBS_DIR = path.join(__dirname, '..', '.jobs');
+
+function parseArgs(argv) {
+  const mode = argv.includes('--record') ? 'record'
+             : argv.includes('--replay') ? 'replay'
+             : null;
+  const flagIdx = argv.indexOf(`--${mode}`);
+  const name = mode ? argv[flagIdx + 1] : null;
+  const goal = argv.slice(flagIdx + 2).join(' ');
+  return { mode, name, goal };
+}
+
+function jobPath(name) { return path.join(JOBS_DIR, `${name}.json`); }
+
+function loadProvider() {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) { console.error('Set OPENAI_API_KEY'); process.exit(1); }
+  const { OpenAIProvider } = require('../src/provider-openai');
+  return new OpenAIProvider({ apiKey, model: 'gpt-4.1-mini' });
+}
+
+async function loadBrowseTools() {
+  const mod = await import('barebrowse/bareagent');
+  return mod.createBrowseTools({});
+}
+
+// --- RECORD ----------------------------------------------------------------
+// Run Loop normally. The onToolCall hook captures each step as it happens.
+// The trace stores the LLM's free-text "intent" (the assistant message
+// immediately preceding the tool call) alongside the tool name and args.
+// On replay, intent is what the locator LLM matches against — not args.
+async function record({ name, goal }) {
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+
+  const trace = [];
+  let pendingIntent = '';
+
+  const loop = new Loop({
+    provider,
+    maxRounds: 15,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      trace.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+
+  try {
+    const result = await loop.run([{ role: 'user', content: goal }], tools);
+    fs.mkdirSync(JOBS_DIR, { recursive: true });
+    fs.writeFileSync(jobPath(name), JSON.stringify({ goal, recordedAt: new Date().toISOString(), trace }, null, 2));
+    console.log(`[record] saved ${trace.length} steps to ${jobPath(name)}`);
+    console.log(`[record] cost: $${(result.cost ?? 0).toFixed(4)}`);
+  } finally {
+    await close();
+  }
+}
+
+// --- REPLAY ----------------------------------------------------------------
+// For each recorded step:
+//   1. Take a fresh snapshot.
+//   2. Ask the LLM (no tools, JSON-mode) to map the recorded intent to a ref
+//      in the current snapshot — OR return null if no match.
+//   3. On match: execute the tool with the resolved ref. The recorded args
+//      that aren't refs (e.g. type's `text`, goto's `url`) carry over verbatim.
+//   4. On miss: fall back to driving Loop from the remaining goal, capture
+//      the new sub-trace, and splice it into the saved trace.
+async function replay({ name }) {
+  const job = JSON.parse(fs.readFileSync(jobPath(name), 'utf8'));
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+  const toolByName = Object.fromEntries(tools.map((t) => [t.name, t]));
+
+  let mutated = false;
+
+  try {
+    for (let i = 0; i < job.trace.length; i++) {
+      const step = job.trace[i];
+      const tool = toolByName[step.tool];
+      if (!tool) throw new Error(`unknown tool in trace: ${step.tool}`);
+
+      // Steps whose args have no ref (goto, browse, back, scroll) replay verbatim.
+      if (!('ref' in (step.args || {}))) {
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(${JSON.stringify(step.args)})`);
+        await tool.execute(step.args);
+        continue;
+      }
+
+      // Ref-bearing steps: snapshot, then ask the LLM to locate.
+      const snapshot = await toolByName.snapshot.execute({});
+      const snapshotText = typeof snapshot === 'string' ? snapshot : (snapshot?.snapshot ?? JSON.stringify(snapshot));
+      const located = await locate({ provider, intent: step.intent, tool: step.tool, snapshotText });
+
+      if (located.ref) {
+        const args = { ...step.args, ref: located.ref };
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(ref=${located.ref}) — intent="${step.intent.slice(0, 60)}"`);
+        await tool.execute(args);
+      } else {
+        console.warn(`[replay ${i + 1}/${job.trace.length}] locator miss — falling back to full Loop`);
+        const remaining = `Continue this task from the current page. Original goal: ${job.goal}. We have completed ${i} of ${job.trace.length} recorded steps; the next intended step was: "${step.intent}".`;
+        const subTrace = await driveFallback({ provider, tools, goal: remaining });
+        job.trace.splice(i, job.trace.length - i, ...subTrace);
+        mutated = true;
+        break;
+      }
+    }
+
+    if (mutated) {
+      job.recordedAt = new Date().toISOString();
+      fs.writeFileSync(jobPath(name), JSON.stringify(job, null, 2));
+      console.log(`[replay] trace patched after locator miss; saved ${job.trace.length} steps`);
+    } else {
+      console.log(`[replay] completed ${job.trace.length} steps without falling back`);
+    }
+  } finally {
+    await close();
+  }
+}
+
+// Locator: structured-output call, no tools, no loop. One LLM call per ref-bearing step.
+async function locate({ provider, intent, tool, snapshotText }) {
+  const system = 'You map a recorded intent to a ref in a current ARIA snapshot. Reply with strict JSON: {"ref": "<ref>"} if confident, or {"ref": null, "reason": "<why>"} if no element matches. Never invent refs not present in the snapshot.';
+  const user = `Recorded intent: ${intent}\nTool: ${tool}\n\nCurrent snapshot:\n${snapshotText}\n\nReturn JSON only.`;
+  const { text } = await provider.generate({
+    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+  });
+  try {
+    const match = text.match(/\{[\s\S]*\}/);
+    return JSON.parse(match ? match[0] : text);
+  } catch {
+    return { ref: null, reason: 'unparseable locator response' };
+  }
+}
+
+// Fallback driver: same shape as record(), just used mid-replay when the
+// locator can't resolve a step. Returns the new sub-trace to splice in.
+async function driveFallback({ provider, tools, goal }) {
+  const sub = [];
+  let pendingIntent = '';
+  const loop = new Loop({
+    provider,
+    maxRounds: 10,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      sub.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+  await loop.run([{ role: 'user', content: goal }], tools);
+  return sub;
+}
+
+async function main() {
+  const { mode, name, goal } = parseArgs(process.argv.slice(2));
+  if (!mode || !name) {
+    console.error('Usage:\n  --record <name> "<goal>"\n  --replay <name>');
+    process.exit(1);
+  }
+  if (mode === 'record') {
+    if (!goal) { console.error('record mode requires a goal string'); process.exit(1); }
+    await record({ name, goal });
+  } else {
+    if (!fs.existsSync(jobPath(name))) { console.error(`no job at ${jobPath(name)}`); process.exit(1); }
+    await replay({ name });
+  }
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/examples/wake.md

@@ -0,0 +1,99 @@
+# wake.sh — defer queue runner
+
+`examples/wake.sh` is the reference scheduler that fires bareagent's
+deferred actions. It's not a library primitive — it's a small bash script
+you copy into your project and adapt. Bareagent emits JSONL records via
+the `defer` tool; wake.sh reads the queue and re-invokes bareagent with
+the fired action.
+
+## Installation
+
+```bash
+cp examples/wake.sh /usr/local/bin/bareagent-wake
+chmod +x /usr/local/bin/bareagent-wake
+```
+
+## Cron entry (every minute)
+
+```cron
+* * * * *  /usr/local/bin/bareagent-wake
+```
+
+For project-scoped use, run from the project directory:
+
+```cron
+* * * * *  cd /path/to/your/project && /usr/local/bin/bareagent-wake
+```
+
+## Environment overrides
+
+| Variable | Default | What it does |
+|---|---|---|
+| `BAREAGENT_DEFER_QUEUE` | `./bareagent-defers.jsonl` | Path to the JSONL defer queue (must match what the `defer` tool writes). |
+| `ORCHESTRATOR_CONFIG` | `./orchestrator.json` | Bareagent config file the wake script invokes for fired actions. |
+| `LOCKFILE` | `/tmp/bareagent-wake.lock` | Single-instance lock via `flock`. |
+| `BAREAGENT_WAKE_LOG_DIR` | `/tmp/bareagent-wake` | Per-fired-action log directory. |
+
+## Dependencies
+
+- `jq` — JSONL fold + filter
+- `flock` (Linux util-linux) — single-instance lock
+- `bare-agent` on `$PATH` — `npm install -g bare-agent` or use the full path
+
+## Behaviour
+
+1. **Folds** the queue: `{id, status, ...}` records are append-only; the
+   live status of each id is the *latest* line. jq does the fold.
+2. **Filters** to `status === 'pending' AND when <= now()`.
+3. For each due record: appends `{id, status: 'fired', ts}` (atomic JSONL
+   append on POSIX), then invokes
+   `bare-agent --config $ORCHESTRATOR_CONFIG` with the inner action as
+   stdin input. Bareagent runs the action through bareguard's gate as a
+   fresh action — full pipeline against the inner action, separate audit
+   line.
+4. After the fired invocation completes: appends `{id, status: 'done|failed', ts, exit_code?}`.
+
+## Why bash and not Node
+
+The wake script is OS-level glue — cron + filesystem + subprocess. Keeping
+it as a shell script makes the dependency on bareagent (and only bareagent)
+obvious, and avoids users thinking the script is a library to import.
+
+## Customisation points
+
+- **Different queue path:** set `BAREAGENT_DEFER_QUEUE` and pass the same
+  to your `defer` tool config (or `BAREAGENT_DEFER_QUEUE` env on the
+  bareagent process that emits).
+- **Different orchestrator per action type:** parse `record.action.type`
+  and pick a config file accordingly. ~5 lines added inside the per-record
+  loop.
+- **Different fire-time semantics:** instead of invoking bareagent CLI,
+  shell out to a Node script that wires Loop differently. The defer queue
+  schema doesn't constrain you.
+
+## Log rotation
+
+`logrotate(8)` is the standard answer. Example
+`/etc/logrotate.d/bareagent-wake`:
+
+```
+/tmp/bareagent-wake/*.log {
+    daily
+    rotate 7
+    compress
+    missingok
+    notifempty
+}
+
+/path/to/your/project/bareagent-defers.jsonl {
+    weekly
+    rotate 4
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+`copytruncate` matters for the queue: it preserves the file inode (which
+the defer tool's `appendFile` depends on for atomic POSIX appends).