seisin 0.4.0 → 0.5.0

package/src/controls.js

@@ -0,0 +1,244 @@
+/**
+ * Handing a role a family of control files, and protecting instruction files,
+ * as edits a person makes from the console.
+ *
+ * Both settings were only reachable by opening seisin.toml in an editor. That
+ * is fine for whoever wrote the policy and a wall for whoever inherited it:
+ * the console showed the refusal ("protected: .vscode, whose settings … VS
+ * Code applies outside the sandbox") and offered no way to act on it except
+ * approving a request that a grant can never satisfy (refuseIfBarred says so).
+ *
+ * What this module does not do is widen the menu. The families are exactly
+ * config.js's CONTROL_FAMILIES; `.claude/`, git hooks, `.mcp.json` and `.envrc`
+ * are never offered, because they are what a program outside the sandbox executes
+ * and no role writes them — not from the file, not from here.
+ *
+ * Every edit is text, bounded to one table, like applyGrant: comments and the
+ * order a person gave the file survive, and a change for one role can never
+ * land in another role's table.
+ */
+import { createHash } from "node:crypto";
+import { loadConfig, CONTROL_FAMILIES, stripComment, closesArray } from "./config.js";
+import { settingsFor } from "./srt.js";
+import { denyFor } from "./surface.js";
+import { cleanReason } from "./requests.js";
+
+const RE_HEADER = /^\[([A-Za-z0-9_.\-]+)\]$/;
+const RE_KEY = /^([A-Za-z0-9_\-]+)\s*=/;
+
+/** An error that is the caller's fault: the server answers it with 400. */
+function bad(message) {
+  return Object.assign(new Error(message), { status: 400 });
+}
+
+export const hashOf = (text) => createHash("sha256").update(text).digest("hex").slice(0, 24);
+
+/**
+ * The families as the caller sent them, validated and in the canonical order.
+ *
+ * Refused, not filtered: a request for ".claude" is somebody asking for the
+ * one thing this tool will not hand out, and silently dropping it would save a
+ * policy that is not what they asked for.
+ */
+export function normalizeFamilies(families) {
+  if (!Array.isArray(families) || families.some((f) => typeof f !== "string"))
+    throw bad(`families must be a list of names — some of ${CONTROL_FAMILIES.map((f) => JSON.stringify(f)).join(", ")}`);
+  for (const f of families)
+    if (!CONTROL_FAMILIES.includes(f))
+      throw bad(`${JSON.stringify(f)} is not a family of control files. Known: ` +
+        `${CONTROL_FAMILIES.map((x) => JSON.stringify(x)).join(", ")}. The others ` +
+        `(.claude, git hooks, .mcp.json, .envrc) are never handed to a role.`);
+  return CONTROL_FAMILIES.filter((f) => families.includes(f));
+}
+
+/**
+ * The lines of one table: where its header is, where it ends, and each
+ * key's first and last line. A multi-line array is one key, so a line inside
+ * one is never taken for a header or for another key.
+ */
+function tableOf(lines, name) {
+  let header = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const h = RE_HEADER.exec(stripComment(lines[i]).trim());
+    if (h && h[1] === name) { header = i; break; }
+  }
+  if (header === -1) return null;
+  const keys = [];
+  let end = lines.length;
+  for (let i = header + 1; i < lines.length; i++) {
+    const line = stripComment(lines[i]).trim();
+    if (!line) continue;
+    if (RE_HEADER.test(line)) { end = i; break; }
+    const k = RE_KEY.exec(line);
+    if (!k) continue;
+    const from = i;
+    const value = line.slice(line.indexOf("=") + 1).trim();
+    if (value.startsWith("[") && !closesArray(value))
+      while (i + 1 < lines.length && !closesArray(stripComment(lines[++i]).trim()));
+    keys.push({ key: k[1], from, to: i });
+  }
+  return { header, end, keys };
+}
+
+function stamp(note) {
+  return `# set in the console ${new Date().toISOString().slice(0, 10)}` +
+    (note ? ` · «${cleanReason(note)}»` : "");
+}
+
+/**
+ * Sets `key = value` inside one table: replaces the line (or the lines, for a
+ * multi-line array) where the key was, or adds it after the table's last key.
+ * The replaced line's own trailing comment goes with it — it described the
+ * value being replaced, and the stamp now describes the new one. Every other
+ * line, comments included, stays byte for byte.
+ */
+function setKey(text, table, key, value, note) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split("\n");
+  const cr = eol === "\r\n" ? "\r" : "";
+  const t = tableOf(lines, table);
+  if (!t) return null;
+  const at = t.keys.find((k) => k.key === key);
+  if (at) {
+    // The same value is no edit: re-stamping it would record a decision
+    // nobody made, and move the date of the one somebody did.
+    const was = lines.slice(at.from, at.to + 1).map((l) => stripComment(l).trim()).join(" ");
+    if (was.slice(was.indexOf("=") + 1).replace(/\s+/g, "").replace(/,\]$/, "]") === value.replace(/\s+/g, "")) return text;
+    const indent = /^\s*/.exec(lines[at.from])[0];
+    const line = `${indent}${key} = ${value}   ${stamp(note)}${cr}`;
+    lines.splice(at.from, at.to - at.from + 1, line);
+  } else {
+    // After the last key, not the last line: a comment above the next table
+    // belongs to that table, and a line inserted under it would read as the
+    // next role's.
+    const after = t.keys.length ? t.keys[t.keys.length - 1].to : t.header;
+    lines.splice(after + 1, 0, `${key} = ${value}   ${stamp(note)}${cr}`);
+  }
+  return lines.join("\n");
+}
+
+const listOf = (families) => `[${families.map((f) => `"${f}"`).join(", ")}]`;
+
+/**
+ * The policy text with `control_files` of one role set to `families`.
+ *
+ * An empty list is written as `control_files = []` with its stamp when the key
+ * was there, rather than deleted: the line is the record that somebody took
+ * the family away, and when. A role that never had the key and still has none
+ * is left alone.
+ */
+export function applyControlFiles(toml, role, families, note = "") {
+  const want = normalizeFamilies(families);
+  const lines = toml.split("\n");
+  const t = tableOf(lines, `roles.${role}`);
+  if (!t) throw bad(`no [roles.${role}] section in the policy`);
+  if (!want.length && !t.keys.some((k) => k.key === "control_files")) return { toml, changed: false };
+  const out = setKey(toml, `roles.${role}`, "control_files", listOf(want), note);
+  return { toml: out, changed: out !== toml };
+}
+
+/**
+ * The policy text with `[protect] instructions` set.
+ *
+ * A missing `[protect]` table is created only to turn the protection on
+ * (off is the default and needs no line), and it goes above the first role:
+ * it is a setting about every role, and a reader meets it before the roles
+ * it changes. A comment block that sits directly above that role stays with
+ * the role.
+ */
+export function applyProtect(toml, on, note = "") {
+  if (typeof on !== "boolean") throw bad("protect must be true or false");
+  const lines = toml.split("\n");
+  if (tableOf(lines, "protect")) {
+    const out = setKey(toml, "protect", "instructions", String(on), note);
+    return { toml: out, changed: out !== toml };
+  }
+  if (!on) return { toml, changed: false };
+  const cr = toml.includes("\r\n") ? "\r" : "";
+  let at = lines.findIndex((l) => /^roles\./.test(RE_HEADER.exec(stripComment(l).trim())?.[1] ?? ""));
+  const block = [`[protect]${cr}`, `instructions = true   ${stamp(note)}${cr}`, cr];
+  if (at === -1) {
+    // Unreachable for a policy that loads (it has roles), kept total anyway.
+    const sep = toml.endsWith("\n") || !toml ? "" : "\n";
+    return { toml: `${toml}${sep}\n${block[0]}\n${block[1]}\n`, changed: true };
+  }
+  while (at > 0 && /^\s*#/.test(lines[at - 1])) at--;
+  lines.splice(at, 0, ...block);
+  return { toml: lines.join("\n"), changed: true };
+}
+
+/** Which roles may write each family after the edit. `null`: nothing protects it. */
+export function accessOf(config) {
+  const roles = Object.values(config.roles);
+  return {
+    ide: roles.filter((r) => r.controlFiles.includes("ide")).map((r) => r.name),
+    instructions: config.protect?.instructions
+      ? roles.filter((r) => r.controlFiles.includes("instructions")).map((r) => r.name)
+      : null,
+  };
+}
+
+/** A role's denyWrite, each entry with the reason denyFor gives for it. */
+function deniesOf(config, name) {
+  const why = new Map();
+  try { for (const e of denyFor(config, config.roles[name])) why.set(e.path, e.why); } catch {}
+  const list = settingsFor(config, name).filesystem?.denyWrite ?? [];
+  return new Map(list.map((p) => [p, why.get(p) ?? "never_writes, or a runtime default"]));
+}
+
+/**
+ * What the edit changes in each role's sandbox profile, by denyWrite entry.
+ *
+ * Computed from the two policies as `seisin run` would build them — settingsFor
+ * over the text before and the text after — never from a description of the
+ * families. A role whose territory holds no project where these files could
+ * be gets an empty diff, and that is the honest answer: the toggle changes
+ * nothing for it today.
+ */
+export function profileDiff(before, after, names) {
+  return names.map((name) => {
+    try {
+      const a = deniesOf(before, name);
+      const b = deniesOf(after, name);
+      return {
+        role: name,
+        added: [...b].filter(([p]) => !a.has(p)).map(([path, why]) => ({ path, why })),
+        removed: [...a].filter(([p]) => !b.has(p)).map(([path, why]) => ({ path, why })),
+      };
+    } catch (e) {
+      return { role: name, error: e.message, added: [], removed: [] };
+    }
+  });
+}
+
+/**
+ * One edit, described without writing it: the new text, and what it changes.
+ *
+ * The new text is loaded with the real loader against the real root, so an
+ * edit that would leave a policy that no longer loads is refused here, before
+ * anything is written.
+ */
+export function planEdit(config, text, edit) {
+  let result;
+  if (edit.kind === "role") {
+    if (typeof edit.role !== "string" || !Object.hasOwn(config.roles, edit.role))
+      throw bad(`unknown role ${JSON.stringify(edit.role)}`);
+    result = applyControlFiles(text, edit.role, edit.families, edit.reason);
+  } else {
+    result = applyProtect(text, edit.on, edit.reason);
+  }
+  let after;
+  try { after = loadConfig(config.path, result.toml); }
+  catch (e) { throw bad(`the edited policy would not load, so nothing was written: ${e.message}`); }
+  const names = edit.kind === "role" ? [edit.role] : Object.keys(config.roles);
+  const diff = result.changed ? profileDiff(config, after, names).filter((d) => d.error || d.added.length || d.removed.length) : [];
+  return {
+    changed: result.changed,
+    toml: result.toml,
+    base: hashOf(text),
+    diff,
+    access: accessOf(after),
+    protect: { instructions: after.protect.instructions },
+    ...(edit.kind === "role" && { role: edit.role, controlFiles: after.roles[edit.role].controlFiles }),
+  };
+}

package/src/diagnose.js

@@ -2,10 +2,10 @@
  * The refusal the agent never heard, said after the fact.
  *
  * PreToolUse sees the path a tool call names, and that is all it sees. What the
- * kernel refuses on its own — a child process, `/bin/rm` inside a script, a
+ * kernel denies on its own — a child process, `/bin/rm` inside a script, a
  * path the regex did not catch — reaches the agent as `Operation not permitted`
- * with no path and no reason, and it retries. Measured on a real portfolio from
- * 2026-09-14 to 2026-09-22: 5,617 refusals, all of them from the kernel, 72%
+ * with no path and no reason, and it retries. Measured on a multi-repo workspace from
+ * 2026-09-14 to 2026-09-22: 5,617 denials, all of them from the kernel, 72%
  * the same role hitting the same path again.
  *
  * Two hooks close that, the shape nono uses for its sandbox diagnostics:
@@ -15,7 +15,7 @@
  *     refusals from the last moments and hand the agent the same sentence the
  *     PreToolUse hook would have — whose it is, how many times, and that it
  *     should hand it over rather than retry. The kernel's line reaches the log
- *     about 30 ms after the refusal (measured inside the box), so this reads it.
+ *     about 30 ms after the refusal (measured inside the sandbox), so this reads it.
  *   - when a session starts, resumes or is compacted (SessionStart): the role's
  *     territory and what it keeps being refused, before the first refusal —
  *     and right after compaction, which is when an agent forgets what it was
@@ -28,7 +28,7 @@
  * On Linux the runtime's refusals cannot be read from outside (violations.js),
  * so the after-the-fact half finds nothing there and stays quiet.
  */
-import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { readEntries } from "./log.js";
 import { explain } from "./owners.js";
 import { timesHit, walls } from "./walls.js";
 import { collapseSidecars } from "./render.js";
@@ -64,37 +64,16 @@ export function knownRefusals(evidence) {
 
 /** How far back a refusal still belongs to the call that just failed. */
 const WINDOW_MS = 120_000;
-/** Read only the end of the log: this runs on every failed command. */
+/** Read only the end of the log: this runs on every failed command. The line the cut lands in is dropped (readLines). */
 const TAIL_BYTES = 512 * 1024;
 /** How many paths to name. More than this is a wall of text nobody acts on. */
 const MAX_NAMED = 3;
 
-function tail(file) {
-  if (!existsSync(file)) return [];
-  const { size } = statSync(file);
-  const from = Math.max(0, size - TAIL_BYTES);
-  const fd = openSync(file, "r");
-  try {
-    const buf = Buffer.alloc(size - from);
-    readSync(fd, buf, 0, buf.length, from);
-    const lines = buf.toString("utf8").split("\n");
-    if (from > 0) lines.shift();          // the first line is cut in half
-    const out = [];
-    for (const l of lines) {
-      if (!l.trim()) continue;
-      try { out.push(JSON.parse(l)); } catch { /* a line being written */ }
-    }
-    return out;
-  } finally {
-    closeSync(fd);
-  }
-}
-
 /** This role's refusals by the kernel since `sinceMs`, one per path, newest first. */
 export function recentKernelDenials(file, role, sinceMs) {
   const since = new Date(sinceMs).toISOString();
   const seen = new Map();
-  for (const e of tail(file).reverse()) {
+  for (const e of readEntries(file, { tail: TAIL_BYTES }).reverse()) {
     if (e.role !== role || e.verdict !== "denied" || e.source !== "kernel") continue;
     if (!e.at || e.at < since || !e.target) continue;
     const k = `${e.action}\u0000${e.target}`;
@@ -118,22 +97,45 @@ function sentence(config, role, file, e) {
 }
 
 const PREFACE =
-  "seisin — the sandbox this agent runs in — refused part of that. This is not a Unix permission " +
+  "The sandbox this agent runs in, set up by seisin, denied part of that. This is not a Unix permission " +
   "or a macOS privacy prompt: chmod, sudo or a different path to the same file will not change it.";
 
+/**
+ * What the tool said, and whether it said it failed.
+ *
+ * PostToolUseFailure is a failure by definition, and its evidence is all of it.
+ * PostToolUse is a Bash result, and most of those are successes: a command that
+ * prints "Permission denied" to stdout — a grep through logs, a test that
+ * checks for it — used to pay the full retry schedule (413 ms measured) to
+ * find nothing. So there, only stderr counts, and only an explicit failure
+ * (a non-zero exit code, or `is_error`) is a reason to wait for the kernel.
+ * A success with the words on stderr — `cmd; true` swallowed the status —
+ * still gets one look at the log, just not the waits.
+ */
+function evidenceOf(event) {
+  if (event.hook_event_name !== "PostToolUse")
+    return { text: JSON.stringify({ r: event.tool_response, e: event.error, o: event.tool_output }), failed: true };
+  const r = event.tool_response;
+  if (typeof r === "string") return { text: JSON.stringify(r), failed: false };
+  const code = r?.exit_code ?? r?.exitCode ?? r?.code;
+  const failed = r?.is_error === true || (typeof code === "number" && code !== 0);
+  return { text: JSON.stringify(typeof r?.stderr === "string" ? r.stderr : ""), failed };
+}
+
 /**
  * After a tool call failed. Returns the hook output, or null to say nothing.
  *
  * `wait` retries the read a few times: the kernel's line lands ~30 ms after the
- * refusal, and a loaded machine can be slower than the hook.
+ * refusal, and a loaded machine can be slower than the hook. Only when the tool
+ * reported a failure — see {@link evidenceOf}.
  */
 export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300] } = {}) {
-  const evidence = JSON.stringify({ r: event.tool_response, e: event.error, o: event.tool_output });
+  const { text: evidence, failed } = evidenceOf(event);
   if (!DENIAL_SIGNS.test(evidence)) return null;
   // JSON escapes what the program printed; the signatures are written against the text.
   const known = knownRefusals(evidence.replace(/\\n/g, "\n").replace(/\\"/g, '"'));
   let found = [];
-  for (const ms of wait) {
+  for (const ms of failed ? wait : [0]) {
     if (ms) await new Promise((ok) => setTimeout(ok, ms));
     found = recentKernelDenials(file, role, now() - WINDOW_MS);
     if (found.length) break;
@@ -163,7 +165,7 @@ export function atSessionStart(config, role, event, { file } = {}) {
   if (r.keys.length) lines.push(`Keys you hold: ${r.keys.join(", ")}.`);
   const w = file ? walls(config, role, { file, limit: 5, fresh: true }) : [];
   if (w.length) {
-    lines.push("Already refused more than once, and still refused — do not try again, hand it over:");
+    lines.push("Already denied more than once, and still denied — do not try again, hand it over:");
     for (const x of w)
       lines.push(`- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`);
   }

package/src/env.js

@@ -39,8 +39,8 @@ export const BASE = [
  * needs **set**, not forwarded.
  *
  * `GIT_OPTIONAL_LOCKS=0` is the whole list, and it is here because of what the
- * denial log looks like without it. Measured on a real portfolio: of the last
- * 60 refusals, **58 were `.git/index.lock`** — 97% — and most carried no owner
+ * denial log looks like without it. Measured on a multi-repo workspace: of the last
+ * 60 denials, **58 were `.git/index.lock`** — 97% — and most carried no owner
  * at all, so not one of them was a territory question. `git status` and
  * `git diff` refresh the index as a courtesy, refreshing it takes the lock, and
  * a role reading a repo it does not own trips the boundary while doing nothing
@@ -64,7 +64,7 @@ export const DEFAULTS = {
   GIT_OPTIONAL_LOCKS: "0",
   /**
    * Node's built-in `fetch()` ignores HTTP_PROXY/HTTPS_PROXY unless told
-   * otherwise, so inside the box it tries DNS directly and dies with ENOTFOUND
+   * otherwise, so inside the sandbox it tries DNS directly and dies with ENOTFOUND
    * while `npm`, which reads the proxy itself, works. Measured on Node 24.2:
    * ENOTFOUND without it, 200 with it. It only makes Node use the proxy the
    * sandbox already routes everything through — nothing is widened. Older
@@ -90,12 +90,15 @@ export const DEFAULTS = {
 };
 
 /**
- * Names that must never ride along, even if a role asks for them by pattern.
+ * Names that ride along only when the role names them itself.
  *
  * A role can name a variable explicitly and get it — that is the point of the
- * `env` list. What this blocks is a wildcard quietly sweeping up a credential,
- * which is how "pass through what the build needs" becomes "pass through
- * everything" three commits later.
+ * `env` list. Everything else that crosses comes from BASE or from a caller's
+ * `extra`, and this keeps a credential-shaped name out of both. Today it
+ * filters nothing: no BASE name matches it and `run` passes no `extra`. It is
+ * kept, not deleted, as the guard for the day either list grows — a
+ * `SSH_AUTH_SOCK` added "for git" would otherwise cross for every role
+ * silently — and for embedders who pass `extra`.
  */
 const NEVER = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|SESSION|COOKIE|PRIVATE)(_|$)/i;
 
@@ -118,7 +121,7 @@ export function buildEnv(parent, role, extra = []) {
     if (!wanted.has(name)) { dropped.push(name); continue; }
     if (NEVER.test(name) && !(role.env ?? []).includes(name)) { dropped.push(name); continue; }
     // Not even when named: whoever can read the notify URL can send the person
-    // a fake "approve #3". Only the parent uses it (notify.js).
+    // a fake "grant #3". Only the parent uses it (notify.js).
     if (name === "SEISIN_NOTIFY_URL") { dropped.push(name); continue; }
     env[name] = value;
   }

package/src/grants.js

@@ -14,11 +14,12 @@ import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { realpathSync, lstatSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { WILD } from "./paths.js";
 
 /**
  * What every agent needs to write no matter which role it is.
  *
- * Found by running a real cell config through the sandbox: territory alone
+ * Found by running a policy with 32 roles through the sandbox: territory alone
  * looks correct and is unusable. An agent writes its session state under its
  * own config directory and its tools write scratch files to the temp dir, so a
  * policy of "your folders and nothing else" stops the agent before it starts.
@@ -67,7 +68,7 @@ export function roleHomeRoot(config) {
    *
    * This was `base64url(root).slice(-16)` — the TAIL of the encoded path, which
    * is the tail of the path itself. Two checkouts that end the same way get the
-   * same id: `/Users/ana/dev/proyecto` and `/Users/bob/dev/proyecto` collide, and
+   * same id: `/Users/ana/dev/project` and `/Users/bob/dev/project` collide, and
    * so do `/home/a/work/api` and `/home/b/work/api`. A collision here is not a
    * cosmetic clash — both repos' role `dev` would share one HOME, which is the
    * session token of one handed to the other. Measured on three of four ordinary
@@ -145,10 +146,18 @@ export function isLink(p) {
   }
 }
 
-/** The path with symlinks followed, or the path itself if it is not on disk. */
+/**
+ * The path with symlinks followed, or the path itself if it is not on disk.
+ *
+ * `.native` is realpath(3): one call instead of an lstat per component, and on
+ * a case-insensitive disk (APFS) it answers with the case the disk has. The JS
+ * version keeps whatever case it was given, so `/users/x` and `/Users/x` —
+ * one directory — compared as two, and a path spelled the other way came out
+ * "outside the repo" while the kernel treated it as inside.
+ */
 export function realOrSelf(p) {
   try {
-    return realpathSync(p);
+    return realpathSync.native(p);
   } catch {
     return p;
   }
@@ -159,7 +168,7 @@ export function expand(p) {
   if (p === "$TMPDIR") out = tmpdir();
   else if (p === "~" || p.startsWith("~/")) out = join(homedir(), p.slice(2));
   try {
-    return realpathSync(out);
+    return realpathSync.native(out);
   } catch {
     return out; // not on disk yet; hand the literal through rather than drop it
   }
@@ -195,7 +204,6 @@ export function toWritePath(glob, key = "writes") {
  * prefixes, and "one level down" is not a prefix. Refusing is not a placeholder
  * here, it is the answer.
  */
-const WILD = /[*?[\]]/;                       // owners.js treats all four as wildcards
 const EXPRESSIBLE = (g) =>
   g === "**" ||                               // the whole repo
   !WILD.test(g) ||                            // a literal path
@@ -217,7 +225,7 @@ function unexpressible(glob, key = "writes") {
  * grants the whole repo, so `observe: true` answers for that case.
  *
  * `.seisin/` is deliberately NOT here. It used to be, because the hook runs
- * inside the box and has to record what it decided — which made the log and
+ * inside the sandbox and has to record what it decided — which made the log and
  * the queue writable by the process they are a record of. The hook now sends
  * its lines to the parent over a socket and the parent holds the file. See
  * spool.js.

package/src/help.js

@@ -0,0 +1,159 @@
+/**
+ * `seisin <command> --help` — one command's flags, examples and exit codes.
+ *
+ * The flags listed here are also the flags each command accepts: cli.js
+ * refuses any other, so a typo is an error instead of a question answered as
+ * if it had not been asked. One table, so the help and the check cannot
+ * disagree about what a command takes.
+ *
+ * `values` are flags that take the next word as their value.
+ */
+export const COMMAND_HELP = {
+  run: {
+    usage: ["seisin run <role> [--observe] [--debug-env] -- <command...>"],
+    flags: [
+      ["--observe", "open the repo for this run and record what the agent writes; keys and network stay shut"],
+      ["--debug-env", "print the environment variables the role does not get"],
+    ],
+    notes: ["Everything after -- is the command's own, flags included: `-- claude --settings x.json` goes to claude."],
+    examples: ['seisin run frontend -- claude', 'seisin run backend --observe -- claude -p "…"'],
+    exits: [["n", "the command's own exit status"], ["127", "the command is not on the role's PATH"],
+      ["128+n", "killed by signal n (130 for ctrl-c)"], ["2", "seisin could not start it (usage, policy, runtime)"]],
+  },
+  check: {
+    usage: ["seisin check [role] [--verbose]"],
+    flags: [["--verbose", "also print the protected paths, each warning's explanation and the standing limits"]],
+    examples: ["seisin check", "seisin check frontend --verbose"],
+    exits: [["0", "the policy can be enforced as written (warnings included)"], ["1", "a role cannot be enforced as written"], ["2", "usage or policy error"]],
+  },
+  explain: {
+    usage: ["seisin explain <role> read|write <path>", "seisin explain <role> read <key>", "seisin explain <role> mcp <server>"],
+    flags: [],
+    notes: ["A relative path is relative to the directory you are in."],
+    examples: ["seisin explain frontend write src/app.js", "seisin explain backend read stripe.txt", "seisin explain frontend mcp github"],
+    exits: [["0", "allowed"], ["1", "denied"], ["2", "usage error"]],
+  },
+  whose: {
+    usage: ["seisin whose <path>"],
+    flags: [],
+    notes: ["Safe to call from inside the sandbox. A relative path is relative to the directory you are in."],
+    examples: ["seisin whose backend/src/server.py"],
+    exits: [["0", "answered"], ["2", "usage error"]],
+  },
+  scan: {
+    usage: ["seisin scan [--all]"],
+    flags: [["--all", "walk the whole folder, not only where the territories are"]],
+    examples: ["seisin scan", "seisin scan --all"],
+    exits: [["0", "no certain credential outside the key dirs"], ["1", "at least one certain credential"], ["2", "usage error"]],
+  },
+  review: {
+    usage: ["seisin review [--all] [--min <n>]"],
+    values: ["--min"],
+    flags: [["--all", "every row, not the first ten per section"], ["--min <n>", "denials before a place counts as repeated (default 3)"]],
+    examples: ["seisin review", "seisin review --min 5 --all"],
+    exits: [["0", "no role denied repeatedly"], ["1", "a role was denied repeatedly"], ["2", "usage error"]],
+  },
+  walls: {
+    usage: ["seisin walls <role> [--all] [--since <iso>] [--min <n>]"],
+    values: ["--since", "--min"],
+    flags: [["--all", "include walls not hit in the last few runs"], ["--since <iso>", "only denials after this time"],
+      ["--min <n>", "times denied before it is a wall (default 2)"]],
+    examples: ["seisin walls frontend", "seisin walls frontend --since 2026-09-01 --min 3"],
+    exits: [["0", "no walls"], ["1", "walls listed"], ["2", "usage error"]],
+  },
+  wire: {
+    usage: ["seisin wire"],
+    flags: [],
+    notes: ["Writes .claude/settings.json in this repo, merged with what is there."],
+    examples: ["seisin wire"],
+    exits: [["0", "wired, or already wired"], ["2", "usage error, or settings.json is not valid JSON"]],
+  },
+  requests: {
+    usage: ["seisin requests"],
+    flags: [],
+    notes: ["#n is a position and shifts as requests are settled; the id under each one does not."],
+    examples: ["seisin requests"],
+    exits: [["0", "nothing pending"], ["1", "requests pending"], ["2", "usage error"]],
+  },
+  grant: {
+    usage: ['seisin grant <n|id> [--reason "…"]'],
+    values: ["--reason"],
+    flags: [['--reason "…"', "recorded beside the grant in the policy"]],
+    examples: ["seisin grant 1", "seisin grant 'frontend:write:docs' --reason \"owns the docs now\""],
+    exits: [["0", "granted, or already granted"], ["2", "no such request, or it cannot be granted"]],
+  },
+  decline: {
+    usage: ['seisin decline <n|id> [--reason "…"]'],
+    values: ["--reason"],
+    flags: [['--reason "…"', "recorded with the decision"]],
+    examples: ["seisin decline 2 --reason \"not frontend's key\""],
+    exits: [["0", "declined"], ["2", "no such request"]],
+  },
+  log: {
+    usage: ["seisin log [--role <r>] [--verdict allowed|denied|observed] [--limit <n>]", "seisin log verify"],
+    values: ["--role", "--verdict", "--limit"],
+    flags: [["--role <r>", "only this role"], ["--verdict <v>", "allowed, denied or observed"], ["--limit <n>", "how many entries (default 40)"]],
+    examples: ["seisin log --role frontend --verdict denied", "seisin log verify"],
+    exits: [["0", "printed; for verify, the hash chain holds"], ["1", "verify: the hash chain is broken"], ["2", "usage error"]],
+  },
+  watch: {
+    usage: ["seisin watch"],
+    flags: [],
+    examples: ["seisin watch"],
+    exits: [["0", "stopped with ctrl-c"], ["2", "usage error"]],
+  },
+  init: {
+    usage: ["seisin init [--force]", "seisin init --from-observations"],
+    flags: [["--force", "overwrite an existing seisin.toml, keeping the old one as seisin.toml.bak"],
+      ["--from-observations", "write seisin.toml.observed from what observed runs recorded"]],
+    examples: ["seisin init", "seisin init --from-observations"],
+    exits: [["0", "written"], ["2", "a policy is already there, or nothing was observed"]],
+  },
+  ui: {
+    usage: ["seisin ui [--port <n>] [--link]"],
+    values: ["--port"],
+    flags: [["--port <n>", "port on 127.0.0.1 (default 4178)"], ["--link", "print the link of a console already running, start nothing"]],
+    examples: ["seisin ui", "seisin ui --link"],
+    exits: [["0", "stopped"], ["2", "could not start"]],
+  },
+  mcp: {
+    usage: ["seisin mcp"],
+    flags: [],
+    notes: ["An MCP server on stdio, read-only: it can explain and draft, never grant."],
+    examples: ["claude mcp add seisin -- seisin mcp"],
+    exits: [["0", "stdin closed"]],
+  },
+  hook: {
+    usage: ["seisin hook"],
+    flags: [],
+    notes: ["Claude Code's hook: one event on stdin, a decision on stdout. `seisin wire` installs it."],
+    examples: [],
+    exits: [["0", "always — the hook explains, the kernel enforces"]],
+  },
+};
+COMMAND_HELP.deny = COMMAND_HELP.decline;
+
+/** The flag words a command accepts, for the unknown-flag check. */
+export function flagsOf(name) {
+  const h = COMMAND_HELP[name];
+  if (!h) return null;
+  const values = h.values ?? [];
+  const known = h.flags.map(([f]) => f.split(" ")[0]).filter((f) => !values.includes(f));
+  return { known, values };
+}
+
+/** The help for one command, as text. */
+export function renderHelp(name, C) {
+  const h = COMMAND_HELP[name];
+  const lines = ["", "usage:", ...h.usage.map((u) => `  ${u}`)];
+  if (h.flags.length) {
+    const w = Math.max(...h.flags.map(([f]) => f.length));
+    lines.push("", "flags:", ...h.flags.map(([f, d]) => `  ${f.padEnd(w)}  ${d}`));
+  }
+  if (h.notes?.length) lines.push("", ...h.notes.map((n) => `  ${n}`));
+  if (h.examples.length) lines.push("", "examples:", ...h.examples.map((e) => `  ${e}`));
+  const w = Math.max(...h.exits.map(([c]) => c.length));
+  lines.push("", "exit codes:", ...h.exits.map(([c, d]) => `  ${c.padEnd(w)}  ${d}`));
+  lines.push("", `  ${C.dim}seisin --help for every command${C.off}`, "", "");
+  return lines.join("\n");
+}