attesso 0.4.0 → 0.6.0

package/bin/attesso.mjs

@@ -7,11 +7,28 @@
 //   attesso verify
 //   attesso show
 import { verifyChain } from './../src/ledger.mjs';
-import { formatMinor, toMinor } from './../src/policy.mjs';
-import { append, init, isInitialised, paths, readState } from './../src/store.mjs';
-import { buildReport, renderReport } from './../src/report.mjs';
+import { bundleFor, verifyBundle } from './../src/bundle.mjs';
+import { formatMinor, toMinor, validatePolicy } from './../src/policy.mjs';
+import { checkpointFor, receiptFor, signerOf, verifyPinned, verifyReceipt } from './../src/receipt.mjs';
+import { append, init, isInitialised, paths, readState, readToolLock, setRulesProfile, verifyLedger, withLedgerLock, writeMcpManifest, writeToolLock } from './../src/store.mjs';
+import { buildReportStream, renderReport } from './../src/report.mjs';
+import { replay, renderReplay } from './../src/replay.mjs';
+import { watchEntries } from './../src/watch.mjs';
 import { serve } from './../src/serve.mjs';
-import { decide } from './../src/hook.mjs';
+import { createHookDecider } from './../src/hook.mjs';
+import { HARNESSES, normalizeHookPayload, renderHook } from './../src/harness.mjs';
+import { clearTaskControl, listControl, setTaskControl } from './../src/control.mjs';
+import { detectHarnesses, explain, suggest, writeAgentContext } from './../src/setup.mjs';
+import { CONNECT_MODES, connect as connectAgent, readMode, setModeAll, status as agentStatus } from './../src/connect.mjs';
+import { wireHarness } from './../src/install.mjs';
+import { loadTools } from './../src/classify.mjs';
+import { comparePin, pinManifest } from './../src/toolpin.mjs';
+import { flags, parseMeta, publicKey, readJsonFile, writeJsonOut } from './../src/cli-io.mjs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { CAPABILITIES, TRUST_LEVELS, validateRules } from './../src/rules.mjs';
+import { validatePathsConfig } from './../src/fs-paths.mjs';
+import { startUi } from './../src/ui/server.mjs';
 
 const argv = process.argv.slice(2);
 const dirAt = argv.indexOf('--dir');
@@ -20,17 +37,50 @@ if (dirAt !== -1) argv.splice(dirAt, 2);
 
 const USAGE = `attesso: a local, signed ledger of what your agents attempted
 
-  attesso init [--dir PATH]          create .attesso with a key and a policy
+  attesso init [--dir PATH] [--profile balanced|strict]
+                                     create .attesso with a key and a policy
   attesso log --action A [--subject S] [--amount 12.50 --currency EUR]
-              [--task T] [--trust internal|untrusted] [--capability read|send|execute|spend]
+              [--task T] [--trust internal|untrusted] [--capability read|write|send|execute|spend]
               [--meta k=v ...] [--json]
                                      evaluate one proposed action against the policy
                                      and the path of its task, then record it
   attesso verify                     recompute the chain and report the first defect
+  attesso verify --pin PATH          also check the log extends a pinned checkpoint
+  attesso rules set-profile balanced|strict
+                                     adopt a shipped rule profile, keeping the old file as .bak
+  attesso pause <task> [--reason TEXT]  refuse the next actions of one task
+  attesso stop <task> [--reason TEXT]   refuse one task until it is resumed
+  attesso resume <task>                 release a paused or stopped task
+  attesso control [--json]              list paused and stopped tasks
+  attesso watch [--from-seq N] [--task ID] [--json]
+                                     follow new decisions in one terminal
+  attesso prove <seq> [--out PATH]   a portable receipt for one entry
+  attesso verify-receipt PATH [--key PATH]
+                                     verify a receipt offline; no ledger needed
+  attesso checkpoint [--out PATH]    a signed head you can keep off this machine
+  attesso export <seq> [--out PATH]  entry, receipt, policy and rules in one bundle
+  attesso verify-bundle PATH [--replay]
+                                     verify a bundle offline, and re-run the verdict
   attesso show                       what was allowed, what was refused, and why
   attesso report [--json]            per task: actions, refusals with reasons, tokens and cost
+  attesso replay [--policy PATH] [--rules PATH] [--json]
+              [--max-newly-denied N] re-judge the whole ledger under a candidate policy;
+                                     exit 1 when the gate is exceeded
   attesso serve [--observe]          long-lived: one JSON request per line in, one verdict out
-  attesso hook [--observe]           harness hook: reads one tool call on stdin, exits 2 to refuse
+  attesso hook [--observe]           harness hook: one tool call on stdin, native refusal on stdout
+  attesso setup [--write] [--enforce] [--dry-run]
+                                     detect a harness, wire the hook, write the agent block
+  attesso connect [--write] [--mode observe|enforce|off] [--json]
+                                     self-service: init, mode, hook and AGENTS.md
+  attesso status [--json]           connection, mode and wired harnesses
+  attesso mode [observe|enforce|off]  read or set the active hook mode
+  attesso paths [--json|--set FILE]   read or replace the filesystem scope
+  attesso ui [--port N] [--no-open]    local control surface for the signed ledger
+  attesso explain <seq>              one entry in full: rule, tainting step, what to do
+  attesso suggest [--json]           rules the ledger's own counts justify
+  attesso tools pin --manifest PATH  pin the tool definitions a decision was made under
+  attesso tools verify --manifest PATH
+                                     compare the pinned definitions with the manifest
 
 Any action can be logged, not only payments. --subject is the thing acted on (a
 tool name, a payee, a repo). --task scopes the path, --trust marks where the
@@ -43,39 +93,6 @@ The log is signed with a key that lives in .attesso/key.json. That proves the
 ledger was not edited; it does not prove a human authorized anything. Hosted
 Attesso adds passkey approval and evidence a third party verifies offline.`;
 
-function flags(argv) {
-  const out = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (!token.startsWith('--')) continue;
-    const name = token.slice(2);
-    const next = argv[index + 1];
-    if (next === undefined || next.startsWith('--')) {
-      out[name] = true;
-      continue;
-    }
-    if (name === 'meta') {
-      out.meta = [...(out.meta ?? []), next];
-    } else {
-      out[name] = next;
-    }
-    index += 1;
-  }
-  return out;
-}
-
-function parseMeta(pairs = []) {
-  const meta = {};
-  for (const pair of pairs) {
-    const at = pair.indexOf('=');
-    if (at <= 0) throw new Error(`--meta expects key=value, got ${pair}`);
-    const key = pair.slice(0, at);
-    const raw = pair.slice(at + 1);
-    meta[key] = raw !== '' && !Number.isNaN(Number(raw)) ? Number(raw) : raw;
-  }
-  return meta;
-}
-
 function requireLedger() {
   if (!isInitialised(DIR)) {
     console.error(`no ledger at ${paths(DIR).dir}; run attesso init first`);
@@ -89,6 +106,54 @@ function describe(entry) {
   return `${entry.action}${subject}${amount}`;
 }
 
+function renderWatchEntry(entry) {
+  const at = typeof entry.at === 'string' ? entry.at.slice(11, 19) : '--:--:--';
+  const rule = entry.rule ? ` ${entry.rule}` : '';
+  const control = entry.control ? ` control=${entry.control.mode}` : '';
+  const task = entry.task ? ` task=${String(entry.task).slice(0, 12)}` : '';
+  return `#${entry.seq} ${at} ${String(entry.decision).padEnd(5)} ${entry.subject ?? '(none)'} ${entry.capability ?? ''} ${entry.code}${rule}${task}${control}`;
+}
+
+function toolsCommand(rest) {
+  requireLedger();
+  const [subcommand, ...args] = rest;
+  const options = flags(args);
+  if ((subcommand !== 'pin' && subcommand !== 'verify') || typeof options.manifest !== 'string') {
+    console.error('usage: attesso tools pin|verify --manifest PATH');
+    process.exit(2);
+  }
+  const manifest = readJsonFile(options.manifest, 'tools');
+  try {
+    const tools = loadTools(DIR);
+    if (subcommand === 'pin') {
+      const pin = pinManifest(manifest, tools);
+      writeMcpManifest(DIR, manifest);
+      writeToolLock(DIR, pin);
+      const surfaces = ['server', 'prompts', 'resources', 'resource_templates'].filter((field) => pin[`${field}_digest`]);
+      console.log(`pinned ${Object.keys(pin.tools).length} tools${surfaces.length ? ` and ${surfaces.join(', ')}` : ''}; tools digest ${pin.tools_digest}`);
+      return;
+    }
+    const lock = readToolLock(DIR);
+    if (!lock) {
+      console.error('no tool pin at .attesso/tools.lock.json; run attesso tools pin first');
+      process.exit(1);
+    }
+    const result = comparePin(lock, manifest, tools);
+    if (!result.ok) {
+      if (result.digestChanged) console.error('tools.json changed since the pin');
+      for (const name of result.changed) console.error(`changed tool: ${name}`);
+      for (const name of result.added) console.error(`added tool: ${name}`);
+      for (const name of result.removed) console.error(`removed tool: ${name}`);
+      for (const surface of result.surfaces) console.error(`changed ${surface} surface`);
+      process.exit(1);
+    }
+    console.log(`tool pin verifies: ${Object.keys(lock.tools).length} tools`);
+  } catch (error) {
+    console.error(`tools: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 function log(argv) {
   requireLedger();
   const options = flags(argv);
@@ -117,12 +182,12 @@ function log(argv) {
     process.exit(2);
   }
 
-  if (options.trust !== undefined && !['internal', 'untrusted', 'unknown'].includes(options.trust)) {
-    console.error('--trust takes internal, untrusted or unknown');
+  if (options.trust !== undefined && !TRUST_LEVELS.includes(options.trust)) {
+    console.error(`--trust takes ${TRUST_LEVELS.join(', ')}`);
     process.exit(2);
   }
-  if (options.capability !== undefined && !['read', 'send', 'execute', 'spend'].includes(options.capability)) {
-    console.error('--capability takes read, send, execute or spend');
+  if (options.capability !== undefined && !CAPABILITIES.includes(options.capability)) {
+    console.error(`--capability takes ${CAPABILITIES.join(', ')}`);
     process.exit(2);
   }
   const entry = append(DIR, {
@@ -138,20 +203,94 @@ function log(argv) {
     console.log(JSON.stringify(entry));
     return;
   }
-  const taint = entry.meta?.tainted_by === undefined ? '' : ` by step #${entry.meta.tainted_by} under ${entry.meta.rule}`;
+  const taint = entry.tainted_by === undefined ? '' : ` by step #${entry.tainted_by} under ${entry.rule}`;
   console.log(`#${entry.seq} ${entry.decision} ${describe(entry)} (${entry.code}${taint})`);
   process.exitCode = entry.decision === 'ALLOW' ? 0 : 1;
 }
 
-function verify() {
+function verify(rest = []) {
   requireLedger();
+  const options = flags(rest);
+  if (options.pin !== undefined) {
+    let state;
+    let result;
+    try {
+      // Verify a snapshot, not a writer's in-flight line: the lock makes the
+      // line and the head it belongs to visible together.
+      state = withLedgerLock(DIR, () => readState(DIR));
+      result = verifyChain(state.entries, state.key.public, state.config.head);
+    } catch {
+      // A read-only archive cannot take the lock; there is no writer to race.
+      state = readState(DIR);
+      result = verifyChain(state.entries, state.key.public, state.config.head);
+    }
+    if (!result.ok) {
+      console.error(`ledger does not verify: ${result.reason}`);
+      process.exit(1);
+    }
+    console.log(`ledger verifies: ${result.reason}, key ${state.key.kid}`);
+    const pinned = readJsonFile(options.pin, 'verify --pin');
+    const check = verifyPinned(state.entries, pinned, state.key.public);
+    if (!check.ok) {
+      console.error(`pinned head does not verify: ${check.reason}`);
+      process.exit(1);
+    }
+    console.log(`pinned head: ${check.reason}`);
+    return;
+  }
+  return (async () => {
+    let result;
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      result = await verifyLedger(DIR);
+      if (result.ok) break;
+      // A writer can be between its signed line and the head update. The lock
+      // used to hide that window; a streamed read waits it out instead.
+      if (!/more .* than the recorded head|last entry does not match|Unexpected end of JSON input|Unexpected token|Expected property name/.test(result.reason)) break;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (!result.ok) {
+      console.error(`ledger does not verify: ${result.reason}`);
+      process.exit(1);
+    }
+    console.log(`ledger verifies: ${result.reason}, key ${result.kid}`);
+  })();
+}
+
+function prove(rest) {
+  requireLedger();
+  const options = flags(rest);
+  const seq = Number(rest[0]);
   const state = readState(DIR);
-  const result = verifyChain(state.entries, state.key.public, state.config.head);
+  const index = state.entries.findIndex((entry) => entry.seq === seq);
+  if (index === -1) {
+    console.error(`no entry #${seq} in this ledger`);
+    process.exit(1);
+  }
+  writeJsonOut(DIR, receiptFor(state.entries, index, signerOf(state.key)), options.out);
+}
+
+function checkpoint(rest) {
+  requireLedger();
+  const options = flags(rest);
+  const state = readState(DIR);
+  writeJsonOut(DIR, checkpointFor(state.entries, signerOf(state.key)), options.out);
+}
+
+function verifyReceiptCommand(rest) {
+  const options = flags(rest);
+  const file = rest[0];
+  if (!file) {
+    console.error('attesso verify-receipt <file>');
+    process.exit(2);
+  }
+  const receipt = readJsonFile(file, 'verify-receipt');
+  const result = verifyReceipt(receipt, options.key ? publicKey(options.key) : receipt.key);
   if (!result.ok) {
-    console.error(`ledger does not verify: ${result.reason}`);
+    console.error(`receipt does not verify: ${result.reason}`);
     process.exit(1);
   }
-  console.log(`ledger verifies: ${result.reason}, key ${state.key.kid}`);
+  const trust = options.key ? '' : ' (against the key embedded in the receipt; pass --key to pin a trusted one)';
+  console.log(`receipt verifies: ${result.reason}${trust}`);
 }
 
 function totals(entries) {
@@ -202,12 +341,20 @@ function show() {
 }
 
 const [command, ...rest] = argv;
+
+process.on('uncaughtException', (error) => {
+  if (process.env.ATTESSO_DEBUG) throw error;
+  console.error(`attesso: ${error.message}`);
+  process.exit(1);
+});
+
 switch (command) {
   case 'init': {
     try {
-      const result = init(DIR);
-      console.log(`created ${result.dir} with key ${result.kid}`);
-      console.log('edit .attesso/policy.json to set what is allowed (it starts at nothing)');
+      const options = flags(rest);
+      const result = init(DIR, { profile: typeof options.profile === 'string' ? options.profile : 'balanced' });
+      console.log(`created ${result.dir} with key ${result.kid} (${result.profile} rules)`);
+      console.log(`review ${paths(DIR).policy}, ${paths(DIR).rules} and ${paths(DIR).tools} before enforcing`);
     } catch (error) {
       console.error(error.message);
       process.exit(1);
@@ -218,14 +365,371 @@ switch (command) {
     log(rest);
     break;
   case 'verify':
-    verify();
+    await verify(rest);
+    break;
+  case 'rules': {
+    requireLedger();
+    const [subcommand, ...args] = rest;
+    const options = flags(args);
+    const profile = typeof options.profile === 'string' ? options.profile : args.find((arg) => !arg.startsWith('--'));
+    if (subcommand !== 'set-profile' || typeof profile !== 'string') {
+      console.error('usage: attesso rules set-profile balanced|strict');
+      process.exit(2);
+    }
+    try {
+      const result = setRulesProfile(DIR, profile);
+      const state = result.changed ? 'updated' : 'already current';
+      console.log(`rules ${result.profile}: ${state}; digest ${result.digest}`);
+    } catch (error) {
+      console.error(`rules: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'checkpoint':
+    checkpoint(rest);
     break;
+  case 'pause':
+  case 'stop': {
+    requireLedger();
+    const options = flags(rest);
+    const task = rest.find((arg) => !arg.startsWith('--'));
+    if (!task) {
+      console.error(`usage: attesso ${command} <task> [--reason TEXT]`);
+      process.exit(2);
+    }
+    try {
+      const result = setTaskControl(DIR, task, command, { reason: options.reason });
+      console.log(`${command} ${result.task}: ${result.mode} at ${result.at}`);
+    } catch (error) {
+      console.error(`${command}: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'resume': {
+    requireLedger();
+    const task = rest.find((arg) => !arg.startsWith('--'));
+    if (!task) {
+      console.error('usage: attesso resume <task>');
+      process.exit(2);
+    }
+    try {
+      const changed = clearTaskControl(DIR, task);
+      console.log(changed ? `resumed ${task}` : `${task} was not paused or stopped`);
+    } catch (error) {
+      console.error(`resume: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'control': {
+    requireLedger();
+    const options = flags(rest);
+    try {
+      const tasks = listControl(DIR);
+      if (options.json) {
+        console.log(JSON.stringify(tasks));
+        break;
+      }
+      if (tasks.length === 0) {
+        console.log('no paused or stopped tasks');
+        break;
+      }
+      for (const item of tasks) {
+        console.log(`${item.task}\t${item.mode}\t${item.at}${item.reason ? `\t${item.reason}` : ''}`);
+      }
+    } catch (error) {
+      console.error(`control: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'prove':
+    prove(rest);
+    break;
+  case 'verify-receipt':
+    verifyReceiptCommand(rest);
+    break;
+  case 'export': {
+    requireLedger();
+    const options = flags(rest);
+    try {
+      writeJsonOut(DIR, bundleFor(DIR, rest[0]), options.out);
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    break;
+  }
+  case 'verify-bundle': {
+    const options = flags(rest);
+    const file = rest[0];
+    if (!file) {
+      console.error('attesso verify-bundle <file>');
+      process.exit(2);
+    }
+    const bundle = readJsonFile(file, 'verify-bundle');
+    const result = verifyBundle(bundle, {
+      replay: options.replay === true,
+      publicPem: options.key ? publicKey(options.key) : undefined,
+    });
+    if (!result.ok) {
+      console.error(`bundle does not verify: ${result.reason}`);
+      process.exit(1);
+    }
+    const note = result.historical ? ' (historical entry: no rules digest)' : '';
+    console.log(`bundle verifies: ${result.reason}${note}`);
+    break;
+  }
   case 'show':
     show();
     break;
+  case 'watch': {
+    requireLedger();
+    const options = flags(rest);
+    const raw = options['from-seq'];
+    const fromSeq = raw === undefined ? Number.MAX_SAFE_INTEGER : Number(raw);
+    if (!Number.isInteger(fromSeq) || fromSeq < 0) {
+      console.error('--from-seq takes a whole sequence number');
+      process.exit(2);
+    }
+    if (options.task !== undefined && typeof options.task !== 'string') {
+      console.error('--task takes a task id');
+      process.exit(2);
+    }
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    try {
+      for await (const entry of watchEntries(DIR, {
+        fromSeq,
+        task: options.task,
+        signal: controller.signal,
+      })) {
+        console.log(options.json ? JSON.stringify(entry) : renderWatchEntry(entry));
+      }
+    } catch (error) {
+      console.error(`watch: ${error.message}`);
+      process.exitCode = 1;
+    } finally {
+      process.removeListener('SIGINT', stop);
+    }
+    break;
+  }
+  case 'connect': {
+    try {
+      const options = flags(rest);
+      const mode = typeof options.mode === 'string'
+        ? options.mode
+        : options.off ? 'off' : options.enforce ? 'enforce' : options.observe ? 'observe' : 'observe';
+      const result = connectAgent({
+        dir: DIR,
+        cwd: process.cwd(),
+        cli: resolve(process.argv[1]),
+        write: rest.includes('--write'),
+        mode,
+        harness: typeof options.harness === 'string' ? options.harness : null,
+      });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`mode: ${result.mode ?? 'unset'}`);
+        console.log(`ledger: ${result.initialized ? result.ledger : 'not initialized'}`);
+        for (const harness of result.harnesses) {
+          const state = harness.applied ? 'wired' : harness.dryRun ? 'would wire' : harness.wired || harness.reason === 'already wired' ? 'already wired' : harness.error || harness.reason || 'manual';
+          console.log(`${harness.key}: ${state}`);
+          for (const warning of harness.warnings ?? []) console.log(`  note: ${warning}`);
+        }
+        if (result.manual.length) console.log(`manual: ${result.manual.join(', ')}`);
+        for (const line of result.next) console.log(`next: ${line}`);
+      }
+      if (!result.initialized && rest.includes('--write')) process.exitCode = 1;
+    } catch (error) {
+      console.error(`connect: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'status': {
+    try {
+      const options = flags(rest);
+      const result = agentStatus({ dir: DIR, cwd: process.cwd() });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`connected: ${result.connected ? 'yes' : 'no'}`);
+        console.log(`mode: ${result.mode ?? 'unset'}`);
+        console.log(`ledger: ${result.ledger ?? 'not initialized'}`);
+        for (const harness of result.harnesses) console.log(`${harness.key}: ${harness.wired ? 'wired' : 'not wired'}`);
+      }
+    } catch (error) {
+      console.error(`status: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'mode': {
+    try {
+      const options = flags(rest);
+      const desired = typeof options.mode === 'string' ? options.mode : rest.find((value) => !value.startsWith('--'));
+      if (desired === undefined) {
+        const current = readMode(DIR);
+        if (options.json) console.log(JSON.stringify({ mode: current }));
+        else console.log(`mode: ${current ?? 'unset'}`);
+        break;
+      }
+      if (!CONNECT_MODES.includes(desired)) {
+        console.error(`mode takes ${CONNECT_MODES.join(', ')}`);
+        process.exit(2);
+      }
+      const result = setModeAll(DIR, desired);
+      if (options.json) console.log(JSON.stringify({ mode: result }));
+      else console.log(`mode: ${result}`);
+    } catch (error) {
+      console.error(`mode: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'paths': {
+    try {
+    const options = flags(rest);
+    const file = paths(DIR).fsPaths;
+    if (options.set) {
+      const value = validatePathsConfig(readJsonFile(options.set, 'paths'));
+      mkdirSync(DIR, { recursive: true });
+      const temp = `${file}.${process.pid}.tmp`;
+      writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+      renameSync(temp, file);
+      if (options.json) console.log(JSON.stringify({ ok: true, paths: value }, null, 2));
+      else console.log(`paths: ${value.allowed_roots.length} roots, ${value.exclusions.length} exclusions`);
+      break;
+    }
+    if (!existsSync(file)) {
+      if (options.json) console.log(JSON.stringify({ configured: false, paths: null }));
+      else console.log('paths: not configured');
+      break;
+    }
+    const value = validatePathsConfig(readJsonFile(file, 'paths'));
+    if (options.json) console.log(JSON.stringify({ configured: true, paths: value }, null, 2));
+    else console.log(`paths: ${value.allowed_roots.length} roots, ${value.exclusions.length} exclusions`);
+    } catch (error) {
+      console.error(`paths: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'ui': {
+    try {
+      const options = flags(rest);
+      const requested = options.port === undefined ? 0 : Number(options.port);
+      if (!Number.isInteger(requested) || requested < 0 || requested > 65535) {
+        console.error('ui: --port must be an integer from 0 to 65535');
+        process.exit(2);
+      }
+      const ui = await startUi({
+        dir: DIR,
+        cwd: process.cwd(),
+        port: requested,
+        open: !rest.includes('--no-open'),
+      });
+      console.log(`bounds ui: ${ui.url}`);
+      console.log('press Ctrl-C to stop');
+      const stop = () => { ui.close().then(() => process.exit(0), () => process.exit(1)); };
+      process.once('SIGINT', stop);
+      process.once('SIGTERM', stop);
+    } catch (error) {
+      console.error(`ui: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
+  case 'setup': {
+    const dryRun = rest.includes('--dry-run');
+    const write = rest.includes('--write');
+    const enforce = rest.includes('--enforce');
+    const harnesses = detectHarnesses();
+    const cli = resolve(process.argv[1]);
+    const ledgerDir = resolve(DIR);
+    const agent = writeAgentContext(process.cwd(), { dryRun });
+    console.log(`agent context: ${agent.changed ? (dryRun ? 'would update' : 'updated') : 'already current'} ${agent.path}`);
+    if (harnesses.length === 0) {
+      console.log('no harness config found in this directory or ~/.hermes');
+      console.log('wire any harness with this contract: run `attesso hook` as a pre_tool_call hook; exit 2 refuses.');
+    }
+    for (const harness of harnesses) {
+      if (!HARNESSES[harness.key]) {
+        console.log(`${harness.key}: found ${harness.path}; wire it with \`${cli} --dir ${ledgerDir} hook\` as its pre-tool hook`);
+        continue;
+      }
+      if (harness.key !== 'hermes' && !write) {
+        console.log(`${harness.key}: found ${harness.path}; run setup --write to install the ${enforce ? 'enforce' : 'observe'} hook`);
+        continue;
+      }
+      try {
+        const result = wireHarness(harness.key, cli, ledgerDir, {
+          dryRun,
+          enforce,
+          path: harness.path,
+        });
+        const state = result.applied ? 'wired' : result.dryRun ? 'would wire' : result.reason;
+        console.log(`${harness.key}: ${state}`);
+        if (result.snippet && !result.applied) console.log(result.snippet);
+      } catch (error) {
+        console.error(`${harness.key}: ${error.message}`);
+      }
+    }
+    break;
+  }
+  case 'explain': {
+    requireLedger();
+    const seq = rest[0];
+    if (!seq) {
+      console.error('attesso explain <seq>');
+      process.exit(1);
+    }
+    const detail = explain(DIR, seq, readState(DIR));
+    if (!detail.found) {
+      console.error(`no entry #${seq} in this ledger`);
+      process.exit(1);
+    }
+    console.log(JSON.stringify(detail, null, 2));
+    break;
+  }
+  case 'suggest': {
+    requireLedger();
+    const proposal = suggest(DIR, readState(DIR));
+    if (rest.includes('--json')) {
+      console.log(JSON.stringify(proposal, null, 2));
+    } else if (proposal.repeats.length === 0) {
+      console.log('no repeats yet: nothing the ledger can justify narrowing');
+    } else {
+      for (const repeat of proposal.repeats) {
+        console.log(`${repeat.id}: ${repeat.why}`);
+        console.log(`  ${JSON.stringify(repeat.rule)}`);
+      }
+    }
+    break;
+  }
+  case 'tools':
+    toolsCommand(rest);
+    break;
   case 'hook': {
+    let configuredMode;
+    try {
+      configuredMode = readMode(DIR);
+    } catch (error) {
+      console.error(`attesso hook: ${error.message}`);
+      process.exit(2);
+    }
+    if (configuredMode === 'off') {
+      process.exitCode = 0;
+      break;
+    }
     requireLedger();
-    const run = decide({ append, dir: DIR, observe: rest.includes('--observe') });
+    const observe = configuredMode === null ? rest.includes('--observe') : configuredMode === 'observe';
+    const run = createHookDecider({ append, dir: DIR, observe });
     let raw = '';
     process.stdin.setEncoding('utf8');
     process.stdin.on('data', (chunk) => {
@@ -237,24 +741,55 @@ switch (command) {
         payload = JSON.parse(raw || '{}');
       } catch {
         console.error('attesso hook: stdin was not JSON, so no decision was made');
-        process.exit(1);
+        process.exit(observe ? 0 : 2);
       }
+      let normalized;
       try {
-        const result = run(payload);
-        if (result.exitCode !== 0) {
-          process.stdout.write(`${JSON.stringify({ decision: 'block', message: result.body.message, code: result.body.code })}\n`);
-          process.exit(2);
-        }
-        process.stdout.write(`${JSON.stringify({ decision: result.body.decision, code: result.body.code })}\n`);
+        normalized = normalizeHookPayload(payload);
+        const result = run(normalized.payload);
+        const rendered = renderHook({ harness: normalized.harness, result });
+        if (rendered.stdout) process.stdout.write(rendered.stdout);
+        process.exit(rendered.exitCode);
       } catch (error) {
-        // An unwritable ledger is an outage, not a policy decision: say so and
-        // exit 1 so a fail-closed harness can tell the two apart.
+        // An unwritable ledger is not a policy statement, but enforcement must
+        // fail closed. Observe mode stays out of the way.
+        const body = {
+          decision: 'DENY',
+          code: 'LEDGER_UNAVAILABLE',
+          message: `Attesso could not read the ledger: ${error.message}`,
+          enforced: !observe,
+        };
+        const rendered = renderHook({ harness: normalized?.harness ?? 'generic', result: { body } });
+        if (rendered.stdout) process.stdout.write(rendered.stdout);
         console.error(`attesso hook: ${error.message}`);
-        process.exit(1);
+        process.exit(observe ? 0 : rendered.exitCode);
       }
     });
     break;
   }
+  case 'replay': {
+    requireLedger();
+    const options = flags(rest);
+    let candidatePolicy;
+    let candidateRules;
+    try {
+      candidatePolicy = validatePolicy(JSON.parse(readFileSync(options.policy ?? paths(DIR).policy, 'utf8')));
+      candidateRules = validateRules(JSON.parse(readFileSync(options.rules ?? paths(DIR).rules, 'utf8')));
+    } catch (error) {
+      console.error(`replay: ${error.message}`);
+      process.exit(2);
+    }
+    const summary = replay(readState(DIR).entries, { policy: candidatePolicy, rules: candidateRules });
+    if (options.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      process.stdout.write(renderReplay(summary));
+    }
+    if (options['max-newly-denied'] !== undefined && summary.newly_denied > Number(options['max-newly-denied'])) {
+      process.exitCode = 1;
+    }
+    break;
+  }
   case 'serve':
     requireLedger();
     serve(DIR, { observe: rest.includes('--observe') }).catch((error) => {
@@ -264,7 +799,7 @@ switch (command) {
     break;
   case 'report': {
     requireLedger();
-    const report = buildReport(DIR);
+    const report = await buildReportStream(DIR);
     if (rest.includes('--json')) {
       console.log(JSON.stringify(report, null, 2));
     } else {