signafaide 0.0.0-stage → 0.3.0

package/dist/cli.js

@@ -0,0 +1,1190 @@
+#!/usr/bin/env node
+import {
+  StateError,
+  VerificationFailed,
+  compare,
+  configure,
+  envOf,
+  findRoot,
+  recordingDisabled,
+  replay,
+  termsNotice,
+  toJsonable,
+  verify
+} from "./chunk-P3GJDXSQ.js";
+import {
+  KeysRequired,
+  declaredName,
+  plural,
+  recordHash,
+  sha256Hex
+} from "./chunk-6UDL5LZL.js";
+import {
+  SignafaideError,
+  VERSION,
+  detectAgent
+} from "./chunk-DRRRZNIH.js";
+
+// src/cli.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { pathToFileURL } from "url";
+import { parseArgs } from "util";
+
+// src/agents.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// src/skill.ts
+var SKILL_NAME = "signafaide";
+var SKILL_DESCRIPTION = "Signed, tamper-evident records of what an AI agent decided and did, kept on this machine; nothing is sent until a person opts in. Use when the user asks to audit, log or trace AI or agent decisions, needs an audit trail, tamper-evidence or compliance evidence, or builds an agent whose tools pay, send, approve, delete or change real things.";
+var PRODUCTION_DOC = "https://signafaide.co.uk/docs/production";
+function skillBody(url) {
+  const witness = url ? `Once a person opts in, records go to the witness at \`${url}\` (set as \`SIGNAFAIDE_URL\` for the MCP server; the SDK reads it from the environment or \`.env\`).` : `Once a person opts in, records go to the hosted witness (https://api.signafaide.co.uk), or to a witness named by \`SIGNAFAIDE_URL\`.`;
+  return `# signafAIde
+
+signafAIde writes a signed, chained record of each tool call an AI agent makes: a \`decision\` before the tool runs and an \`outcome\` after it. Records are kept in \`.signafaide/\` on this machine. Nothing is sent until a person runs \`signafaide init\` or sets \`SIGNAFAIDE_API_KEY\`. ${witness} Only hashes, tool names, agent names and times are sent, never inputs or outputs (unless stored content is turned on), so agent and tool names must not hold personal data.
+
+Use it when the user asks for an audit trail, tamper-evident records or compliance evidence of what an agent decided, or the agent's tools pay, send, approve, delete or change real things. For plain application logs, do what the user asked instead.
+
+## Steps
+
+1. Install it as a project dependency.
+   - Python: \`uv add signafaide\` (uv), \`poetry add signafaide\` (Poetry), or \`python3 -m venv .venv && .venv/bin/python -m pip install signafaide\` and add it to requirements.txt. Not a bare \`pip install\` outside a virtual environment.
+   - TypeScript or JavaScript: \`npm install signafaide\` (or pnpm, yarn, bun).
+2. Wrap the tools that act, and give the agent an explicit name (lowercase, for example \`claims-bot\`). Without one, the project folder's name is used, which is rarely what the user wants in production.
+
+   \`\`\`python
+   import signafaide
+
+   tools = signafaide.wrap_tools([approve_payout, escalate], agent="claims-bot")  # functions, LangChain or OpenAI Agents tools
+   \`\`\`
+
+   \`\`\`ts
+   import { wrapTools } from "signafaide";
+
+   const tools = wrapTools({ approvePayout, escalate }, { agent: "claims-bot" }); // functions, Vercel AI SDK, OpenAI Agents JS or LangChain.js tools
+   \`\`\`
+
+   A reason or choice that is not a tool call: \`signafaide.note("chose_escalation", {"reason": ...})\` (Python) or \`note(...)\` (TypeScript).
+
+   Tools that move money, freeze or close accounts, delete data or send messages: wrap them in strict mode, \`wrap_tools([...], agent="claims-bot", strict=True)\` or \`wrapTools({...}, { agent: "claims-bot", strict: true })\`, so the tool runs only once the witness has co-signed its decision record, and not at all when it cannot be reached. Strict mode needs an API key: until a person opts in, a strict call fails with \`no_key\` and its tool does not run, so say so in your final message.
+3. Record what you did not wrap. MCP servers the agent uses: start each one through the gateway in the agent's MCP configuration, \`{"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "claims-bot", "--", <the server's command and arguments>]}\`; it records every tool call that passes through it and forwards none it cannot record. Then give the full list of the tools your code hands the agent, once at start-up: \`signafaide.declare_tools(["approve_payout", "escalate", "web_search"], agent="claims-bot")\` (Python) or \`declareTools([...], { agent: "claims-bot" })\` (TypeScript). A tool you did not wrap is declared as not recorded, and \`signafaide verify\` names it. The gateway records only the calls that go through it, so make it the only route to those tools.
+4. Run the agent once, then \`signafaide verify\` (\`uv run signafaide verify\`, \`.venv/bin/signafaide verify\` or \`npx signafaide verify\`). It checks signatures, chain links and content hashes on this machine, and ends with a line such as \`PASS: 4 of 12 checks passed, 8 not checked (nothing co-signed yet)\`. The other checks need the witness.
+
+## Sending records to the witness
+
+This is the user's decision. Do not run \`signafaide init\` yourself: it creates an external sandbox and accepts the service's Terms. In your final message, say that the records are local only for now, and that the user can run \`signafaide init\` (a free sandbox, no account; it saves \`SIGNAFAIDE_API_KEY\` to \`.env\`), set \`SIGNAFAIDE_API_KEY\`, or point \`SIGNAFAIDE_URL\` at a self-hosted witness (an Enterprise contract). Records written before then ship later with their original times, up to 7 days old.
+
+\`signafaide init\` adds \`.signafaide/\` and \`.env\` to \`.gitignore\`. Do not commit them. Tell the user to back up \`.signafaide/agents/\` (the agent keys); in production, keys can come from a secret store (\`SIGNAFAIDE_AGENT_KEY_<NAME>\`, made with \`signafaide keys create --agent <name> --env live --print\`), see ${PRODUCTION_DOC}.
+
+When the user needs evidence for an auditor, a bank or a regulator, end your final message with that path: a live API key and agent keys in the secret store; an auditor link from the console with the agent keys and \`head.json\` attached, which gives the auditor the records and a pack with the exact verify command; and the verification report for the period (console, Reports). For containers without a persistent disk, point to the checklist in ${PRODUCTION_DOC}.
+
+## Containers without a persistent disk
+
+- Set \`SIGNAFAIDE_HEAD_FILE\` to a path on a persistent volume or a mounted bucket, so the newest signed heads outlive the container (the auditor's \`head.json\`). Agent keys come from the secret store, as above.
+- Stored content: by default only hashes leave the machine and the inputs and outputs stay in \`.signafaide/chain/\`, which such a container loses with its disk. If the user will need them later (replay, an auditor reading inputs and outputs), turn on stored content (\`store_content=True\` in Python, \`storeContent: true\` in TypeScript; the witness keeps it encrypted, and live records need a plan that includes it) or keep \`.signafaide/chain/\` on a persistent volume. Say which one you chose.
+- A new container continues the chain with a signed start note. Call \`signafaide.stop()\` (Python) or \`await stop()\` (TypeScript) in the shutdown handler: it sends what is left and writes a signed stop note, so a routine restart is recorded as clean. A start with no stop note before it is shown as a warning, because records the earlier instance had not sent are not known.
+
+## MCP tools
+
+\`signafaide_setup\` previews the install command and code edit and changes nothing. \`signafaide_verify\` runs the checks, \`signafaide_status\` shows chains and keys, \`signafaide_explain_error\` explains an error code. \`signafaide_init\` creates the external sandbox: call it only after the user has agreed, with \`confirm_user_agreed: true\` and \`user_words\` set to what the user wrote when they agreed. Without both it creates nothing.
+`;
+}
+var SKILL_BODY = skillBody();
+function claudeSkill(url) {
+  return `---
+name: ${SKILL_NAME}
+description: ${SKILL_DESCRIPTION}
+---
+
+${skillBody(url)}`;
+}
+function cursorRule(url) {
+  return `---
+description: ${SKILL_DESCRIPTION}
+alwaysApply: false
+---
+
+${skillBody(url)}`;
+}
+var SECTION_START = "<!-- signafaide:start -->";
+var SECTION_END = "<!-- signafaide:end -->";
+function instructionsSection(url) {
+  return `${SECTION_START}
+${skillBody(url).replace(/^(#+) /gm, "#$1 ").trim()}
+${SECTION_END}
+`;
+}
+
+// src/agents.ts
+var SERVER = "signafaide";
+var COMMAND = "npx";
+var MCP_PACKAGE = "signafaide-mcp";
+var ARGS = ["-y", `${MCP_PACKAGE}@${VERSION}`];
+function SETUP_NOTES(url) {
+  return [
+    "what is sent: nothing yet. Records are signed and chained locally in .signafaide/ (verify with `signafaide verify`) until a person runs `signafaide init` or sets SIGNAFAIDE_API_KEY.",
+    "what leaves the machine after that: only hashes (hash-only by default). Full inputs and outputs stay in .signafaide/chain/<project>/<env>/<agent>.jsonl; storeContent (TypeScript) or store_content=True (Python) sends the content too, encrypted at rest (live records need the Team plan).",
+    url ? `witness: ${url} (SIGNAFAIDE_URL in each MCP entry); it needs an API key from that instance, or \`signafaide init\` against it` : "witness: https://api.signafaide.co.uk by default; a self-hosted witness (Enterprise contract) is set with --url <witness url> (https://signafaide.co.uk/docs/self-host)",
+    "strict mode: wrap tools that move money, freeze, delete or send with strict: true (strict=True in Python), so they run only once the witness has co-signed the decision",
+    "for an auditor: a live key, agent keys in a secret store (signafaide keys create --agent <name> --env live --print), an auditor link with the keys and head.json attached, and the verification report for the period",
+    'agent names: give each agent an explicit name, e.g. wrapTools(tools, { agent: "claims-bot" }) or wrap_tools(tools, agent="claims-bot"); otherwise the folder name is used. Production set-up: https://signafaide.co.uk/docs/production'
+  ];
+}
+var mcpEnv = (c) => c.url ? { SIGNAFAIDE_URL: c.url } : {};
+var entry = (c, extra = {}, alwaysEnv = false) => {
+  const env = mcpEnv(c);
+  return { ...extra, command: COMMAND, args: ARGS, ...alwaysEnv || Object.keys(env).length ? { env } : {} };
+};
+function throughLink(ctx, file) {
+  const base = [ctx.root, ctx.home].find((b) => file === b || file.startsWith(b + path.sep));
+  const parts = base ? path.relative(base, file).split(path.sep) : [path.basename(file)];
+  let p = base ?? path.dirname(file);
+  for (const part of parts) {
+    p = path.join(p, part);
+    try {
+      if (fs.lstatSync(p).isSymbolicLink()) return p;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function write(ctx, file, next) {
+  const shown = shortPath(ctx, file);
+  const link = throughLink(ctx, file);
+  if (link) return { file: shown, result: `skipped (${shortPath(ctx, link)} is a symbolic link; write it by hand)` };
+  const prev = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+  if (prev === next) return { file: shown, result: "unchanged" };
+  if (!ctx.dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, next);
+  }
+  return { file: shown, result: prev === null ? "created" : "updated" };
+}
+function shortPath(ctx, file) {
+  const rel = path.relative(ctx.root, file);
+  if (!rel.startsWith("..") && !path.isAbsolute(rel)) return rel;
+  return file.startsWith(ctx.home + path.sep) ? "~" + file.slice(ctx.home.length) : file;
+}
+function mergeJson(ctx, file, key, entry2) {
+  const link = throughLink(ctx, file);
+  if (link) return { file: shortPath(ctx, file), result: `skipped (${shortPath(ctx, link)} is a symbolic link; write it by hand)` };
+  let doc = {};
+  if (fs.existsSync(file)) {
+    const raw = fs.readFileSync(file, "utf8");
+    if (raw.trim()) {
+      try {
+        doc = JSON.parse(raw);
+      } catch {
+        return { file: shortPath(ctx, file), result: `skipped (not plain JSON; add "${SERVER}": ${JSON.stringify(entry2)} under "${key}" by hand)` };
+      }
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return { file: shortPath(ctx, file), result: "skipped (not a JSON object)" };
+  }
+  const servers = typeof doc[key] === "object" && doc[key] !== null ? doc[key] : {};
+  if (JSON.stringify(servers[SERVER]) === JSON.stringify(entry2)) return { file: shortPath(ctx, file), result: "unchanged" };
+  doc[key] = { ...servers, [SERVER]: entry2 };
+  return write(ctx, file, JSON.stringify(doc, null, 2) + "\n");
+}
+function mergeSection(ctx, file) {
+  const section = instructionsSection(ctx.url);
+  const prev = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const a = prev.indexOf(SECTION_START);
+  const b = prev.indexOf(SECTION_END, a);
+  let next;
+  if (a >= 0 && b > a) {
+    let end = b + SECTION_END.length;
+    if (prev[end] === "\n") end++;
+    next = prev.slice(0, a) + section + prev.slice(end);
+  } else {
+    next = prev ? prev.replace(/\n*$/, "\n\n") + section : section;
+  }
+  return write(ctx, file, next);
+}
+var tomlString = (s) => JSON.stringify(s);
+function mergeToml(ctx, file) {
+  const want = [`command = ${tomlString(COMMAND)}`, `args = [${ARGS.map(tomlString).join(", ")}]`];
+  const urlKey = ctx.url ? `SIGNAFAIDE_URL = ${tomlString(ctx.url)}` : null;
+  const prev = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const lines = prev.split("\n");
+  const header = new RegExp(`^\\s*\\[\\s*mcp_servers\\.(${SERVER}|"${SERVER}")\\s*\\]\\s*(#.*)?$`);
+  const envHeader = new RegExp(`^\\s*\\[\\s*mcp_servers\\.(${SERVER}|"${SERVER}")\\.env\\s*\\]\\s*(#.*)?$`);
+  const start = lines.findIndex((l) => header.test(l));
+  if (start < 0) {
+    const env = urlKey ? [`env = { ${urlKey} }`] : [];
+    return write(ctx, file, (prev.trim() ? prev.replace(/\n*$/, "\n\n") : "") + `[mcp_servers.${SERVER}]
+${[...want, ...env].join("\n")}
+`);
+  }
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[/.test(lines[end])) end++;
+  const body = [];
+  let inlineEnv = false;
+  for (let i = start + 1; i < end; i++) {
+    if (/^\s*command\s*=/.test(lines[i])) continue;
+    if (/^\s*args\s*=/.test(lines[i])) {
+      while (i < end - 1 && !lines[i].includes("]")) i++;
+      continue;
+    }
+    const m = urlKey && lines[i].match(/^(\s*env\s*=\s*\{)([^}]*)(\}.*)$/);
+    if (m) {
+      const vars = m[2].split(",").map((v) => v.trim()).filter((v) => v && !/^"?SIGNAFAIDE_URL"?\s*=/.test(v));
+      body.push(`${m[1]} ${[...vars, urlKey].join(", ")} ${m[3]}`);
+      inlineEnv = true;
+      continue;
+    }
+    body.push(lines[i]);
+  }
+  let out2 = [...lines.slice(0, start + 1), ...want, ...body, ...lines.slice(end)];
+  if (urlKey && !inlineEnv) {
+    const e = out2.findIndex((l) => envHeader.test(l));
+    if (e >= 0) {
+      let f = e + 1;
+      while (f < out2.length && !/^\s*\[/.test(out2[f])) f++;
+      const kept = out2.slice(e + 1, f).filter((l) => !/^\s*"?SIGNAFAIDE_URL"?\s*=/.test(l));
+      out2 = [...out2.slice(0, e + 1), urlKey, ...kept, ...out2.slice(f)];
+    } else out2.splice(start + 1 + want.length, 0, `env = { ${urlKey} }`);
+  }
+  return write(ctx, file, out2.join("\n"));
+}
+var onPath = (ctx, bin) => (ctx.env.PATH ?? "").split(path.delimiter).filter(Boolean).some((d) => [bin, `${bin}.cmd`, `${bin}.exe`].some((b) => fs.existsSync(path.join(d, b))));
+var why = (checks) => checks.find(([, ok]) => ok)?.[0] ?? null;
+var inProject = (ctx, f) => fs.existsSync(path.join(ctx.root, f));
+var inHome = (ctx, f) => fs.existsSync(path.join(ctx.home, f));
+var running = (ctx, id) => detectAgent(ctx.env) === id;
+var AGENTS = [
+  {
+    id: "claude-code",
+    detect: (c) => why([
+      ["running in it", running(c, "claude-code")],
+      ["`claude` on PATH", onPath(c, "claude")],
+      [".claude/ in the project", inProject(c, ".claude")],
+      ["~/.claude", inHome(c, ".claude")]
+    ]),
+    note: "Claude Code asks once to approve the project's MCP servers when it next starts here",
+    install: (c) => [
+      mergeJson(c, path.join(c.root, ".mcp.json"), "mcpServers", entry(c, { type: "stdio" }, true)),
+      write(c, path.join(c.root, ".claude", "skills", "signafaide", "SKILL.md"), claudeSkill(c.url)),
+      // Claude Code reads CLAUDE.md as the project's instructions; the skill alone is read as a file.
+      mergeSection(c, path.join(c.root, "CLAUDE.md"))
+    ]
+  },
+  {
+    id: "codex",
+    detect: (c) => why([
+      ["running in it", running(c, "codex")],
+      ["`codex` on PATH", onPath(c, "codex")],
+      ["CODEX_HOME", !!c.env.CODEX_HOME],
+      ["~/.codex", inHome(c, ".codex")]
+    ]),
+    install: (c) => [mergeToml(c, path.join(c.env.CODEX_HOME || path.join(c.home, ".codex"), "config.toml")), mergeSection(c, path.join(c.root, "AGENTS.md"))]
+  },
+  {
+    id: "cursor",
+    detect: (c) => why([
+      ["running in it", running(c, "cursor")],
+      ["`cursor` on PATH", onPath(c, "cursor") || onPath(c, "cursor-agent")],
+      [".cursor/ in the project", inProject(c, ".cursor")],
+      ["~/.cursor", inHome(c, ".cursor")]
+    ]),
+    install: (c) => [
+      mergeJson(c, path.join(c.root, ".cursor", "mcp.json"), "mcpServers", entry(c, { type: "stdio" })),
+      write(c, path.join(c.root, ".cursor", "rules", "signafaide.mdc"), cursorRule(c.url))
+    ]
+  },
+  {
+    id: "gemini-cli",
+    detect: (c) => why([
+      ["running in it", running(c, "gemini-cli")],
+      ["`gemini` on PATH", onPath(c, "gemini")],
+      [".gemini/ in the project", inProject(c, ".gemini")],
+      ["~/.gemini", inHome(c, ".gemini")]
+    ]),
+    note: "Gemini CLI reads .gemini/settings.json only in folders you trust (it asks when it first starts in a folder)",
+    install: (c) => [mergeJson(c, path.join(c.root, ".gemini", "settings.json"), "mcpServers", entry(c)), mergeSection(c, path.join(c.root, "GEMINI.md"))]
+  },
+  {
+    id: "copilot",
+    detect: (c) => why([
+      ["running in it", running(c, "copilot")],
+      [".github/copilot-instructions.md in the project", inProject(c, ".github/copilot-instructions.md")],
+      [".vscode/mcp.json in the project", inProject(c, ".vscode/mcp.json")],
+      ["`copilot` on PATH", onPath(c, "copilot")]
+    ]),
+    install: (c) => [
+      mergeJson(c, path.join(c.root, ".vscode", "mcp.json"), "servers", entry(c, { type: "stdio" })),
+      mergeSection(c, path.join(c.root, ".github", "copilot-instructions.md"))
+    ]
+  },
+  {
+    id: "windsurf",
+    detect: (c) => why([
+      ["running in it", running(c, "windsurf")],
+      ["`windsurf` on PATH", onPath(c, "windsurf")],
+      [".windsurf/ or .devin/ in the project", inProject(c, ".windsurf") || inProject(c, ".devin")],
+      ["~/.codeium/windsurf", inHome(c, ".codeium/windsurf")]
+    ]),
+    install: (c) => [mergeJson(c, path.join(c.root, ".devin", "mcp_config.json"), "mcpServers", entry(c)), mergeSection(c, path.join(c.root, "AGENTS.md"))]
+  }
+];
+var AGENT_IDS = AGENTS.map((a) => a.id);
+function witnessUrl(raw) {
+  if (raw === void 0) return void 0;
+  let u;
+  try {
+    u = new URL(raw.trim());
+  } catch {
+    throw new Error(`--url ${raw} is not a URL; use the witness's base URL, e.g. https://signafaide.internal.example.com`);
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:" || u.username || u.password || u.search || u.hash) {
+    throw new Error(`--url ${raw} must be an http(s) base URL without credentials, query or fragment`);
+  }
+  return u.toString().replace(/\/+$/, "");
+}
+var ALIASES = { claude: "claude-code", gemini: "gemini-cli", "github-copilot": "copilot", vscode: "copilot" };
+function setup(opts) {
+  const ctx = { root: path.resolve(opts.root), home: opts.home ?? os.homedir(), env: opts.env ?? process.env, dryRun: !!opts.dryRun, url: witnessUrl(opts.url) };
+  let chosen;
+  if (opts.agents?.length) {
+    const ids = opts.agents.flatMap((a) => a.split(",")).map((a) => a.trim().toLowerCase()).filter(Boolean);
+    const wanted = ids.includes("all") ? AGENT_IDS : ids.map((a) => ALIASES[a] ?? a);
+    const unknown = wanted.filter((a) => !AGENT_IDS.includes(a));
+    if (unknown.length) throw new Error(`unknown agent ${unknown.join(", ")}; use one of ${AGENT_IDS.join(", ")} or all`);
+    chosen = AGENTS.filter((a) => wanted.includes(a.id)).map((agent) => ({ agent, reason: "asked for" }));
+  } else {
+    chosen = AGENTS.map((agent) => ({ agent, reason: agent.detect(ctx) ?? "" })).filter((a) => a.reason);
+  }
+  return chosen.map(({ agent, reason }) => ({ agent: agent.id, reason, changes: agent.install(ctx), ...agent.note ? { note: agent.note } : {} }));
+}
+
+// src/gateway.ts
+import { spawn } from "child_process";
+import * as os2 from "os";
+var GATEWAY_ERROR = -32e3;
+var FORWARD = { forward: true };
+var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function idKey(id) {
+  return typeof id === "string" ? `s:${id}` : typeof id === "number" ? `n:${id}` : void 0;
+}
+function parse(line) {
+  const text = line.toString("utf8").trim();
+  if (!text || text[0] !== "{" && text[0] !== "[") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function resultText(result) {
+  const parts = Array.isArray(result.content) ? result.content.filter((c) => isObject(c) && c.type === "text" && typeof c.text === "string").map((c) => c.text) : [];
+  return parts.join("\n").slice(0, 2e3) || "the tool reported an error";
+}
+function outcomeContent(answer) {
+  if (isObject(answer.error)) {
+    return { error: toJsonable({ type: "JsonRpcError", message: String(answer.error.message ?? "the server answered with an error"), code: answer.error.code ?? null }) };
+  }
+  const result = answer.result;
+  if (isObject(result) && result.isError === true) return { error: { type: "ToolError", message: resultText(result) }, output: toJsonable(result) };
+  return { output: toJsonable(result) ?? null };
+}
+function runGateway(opts) {
+  return new Gateway(opts).run();
+}
+var Gateway = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.input = opts.stdin ?? process.stdin;
+    this.out = opts.stdout ?? process.stdout;
+    this.err = opts.stderr ?? process.stderr;
+    this.prefix = opts.namePrefix ?? "";
+    this.strictTools = new Set(opts.strictTools ?? []);
+    this.source = `gateway:${this.prefix || sha256Hex(new TextEncoder().encode([opts.command, ...opts.args ?? []].join("\0"))).slice(0, 8)}`;
+    this.rec = opts.recorder ?? configure({ via: "gateway", storeContent: opts.storeContent });
+  }
+  opts;
+  rec;
+  input;
+  out;
+  err;
+  prefix;
+  source;
+  strictTools;
+  off = recordingDisabled();
+  child;
+  /** Client-to-server `tools/call` requests waiting for their answer, by id. Server-to-client
+   * requests have ids of their own and are never looked up here. */
+  calls = /* @__PURE__ */ new Map();
+  /** Client-to-server `tools/list` requests waiting for their answer, by id. */
+  lists = /* @__PURE__ */ new Map();
+  /** The listing the client is paging through, and the tools of the last one it finished. */
+  listing = null;
+  shown = null;
+  /** Answers held for a client batch whose other entries went on to the server, by their ids. */
+  held = /* @__PURE__ */ new Map();
+  /** Strict calls waiting for the witness. */
+  waiting = /* @__PURE__ */ new Set();
+  /** The shown tools changed since they were last declared. */
+  undeclared = false;
+  toldDeclare = false;
+  done = false;
+  diag(msg) {
+    this.err.write(`signafaide gateway: ${msg}
+`);
+  }
+  // --- relay --------------------------------------------------------------------------
+  toServer(data) {
+    const stdin = this.child.stdin;
+    if (!stdin || stdin.destroyed || stdin.writableEnded) return;
+    if (!stdin.write(data)) {
+      this.input.pause();
+      stdin.once("drain", () => this.input.resume());
+    }
+  }
+  toClient(data) {
+    if (!this.out.write(data)) {
+      this.child.stdout?.pause();
+      this.out.once("drain", () => this.child.stdout?.resume());
+    }
+  }
+  send(v, original) {
+    if ("forward" in v) this.toServer(Buffer.concat([original, NL]));
+    else if ("reply" in v) this.toClient(JSON.stringify(v.reply) + "\n");
+  }
+  error(id, message, code) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code: GATEWAY_ERROR, message, data: { signafaide: code } } };
+  }
+  // --- client to server -----------------------------------------------------------------
+  fromClient(line) {
+    const msg = this.off ? void 0 : parse(line);
+    if (msg === void 0) return this.toServer(Buffer.concat([line, NL]));
+    if (Array.isArray(msg)) return this.clientBatch(msg, line);
+    const v = this.clientMessage(msg);
+    if (v instanceof Promise) this.later(v.then((got) => this.send(got, line)));
+    else this.send(v, line);
+  }
+  /** Keep a strict call's wait, so the server's stdin is not closed under it. */
+  later(p) {
+    const tracked = p.catch((e) => this.diag(`${e.message}`)).finally(() => this.waiting.delete(tracked));
+    this.waiting.add(tracked);
+  }
+  /** A batch: each entry is judged like a single message. Entries that may not run are taken
+   * out and answered here; their answers travel with the server's answer to the rest. */
+  clientBatch(msgs, line) {
+    const verdicts = msgs.map((m) => this.clientMessage(m));
+    const finish = (vs) => {
+      const forward = msgs.filter((_, i) => "forward" in vs[i]);
+      const replies = vs.flatMap((v) => "reply" in v ? [v.reply] : []);
+      if (forward.length === msgs.length) return this.toServer(Buffer.concat([line, NL]));
+      if (forward.length) this.toServer(JSON.stringify(forward) + "\n");
+      if (!replies.length) return;
+      const answered = forward.flatMap((m) => isObject(m) && typeof m.method === "string" && idKey(m.id) !== void 0 ? [idKey(m.id)] : []);
+      if (!answered.length) return this.toClient(JSON.stringify(replies) + "\n");
+      const group = { replies };
+      for (const k of answered) this.held.set(k, group);
+    };
+    if (verdicts.some((v) => v instanceof Promise)) this.later(Promise.all(verdicts).then(finish));
+    else finish(verdicts);
+  }
+  clientMessage(msg) {
+    if (!isObject(msg) || typeof msg.method !== "string") return FORWARD;
+    const key = idKey(msg.id);
+    if (msg.method === "tools/list" && key !== void 0) {
+      const cursor = isObject(msg.params) ? msg.params.cursor : void 0;
+      if (typeof cursor !== "string" || !cursor || !this.listing) this.listing = { names: /* @__PURE__ */ new Set(), complete: false };
+      this.lists.set(key, this.listing);
+    } else if (msg.method === "notifications/cancelled") {
+      this.cancelled(isObject(msg.params) ? msg.params : {});
+    } else if (msg.method === "tools/call") {
+      return this.call(msg, key);
+    }
+    return FORWARD;
+  }
+  call(msg, key) {
+    const params = isObject(msg.params) ? msg.params : {};
+    const tool = params.name;
+    if (typeof tool !== "string" || !tool) return FORWARD;
+    const full = this.prefix + tool;
+    const name = declaredName(full);
+    this.declareShown();
+    const meta = { sdk: `signafaide-js/${VERSION}`, gateway: true };
+    if (name !== tool) meta.tool = tool;
+    let decision;
+    try {
+      const content = { input: toJsonable(params.arguments) ?? null, meta };
+      decision = this.rec.write("decision", name, content, { agent: this.opts.agent, storeContent: this.opts.storeContent });
+    } catch (e) {
+      const why2 = e.message;
+      this.diag(`${tool} was not run because the call could not be recorded: ${why2}`);
+      return key === void 0 ? { drop: true } : { reply: this.error(msg.id, `signafaide gateway: ${tool} was not run because the call could not be recorded: ${why2}`, "not_written") };
+    }
+    if (key === void 0) return FORWARD;
+    const old = this.calls.get(key);
+    if (old && old.state !== "cancelled") this.outcome(old, { error: { type: "NoAnswer", message: "the client used this request id again before the server answered" } });
+    const call = { key, name, decision, state: "forwarded" };
+    this.calls.set(key, call);
+    if (!(this.opts.strict || this.strictTools.has(tool)) || this.rec.test) return FORWARD;
+    call.state = "waiting";
+    const gone = () => {
+      if (this.calls.get(key) === call) this.calls.delete(key);
+      return { drop: true };
+    };
+    return this.rec.ensureReceipt(decision).then(
+      () => {
+        if (call.state === "cancelled") return gone();
+        call.state = "forwarded";
+        return FORWARD;
+      },
+      (e) => {
+        const err2 = e instanceof SignafaideError ? e : new SignafaideError(e.message);
+        this.rec.warnStrictRefused(name, err2);
+        if (call.state === "cancelled") return gone();
+        this.calls.delete(key);
+        return { reply: this.error(msg.id, `${err2.message} (strict mode: ${name} did not run)`, err2.code) };
+      }
+    );
+  }
+  cancelled(params) {
+    const key = idKey(params.requestId);
+    const call = key === void 0 ? void 0 : this.calls.get(key);
+    if (!call || call.state === "cancelled") return;
+    const reason = typeof params.reason === "string" && params.reason ? `: ${params.reason.slice(0, 500)}` : "";
+    const when = call.state === "waiting" ? "before the call was forwarded to the server" : "before the server answered";
+    this.outcome(call, { error: { type: "Cancelled", message: `the client cancelled the call ${when}${reason}` } });
+    if (call.state === "waiting") call.state = "cancelled";
+    else this.calls.delete(call.key);
+  }
+  // --- server to client -----------------------------------------------------------------
+  fromServer(line) {
+    const msg = this.off ? void 0 : parse(line);
+    if (msg === void 0) return this.toClient(Buffer.concat([line, NL]));
+    const answers = (Array.isArray(msg) ? msg : [msg]).filter((m) => isObject(m) && typeof m.method !== "string" && idKey(m.id) !== void 0);
+    for (const m of answers) this.answer(m);
+    const groups = new Set(answers.flatMap((m) => this.held.has(idKey(m.id)) ? [this.held.get(idKey(m.id))] : []));
+    for (const m of answers) this.held.delete(idKey(m.id));
+    const extra = [...groups].flatMap((g) => g.replies.splice(0));
+    if (!extra.length) return this.toClient(Buffer.concat([line, NL]));
+    if (Array.isArray(msg)) return this.toClient(JSON.stringify([...msg, ...extra]) + "\n");
+    this.toClient(Buffer.concat([line, NL]));
+    this.toClient(JSON.stringify(extra) + "\n");
+  }
+  /** An answer from the server to a request of the client's. */
+  answer(m) {
+    const key = idKey(m.id);
+    const listing = this.lists.get(key);
+    if (listing) {
+      this.lists.delete(key);
+      this.listed(listing, m);
+    }
+    const call = this.calls.get(key);
+    if (call && call.state === "forwarded") {
+      this.calls.delete(key);
+      this.outcome(call, outcomeContent(m));
+    }
+  }
+  listed(listing, m) {
+    const result = m.result;
+    if (!isObject(result) || !Array.isArray(result.tools)) return;
+    for (const t of result.tools) if (isObject(t) && typeof t.name === "string" && t.name) listing.names.add(t.name);
+    this.undeclared = true;
+    if (typeof result.nextCursor === "string" && result.nextCursor) return;
+    listing.complete = true;
+    this.shown = listing.names;
+    this.declareShown();
+  }
+  /** Declare the tools the client has been shown: the last finished listing, with the pages of
+   * the one it is still paging through. Written once per distinct list (the recorder sees to
+   * that). A failure is reported once and never stops the relay. */
+  declareShown() {
+    const paging = this.listing && !this.listing.complete ? this.listing.names : null;
+    if (!this.undeclared || !this.shown && !paging?.size) return;
+    const tools = {};
+    for (const n of [...this.shown ?? [], ...paging ?? []]) tools[this.prefix + n] = true;
+    try {
+      this.rec.declareTools(tools, { agent: this.opts.agent, source: this.source, origin: "gateway", storeContent: this.opts.storeContent });
+      this.undeclared = false;
+    } catch (e) {
+      if (!this.toldDeclare) this.diag(`could not write the tool declaration: ${e.message}`);
+      this.toldDeclare = true;
+    }
+  }
+  outcome(call, content) {
+    try {
+      this.rec.write("outcome", call.name, content, { agent: call.decision.envelope.agent, ref: recordHash(call.decision), storeContent: this.opts.storeContent });
+    } catch (e) {
+      this.diag(`could not write the outcome of ${call.name}: ${e.message}`);
+    }
+  }
+  // --- life cycle -----------------------------------------------------------------------
+  run() {
+    return new Promise((resolve3) => {
+      const { command, args = [] } = this.opts;
+      if (this.off) this.diag("SIGNAFAIDE_DISABLED is set: relaying only, nothing is recorded");
+      const child = this.child = spawn(command, args, { stdio: ["pipe", "pipe", this.opts.stderr ? "pipe" : "inherit"], windowsHide: true, env: this.opts.env ?? process.env });
+      const signals = this.opts.forwardSignals === false ? [] : ["SIGINT", "SIGTERM", "SIGHUP"];
+      let killer;
+      const onSignal = (sig) => {
+        child.kill(sig);
+        killer ??= setTimeout(() => child.kill("SIGKILL"), this.opts.killAfterMs ?? 5e3);
+        killer.unref?.();
+      };
+      for (const s of signals) process.on(s, onSignal);
+      const finish = async (result, upstream) => {
+        if (this.done) return;
+        this.done = true;
+        clearTimeout(killer);
+        for (const s of signals) process.off(s, onSignal);
+        this.input.off("data", onInput);
+        this.input.off("end", onEnd);
+        this.input.pause();
+        await Promise.allSettled([...this.waiting]);
+        for (const call of [...this.calls.values()]) {
+          if (call.state !== "cancelled") this.outcome(call, { error: { type: "UpstreamExited", message: `${upstream} before it answered` } });
+        }
+        this.calls.clear();
+        if (!this.off) this.declareShown();
+        try {
+          this.rec.releaseToolSources(this.source);
+          if (!this.opts.recorder) await this.rec.shutdown();
+        } catch (e) {
+          this.diag(e.message);
+        }
+        if (this.out.writableLength && !this.out.destroyed) await new Promise((r) => this.out.write("", () => r()));
+        resolve3(result);
+      };
+      child.once("error", (e) => {
+        this.diag(`could not start ${command}: ${e.message}`);
+        void finish({ code: e.code === "ENOENT" ? 127 : e.code === "EACCES" ? 126 : 1, signal: null }, "the MCP server could not be started");
+      });
+      const guard = (what, fn) => {
+        try {
+          fn();
+        } catch (e) {
+          this.diag(`${what} dropped: ${e.message}`);
+        }
+      };
+      const clientLines = new Lines((l) => guard("a client message was", () => this.fromClient(l)));
+      const serverLines = new Lines((l) => guard("a server message was", () => this.fromServer(l)));
+      const onInput = (chunk) => clientLines.push(chunk);
+      const onEnd = () => {
+        guard("a client message was", () => clientLines.end((rest) => this.off ? this.toServer(rest) : this.fromClientTail(rest)));
+        void Promise.allSettled([...this.waiting]).then(() => child.stdin?.end());
+      };
+      this.input.on("data", onInput);
+      this.input.once("end", onEnd);
+      child.stderr?.on("data", (chunk) => this.err.write(chunk));
+      child.stdin?.on("error", () => void 0);
+      this.out.on("error", () => child.kill("SIGTERM"));
+      child.stdout?.on("data", (chunk) => serverLines.push(chunk));
+      child.once("close", (code, signal) => {
+        guard("a server message was", () => serverLines.end((rest) => this.toClient(rest)));
+        const how = signal ? `the MCP server was ended by ${signal}` : `the MCP server exited (code ${code ?? 0})`;
+        void finish({ code: code ?? 128 + (os2.constants.signals[signal] ?? 0), signal }, how);
+      });
+    });
+  }
+  /** A last client line with no newline: judged like any other, and sent without one. */
+  fromClientTail(rest) {
+    const msg = parse(rest);
+    const v = msg === void 0 || Array.isArray(msg) ? FORWARD : this.clientMessage(msg);
+    const put = (got) => {
+      if ("forward" in got) this.toServer(rest);
+      else if ("reply" in got) this.toClient(JSON.stringify(got.reply) + "\n");
+    };
+    if (v instanceof Promise) this.later(v.then(put));
+    else put(v);
+  }
+};
+var NL = Buffer.from("\n");
+var Lines = class {
+  constructor(onLine) {
+    this.onLine = onLine;
+  }
+  onLine;
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.length ? Buffer.concat([this.buf, Buffer.from(chunk)]) : Buffer.from(chunk);
+    let start = 0;
+    for (let i = this.buf.indexOf(10, start); i !== -1; i = this.buf.indexOf(10, start)) {
+      const line = this.buf.subarray(start, i);
+      start = i + 1;
+      this.onLine(line);
+    }
+    this.buf = this.buf.subarray(start);
+  }
+  /** What is left when the stream ends: a last line without a newline. */
+  end(onRest) {
+    if (this.buf.length) onRest(this.buf);
+    this.buf = Buffer.alloc(0);
+  }
+};
+
+// src/cli.ts
+var out = (s) => console.log(s);
+var err = (s) => console.error(s);
+var recorder = () => configure({ quiet: true, via: "cli" });
+var mask = (k) => k ? `${k.slice(0, 13)}...` : "none";
+function siteOf(url) {
+  const u = new URL(url);
+  return `${u.protocol}//${u.host.replace(/^api\./, "")}`;
+}
+var UPGRADE_LIMIT = (site) => `upgrade: Solo (\xA319 a month) takes 100,000 live records a month and keeps recording past them at \xA35 per 100,000: ${site}/pricing`;
+var UPGRADE_VERIFY = (site) => `upgrade: Solo (\xA319 a month) adds a verification report for a period and auditor links up to 90 days: ${site}/pricing`;
+var HINT_EVERY_MS = 7 * 864e5;
+async function upgradeAfterVerify(rec) {
+  if (!rec.apiKey?.startsWith("sfa_live_")) return;
+  const last = Date.parse(String(rec.state.config().upgrade_hint ?? ""));
+  if (Number.isFinite(last) && Date.now() - last < HINT_EVERY_MS) return;
+  try {
+    if ((await rec.client(3e3).usage())?.plan !== "free") return;
+    rec.state.saveConfig({ upgrade_hint: (/* @__PURE__ */ new Date()).toISOString() });
+  } catch {
+    return;
+  }
+  out(UPGRADE_VERIFY(siteOf(rec.url)));
+}
+async function statusLines(rec) {
+  const lines = [];
+  const s = rec.status();
+  if (s.test_mode) lines.push("test mode: records go to a temporary folder and nothing is sent (SIGNAFAIDE_TEST, or a test runner); SIGNAFAIDE_TEST=0 turns it off");
+  lines.push(
+    s.api_key_invalid ? `key: SIGNAFAIDE_API_KEY is set but is not a signafAIde key (sfa_test_ or sfa_live_ and 32 letters or digits); nothing is sent until it is fixed` : `key: ${mask(s.api_key)}` + (s.env ? ` (env ${s.env})` : "; records stay on this machine (signed and chained, nothing is sent). `signafaide init` creates a free sandbox and sends hashes; or set SIGNAFAIDE_API_KEY")
+  );
+  lines.push(`service: ${s.url}`);
+  let project = {};
+  if (s.api_key) {
+    try {
+      project = await rec.client(5e3).project() ?? {};
+    } catch {
+      project = {};
+    }
+  }
+  const name = typeof project.name === "string" && project.name ? project.name : null;
+  if (project.project) lines.push(name ? `project: ${name} (${project.project}, ${project.env})` : `project: ${project.project} (${project.env})`);
+  lines.push(`home: ${s.home}`);
+  if (!s.chains.length) lines.push("chains: none yet; wrap a function with record()");
+  const blocked = [];
+  for (const c of s.chains) {
+    const last = c.receipt_seq ? `last receipt seq ${c.receipt_seq} at ${c.receipt_time}` : c.chain.startsWith("_pending/") ? "drafts, signed for the project when they ship" : "no receipt yet";
+    const other = c.current || !c.waiting ? "" : `; ${c.waiting} waiting for the key of that project`;
+    const shown = name && project.project && c.chain.startsWith(`${project.project}/`) ? `${name}/${c.chain.slice(project.project.length + 1)}` : c.chain;
+    lines.push(`chain ${shown}: key ${c.key_id}, ${plural(c.records, "record")}, ${last}${other}${c.blocked ? "; BLOCKED" : ""}`);
+    if (c.blocked) blocked.push(`BLOCKED ${c.chain}: ${c.blocked.reason}; ${plural(c.blocked.records, "record")} cannot ship. Next: ${c.blocked.next}`);
+  }
+  if (s.chains.some((c) => c.agent === rec.defaultAgent)) {
+    lines.push(`note: agent "${rec.defaultAgent}" is named after the project folder; give agents explicit names in production (record(fn, { agent: "claims-bot" }))`);
+  }
+  for (const h of s.held) lines.push(`held: ${h.chain}: ${plural(h.records, "record")} set aside by \`signafaide repair\` in ${h.file} (kept, verifiable locally, not co-signed)`);
+  lines.push(`outbox: ${plural(s.outbox, "record")} waiting` + (s.outbox && !blocked.length ? "; run `signafaide flush`" : ""));
+  lines.push(...blocked);
+  let claimed = !!s.sandbox?.claimed;
+  if (s.api_key) {
+    try {
+      const u = await rec.client(5e3).usage();
+      lines.push(`quota: ${u.used} of ${u.quota} used in ${u.period}`);
+      if (u.plan === "free" && typeof u.quota === "number" && u.used >= u.quota && s.api_key.startsWith("sfa_live_")) lines.push(UPGRADE_LIMIT(siteOf(rec.url)));
+    } catch (e) {
+      lines.push(`quota: unknown (${e.message})`);
+    }
+    if (!claimed && s.api_key.startsWith("sfa_test_") && s.sandbox?.claim_url) {
+      try {
+        claimed = project.claimed === true;
+        if (claimed) rec.state.saveSandbox({ ...s.sandbox, claimed: true });
+      } catch {
+      }
+    }
+  }
+  if (s.sandbox?.claim_url && s.api_key?.startsWith("sfa_test_")) lines.push(claimed ? "claim: done (this sandbox belongs to an organisation now)" : `claim: ${s.sandbox.claim_url}`);
+  return lines;
+}
+var COMMANDS = {
+  init: {
+    help: "opt in to the witness: create a free sandbox if there is no API key (no account, email or card), print the claim link. The witness is https://api.signafaide.co.uk unless SIGNAFAIDE_URL names another (a self-hosted witness, or http://127.0.0.1:7474 for a local one). Adds .signafaide/ and .env to .gitignore",
+    usage: "init   (environment: SIGNAFAIDE_URL=<witness url>, SIGNAFAIDE_API_KEY=<existing key>)",
+    async run() {
+      const rec = recorder();
+      rec.rememberAgent();
+      rec.state.ignoreInGit();
+      const had = rec.apiKey;
+      const key = await rec.createSandbox();
+      const claim = rec.state.sandbox()?.claim_url;
+      if (!had) {
+        out(`sandbox ready at ${rec.url}, key saved to ${path2.join(rec.state.root, ".env")}; claim it at ${claim}`);
+        out(termsNotice(rec.legal()));
+        out("from now on record hashes (never content) are sent for co-signature and public timestamps; records written before now ship with their original times on the next run or with `signafaide flush`");
+      } else if (key.startsWith("sfa_test_") && claim) out(`key found (${mask(key)}); claim the sandbox at ${claim}`);
+      else out(`key found (${mask(key)}, env ${envOf(key)}); nothing to create`);
+      return 0;
+    }
+  },
+  status: {
+    help: "key and env, agents, last receipt, outbox size, quota; BLOCKED chains (exit 1 when any)",
+    async run() {
+      const rec = recorder();
+      const lines = await statusLines(rec);
+      for (const line of lines) out(line);
+      return lines.some((l) => l.startsWith("BLOCKED ")) ? 1 : 0;
+    }
+  },
+  repair: {
+    help: "set aside records the witness can never take (clock went back, revoked key, clock ahead), rotate the agent's key and start a new segment; history is kept and verifiable",
+    usage: "repair [--agent X] [--dry-run]",
+    options: { agent: { type: "string" }, "dry-run": { type: "boolean" } },
+    async run(v) {
+      const rec = recorder();
+      const dry = !!v["dry-run"];
+      const done = rec.repair({ agent: v.agent, dryRun: dry });
+      if (!done.length) {
+        out(`nothing to repair${v.agent ? ` for agent ${v.agent}` : ""}: every chain can ship (\`signafaide status\` shows them)`);
+        return 0;
+      }
+      for (const r of done) {
+        out(`${r.chain}: ${r.blocked.reason}`);
+        if (dry) {
+          out(`  would set aside seq ${r.blocked.seq} onwards (${plural(r.blocked.records, "record")}), give the agent a new key and write a signafaide.repair note`);
+          continue;
+        }
+        out(`  set aside ${plural(r.records, "record")} in ${r.held} (kept; \`signafaide verify\` still checks their signatures and content hashes)`);
+        out(r.newKey ? `  new key ${r.newKey} signs from now on; the old key is retired on the witness at the next send` : "  the key comes from a secret store: rotate it there if it was revoked");
+        out(`  note ${r.note.slice(0, 12)} (signafaide.repair) commits to the held records' hashes and ships with the next send`);
+      }
+      if (!dry) out("next: `signafaide flush` sends the new segment, then `signafaide keys export` for your auditors (it lists the old and new keys)");
+      return 0;
+    }
+  },
+  verify: {
+    help: "verify a pack or the local state; exit 0 PASS, 1 FAIL, 2 unreadable input",
+    usage: "verify [pack.json] [--keys <file|url>] [--agent-keys <file|url>] [--head head.json] [--timestamp-check <url>] [--offline] [--trust-embedded-keys] [--trust-embedded-agent-keys] [--content <file|dir>] [--fail-on-pending-send] [--json]\n  --head: the customer's .signafaide/head.json (their newest receipt per agent). It proves no record was cut from the end of the pack; the customer sends it with the pack.\n  without a pack: checks this machine's records; a BLOCKED chain always exits 1, and --fail-on-pending-send also fails while records wait to be co-signed (for CI)",
+    options: {
+      keys: { type: "string" },
+      "trust-embedded-keys": { type: "boolean" },
+      "agent-keys": { type: "string" },
+      "trust-embedded-agent-keys": { type: "boolean" },
+      head: { type: "string" },
+      "timestamp-check": { type: "string" },
+      bitcoin: { type: "string" },
+      offline: { type: "boolean" },
+      content: { type: "string" },
+      json: { type: "boolean" },
+      "fail-on-pending-send": { type: "boolean" }
+    },
+    async run(v, pos) {
+      const rec = recorder();
+      let report;
+      try {
+        report = await verify(pos[0] ?? null, {
+          keys: v.keys,
+          trustEmbeddedKeys: v["trust-embedded-keys"],
+          agentKeys: v["agent-keys"],
+          trustEmbeddedAgentKeys: v["trust-embedded-agent-keys"],
+          head: v.head,
+          timestampCheck: v["timestamp-check"] ?? v.bitcoin,
+          offline: v.offline,
+          content: v.content,
+          failOnPendingSend: v["fail-on-pending-send"]
+        });
+      } catch (e) {
+        err(`signafaide: ${e.message}`);
+        await rec.event("verify");
+        return 2;
+      }
+      out(v.json ? JSON.stringify(report, null, 2) : String(report));
+      await rec.event("verify");
+      if (report.ok && !v.json) await upgradeAfterVerify(rec);
+      return report.ok ? 0 : 1;
+    }
+  },
+  keys: {
+    help: "export the agent public keys for auditors, make a key for a secret store, or rotate an agent's key",
+    usage: "keys export [-o agent-keys.json] | keys create [--agent X] [--env test|live] [--print] | keys rotate [--agent X] [--env test|live]",
+    options: { output: { type: "string", short: "o" }, agent: { type: "string" }, env: { type: "string" }, print: { type: "boolean" } },
+    async run(v, pos) {
+      const rec = recorder();
+      if (pos[0] === "export" && pos.length === 1) {
+        const doc = rec.state.exportAgentKeys();
+        if (!doc.keys.length) {
+          err("signafaide: no agent keys here yet; they are made with the first record");
+          return 1;
+        }
+        const file = v.output ?? "agent-keys.json";
+        fs2.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+        out(`wrote ${file} (${plural(doc.keys.length, "key")}); give it to your auditors with pack.json and head.json: signafaide verify pack.json --keys <witness>/.well-known/signafaide-keys.json --agent-keys ${file} --head head.json`);
+        return 0;
+      }
+      if (pos[0] === "create" && pos.length === 1) {
+        const agent = v.agent ?? rec.defaultAgent;
+        const env = v.env ?? envOf(rec.apiKey);
+        if (env !== "test" && env !== "live") throw new SyntaxError("--env must be test or live");
+        const r = await rec.createKey(agent, env, !!v.print);
+        if (v.print) {
+          out(JSON.stringify(r.doc));
+          err(
+            `signafaide: registered key ${r.doc.key_id} for ${agent} (${r.project}, ${env}); no record was written and nothing was saved here. Store the line above in your secret store as ${r.envName} and keep a backup: it is the only copy of the private key.`
+          );
+        } else {
+          out(`${agent}: registered key ${r.doc.key_id} (${r.project}, ${env}) and saved it as ${r.file}; no record was written. For a secret store, store that file's content as ${r.envName}.`);
+        }
+        return 0;
+      }
+      if (pos[0] === "rotate" && pos.length === 1) {
+        const agent = v.agent ?? rec.defaultAgent;
+        const env = v.env ?? envOf(rec.apiKey);
+        if (env && env !== "test" && env !== "live") throw new SyntaxError("--env must be test or live");
+        const [old, next] = rec.state.rotateKey(agent, env === "live" ? "live" : "");
+        out(
+          `${agent}: new key ${next.keyId} signs from now on. Records the old key ${old.keyId} signed earlier ship first; the next record then registers the new key, signed by the old one, and the service retires the old key at that moment`
+        );
+        return 0;
+      }
+      err(`usage: signafaide ${COMMANDS.keys.usage}`);
+      return 2;
+    }
+  },
+  export: {
+    help: "download a verification pack of the whole project (every agent), or of one agent with --agent",
+    usage: "export [--agent X] [--from T] [--to T] [-o pack.json]",
+    options: { agent: { type: "string" }, from: { type: "string" }, to: { type: "string" }, output: { type: "string", short: "o" } },
+    async run(v) {
+      const rec = recorder();
+      const agent = v.agent;
+      let pack;
+      try {
+        pack = await rec.client(6e4).export(agent, v.from, v.to);
+      } catch (e) {
+        await rec.event("export");
+        throw e;
+      }
+      const n = pack.records?.length ?? 0;
+      const file = v.output ?? `${agent ?? pack.project}-pack.json`;
+      fs2.writeFileSync(file, JSON.stringify(pack, null, 2) + "\n");
+      out(`wrote ${file} (${plural(n, "record")}); check it with \`signafaide verify ${file}\``);
+      if (!n) err(agent ? `signafaide export: agent '${agent}' has no records in this range; leave out --agent to export every agent (\`signafaide status\` lists them)` : "signafaide export: this project has no records in this range, so the pack proves nothing");
+      await rec.event("export");
+      return 0;
+    }
+  },
+  replay: {
+    help: "show what an agent saw and did, from the local chain, each record verified; exit 1 on FAIL",
+    usage: "replay [--agent X] [--from T] [--to T] [--record <hash>] [--chain <id>] [--keys <file|url>] [--html out.html] [--json]",
+    options: {
+      agent: { type: "string" },
+      from: { type: "string" },
+      to: { type: "string" },
+      record: { type: "string" },
+      chain: { type: "string" },
+      keys: { type: "string" },
+      html: { type: "string" },
+      json: { type: "boolean" }
+    },
+    async run(v) {
+      recorder();
+      const r = await replay({ agent: v.agent, since: v.from, until: v.to, record: v.record, chain: v.chain, keys: v.keys });
+      out(v.json ? JSON.stringify(r, null, 2) : String(r));
+      if (v.html) {
+        fs2.writeFileSync(v.html, r.toHtml());
+        err(`wrote ${v.html}`);
+      }
+      return r.ok ? 0 : 1;
+    }
+  },
+  compare: {
+    help: "re-run recorded decisions with a candidate function and compare the results",
+    usage: "compare --module <file.js|package>:<function> [--agent X] [--name N] [--from T] [--to T] [--limit N] [--label L] [--upload [--values]] [--json]",
+    options: {
+      module: { type: "string" },
+      agent: { type: "string" },
+      name: { type: "string" },
+      from: { type: "string" },
+      to: { type: "string" },
+      limit: { type: "string" },
+      label: { type: "string" },
+      chain: { type: "string" },
+      keys: { type: "string" },
+      upload: { type: "boolean" },
+      values: { type: "boolean" },
+      json: { type: "boolean" }
+    },
+    async run(v) {
+      if (!v.module) {
+        err(`usage: signafaide ${COMMANDS.compare.usage}`);
+        return 2;
+      }
+      recorder();
+      const limit = v.limit === void 0 ? void 0 : Number(v.limit);
+      if (limit !== void 0 && !Number.isInteger(limit)) throw new SyntaxError("--limit must be a whole number");
+      const fn = await loadCandidate(v.module);
+      const r = await compare(fn, { agent: v.agent, name: v.name, since: v.from, until: v.to, limit, label: v.label, chain: v.chain, keys: v.keys });
+      if (v.upload) await r.upload(v.values ? true : void 0);
+      out(v.json ? JSON.stringify({ ...r.toJSON(), ...r.uploaded ? { uploaded: r.uploaded } : {} }, null, 2) : String(r));
+      return 0;
+    }
+  },
+  claim: {
+    help: "print the sandbox claim link again",
+    async run() {
+      const rec = recorder();
+      if (rec.apiKey?.startsWith("sfa_live_")) {
+        out("this project uses a live key; there is nothing to claim");
+        return 0;
+      }
+      const claim = rec.state.sandbox()?.claim_url;
+      if (!claim) {
+        err("no sandbox here; run `signafaide init` first");
+        return 1;
+      }
+      out(claim);
+      return 0;
+    }
+  },
+  agent: {
+    help: "install the MCP server and the skill in your coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot, Windsurf)",
+    usage: "agent setup [--agent <name>]... [--url <self-hosted witness url>] [--dry-run] [--dir <project>]",
+    options: { agent: { type: "string", multiple: true }, "dry-run": { type: "boolean" }, dir: { type: "string" }, url: { type: "string" } },
+    async run(v, pos) {
+      if (pos[0] !== "setup" || pos.length > 1) {
+        err(`usage: signafaide ${COMMANDS.agent.usage}; agents: ${AGENT_IDS.join(", ")}, all`);
+        return 2;
+      }
+      const dry = !!v["dry-run"];
+      const root = v.dir ? path2.resolve(v.dir) : findRoot();
+      const results = setup({ root, agents: v.agent, dryRun: dry, url: v.url });
+      if (!dry && results.length) {
+        const rec = configure({ quiet: true, via: "cli", root });
+        rec.rememberAgent();
+        rec.state.ignoreInGit();
+      }
+      if (!results.length) {
+        out(`no coding agent found for ${root}; name one with --agent ${AGENT_IDS.join("|")} (or --agent all)`);
+        return 1;
+      }
+      if (dry) out("dry run: nothing written");
+      for (const r of results) {
+        const what = r.changes.map((c) => `${c.file} ${dry && /^(created|updated)$/.test(c.result) ? `would be ${c.result}` : c.result}`).join(", ");
+        out(`${r.agent}: ${what}${r.note ? `; note: ${r.note}` : ""}`);
+      }
+      for (const line of SETUP_NOTES(v.url)) out(line);
+      return results.some((r) => r.changes.some((c) => c.result.startsWith("skipped"))) ? 1 : 0;
+    }
+  },
+  mcp: {
+    help: "run the signafAIde MCP server over stdio (the separate signafaide-mcp package; `agent setup` configures it)",
+    async run() {
+      const pkg = "signafaide-mcp";
+      let mod;
+      try {
+        mod = await import(pkg);
+      } catch {
+        err(`signafaide: the MCP server is a separate package: run \`npx -y signafaide-mcp@${VERSION}\` (\`signafaide agent setup\` writes that into your coding agent's configuration)`);
+        return 1;
+      }
+      await mod.serve();
+      return 0;
+    }
+  },
+  gateway: {
+    help: "run an MCP server behind a recording proxy: every tool call that passes through it is recorded (a decision before the call is forwarded, an outcome when the answer arrives), and the server's tools are declared as the agent's recorded tools",
+    usage: 'gateway [--agent X] [--name-prefix P] [--strict | --strict-tools a,b] [--store-content] -- <command> [args...]\n  In the agent\'s MCP configuration, start the gateway in place of the server: {"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "support-bot", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]}\n  --agent: the agent\'s chain name (default: the project folder\'s name)\n  --name-prefix: put before each recorded tool name, for an agent with several servers (--name-prefix github.)\n  --strict: forward a call only once the witness has co-signed its decision; --strict-tools a,b: only for those tools\n  --store-content: send inputs and outputs to the witness too (default: hash-only)\n  A remote (HTTP) server: put a stdio bridge after the --, for example `signafaide gateway -- npx -y mcp-remote https://mcp.example.com/mcp`\n  A call that cannot be recorded is not forwarded. The gateway records every call that goes through it; a call the application makes around it is still not recorded, so the deployment has to make the gateway the only route to those tools.\n  Nothing is sent until the project has run `signafaide init` or has an API key. Only protocol messages go to stdout; diagnostics go to stderr.',
+    options: { agent: { type: "string" }, "name-prefix": { type: "string" }, strict: { type: "boolean" }, "strict-tools": { type: "string" }, "store-content": { type: "boolean" } },
+    async run(v, pos) {
+      if (!pos.length) {
+        err(`usage: signafaide ${(COMMANDS.gateway.usage ?? "").split("\n")[0]}`);
+        return 2;
+      }
+      const r = await runGateway({
+        command: pos[0],
+        args: pos.slice(1),
+        agent: v.agent,
+        namePrefix: v["name-prefix"],
+        strict: !!v.strict,
+        strictTools: typeof v["strict-tools"] === "string" ? v["strict-tools"].split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+        storeContent: v["store-content"] ? true : void 0
+      });
+      if (r.signal) {
+        try {
+          process.kill(process.pid, r.signal);
+        } catch {
+        }
+      }
+      return r.code;
+    }
+  },
+  flush: {
+    help: "ship the outbox now",
+    async run() {
+      const rec = recorder();
+      const r = await rec.flush();
+      for (const [agent, e] of Object.entries(r.errors)) err(`${agent}: ${e.message}`);
+      if (!rec.apiKey) {
+        out(`no API key: nothing was sent; ${plural(r.left, "record")} stay local. Run \`signafaide init\` (or set SIGNAFAIDE_API_KEY) to send hashes`);
+        return 0;
+      }
+      const local = Object.entries(r.errors).filter(([, e]) => e.code === "too_old" || e.code === "chain_exists").reduce((n, [c]) => n + rec.state.draftCount(c), 0);
+      out(`shipped ${plural(r.shipped, "record")}, ${r.left - local} left in the outbox` + (local ? `; ${plural(local, "record")} kept on this machine only (see above)` : ""));
+      for (const b of rec.diagnose()) out(`BLOCKED ${b.chain}: ${plural(b.records, "record")} cannot ship as they are. Next: ${b.next}`);
+      if (rec.apiKey.startsWith("sfa_live_") && Object.values(r.errors).some((e) => e.code === "quota_exceeded")) out(UPGRADE_LIMIT(siteOf(rec.url)));
+      return Object.keys(r.errors).length ? 1 : 0;
+    }
+  }
+};
+async function loadCandidate(spec) {
+  const i = spec.lastIndexOf(":");
+  const [target, fn] = i > 0 ? [spec.slice(0, i), spec.slice(i + 1)] : ["", ""];
+  if (!target || !fn) throw new SyntaxError("--module must be path/to/file.js:function or package:function");
+  const local = /^[./]/.test(target) || /\.[cm]?[jt]s$/.test(target);
+  let mod;
+  try {
+    mod = await (local ? import(pathToFileURL(path2.resolve(target)).href) : import(target));
+  } catch (e) {
+    throw new SyntaxError(`cannot load the candidate ${target}: ${e.message}`);
+  }
+  const f = mod[fn] ?? mod.default?.[fn];
+  if (typeof f !== "function") throw new SyntaxError(`${spec}: no function "${fn}" in ${target}`);
+  return f;
+}
+function help() {
+  const width = Math.max(...Object.keys(COMMANDS).map((c) => c.length));
+  return ["usage: signafaide <command> [options]", "", ...Object.entries(COMMANDS).map(([c, d]) => `  ${c.padEnd(width)}  ${d.help}`)].join("\n");
+}
+var EXIT_WHEN_DONE = /* @__PURE__ */ new Set(["gateway"]);
+async function main(argv = process.argv.slice(2)) {
+  const [name, ...rest] = argv;
+  if (name === "--version" || name === "-v") {
+    out(`signafaide ${VERSION}`);
+    return 0;
+  }
+  const cmd = name ? COMMANDS[name] : void 0;
+  if (!cmd) {
+    (name && name !== "--help" && name !== "-h" ? err : out)(help());
+    return name && name !== "--help" && name !== "-h" ? 1 : 0;
+  }
+  const own = rest.includes("--") ? rest.slice(0, rest.indexOf("--")) : rest;
+  if (own.includes("--help") || own.includes("-h")) {
+    out(`${cmd.help}
+usage: signafaide ${cmd.usage ?? name}`);
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: cmd.options ?? {}, allowPositionals: true, strict: true });
+  } catch (e) {
+    err(`signafaide ${name}: ${e.message}; usage: signafaide ${cmd.usage ?? name}`);
+    return 2;
+  }
+  try {
+    return await cmd.run(parsed.values, parsed.positionals);
+  } catch (e) {
+    if (e instanceof SignafaideError || e instanceof StateError || e instanceof KeysRequired || e instanceof VerificationFailed || e instanceof SyntaxError || e.code) {
+      err(`signafaide: ${e.message}`);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+// src/bin.ts
+main().then((code) => {
+  process.exitCode = code;
+  if (EXIT_WHEN_DONE.has(process.argv[2])) process.exit(code);
+});