chainfess 0.0.0-stage → 0.1.0

package/src/blocks.mjs

@@ -0,0 +1,127 @@
+// Timestamp to block mapping (BRIEF §3.3). k-ary search with 8 probes per request.
+export const BLOCK_TIME = 0.104;
+export const MARGIN_START = 30;
+export const MARGIN_END = 120;
+const WIDEN = 200;
+
+export class PrunedError extends Error {
+  constructor(oldestSeen) {
+    super(`the RPC does not serve blocks that old (oldest seen ${oldestSeen})`);
+    this.name = 'PrunedError';
+    this.oldestSeen = oldestSeen;
+  }
+}
+
+const hex = (n) => '0x' + n.toString(16);
+
+export function createHeaderReader(rpc, cache = new Map()) {
+  let oldest = Infinity;
+  const state = { nonMonotonic: false };
+  async function read(ns) {
+    const need = [...new Set(ns)].filter((n) => !cache.has(n));
+    if (need.length) {
+      const res = await rpc.batch(need.map((n) => ['eth_getBlockByNumber', [hex(n), false]]), { size: 8 });
+      for (let i = 0; i < need.length; i++) {
+        const n = need[i];
+        // One behind-the-load-balancer node can answer null once; two nulls mean the block is not served.
+        const blk = res[i] || await rpc.call('eth_getBlockByNumber', [hex(n), false]);
+        if (!blk) throw new PrunedError(oldest === Infinity ? 'none' : oldest);
+        oldest = Math.min(oldest, n);
+        cache.set(n, Number(blk.timestamp));
+      }
+    }
+    return ns.map((n) => cache.get(n));
+  }
+  return { read, state, cache };
+}
+
+/** First block with timestamp >= t, searching (lo, hi] where ts(hi) >= t. Returns null if t is past latest. */
+async function firstAtOrAfter(reader, t, latest, latestTs, { hintLo = null, hintHi = null } = {}) {
+  if (latestTs < t) return null;
+  let hi = latest;
+  if (hintHi !== null && hintHi < latest) {
+    const [ts] = await reader.read([hintHi]);
+    if (ts >= t) hi = hintHi;
+  }
+  const span = Math.ceil(((latestTs - t) / BLOCK_TIME) * 1.3) + 2;
+  let lo = Math.max(0, latest - span);
+  if (hintLo !== null && hintLo > lo && hintLo < hi) lo = hintLo;
+  let [tsLo] = await reader.read([lo]);
+  while (tsLo >= t && lo > 0) {
+    hi = lo;
+    lo = Math.max(0, lo - Math.max(1000, (latest - lo)));
+    [tsLo] = await reader.read([lo]);
+  }
+  if (tsLo >= t) return lo; // lo == 0: t is before genesis
+  let round = 0;
+  while (hi - lo > 1) {
+    // Block time is close to constant, so aim at the interpolated spot; every other round is even, so the worst case stays log9.
+    const probes = [];
+    const add = (p) => {
+      const q = Math.floor(p);
+      if (q > lo && q < hi && !probes.includes(q)) probes.push(q);
+    };
+    if (round++ % 2 === 0) {
+      const [tsHi] = await reader.read([hi]);
+      const est = lo + ((t - tsLo) / Math.max(1, tsHi - tsLo)) * (hi - lo);
+      const d = Math.max(50, (hi - lo) / 40);
+      for (const f of [-1, -0.2, -0.04, -0.008, 0.008, 0.04, 0.2, 1]) add(est + f * d);
+      probes.sort((x, y) => x - y);
+    }
+    if (!probes.length) {
+      const step = (hi - lo) / 9;
+      for (let i = 1; i <= 8; i++) add(lo + step * i);
+    }
+    if (!probes.length) break;
+    const ts = await reader.read(probes);
+    let seq = tsLo;
+    let nextLo = lo;
+    let nextHi = hi;
+    let settled = false;
+    for (let i = 0; i < probes.length; i++) {
+      if (ts[i] < seq) reader.state.nonMonotonic = true;
+      seq = ts[i];
+      if (!settled) {
+        if (ts[i] >= t) { nextHi = probes[i]; settled = true; } else { nextLo = probes[i]; tsLo = ts[i]; }
+      }
+    }
+    lo = nextLo;
+    hi = nextHi;
+  }
+  return hi;
+}
+
+/**
+ * tStartMs/tEndMs: session span in ms. Returns inclusive blocks and notes.
+ * Margins are 0 for times given explicitly by --from/--to.
+ */
+export async function mapRange({ rpc, tStartMs, tEndMs, latest, latestTs, cache, marginStart = MARGIN_START, marginEnd = MARGIN_END }) {
+  const reader = createHeaderReader(rpc, cache);
+  reader.cache.set(latest, latestTs);
+  const notes = [];
+  const a = Math.ceil(tStartMs / 1000 - marginStart);
+  const b = Math.floor(tEndMs / 1000 + marginEnd);
+  let startBlock = await firstAtOrAfter(reader, a, latest, latestTs);
+  if (startBlock === null) {
+    notes.push('session starts after the latest block; clock ahead');
+    startBlock = latest;
+  } else if (startBlock === 0 && a < reader.cache.get(0)) {
+    notes.push('session start is before block 0; clamped');
+  }
+  let endBlock;
+  if (latestTs <= b) {
+    endBlock = latest;
+    notes.push('session still running or clock ahead');
+  } else {
+    const est = startBlock + Math.ceil(((b - a) / BLOCK_TIME) * 1.5) + 100;
+    const first = await firstAtOrAfter(reader, b + 1, latest, latestTs, { hintLo: startBlock, hintHi: est });
+    endBlock = first === null ? latest : Math.max(startBlock, first - 1);
+    if (first === 0) { endBlock = 0; notes.push('session end is before block 0; clamped'); }
+  }
+  if (reader.state.nonMonotonic) {
+    startBlock = Math.max(0, startBlock - WIDEN);
+    endBlock = Math.min(latest, endBlock + WIDEN);
+    notes.push('block timestamps not in order near this range; range widened by 200 blocks each side');
+  }
+  return { startBlock, endBlock, notes };
+}

package/src/canonical.mjs

@@ -0,0 +1,19 @@
+// Canonical JSON: keys sorted at every depth, no whitespace. Used for signing and verifying.
+export function canonicalJSON(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(v) {
+  if (v === null || typeof v !== 'object') {
+    if (typeof v === 'number' && !Number.isFinite(v)) throw new TypeError('canonicalJSON: non-finite number');
+    if (typeof v === 'bigint') throw new TypeError('canonicalJSON: bigint not allowed (use strings)');
+    return v;
+  }
+  if (Array.isArray(v)) return v.map((x) => (x === undefined ? null : sortKeys(x)));
+  const out = {};
+  for (const k of Object.keys(v).sort()) {
+    if (v[k] === undefined) continue;
+    out[k] = sortKeys(v[k]);
+  }
+  return out;
+}

package/src/classify.mjs

@@ -0,0 +1,111 @@
+// The ten rows of BRIEF §2.3. Pure. Only rows 6 and 7 are findings.
+export const STATUS = {
+  PRE: 'pre-session', POST: 'post-session', PENDING: 'pending', ACCOUNTED: 'accounted', PARTIAL: 'partial',
+  UNACCOUNTED: 'unaccounted', FOREIGN: 'foreign-signer', RECENT: 'recent-other', OBSERVED: 'observed',
+};
+
+export const WINDOW_BEFORE_MS = 5000;
+export const WINDOW_AFTER_MS = 60000;
+
+/** W(id) of §2.1. An unmatched tool_use runs to the end of the session. */
+export function inWindow(tool, timestampSec, tEndMs) {
+  if (!tool || tool.start === null || tool.start === undefined || timestampSec === null || timestampSec === undefined) return false;
+  const t = timestampSec * 1000;
+  const end = tool.end !== null && tool.end !== undefined ? tool.end + WINDOW_AFTER_MS : tEndMs;
+  return t >= tool.start - WINDOW_BEFORE_MS && t <= end;
+}
+
+/** Earliest structured occurrence; a tool_result occurrence is what can tie a tx to a tool call. */
+function toolOccurrence(occ) {
+  if (occ && occ.first && occ.first.toolId && (occ.first.kind === 'tool_result' || occ.first.kind === 'tool-results')) return occ.first;
+  return null;
+}
+
+/**
+ * A sending pattern explains the call's own send, not everything its output prints.
+ * `cast send … && cast block latest` must not turn a block dump into findings, so a call is left out of
+ * row 7 when its output prints a tx of a registered wallet (that is the send) or txs of more than two senders.
+ */
+export function dumpCalls(items, ctx) {
+  const senders = new Map();
+  const own = new Set();
+  for (const t of items) {
+    const occ = toolOccurrence(ctx.occurrence(t.hash));
+    if (!occ) continue;
+    const tool = ctx.tool(occ.toolId);
+    if (!tool || !inWindow(tool, t.timestamp, ctx.tEnd)) continue;
+    if (ctx.wallets.has(t.from)) { own.add(occ.toolId); continue; }
+    if (!senders.has(occ.toolId)) senders.set(occ.toolId, new Set());
+    senders.get(occ.toolId).add(t.from);
+  }
+  const out = new Set(own);
+  for (const [id, set] of senders) if (set.size > 2) out.add(id);
+  return out;
+}
+
+export function classify(tx, ctx) {
+  const mine = ctx.wallets.has(tx.from);
+  const occ = ctx.occurrence(tx.hash);
+  const row = (status, extra = {}) => ({ status, finding: status === STATUS.UNACCOUNTED || status === STATUS.FOREIGN, source: null, pattern: null, ...extra });
+
+  if (mine && tx.block !== null && tx.block < ctx.startBlock) return row(STATUS.PRE, sourceOf(occ, ctx));
+  if (tx.block !== null && tx.block > ctx.endBlock) return row(STATUS.POST, sourceOf(occ, ctx));
+  if (tx.block === null) return row(STATUS.PENDING, sourceOf(occ, ctx));
+
+  if (mine) {
+    if (occ && (occ.first || occ.other || occ.broadcast || occ.bare)) return row(STATUS.ACCOUNTED, sourceOf(occ, ctx));
+    const part = ctx.partial(tx.hash);
+    if (part) return row(STATUS.PARTIAL, { source: { kind: displayKind(part), line: part.line }, pattern: null });
+    return row(STATUS.UNACCOUNTED);
+  }
+
+  const toolOcc = toolOccurrence(occ);
+  const src = sourceOf(occ, ctx);
+  if (toolOcc) {
+    const tool = ctx.tool(toolOcc.toolId);
+    if (inWindow(tool, tx.timestamp, ctx.tEnd)) {
+      const isDump = ctx.dumps && ctx.dumps.has(toolOcc.toolId);
+      if (tool.pattern && !isDump) return row(STATUS.FOREIGN, { ...src, pattern: tool.pattern });
+      return row(STATUS.RECENT, src);
+    }
+  }
+  return row(STATUS.OBSERVED, src);
+}
+
+function displayKind(o) {
+  if (o.origin === 'subagent') return 'subagent';
+  if (o.kind === 'other') return 'text';
+  return o.kind;
+}
+
+function sourceOf(occ, ctx) {
+  if (!occ) return { source: null, pattern: null };
+  const o = occ.first || occ.other || occ.bare || occ.broadcast;
+  if (!o) return { source: null, pattern: null };
+  const tool = o.toolId ? ctx.tool(o.toolId) : null;
+  return { source: { kind: displayKind(o), line: o.line }, pattern: tool && tool.pattern ? tool.pattern : null };
+}
+
+/** mentioned-in-text flag of §2.4. Display only, never a status. */
+export function mentionFlag(hash, ctx) {
+  const matches = (set) => {
+    for (const key of set) {
+      const [p, s] = key.split('|');
+      if (hash.startsWith('0x' + p) && (!s || hash.endsWith(s))) return true;
+    }
+    return false;
+  };
+  for (const f of ctx.finals) if (f && (f.full.has(hash) || matches(f.partials))) return 'final';
+  if (ctx.textFull.has(hash) || matches(ctx.textPartials)) return 'text';
+  return 'none';
+}
+
+/** Prefix and suffix, or an 8+ hex prefix when the log gave no suffix. */
+export function partialMatch(hash, partials) {
+  for (const [key, occ] of partials) {
+    const [p, s] = key.split('|');
+    if (!hash.startsWith('0x' + p)) continue;
+    if (s ? hash.endsWith(s) : p.length >= 8) return occ;
+  }
+  return null;
+}

package/src/cli.mjs

@@ -0,0 +1,231 @@
+// Command line entry. Exit codes (BRIEF §2.3): 0 clean, 1 findings, 2 input error, 3 RPC unavailable, 4 partial scan.
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { auditReport, Declined, InputError } from './audit.mjs';
+import { renderText } from './report.mjs';
+import { RpcUnavailableError } from './rpc.mjs';
+import { PrunedError } from './blocks.mjs';
+import { createReplay } from './replay.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const DEMO_DIR = join(HERE, '..', 'fixtures', 'demo');
+
+const HELP = `chainfess: your agent says X, the chain says Y.
+Lists every transaction a coding agent's session log does not account for.
+
+  chainfess demo [--json]
+      Bundled fixture, recorded RPC replies, no wallet, no network.
+
+  chainfess audit --wallet 0x… [--log file]… [--all-sessions] [--rpc url] [--chain-id n]
+      [--from ISO] [--to ISO] [--from-block n] [--to-block n] [--max-hours h]
+      [--yes] [--json] [--no-subagents] [--quiet] [--debug]
+      Default log: the latest Claude Code session for this directory.
+      --no-subagents skips subagent transcripts only; the main session's saved tool outputs are still read.
+      A 32-byte value goes to the RPC only with a tx-hash label or read command beside it; the rest stays local.
+
+  chainfess sign --burn-tx 0x… --wallet 0x… [--log file]… [--server url]
+  chainfess verify <statement.json> [--pubkey file]
+  chainfess hook install --wallet 0x… | uninstall | status
+
+Exit codes: 0 no findings, 1 findings, 2 input error, 3 RPC unavailable, 4 partial scan.
+`;
+
+const AUDIT_OPTIONS = {
+  wallet: { type: 'string', multiple: true },
+  log: { type: 'string', multiple: true },
+  'all-sessions': { type: 'boolean' },
+  rpc: { type: 'string' },
+  'chain-id': { type: 'string' },
+  from: { type: 'string' },
+  to: { type: 'string' },
+  'from-block': { type: 'string' },
+  'to-block': { type: 'string' },
+  'max-hours': { type: 'string' },
+  yes: { type: 'boolean' },
+  json: { type: 'boolean' },
+  'no-subagents': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  debug: { type: 'boolean' },
+};
+
+function defaultIo() {
+  return {
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+    isTTY: !!process.stdout.isTTY,
+    errTTY: !!process.stderr.isTTY,
+    stdinTTY: !!process.stdin.isTTY,
+    env: process.env,
+    cwd: process.cwd(),
+  };
+}
+
+const useColor = (io) => io.isTTY && !io.env.NO_COLOR;
+
+function confirmer(io) {
+  if (!io.stdinTTY) return null;
+  return (question) => new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(`${question} [y/N] `, (a) => { rl.close(); resolve(/^y(es)?$/i.test(a.trim())); });
+  });
+}
+
+function auditOptsFrom(values, io) {
+  return {
+    wallets: values.wallet, logs: values.log, allSessions: values['all-sessions'],
+    rpc: values.rpc, chainId: values['chain-id'],
+    from: values.from, to: values.to, fromBlock: values['from-block'], toBlock: values['to-block'],
+    maxHours: values['max-hours'], yes: values.yes, noSubagents: values['no-subagents'],
+    cwd: io.cwd,
+  };
+}
+
+function printDebug(io, audit) {
+  const s = audit.rpcStats;
+  io.err(`debug: ${s.requests} RPC requests (${Object.entries(s.byMethod).map(([m, c]) => `${m}:${c}`).join(', ')}), fallback ${s.fallbackUsed ? "yes" : "no"}, throttle signals ${s.throttles}\n`);
+  io.err(`debug: candidates ${audit.candidates.hashes.length} looked up, ${audit.candidates.localOnly} local only, ${audit.candidates.notLookedUp} over limit; partial ${audit.sink.partials.size}; tool calls ${audit.sink.tools.size}\n`);
+  io.err(`debug: planned ${audit.ledger.plannedBlocks} blocks, scanned ${audit.ledger.scannedBlocks}, total ${audit.seconds.toFixed(1)} s\n`);
+}
+
+async function cmdAudit(argv, io, extra = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: AUDIT_OPTIONS, allowPositionals: false });
+  } catch (e) {
+    io.err(`${e.message}\n`);
+    return 2;
+  }
+  const v = parsed.values;
+  const showProgress = io.errTTY && !v.quiet && !v.json;
+  let lastLen = 0;
+  const progress = showProgress
+    ? (msg, transient) => {
+      io.err(`\r${msg.padEnd(lastLen)}${transient ? '' : '\n'}`);
+      lastLen = transient ? msg.length : 0;
+    }
+    : () => {};
+  try {
+    const { report, audit } = await auditReport({
+      ...auditOptsFrom(v, io), progress, confirm: confirmer(io), ...extra,
+    });
+    if (lastLen) io.err('\r' + ' '.repeat(lastLen) + '\r');
+    if (v.json) io.out(JSON.stringify(report, null, 2) + '\n');
+    else io.out(renderText(report, { color: useColor(io), quiet: v.quiet }));
+    if (v.debug) printDebug(io, audit);
+    return report.exitCode;
+  } catch (e) {
+    return reportError(e, io);
+  }
+}
+
+function reportError(e, io) {
+  if (e instanceof InputError || e instanceof Declined) { io.err(`${e.message}\n`); return 2; }
+  if (e instanceof RpcUnavailableError) { io.err(`${e.message}\n`); return 3; }
+  if (e instanceof PrunedError) { io.err(`${e.message}\n`); return 3; }
+  io.err(`unexpected error: ${e && e.message ? e.message : 'unknown'}\n`);
+  return 3;
+}
+
+export async function cmdDemo(argv, io) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { json: { type: 'boolean' } }, allowPositionals: false });
+  } catch (e) {
+    io.err(`${e.message}\n`);
+    return 2;
+  }
+  const world = JSON.parse(readFileSync(join(DEMO_DIR, 'rpc.json'), 'utf8'));
+  const { fetchImpl } = createReplay(world);
+  const { report } = await auditReport({
+    wallets: world.demoWallets, logs: [join(DEMO_DIR, 'session.jsonl')], cwd: DEMO_DIR,
+    fetchImpl, paceMs: 0, fallback: false, demo: true, noBroadcast: true, now: Date.parse(world.demoNow),
+    sleep: async () => {},
+  });
+  if (parsed.values.json) io.out(JSON.stringify(report, null, 2) + '\n');
+  else io.out(renderText(report, { color: useColor(io) }));
+  return report.exitCode;
+}
+
+async function cmdSign(argv, io) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: { ...AUDIT_OPTIONS, 'burn-tx': { type: 'string' }, server: { type: 'string' }, out: { type: 'string' } },
+      allowPositionals: false,
+    });
+  } catch (e) {
+    io.err(`${e.message}\n`);
+    return 2;
+  }
+  const mod = await loadSign(io);
+  if (!mod) return 2;
+  const v = parsed.values;
+  return mod.runSign({
+    ...auditOptsFrom(v, io), burnTx: v['burn-tx'], server: v.server, outFile: v.out,
+    out: (s) => io.out(s + '\n'), err: (s) => io.err(s + '\n'),
+  });
+}
+
+async function cmdVerify(argv, io) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { pubkey: { type: 'string' } }, allowPositionals: true });
+  } catch (e) {
+    io.err(`${e.message}\n`);
+    return 2;
+  }
+  const mod = await loadSign(io);
+  if (!mod) return 2;
+  return mod.runVerify(parsed.positionals[0], {
+    pubkey: parsed.values.pubkey ?? null, out: (s) => io.out(s + '\n'), err: (s) => io.err(s + '\n'),
+  });
+}
+
+async function loadSign(io) {
+  try {
+    return await import('./sign.mjs');
+  } catch {
+    io.err('this install of chainfess has no sign module (src/sign.mjs).\n');
+    return null;
+  }
+}
+
+async function cmdHook(argv, io) {
+  let mod;
+  try {
+    mod = await import('./hook.mjs');
+  } catch {
+    io.err('this install of chainfess has no hook module (src/hook.mjs).\n');
+    return 2;
+  }
+  return mod.runHook(argv, io);
+}
+
+export async function main(argv, ioOverride = {}) {
+  const io = { ...defaultIo(), ...ioOverride };
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case 'audit': return cmdAudit(rest, io);
+    case 'demo': return cmdDemo(rest, io);
+    case 'sign': return cmdSign(rest, io);
+    case 'verify': return cmdVerify(rest, io);
+    case 'hook': return cmdHook(rest, io);
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      io.out(HELP);
+      return cmd === undefined ? 2 : 0;
+    case '--version':
+    case '-v':
+      io.out('0.1.0\n');
+      return 0;
+    default:
+      io.err(`unknown command: ${String(cmd).slice(0, 40)}\n${HELP}`);
+      return 2;
+  }
+}

package/src/hook.mjs

@@ -0,0 +1,202 @@
+// `chainfess hook install|uninstall|status` and the SessionEnd command itself (BRIEF claim 16, SPIKE).
+// The hook must never block or fail a session: `hook run` hands off to a detached process and exits 0.
+import { spawn } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const BIN = fileURLToPath(new URL('../bin/chainfess.mjs', import.meta.url));
+const MARKER = 'chainfess-session-end-hook';
+const VERSION = '0.1.0';
+const STDIN_WAIT_MS = 2000;
+
+function paths(io) {
+  const env = io.env || process.env;
+  const home = io.home || env.HOME || homedir();
+  const base = env.CLAUDE_CONFIG_DIR || join(home, '.claude');
+  return { settings: join(base, 'settings.json'), reports: join(home, '.chainfess', 'reports') };
+}
+
+/** Under npx the package lives in a cache that can be pruned, so the hook names a pinned npx command instead. */
+function runner(binPath = BIN, nodePath = process.execPath) {
+  if (binPath.includes('/_npx/')) return `npx --yes chainfess@${VERSION}`;
+  return `"${nodePath}" "${binPath}"`;
+}
+
+export function hookCommand(wallets, binPath, nodePath) {
+  const flags = wallets.map((w) => `--wallet ${w}`).join(' ');
+  return `${runner(binPath, nodePath)} hook run ${flags} --tag ${MARKER} || true`;
+}
+
+const isOurs = (h) => h && typeof h.command === 'string' && h.command.includes(MARKER);
+
+function readSettings(file) {
+  if (!existsSync(file)) return {};
+  const doc = JSON.parse(readFileSync(file, 'utf8'));
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) throw new Error('not a JSON object');
+  return doc;
+}
+
+function writeSettings(file, doc, hadFile) {
+  mkdirSync(dirname(file), { recursive: true });
+  let backup = null;
+  if (hadFile) {
+    backup = `${file}.chainfess-backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    copyFileSync(file, backup);
+  }
+  const tmp = `${file}.chainfess-tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n');
+  renameSync(tmp, file);
+  return backup;
+}
+
+/** Pure: settings without our hook. Other hooks, even in the same group, stay. */
+export function withoutOurs(doc) {
+  const next = { ...doc };
+  const list = next.hooks && next.hooks.SessionEnd;
+  if (!Array.isArray(list)) return next;
+  const groups = [];
+  for (const g of list) {
+    if (!g || !Array.isArray(g.hooks)) { groups.push(g); continue; }
+    const kept = g.hooks.filter((h) => !isOurs(h));
+    if (kept.length) groups.push(kept.length === g.hooks.length ? g : { ...g, hooks: kept });
+  }
+  const hooks = { ...next.hooks };
+  if (groups.length) hooks.SessionEnd = groups; else delete hooks.SessionEnd;
+  if (Object.keys(hooks).length) next.hooks = hooks; else delete next.hooks;
+  return next;
+}
+
+export function withOurs(doc, command) {
+  const next = withoutOurs(doc);
+  if (next.hooks !== undefined && (typeof next.hooks !== 'object' || Array.isArray(next.hooks))) throw new Error('"hooks" is not an object');
+  const hooks = { ...(next.hooks || {}) };
+  if (hooks.SessionEnd !== undefined && !Array.isArray(hooks.SessionEnd)) throw new Error('"hooks.SessionEnd" is not a list');
+  hooks.SessionEnd = [...(hooks.SessionEnd || []), { hooks: [{ type: 'command', command }] }];
+  return { ...next, hooks };
+}
+
+function install(argv, io) {
+  let values;
+  try {
+    ({ values } = parseArgs({ args: argv, options: { wallet: { type: 'string', multiple: true } }, allowPositionals: false }));
+  } catch (e) { io.err(`${e.message}\n`); return 2; }
+  const wallets = values.wallet || [];
+  if (!wallets.length) { io.err('usage: chainfess hook install --wallet 0x… [--wallet 0x…]\n'); return 2; }
+  for (const w of wallets) if (!/^0x[0-9a-fA-F]{40}$/.test(w)) { io.err('not a wallet address\n'); return 2; }
+  const { settings, reports } = paths(io);
+  const had = existsSync(settings);
+  let doc;
+  try { doc = readSettings(settings); } catch (e) { io.err(`${settings} could not be read (${e.message}); not touching it.\n`); return 2; }
+  let next;
+  try { next = withOurs(doc, hookCommand(wallets, io.binPath, io.nodePath)); } catch (e) { io.err(`${settings}: ${e.message}; not touching it.\n`); return 2; }
+  const backup = writeSettings(settings, next, had);
+  io.out(`SessionEnd hook installed in ${settings}\n`);
+  if (backup) io.out(`backup: ${backup}\n`);
+  io.out(`each session end audits ${wallets.join(', ')} in the background; reports go to ${reports}\n`);
+  return 0;
+}
+
+function uninstall(io) {
+  const { settings } = paths(io);
+  if (!existsSync(settings)) { io.out('no settings file; nothing to remove.\n'); return 0; }
+  let doc;
+  try { doc = readSettings(settings); } catch (e) { io.err(`${settings} could not be read (${e.message}); not touching it.\n`); return 2; }
+  const before = JSON.stringify(doc);
+  const next = withoutOurs(doc);
+  if (JSON.stringify(next) === before) { io.out('hook was not installed.\n'); return 0; }
+  const backup = writeSettings(settings, next, true);
+  io.out(`hook removed from ${settings}\nbackup: ${backup}\n`);
+  return 0;
+}
+
+function status(io) {
+  const { settings, reports } = paths(io);
+  let doc = {};
+  try { doc = readSettings(settings); } catch (e) { io.err(`${settings} could not be read (${e.message}).\n`); return 2; }
+  const ours = [];
+  for (const g of (doc.hooks && Array.isArray(doc.hooks.SessionEnd) ? doc.hooks.SessionEnd : [])) {
+    for (const h of (g && Array.isArray(g.hooks) ? g.hooks : [])) if (isOurs(h)) ours.push(h.command);
+  }
+  if (!ours.length) { io.out('hook: not installed\n'); return 0; }
+  const wallets = [...new Set(ours.flatMap((c) => c.match(/0x[0-9a-fA-F]{40}/g) || []))];
+  io.out(`hook: installed (SessionEnd) in ${settings}\nwallets: ${wallets.join(', ')}\n`);
+  let files = [];
+  try { files = readdirSync(reports).filter((f) => f.endsWith('.json')); } catch { /* none yet */ }
+  io.out(`reports: ${files.length} in ${reports}\n`);
+  if (files.length) {
+    const newest = files.map((f) => join(reports, f)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+    try {
+      const r = JSON.parse(readFileSync(newest, 'utf8'));
+      io.out(`latest: ${newest}: ${r.summary.findings} finding(s), ${r.summary.accounted} accounted\n`);
+    } catch { io.out(`latest: ${newest}\n`); }
+  }
+  return 0;
+}
+
+function readStdin(stream, waitMs) {
+  return new Promise((resolve) => {
+    let buf = '';
+    const done = () => { stream.removeAllListeners(); if (stream.pause) stream.pause(); clearTimeout(timer); resolve(buf); };
+    const timer = setTimeout(done, waitMs);
+    stream.setEncoding('utf8');
+    stream.on('data', (d) => { buf += d; if (buf.length > 1048576) done(); });
+    stream.on('end', done);
+    stream.on('error', done);
+  });
+}
+
+/** The hook command. Always returns 0. */
+async function run(argv, io) {
+  try {
+    const { values } = parseArgs({ args: argv, options: { wallet: { type: 'string', multiple: true }, tag: { type: 'string' } }, allowPositionals: false });
+    const payload = JSON.parse(await readStdin(io.stdin || process.stdin, STDIN_WAIT_MS));
+    const log = payload.transcript_path;
+    if (typeof log !== 'string' || !log.endsWith('.jsonl') || !existsSync(log)) return 0;
+    const id = String(payload.session_id || 'session').replace(/[^A-Za-z0-9-]/g, '-');
+    const cwd = typeof payload.cwd === 'string' && existsSync(payload.cwd) ? payload.cwd : (io.home || homedir());
+    const { reports } = paths(io);
+    const args = [BIN, 'hook', 'worker', '--log', log, '--id', id, '--reports', reports];
+    for (const w of values.wallet || []) args.push('--wallet', w);
+    const child = spawn(process.execPath, args, { cwd, detached: true, stdio: 'ignore', env: io.env || process.env });
+    child.on('error', () => {});
+    child.unref();
+  } catch { /* a hook never fails a session */ }
+  return 0;
+}
+
+/** Runs the audit, detached from the session. Failures only ever mean no report file. */
+async function worker(argv, io) {
+  try {
+    const { values } = parseArgs({
+      args: argv,
+      options: { wallet: { type: 'string', multiple: true }, log: { type: 'string' }, id: { type: 'string' }, reports: { type: 'string' } },
+      allowPositionals: false,
+    });
+    const { auditReport } = await import('./audit.mjs');
+    const { renderText } = await import('./report.mjs');
+    const { report } = await auditReport({
+      wallets: values.wallet, logs: [values.log], cwd: io.cwd || process.cwd(), yes: true, ...(io.auditExtra || {}),
+    });
+    mkdirSync(values.reports, { recursive: true, mode: 0o700 });
+    writeFileSync(join(values.reports, `${values.id}.json`), JSON.stringify(report, null, 2) + '\n', { mode: 0o600 });
+    writeFileSync(join(values.reports, `${values.id}.txt`), renderText(report, {}), { mode: 0o600 });
+  } catch { /* nothing to write */ }
+  return 0;
+}
+
+export async function runHook(argv, io = {}) {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case 'install': return install(rest, io);
+    case 'uninstall': return uninstall(io);
+    case 'status': return status(io);
+    case 'run': return run(rest, io);
+    case 'worker': return worker(rest, io);
+    default:
+      io.err('usage: chainfess hook install --wallet 0x… | uninstall | status\n');
+      return 2;
+  }
+}