seisin 0.4.2 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "seisin",
-  "version": "0.4.2",
-  "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it blocks it tells you whose file it was.",
+  "version": "0.6.0",
+  "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it denies something it tells you whose file it was.",
   "keywords": [
     "ai-agents",
     "claude-code",
@@ -13,7 +13,10 @@
     "codeowners",
     "rbac",
     "agent-permissions",
-    "code-ownership"
+    "code-ownership",
+    "mcp",
+    "security",
+    "developer-tools"
   ],
   "license": "MIT",
   "author": "Carlos Tapia",
@@ -31,7 +34,7 @@
   },
   "files": [
     "src",
-    "ui",
+    "ui/index.html",
     "README.md",
     "LICENSE"
   ],
@@ -39,15 +42,20 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.77"
+    "@anthropic-ai/sandbox-runtime": "0.0.81"
   },
   "scripts": {
     "test": "node --test test/*.test.js",
+    "build:ui": "node ui/build.js",
     "prepublishOnly": "npm test"
   },
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
     "./package.json": "./package.json"
   }
 }

package/src/browsers.js

@@ -0,0 +1,52 @@
+/**
+ * `browsers = ["chromium"]`: what a headless browser needs from the sandbox
+ * beyond files and the network, per role and only when the role says so.
+ *
+ * Measured on macOS with Playwright's Chromium headless shell (build 1208), as
+ * the kernel saw it under the default profile:
+ *
+ *   - the browser process starts by registering a Mach service named
+ *     `org.chromium.Chromium.MachPortRendezvousServer.<its pid>`, and dies at
+ *     once when that is refused (`bootstrap_check_in ... Permission denied
+ *     (1100)`, FATAL in base/apple/mach_port_rendezvous_mac.cc);
+ *   - every child it starts (GPU, network, renderer) then looks that same
+ *     service up to receive its ports, and loops forever when the lookup is
+ *     refused: over a thousand refusals in forty seconds, no page.
+ *
+ * Those two, with that one prefix, are all it took: with them the browser
+ * started, rendered and navigated through seisin's proxy, and the other Mach
+ * services it reached for (configd, the window server, analytics) stayed
+ * refused without stopping it. So that is all a preset grants. Never a bare
+ * `mach-register`: a name is registered in the bootstrap namespace other
+ * processes look names up in, and an open grant would let the role stand up a
+ * service under any name.
+ *
+ * The prefix is the browser's bundle id, which is why the preset is named for
+ * the build. Chrome and Chrome for Testing use their own (`com.google.Chrome`,
+ * `com.google.chrome.for.testing`) and also need a unix socket for their
+ * process singleton, measured and not granted here: they are not presets yet.
+ */
+export const BROWSERS = {
+  chromium: {
+    // The browser registers it; its children look it up.
+    register: ["org.chromium.Chromium.MachPortRendezvousServer."],
+    lookup: ["org.chromium.Chromium.MachPortRendezvousServer."],
+  },
+};
+
+/** A Mach name prefix as the profile may carry it: no quotes, no spaces, ends in a dot. */
+export const MACH_PREFIX = /^[A-Za-z0-9][A-Za-z0-9.-]*\.$/;
+
+/** The Mach names a role's browsers need registered and looked up, de-duplicated. */
+export function machOf(role) {
+  const names = (role?.browsers ?? []).map((b) => BROWSERS[b]).filter(Boolean);
+  return {
+    register: [...new Set(names.flatMap((b) => b.register))],
+    lookup: [...new Set(names.flatMap((b) => b.lookup))],
+  };
+}
+
+/** The preset whose register prefix this Mach name falls under, or null. */
+export function browserFor(name) {
+  return Object.keys(BROWSERS).find((b) => BROWSERS[b].register.some((p) => name.startsWith(p))) ?? null;
+}

package/src/canary.js

@@ -0,0 +1,149 @@
+/**
+ * The canary: before the agent starts, the policy is tried from inside.
+ *
+ * The settings are generated by software, and software breaks. A runtime
+ * upgrade, a path that turned out to be a symlink, an `isolate` level combined
+ * with something it was not measured with — any of them can leave a door open,
+ * and without this the first anyone hears of it is after something went
+ * through it. So every run starts with a short process under the SAME runtime,
+ * the SAME settings file and the SAME environment as the agent, and the agent
+ * starts only if every answer is the expected one.
+ *
+ * Judged by effect, never by exit code: a write "denied" is a file that is not
+ * there afterwards; a read "denied" is a nonce that never came out; a
+ * connection "refused" is a nonce the decoy never delivered. And each denial
+ * has a positive control beside it — the sandbox ran at all, and a place the
+ * role may write took the write — because a sandbox that runs nothing denies
+ * everything too.
+ *
+ * **Fails closed, including on a missing tool.** In an orchestrator we compared against, the network
+ * probe passed whenever `nc` was absent: no tool, no connection, "refused".
+ * Here a probe that cannot be made is a failed canary.
+ *
+ * **No flag skips it.** A flag becomes an alias, and the alias becomes the way
+ * every run starts. It costs one extra start of the runtime, a few tenths of a
+ * second, against a run that lasts minutes.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { randomBytes } from "node:crypto";
+import { writeFileSync, readFileSync, rmSync, existsSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/** Where sandbox-runtime's shared temp directory is on this host. */
+const SHARED_TMP_DIR = "/tmp/claude";
+
+/** The exit code of a run the canary stopped: not the agent's, and not one a shell uses. */
+export const CANARY_EXIT = 86;
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+/**
+ * Runs the canary and resolves to `{ ok, failed: [reasons], ms }`.
+ *
+ * `runDir` is this run's directory and `runsRoot` the one above it; the
+ * secret is planted in the second, which the settings deny to every run but
+ * the run's own directory. `role.localBinding` skips the network probe and
+ * says so: that role was granted every localhost port on purpose.
+ */
+export async function runCanary({ srt, wrap = null, settingsFile, settings, env, cwd, runDir, runsRoot, role, granted, timeoutMs = 20_000 }) {
+  // How the probe is started: under the run's sandbox, exactly as the agent
+  // will be (sandboxes/). `srt` alone is the runtime's own command line, kept
+  // for callers from before there was more than one sandbox.
+  const boxed = wrap ?? ((inner) => [srt, "--settings", settingsFile, "--", ...inner]);
+  const t0 = Date.now();
+  const nonce = randomBytes(8).toString("hex");
+  const failed = [];
+
+  const secret = join(runsRoot, `canary-${nonce}.secret`);
+  const outside = join(runDir, `canary-${nonce}.out`);
+  // The first directory the POLICY grants that exists — taken from the
+  // policy and not from the settings, so settings that lost the grant fail
+  // here instead of skipping the check. Absent (a role with nothing to
+  // write), the write control is skipped and "the sandbox ran" stands alone.
+  // Outside the repo first (the runtime's scratch, the role's home): a file
+  // appearing and vanishing in a watched tree restarts a dev server.
+  const candidates = (granted ?? settings.filesystem.allowWrite ?? []).filter((p) => isDir(p));
+  const writable = candidates.find((p) => !(cwd && (p === cwd || p.startsWith(cwd + "/") || cwd.startsWith(p + "/")))) ?? candidates[0];
+  const inside = writable ? join(writable, `.seisin-canary-${nonce}`) : null;
+  // The runtime's shared temp directory (srt.js, SHARED_TMP): granted by the
+  // runtime to every sandbox, taken back by seisin. Probed where it exists;
+  // where it does not, there is nothing beside which to write.
+  const shared = isDir(SHARED_TMP_DIR) ? join(SHARED_TMP_DIR, `.seisin-canary-${nonce}`) : null;
+  const policy = settingsFile;
+
+  writeFileSync(secret, `SECRET-${nonce}\n`, { mode: 0o600 });
+
+  let server = null;
+  let port = null;
+  if (!role.localBinding) {
+    server = createServer((s) => s.end(`HTTP/1.0 200 OK\r\nContent-Type: text/plain\r\n\r\nNET-${nonce}\n`));
+    await new Promise((res, rej) => server.listen(0, "127.0.0.1", res).on("error", rej));
+    port = server.address().port;
+  }
+
+  const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+  const script = [
+    `echo ALIVE-${nonce}`,
+    `(echo x > ${q(outside)}) 2>/dev/null`,
+    `cat ${q(secret)} 2>/dev/null`,
+    `cat ${q(policy)} >/dev/null 2>&1 && echo POLICY-READ-${nonce}`,
+    inside ? `(echo IN-${nonce} > ${q(inside)}) 2>/dev/null` : ":",
+    shared ? `(echo x > ${q(shared)}) 2>/dev/null` : ":",
+    // curl when there is one; otherwise the node seisin itself runs on, which
+    // every machine with seisin has — a slim image without curl would
+    // otherwise never start anything. Neither: a failed canary, not a pass.
+    port ? `if command -v curl >/dev/null 2>&1; then curl -s -m 3 -w PROBED-${nonce} http://127.0.0.1:${port}/ 2>/dev/null; ` +
+      `elif [ -x ${q(process.execPath)} ]; then ${q(process.execPath)} -e ${q(`process.stdout.write("PROBED-${nonce}");const s=require("net").connect(${port},"127.0.0.1");s.on("data",d=>process.stdout.write(d));s.on("error",()=>{});setTimeout(()=>process.exit(0),3000)`)} 2>/dev/null; ` +
+      `else echo NO-PROBE-${nonce}; fi` : ":",
+  ].join("; ");
+
+  let output = "";
+  let stderr = "";
+  let timedOut = false;
+  try {
+    const status = await new Promise((resolve) => {
+      const [file, ...args] = boxed(["/bin/sh", "-c", script]);
+      const child = spawn(file, args, {
+        cwd, env, stdio: ["ignore", "pipe", "pipe"],
+      });
+      const timer = setTimeout(() => { timedOut = true; try { child.kill("SIGKILL"); } catch {} }, timeoutMs);
+      child.stdout.on("data", (d) => { output += d; });
+      child.stderr.on("data", (d) => { stderr = (stderr + d).slice(-2000); });
+      child.on("error", () => { clearTimeout(timer); resolve(null); });
+      child.on("close", (code) => { clearTimeout(timer); resolve(code); });
+    });
+    void status;
+  } finally {
+    server?.close();
+  }
+
+  if (timedOut) failed.push(`the canary did not finish in ${timeoutMs / 1000}s`);
+  if (!output.includes(`ALIVE-${nonce}`)) {
+    // The runtime's own words, when it said any: a sandbox that refuses to
+    // start usually says why (measured: a path the runtime read as a broken
+    // glob), and without this the reason was thrown away with the stream.
+    const said = stderr.trim().split("\n").filter(Boolean).slice(-3).join(" / ");
+    failed.push(`the sandbox did not run the canary at all${said ? ` — the runtime said: ${said}` : ""}`);
+  }
+  if (existsSync(outside)) failed.push(`a write outside the territory went through (${outside})`);
+  if (shared && existsSync(shared)) failed.push(`a write into the runtime's shared temp directory went through (${shared})`);
+  if (output.includes(`SECRET-${nonce}`)) failed.push(`a planted secret was readable (${secret})`);
+  if (output.includes(`POLICY-READ-${nonce}`)) failed.push(`the run's own settings were readable (${policy})`);
+  if (inside) {
+    let wrote = false;
+    try { wrote = readFileSync(inside, "utf8").trim() === `IN-${nonce}`; } catch {}
+    if (!wrote) failed.push(`a write the role is granted did not go through (${dirname(inside)}) — the positive control`);
+  }
+  if (port) {
+    // The probe has to say it ran. Silence is not "unreachable": a node the
+    // sandbox will not execute prints nothing, and nothing would read as a pass.
+    if (!output.includes(`PROBED-${nonce}`) && !output.includes(`NO-PROBE-${nonce}`))
+      failed.push("the network probe did not run — a probe that cannot be made is not a pass");
+    if (output.includes(`NO-PROBE-${nonce}`)) failed.push("neither curl nor node can run inside the sandbox to probe the network with — a probe that cannot be made is not a pass");
+    if (output.includes(`NET-${nonce}`)) failed.push(`a loopback port outside the policy was reachable (127.0.0.1:${port})`);
+  }
+
+  for (const p of [secret, outside, inside, shared]) if (p) try { rmSync(p, { force: true }); } catch {}
+  return { ok: failed.length === 0, failed, ms: Date.now() - t0 };
+}

package/src/cli.js

@@ -3,7 +3,7 @@
  * seisin — give each agent its own folders and its own keys.
  *
  * This file is dispatch and nothing else: parse argv, load the config, call one
- * command, turn a thrown error into an exit code. Every command lives in
+ * command, make a thrown error an exit code. Every command lives in
  * `commands/` and every decision lives in a module beside it, so that a change
  * to how something is printed cannot change what is allowed.
  *
@@ -19,21 +19,19 @@ import { fileURLToPath } from "node:url";
 import { findConfig, loadConfig } from "./config.js";
 import { CONFIG_NAME } from "./layout.js";
 import { C, out, err } from "./render.js";
+import { COMMAND_HELP, flagsOf, renderHelp, renderLimits } from "./help.js";
+import { nearest, checkFlags } from "./suggest.js";
 
-import { run } from "./commands/run.js";
-import { check } from "./commands/check.js";
-import { explainCommand } from "./commands/explain.js";
-import { scanCommand } from "./commands/scan.js";
-import { init, initFromObservations } from "./commands/init.js";
-import { log, watch } from "./commands/log.js";
-import { hook } from "./commands/hook.js";
-import { ui } from "./commands/ui.js";
-import { requests, grant, deny } from "./commands/requests.js";
-import { whose } from "./commands/whose.js";
-import { wallsCommand } from "./commands/walls.js";
-import { reviewCommand } from "./commands/review.js";
-import { wire } from "./commands/wire.js";
-import { serveMcp } from "./mcp.js";
+/**
+ * Each command is imported when it is the one being run, not before.
+ *
+ * All fifteen used to load up front — 42 of 47 modules, the MCP server and the
+ * HTTP console among them — and `seisin hook` paid for every one on every tool
+ * call of every agent: 218 ms measured, where the hook itself needs a fraction
+ * of that. A dispatcher that loads everything to run one thing charges the
+ * most frequent command for the rarest ones. So each entry in COMMANDS below
+ * does its own `import()`.
+ */
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const [, , command, ...argv] = process.argv;
@@ -43,23 +41,27 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
 
   seisin run <role> -- <command...>     run a command as that role
   seisin run <role> --observe -- <cmd>  open the repo and watch — the network stays shut
-  seisin check [role]                   print the map, run nothing
-  seisin explain <role> read|write <path>
-  seisin whose <path>                   who owns it — safe to call from inside the box
-  seisin scan                           find secrets outside the declared key dirs
-  seisin review [--all]                 what the log says about the policy
+  seisin check [role] [--verbose] [--verify] [--parallel] [--system-log]  --parallel is experimental; --system-log measures log loss (macOS)
+  seisin explain <role> read|write|mcp <path, key or server>
+  seisin whose <path>                   who owns it — safe to call from inside the sandbox
+  seisin scan [--all]                   find secrets outside the declared key dirs
+  seisin review [--all] [--since 7d]    what the log says about the policy
   seisin walls <role> [--all]           what that role keeps being denied, and what it cost
   seisin wire                           let the agent record what it does
   seisin requests                       what the agents asked for and cannot have
-  seisin grant <n> [--reason "…"]       approve one, with its provenance
-  seisin decline <n> [--reason "…"]     turn one down, and record why
-  seisin log [--role r] [--verdict denied]
+  seisin grant <n> [--reason "…"]       grant one: add it to ${CONFIG_NAME}, with its provenance
+  seisin decline <n> [--reason "…"]     decline one, and record why
+  seisin log [--role r] [--verdict denied] [--limit n]
   seisin log verify                     does the log's hash chain hold
   seisin watch                          follow the log live
-  seisin init [--from-observations]     propose a ${CONFIG_NAME} for this repo
+  seisin init [--force]                 propose a ${CONFIG_NAME} for this repo
+  seisin init --from-observations       write ${CONFIG_NAME}.observed from observed runs
   seisin ui [--port n] [--link]         open the console, live (--link reopens a running one)
   seisin mcp                            an MCP server on stdio — read-only
 
+seisin <command> --help lists a command's flags, examples and exit codes.
+seisin help limits says what seisin cannot do, in any repo.
+
 Enforcement comes from @anthropic-ai/sandbox-runtime, which asks the OS.
 seisin decides what to ask for, and says whose file it was when the answer is no.
 `;
@@ -71,6 +73,12 @@ function config() {
   return loadConfig(path);
 }
 
+/** The policy here, or null — for a command that can answer without one. */
+function maybeConfig() {
+  const path = findConfig();
+  return path ? loadConfig(path) : null;
+}
+
 /**
  * Commands that need a config get it; commands that make one do not.
  *
@@ -78,42 +86,58 @@ function config() {
  * the exceptions — they hand the process over and never come back here.
  */
 const COMMANDS = {
-  run: async () => await run(config(), argv),
+  run: async () => await (await import("./commands/run.js")).run(config(), argv),
   // Non-zero when the policy cannot be enforced as written, so `seisin check`
   // composes in a pre-commit hook or CI the way `explain` and `scan` already do.
   // Warnings about a config that WILL work still exit 0 — failing on those
   // would make the command unusable within a week.
-  check: () => (check(config(), argv).warnings.some((w) => w.kind === "cannot-be-enforced") ? 1 : 0),
-  explain: () => (explainCommand(config(), argv).allowed ? 0 : 1),
-  scan: () => (scanCommand(config()).certain.length ? 1 : 0),
-  log: () => void log(config(), argv),
-  watch: () => void watch(config()),
-  init: () => void (argv.includes("--from-observations") ? initFromObservations(config()) : init()),
-  ui: () => ui(config(), argv),
-  whose: () => void whose(config(), argv),
-  wire: () => void wire(config()),
-  review: () => (reviewCommand(config(), argv).friction.length ? 1 : 0),
-  walls: () => (wallsCommand(config(), argv).length ? 1 : 0),
-  requests: () => (requests(config()).length ? 1 : 0),
-  grant: () => void grant(config(), argv),
+  check: async () => {
+    const report = await (await import("./commands/check.js")).check(config(), argv);
+    return (await import("./commands/check.js")).checkStatus(report);
+  },
+  explain: async () => ((await import("./commands/explain.js")).explainCommand(config(), argv).allowed ? 0 : 1),
+  scan: async () => ((await import("./commands/scan.js")).scanCommand(config(), argv).certain.length ? 1 : 0),
+  log: async () => void (await import("./commands/log.js")).log(config(), argv),
+  watch: async () => void (await import("./commands/log.js")).watch(config()),
+  init: async () => {
+    const { init, initFromObservations } = await import("./commands/init.js");
+    void (argv.includes("--from-observations") ? initFromObservations(config()) : init(process.cwd(), { force: argv.includes("--force") }));
+  },
+  // --link only reads a record; it answers without a policy here too, and
+  // says so when the console it finds serves another one.
+  ui: async () => (await import("./commands/ui.js")).ui(argv.includes("--link") ? maybeConfig() : config(), argv),
+  whose: async () => void (await import("./commands/whose.js")).whose(config(), argv),
+  wire: async () => void (await import("./commands/wire.js")).wire(config()),
+  review: async () => ((await import("./commands/review.js")).reviewCommand(config(), argv).friction.length ? 1 : 0),
+  walls: async () => ((await import("./commands/walls.js")).wallsCommand(config(), argv).some((w) => !w.expected) ? 1 : 0),
+  requests: async () => ((await import("./commands/requests.js")).requests(config(), argv).length ? 1 : 0),
+  grant: async () => void (await import("./commands/requests.js")).grant(config(), argv),
   /**
    * A person DECLINES a request; the boundary DENIES a write. One word each,
-   * because they are opposite events and `deny` used to name both — a queue
+   * because they are opposite events and one word used to name both — a queue
    * entry said `first refused on …` (the kernel) and the answer said
-   * `refused frontend ✕ …` (you).
-   *
-   * `deny` stays and is not documented. Renaming a published command over a
-   * word is not worth breaking somebody's script; teaching the new one is.
+   * `refused frontend ✕ …` (you). The old command is gone (see RETIRED).
    */
-  decline: () => void deny(config(), argv),
-  deny: () => void deny(config(), argv),
+  decline: async () => void (await import("./commands/requests.js")).decline(config(), argv),
   mcp: async () => {
-    await serveMcp(version());
+    await (await import("./mcp.js")).serveMcp(version());
     return 0;
   },
+  // Always 0. Claude Code reads a non-zero exit from a PreToolUse hook as
+  // "block", so an internal error here would stop the agent's tool call — and
+  // the hook explains, it never enforces. The error goes to stderr instead.
   hook: async () => {
-    const decision = await hook();
-    if (decision?.hookSpecificOutput) out(JSON.stringify(decision) + "\n");
+    try {
+      const decision = await (await import("./commands/hook.js")).hook();
+      // Only what the hook protocol defines. `decision` and `logged` are for the
+      // callers inside seisin; Codex validates a hook's output against a schema
+      // that admits no other field (and `decision` only as approve|block), and
+      // drops the whole answer when it does not fit — measured 2026-09-30 with
+      // codex 0.150.1: the deny was ignored and the command ran into the kernel.
+      if (decision?.hookSpecificOutput) out(JSON.stringify({ hookSpecificOutput: decision.hookSpecificOutput }) + "\n");
+    } catch (e) {
+      err(`seisin hook: ${e?.message ?? e} — no decision, the tool call goes ahead\n`);
+    }
     return 0;
   },
   "--version": () => void out(version() + "\n"),
@@ -124,16 +148,115 @@ function version() {
   return JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
 }
 
-const chosen = COMMANDS[command];
+/**
+ * `--help` is a question, never an instruction to do the thing.
+ *
+ * No command looked for it, so each one took it as an argument: `ui --help`
+ * started a server on 4178, `wire --help` wrote .claude/settings.json, `watch
+ * --help` followed the log until ctrl-c, `mcp --help` sat waiting on stdin, and
+ * `seisin --help` printed the usage and exited 2. Answered here, before any
+ * command is loaded or any policy read, so it works in a directory with none.
+ *
+ * Only seisin's own part of the line is searched: after `--` the words are the
+ * agent's, and so is everything after `run <role> <command>` without one —
+ * `seisin run dev -- ls --help` asks `ls`. The value of a flag that takes one
+ * (`--reason -h`) is a value.
+ */
+const HELP = new Set(["--help", "-h"]);
+function asksHelp(name, args) {
+  const takesValue = new Set(flagsOf(name)?.values ?? []);
+  const split = args.indexOf("--");
+  let ours = split === -1 ? args : args.slice(0, split);
+  if (name === "run" && split === -1) {
+    let i = 1;
+    while (i < args.length && args[i].startsWith("-")) i += takesValue.has(args[i]) ? 2 : 1;
+    ours = args.slice(0, i);
+  }
+  for (let i = 0; i < ours.length; i++) {
+    if (takesValue.has(ours[i])) i++;
+    else if (HELP.has(ours[i])) return true;
+  }
+  return false;
+}
+
+/** One command's help: its flags, examples and exit codes, or the whole usage. */
+function helpFor(name) {
+  if (COMMAND_HELP[name]) return renderHelp(name, C);
+  const lines = USAGE.split("\n").filter((l) => l.startsWith(`  seisin ${name} `) || l === `  seisin ${name}`);
+  if (!lines.length) return USAGE;
+  return `\nusage:\n${lines.join("\n")}\n\n  ${C.dim}seisin --help for every command${C.off}\n\n`;
+}
+
+// The standing limits: the same for every repo, so they are help, not `check`.
+if (command === "help" && argv[0] === "limits") {
+  out(renderLimits(C));
+  process.exit(0);
+}
+if (command === undefined || command === "help" || HELP.has(command)) {
+  const about = command === "help" && COMMANDS[argv[0]] && !argv[0].startsWith("-") ? argv[0] : null;
+  out(about ? helpFor(about) : USAGE);
+  process.exit(0);
+}
+
+/**
+ * Commands that were renamed, and what to type now. Not aliases: the old name
+ * runs nothing, so a script that calls it stops and says what changed rather
+ * than doing the right thing under the wrong word for ever.
+ */
+const RETIRED = {
+  deny: `"seisin deny" was removed in 0.6.0: a person declines, the boundary denies.\n` +
+    `  Use seisin decline <n|id> [--reason "…"] — same arguments, same effect.`,
+};
+
+const chosen = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : null;
+if (!chosen && Object.hasOwn(RETIRED, command)) {
+  err(`${C.red}seisin:${C.off} ${RETIRED[command]}\n`);
+  process.exit(2);
+}
 if (!chosen) {
-  out(USAGE);
-  process.exit(command ? 2 : 0);
+  // One line, and the nearest command. The whole usage, printed for a typo,
+  // pushed the one line that mattered off the screen.
+  const near = command.startsWith("-") ? nearest(command, ["--help", "--version"])
+    : nearest(command, Object.keys(COMMANDS).filter((c) => !c.startsWith("-")));
+  err(`${C.red}seisin:${C.off} unknown ${command.startsWith("-") ? "option" : "command"} "${command}"` +
+    `${near ? ` — did you mean "${near}"?` : ""}\n  seisin --help lists every command\n`);
+  process.exit(2);
+}
+if (!command.startsWith("-") && asksHelp(command, argv)) {
+  out(helpFor(command));
+  process.exit(0);
 }
 
 try {
+  refuseUnknownFlags(command, argv);
   const code = await chosen();
   if (typeof code === "number") process.exit(code);
 } catch (e) {
   err(`${C.red}seisin:${C.off} ${e.message}\n`);
-  process.exit(2);
+  // A command that was not found is 127 wherever a shell runs it; everything
+  // else seisin refuses is a usage or policy error.
+  process.exit(e.exitCode ?? 2);
+}
+
+/**
+ * A flag a command does not take is an error, never ignored: `check --verbsoe`
+ * printed the short map as if nothing had been asked. For `run`, only seisin's
+ * own part of the line — before `--`, or the leading options — is checked.
+ */
+function refuseUnknownFlags(name, args) {
+  const f = flagsOf(name);
+  if (!f || name === "hook" || name === "mcp") return;
+  let ours = args;
+  if (name === "run") {
+    const split = args.indexOf("--");
+    if (split !== -1) ours = args.slice(1, split);
+    else {
+      let i = 1;
+      // Every flag that takes a value, from the one table: listing them here by
+      // hand left `--handoff` out, so its id was checked as a flag of its own.
+      while (i < args.length && args[i].startsWith("-")) i += f.values.includes(args[i]) ? 2 : 1;
+      ours = args.slice(1, i);
+    }
+  }
+  checkFlags(name, ours, f.known, f.values);
 }