agentbox-flight-recorder 0.2.1

package/src/adapters/mcp.js

@@ -0,0 +1,346 @@
+'use strict';
+/**
+ * agentbox — adapters/mcp.js
+ * The MCP wire tap: run any MCP server behind a recording proxy.
+ *
+ *   agentbox mcp -- npx -y @modelcontextprotocol/server-everything
+ *
+ * Point your MCP client (Claude Desktop, Cursor, Claude Code, any harness)
+ * at agentbox instead of the server. Agentbox spawns the real server, forwards
+ * every JSON-RPC message verbatim, and writes a hash-chained tape of:
+ *
+ *   mcp_msg   every message, both directions (method + id + preview)
+ *   tool_call every tools/call — start (name + arguments) and end
+ *             (ok/error + duration + result preview), paired by request id
+ *   note      initialize handshake (server name/version/protocol)
+ *
+ * MCP stdio transport is newline-delimited JSON — the proxy is a line pump.
+ * Unknown bytes still get forwarded untouched; the tape never blocks a flight.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const { Recorder, newSessionFile, VERSION } = require('../chain');
+const MAX_PARTIAL_LINE = 1024 * 1024;
+
+function trunc(s, n) {
+  const str = s == null ? '' : String(s);
+  return str.length <= n ? str : `${str.slice(0, n)}…`;
+}
+
+/** Keep small JSON values intact; stringify+truncate anything chunky. */
+function slim(v, cap) {
+  if (v == null) return null;
+  if (typeof v === 'string') return trunc(v, cap);
+  try {
+    const j = JSON.stringify(v);
+    if (j.length <= cap) return v;
+    const keys = ['command', 'file_path', 'notebook_path', 'path', 'url', 'query', 'pattern'];
+    const summary = { _truncated: true };
+    for (const key of keys) if (v[key] != null) summary[key] = trunc(v[key], cap / 2);
+    return Object.keys(summary).length > 1 ? summary : trunc(j, cap);
+  } catch { return trunc(String(v), cap); }
+}
+
+function requestKey(id) {
+  if (id === undefined) return null;
+  return `${typeof id}:${String(id)}`;
+}
+
+function responseStatus(msg) {
+  return msg && (msg.error != null || (msg.result && msg.result.isError)) ? 'error' : 'ok';
+}
+
+/** Split a byte stream into complete lines (MCP stdio = 1 JSON-RPC msg/line). */
+class LineSplitter {
+  constructor(onLine, onFlush) {
+    this.parts = [];
+    this.length = 0;
+    this.onLine = onLine;
+    this.onFlush = onFlush;
+  }
+
+  push(chunk) {
+    const data = chunk.toString('utf8');
+    let start = 0;
+    let idx;
+    while ((idx = data.indexOf('\n', start)) !== -1) {
+      const part = data.slice(start, idx);
+      const line = (this.parts.length ? this.parts.join('') + part : part).replace(/\r$/, '');
+      this.parts = [];
+      this.length = 0;
+      if (line) this.onLine(line);
+      start = idx + 1;
+    }
+    if (start < data.length) {
+      const rest = data.slice(start);
+      this.parts.push(rest);
+      this.length += rest.length;
+      if (this.length >= MAX_PARTIAL_LINE) {
+        const bounded = this.parts.join('');
+        this.parts = [];
+        this.length = 0;
+        if (this.onFlush) this.onFlush(bounded);
+      }
+    }
+  }
+
+  flush() {
+    if (this.length) {
+      const rest = this.parts.join('');
+      if (rest.trim() && this.onFlush) this.onFlush(rest.replace(/\r$/, ''));
+      this.parts = [];
+      this.length = 0;
+    }
+  }
+}
+
+/**
+ * Run the proxy. `serverArgs` is the real MCP server command line.
+ * opts: { name, cwd, quiet, file }
+ * Returns a promise: { file, exitCode }.
+ */
+function runMcpProxy(serverArgs, opts = {}) {
+  return new Promise((resolve, reject) => {
+    if (!Array.isArray(serverArgs) || serverArgs.length === 0) {
+      reject(new Error('mcp: no server command — usage: agentbox mcp -- <server command> [args…]'));
+      return;
+    }
+    const name = opts.name || `${path.basename(serverArgs[0])}-mcp`;
+    const file = opts.file || newSessionFile(opts.cwd || process.cwd(), name);
+    const rec = new Recorder(file, {
+      name,
+      cmd: `mcp ⇄ ${serverArgs.join(' ')}`,
+      argv: serverArgs,
+      adapter: 'mcp',
+      cwd: process.cwd(),
+      user: os.userInfo().username,
+      host: os.hostname(),
+      platform: `${process.platform} ${process.arch}`,
+      agentbox: VERSION,
+      pid: process.pid,
+    });
+
+    if (!opts.quiet) {
+      const DIM = '\x1b[2m'; const CYAN = '\x1b[36m'; const BOLD = '\x1b[1m'; const RESET = '\x1b[0m';
+      process.stderr.write(`${DIM}${CYAN}⬢ agentbox${RESET}${DIM}: MCP wire tap on → ${file}${RESET}\n`);
+      process.stderr.write(`${DIM}  point your MCP client at agentbox; server: ${serverArgs.join(' ')}${RESET}\n`);
+    }
+
+    const child = spawn(serverArgs[0], serverArgs.slice(1), {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, AGENTBOX: '1', AGENTBOX_SESSION: file },
+      cwd: opts.cwd || process.cwd(),
+      detached: process.platform !== 'win32',
+    });
+
+    const pending = new Map(); // request id (string) → { name, t0 }
+    const t0 = Date.now();
+    let serverName = null;
+    let serverVersion = null;
+    let calls = 0;
+    let done = false;
+    let anonSeq = 0;
+    let shutdownTimer = null;
+    let requestedSignal = null;
+
+    const clientSplit = new LineSplitter(onClientLine, (raw) => forwardToServer(raw));
+    const serverSplit = new LineSplitter(onServerLine, (raw) => forwardToClient(raw));
+
+    function finalize(code, signal) {
+      if (done) return;
+      done = true;
+      clearTimeout(shutdownTimer);
+      process.removeListener('SIGINT', onSigint);
+      process.removeListener('SIGTERM', onSigterm);
+      clientSplit.flush();
+      serverSplit.flush();
+      rec.append('exit', {
+        code: code == null ? (signal ? -1 : 0) : code,
+        durationMs: Date.now() - t0,
+        signal: signal || undefined,
+        server: serverName,
+        unansweredCalls: pending.size,
+        toolCalls: calls,
+      });
+      rec.close();
+      if (!opts.quiet) {
+        const DIM = '\x1b[2m'; const CYAN = '\x1b[36m'; const RESET = '\x1b[0m';
+        process.stderr.write(`${DIM}${CYAN}⬢ agentbox${RESET}${DIM}: ${rec.i} events recorded · ${calls} tool calls · try: agentbox receipt${RESET}\n`);
+      }
+      const exitCode = requestedSignal === 'SIGINT' ? 130 : requestedSignal === 'SIGTERM' ? 143 : (code == null ? (signal ? 1 : 0) : code);
+      resolve({ file, exitCode });
+    }
+
+    function forwardToServer(line) {
+      if (child.stdin && child.stdin.writable && !child.stdin.write(`${line}\n`)) {
+        process.stdin.pause();
+        child.stdin.once('drain', () => process.stdin.resume());
+      }
+    }
+    function forwardToClient(line) {
+      if (!process.stdout.write(`${line}\n`)) {
+        child.stdout.pause();
+        process.stdout.once('drain', () => child.stdout.resume());
+      }
+    }
+
+    /** client (agent) → agentbox → real server */
+    function onClientLine(line) {
+      let msg = null;
+      try { msg = JSON.parse(line); } catch { /* not JSON — still forwarded verbatim */ }
+      if (msg && typeof msg === 'object') {
+        rec.append('mcp_msg', {
+          dir: 'C2S',
+          method: msg.method || null,
+          id: msg.id === undefined ? null : msg.id,
+          preview: trunc(line, 400),
+        });
+        const key = msg.id === undefined ? `anon:${++anonSeq}` : requestKey(msg.id);
+        if (msg.method === 'tools/call' && msg.params) {
+          calls += 1;
+          rec.append('tool_call', {
+            phase: 'start',
+            name: String(msg.params.name || 'unknown'),
+            input: slim(msg.params.arguments, 2000),
+            source: 'mcp',
+            id: msg.id === undefined ? null : msg.id,
+          });
+          pending.set(key, { name: String(msg.params.name || 'unknown'), t0: Date.now() });
+        } else if (msg.method === 'initialize') {
+          rec.append('note', { message: `client initialize · protocol ${msg.params && msg.params.protocolVersion ? msg.params.protocolVersion : '?'}` });
+        }
+      }
+      forwardToServer(line);
+    }
+
+    /** real server → agentbox → client */
+    function onServerLine(line) {
+      let msg = null;
+      try { msg = JSON.parse(line); } catch { /* pass through untouched */ }
+      if (msg && typeof msg === 'object') {
+        rec.append('mcp_msg', {
+          dir: 'S2C',
+          method: msg.method || null,
+          id: msg.id === undefined ? null : msg.id,
+          preview: trunc(line, 400),
+        });
+        const key = requestKey(msg.id);
+        if (pending.has(key)) {
+          const p = pending.get(key);
+          pending.delete(key);
+          const result = msg.result || {};
+          const rpcError = msg.error != null;
+          rec.append('tool_call', {
+            phase: 'end',
+            name: p.name,
+            source: 'mcp',
+            status: responseStatus(msg),
+            durationMs: Date.now() - p.t0,
+            preview: slim(rpcError ? msg.error : (result.content !== undefined ? result.content : result), 500),
+            id: msg.id === undefined ? null : msg.id,
+          });
+        }
+        if (msg.result && msg.result.serverInfo) {
+          serverName = (msg.result.serverInfo && msg.result.serverInfo.name) || null;
+          serverVersion = (msg.result.serverInfo && msg.result.serverInfo.version) || null;
+          rec.append('note', { message: `server: ${serverName || '?'}${serverVersion ? ` v${serverVersion}` : ''} · protocol ${msg.result.protocolVersion || '?'}` });
+        }
+      }
+      forwardToClient(line);
+    }
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => clientSplit.push(c));
+    process.stdin.on('end', () => {
+      clientSplit.flush();
+      try { child.stdin.end(); } catch { /* gone */ }
+      shutdownTimer = setTimeout(() => terminate('SIGTERM'), 1000);
+      shutdownTimer.unref();
+    });
+    process.stdin.on('error', () => { /* client vanished; server close will finalize */ });
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (c) => serverSplit.push(c));
+
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (c) => {
+      process.stderr.write(c); // server logs stay visible — transparency first
+      for (const line of String(c).split('\n')) {
+        if (line.trim()) rec.append('out', { stream: 'stderr', kind: 'plain', text: trunc(line, 500) });
+      }
+    });
+
+    child.on('error', (e) => {
+      rec.append('out', { stream: 'stderr', kind: 'plain', text: `agentbox: failed to spawn MCP server: ${e.message}` });
+      finalize(127);
+    });
+    child.on('close', (code, signal) => finalize(code, signal));
+
+    const killChild = (signal) => {
+      if (!child.pid) return;
+      try { if (process.platform !== 'win32') process.kill(-child.pid, signal); else child.kill(signal); } catch { /* gone */ }
+    };
+    const terminate = (signal) => {
+      requestedSignal = requestedSignal || signal;
+      rec.append('signal', { signal, source: 'keyboard' });
+      killChild(signal);
+      clearTimeout(shutdownTimer);
+      shutdownTimer = setTimeout(() => killChild('SIGKILL'), 2000);
+      shutdownTimer.unref();
+    };
+    const onSigint = () => terminate('SIGINT');
+    const onSigterm = () => terminate('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+  });
+}
+
+/**
+ * `agentbox init mcp -- <server command>`
+ * Print ready-to-paste MCP config blocks that route the server through agentbox.
+ */
+function initMcp(serverArgs, opts = {}) {
+  if (!Array.isArray(serverArgs) || serverArgs.length === 0) {
+    process.stderr.write('usage: agentbox init mcp -- <server command> [args…]\nexample: agentbox init mcp -- npx -y @modelcontextprotocol/server-everything\n');
+    process.exitCode = 1;
+    return;
+  }
+  const CYAN = '\x1b[36m'; const BOLD = '\x1b[2m'; const DIM = '\x1b[2m'; const RESET = '\x1b[0m';
+  // identity: prefer the package/module arg (npx -y @scope/pkg, node path/server.js)
+  // over the runner binary (npx/node) so config keys are meaningful
+  let serverName = path.basename(serverArgs[0]).replace(/[^\w.-]+/g, '-');
+  for (let i = 1; i < serverArgs.length; i++) {
+    const a = String(serverArgs[i]);
+    if (a.startsWith('-')) continue; // flags (and values we can skip cheaply)
+    if (a.startsWith('@') || a.includes('/') || a.endsWith('.js')) {
+      serverName = a.replace(/^@/, '').replace(/[^\w.-]+/g, '-');
+      break;
+    }
+  }
+  const displayCmd = `agentbox mcp -- ${serverArgs.join(' ')}`;
+
+  process.stdout.write(`${CYAN}${BOLD}⬢ agentbox${RESET}: MCP wire tap — route ${DIM}${serverArgs.join(' ')}${RESET} through agentbox\n\n`);
+  process.stdout.write(`  every ${BOLD}tools/call${RESET} (arguments, results, duration) lands on a tamper-evident tape\n\n`);
+
+  const block = (title, file, json) => {
+    process.stdout.write(`  ${BOLD}${title}${RESET} ${DIM}${file}${RESET}\n    ${json.replace(/\n/g, '\n    ')}\n\n`);
+  };
+
+  block('Claude Code (project)', '.mcp.json', JSON.stringify({
+    mcpServers: { [serverName]: { command: 'agentbox', args: ['mcp', '--', ...serverArgs] } },
+  }, null, 2));
+
+  block('Claude Desktop', 'claude_desktop_config.json', JSON.stringify({
+    mcpServers: { [serverName]: { command: 'agentbox', args: ['mcp', '--', ...serverArgs] } },
+  }, null, 2));
+
+  block('Cursor', '~/.cursor/mcp.json', JSON.stringify({
+    mcpServers: { [serverName]: { command: 'agentbox', args: ['mcp', '--', ...serverArgs] } },
+  }, null, 2));
+
+  process.stdout.write(`  ${DIM}alias: ${displayCmd}\n  agentbox must be on PATH (npm i -g agentbox-cli) or replace "agentbox"\n  with \`node <path>/bin/agentbox.js\`. restart the client to pick it up.${RESET}\n`);
+}
+
+module.exports = { runMcpProxy, initMcp, LineSplitter, requestKey, responseStatus };

package/src/chain.js

@@ -0,0 +1,286 @@
+'use strict';
+/**
+ * agentbox — chain.js
+ * Tamper-evident, hash-chained event log (the "black box tape").
+ *
+ * Every event is a JSONL line:
+ *   { i, t, type, data, prev, hash }
+ * where hash = sha256(prev || i || t || type || JSON(data)).
+ * Genesis prev is 64 zeros. Break or edit ANY line and verify() fails.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { redactEventData } = require('./redact');
+
+const GENESIS = '0'.repeat(64);
+const VERSION = '0.2.1';
+const LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+/** Deterministic event hash. data MUST be a JSON-stable object. */
+function eventHash(prev, i, t, type, data) {
+  return sha256(JSON.stringify([prev, i, t, type, data]));
+}
+
+function assertNotSymlink(file) {
+  const absolute = path.resolve(file);
+  const parsed = path.parse(absolute);
+  let current = parsed.root;
+  for (const part of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) throw new Error(`refusing symlink path: ${current}`);
+    } catch (e) {
+      if (e.code === 'ENOENT') return;
+      throw e;
+    }
+  }
+}
+
+/** Append-only recorder. Writes JSONL, one event per line. */
+class Recorder {
+  constructor(file, meta) {
+    this.file = file;
+    this.i = 0;
+    this.prev = GENESIS;
+    this.redactions = 0;
+    this.pending = [];
+    this.pendingBytes = 0;
+    this.flushTimer = null;
+    assertNotSymlink(file);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    this.fd = fs.openSync(file, 'w');
+    // stamp redaction policy into meta so the tape is self-describing
+    const redactOff = process.env.AGENTBOX_REDACT != null
+      && /^(0|false|off|no)$/i.test(String(process.env.AGENTBOX_REDACT).trim());
+    const metaWithPolicy = { ...meta, redact: !redactOff };
+    this.append('meta', metaWithPolicy); // event 0
+    this.flush(); // make the session discoverable immediately
+  }
+
+  flush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (!this.pendingBytes) return;
+    fs.writeSync(this.fd, this.pending.join(''));
+    this.pending = [];
+    this.pendingBytes = 0;
+  }
+
+  append(type, data) {
+    const { data: scrubbed, count } = redactEventData(data);
+    this.redactions += count;
+    const t = Date.now();
+    const i = this.i++;
+    const hash = eventHash(this.prev, i, t, type, scrubbed);
+    const line = JSON.stringify({ i, t, type, data: scrubbed, prev: this.prev, hash });
+    const record = line + '\n';
+    this.pending.push(record);
+    this.pendingBytes += Buffer.byteLength(record);
+    if (this.pendingBytes >= 64 * 1024) this.flush();
+    else if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => this.flush(), 25);
+      this.flushTimer.unref();
+    }
+    this.prev = hash;
+    return { i, t, type, data: scrubbed, hash, redactions: count };
+  }
+
+  close() {
+    this.flush();
+    try { fs.closeSync(this.fd); } catch { /* already closed */ }
+  }
+}
+
+/** Parse a session file into events (tolerates corrupt lines). */
+function loadEvents(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch (e) {
+    return { events: [], corrupt: { line: 0, error: e.message } };
+  }
+  const events = [];
+  const chunk = Buffer.allocUnsafe(64 * 1024);
+  let carry = Buffer.alloc(0);
+  let lineNo = 0;
+  try {
+    for (;;) {
+      const bytes = fs.readSync(fd, chunk, 0, chunk.length, null);
+      if (!bytes) break;
+      const data = carry.length ? Buffer.concat([carry, chunk.subarray(0, bytes)]) : chunk.subarray(0, bytes);
+      let start = 0;
+      for (let i = 0; i < data.length; i++) {
+        if (data[i] !== 10) continue;
+        const line = data.subarray(start, i).toString('utf8').trim();
+        if (line) events.push(JSON.parse(line));
+        lineNo += 1;
+        start = i + 1;
+      }
+      carry = start < data.length ? Buffer.from(data.subarray(start)) : Buffer.alloc(0);
+    }
+    const tail = carry.toString('utf8').trim();
+    if (tail) events.push(JSON.parse(tail));
+  } catch (e) {
+    return { events, corrupt: { line: lineNo, error: e.message } };
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { events, corrupt: null };
+}
+
+/** Recompute the full hash chain. Returns { ok, reason?, events }. */
+function verifyChain(file) {
+  const { events, corrupt } = loadEvents(file);
+  if (corrupt) {
+    return { ok: false, reason: `unreadable/corrupt JSON at line ${corrupt.line + 1}: ${corrupt.error}`, events };
+  }
+  if (events.length === 0) {
+    return { ok: false, reason: 'empty session', events };
+  }
+  let prev = GENESIS;
+  for (let index = 0; index < events.length; index++) {
+    const ev = events[index];
+    if (!ev || typeof ev !== 'object' || ev.i !== index || !Number.isFinite(ev.t) || typeof ev.type !== 'string' || !ev.data || typeof ev.data !== 'object' || Array.isArray(ev.data) || typeof ev.hash !== 'string') {
+      return { ok: false, reason: `invalid event structure at event ${index}`, events };
+    }
+    if (index === 0 && ev.type !== 'meta') return { ok: false, reason: 'event 0 must be session metadata', events };
+    if (index > 0 && ev.t < events[index - 1].t) return { ok: false, reason: `timestamp moved backwards at event ${index}`, events };
+    if (ev.prev !== prev) {
+      return { ok: false, reason: `chain break at event ${ev.i}: prev-pointer mismatch`, events };
+    }
+    const expect = eventHash(prev, ev.i, ev.t, ev.type, ev.data);
+    if (ev.hash !== expect) {
+      return { ok: false, reason: `hash mismatch at event ${ev.i} — content changed without rebuilding the chain`, events };
+    }
+    prev = ev.hash;
+  }
+  const complete = events[events.length - 1].type === 'exit';
+  return { ok: true, complete, events, count: events.length };
+}
+
+/**
+ * Last event in a session file — the cheap tail-read used to extend a chain
+ * from a different process (hook adapters are short-lived CLI invocations).
+ * Throws on a corrupt tail (never silently fork a broken chain); returns
+ * null only when the file is missing or empty.
+ */
+function lastEvent(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const chunks = [];
+    let end = size;
+    let foundNewline = false;
+    while (end > 0 && !foundNewline) {
+      const start = Math.max(0, end - 4096);
+      const buf = Buffer.allocUnsafe(end - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      chunks.unshift(buf);
+      const combined = Buffer.concat(chunks);
+      let last = combined.length - 1;
+      while (last >= 0 && (combined[last] === 10 || combined[last] === 13 || combined[last] === 32 || combined[last] === 9)) last--;
+      const nl = combined.lastIndexOf(10, last);
+      if (nl >= 0 || start === 0) {
+        foundNewline = true;
+        const line = combined.subarray(nl + 1, last + 1).toString('utf8');
+        return line ? JSON.parse(line) : null;
+      }
+      end = start;
+    }
+    return null;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Append one event to an existing chain file (or start one from genesis).
+ * Single appendFileSync write — atomic for lines < 4 KB on POSIX.
+ * Wrap in withFileLock() when several processes may race.
+ */
+function appendToChain(file, type, data) {
+  assertNotSymlink(file);
+  const { data: scrubbed, count } = redactEventData(data);
+  const last = lastEvent(file);
+  const i = last ? last.i + 1 : 0;
+  const prev = last ? last.hash : GENESIS;
+  const t = Date.now();
+  const hash = eventHash(prev, i, t, type, scrubbed);
+  const line = JSON.stringify({ i, t, type, data: scrubbed, prev, hash });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, line + '\n');
+  return { i, t, type, data: scrubbed, hash, redactions: count };
+}
+
+/**
+ * Exclusive cross-process lock around chain appends (hook adapter).
+ * fn(locked) — locked=false means we gave up after ~5 s; callers should
+ * DROP the event then (a dropped event beats a forked hash chain).
+ */
+function withFileLock(file, fn) {
+  const lock = `${file}.lock`;
+  assertNotSymlink(lock);
+  fs.mkdirSync(path.dirname(file), { recursive: true }); // lock file lives next to the session
+  const deadline = Date.now() + 5000;
+  let acquired = false;
+  const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+  for (;;) {
+    let fd;
+    try {
+      fd = fs.openSync(lock, 'wx');
+      fs.writeSync(fd, token);
+      fs.closeSync(fd);
+      acquired = true;
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // stale lock from a crashed process? reclaim it
+      try {
+        const owner = fs.readFileSync(lock, 'utf8').split(':')[0];
+        let alive = false;
+        try { process.kill(Number(owner), 0); alive = true; } catch { /* dead */ }
+        if (!alive && Date.now() - fs.statSync(lock).mtimeMs > 5000) { fs.unlinkSync(lock); continue; }
+      } catch { /* vanished — retry */ }
+      if (Date.now() > deadline) break;
+      // Synchronous hooks still need to wait, but sleeping avoids burning a core.
+      Atomics.wait(LOCK_SLEEP, 0, 0, 25);
+    }
+  }
+  try {
+    return fn(acquired);
+  } finally {
+    if (acquired) {
+      try { if (fs.readFileSync(lock, 'utf8') === token) fs.unlinkSync(lock); } catch { /* already gone */ }
+    }
+  }
+}
+
+/** Default sessions dir for a project. */
+function sessionsDir(cwd) {
+  return path.join(cwd || process.cwd(), '.agentbox', 'sessions');
+}
+
+let sessionSequence = 0;
+
+function newSessionFile(cwd, name) {
+  const dir = sessionsDir(cwd);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23);
+  const safe = (name || 'session').replace(/[^\w.-]+/g, '-').slice(0, 48);
+  const sequence = sessionSequence++;
+  return path.join(dir, `${stamp}-${process.pid}-${sequence}-${safe}.jsonl`);
+}
+
+module.exports = { GENESIS, VERSION, sha256, eventHash, Recorder, loadEvents, verifyChain, lastEvent, appendToChain, withFileLock, sessionsDir, newSessionFile, assertNotSymlink };