seisin 0.4.0 → 0.5.0

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 } 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,26 @@ ${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 check [role] [--verbose]       print the map, run nothing
+  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]                 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.
+
 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 +72,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,24 +85,29 @@ 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 () => ((await import("./commands/check.js")).check(config(), argv).warnings.some((w) => w.kind === "cannot-be-enforced") ? 1 : 0),
+  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).length ? 1 : 0),
+  requests: async () => ((await import("./commands/requests.js")).requests(config()).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
@@ -105,15 +117,22 @@ const COMMANDS = {
    * `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.
    */
-  decline: () => void deny(config(), argv),
-  deny: () => void deny(config(), argv),
+  decline: async () => void (await import("./commands/requests.js")).deny(config(), argv),
+  deny: async () => void (await import("./commands/requests.js")).deny(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();
+      if (decision?.hookSpecificOutput) out(JSON.stringify(decision) + "\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 +143,96 @@ 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"]);
+const TAKES_VALUE = new Set(["--port", "--role", "--verdict", "--limit", "--min", "--since", "--reason"]);
+
+function asksHelp(name, args) {
+  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++;
+    ours = args.slice(0, i);
+  }
+  for (let i = 0; i < ours.length; i++) {
+    if (TAKES_VALUE.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 alias = name === "deny" ? "decline" : name;
+  const lines = USAGE.split("\n").filter((l) => l.startsWith(`  seisin ${alias} `) || l === `  seisin ${alias}`);
+  if (!lines.length) return USAGE;
+  return `\nusage:\n${lines.join("\n")}\n\n  ${C.dim}seisin --help for every command${C.off}\n\n`;
+}
+
+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);
+}
+
+const chosen = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : null;
 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("-") && c !== "deny"));
+  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;
+      while (i < args.length && args[i].startsWith("-")) i++;
+      ours = args.slice(1, i);
+    }
+  }
+  checkFlags(name === "deny" ? "decline" : name, ours, f.known, f.values);
 }

package/src/commands/check.js

@@ -3,7 +3,8 @@ import { inspect } from "../inspect.js";
 import { renderReport, out } from "../render.js";
 
 export function check(config, argv = []) {
-  const report = inspect(config, argv[0] ?? null, config.path);
-  out(renderReport(report));
+  const role = argv.find((a) => !a.startsWith("-")) ?? null;
+  const report = inspect(config, role, config.path);
+  out(renderReport(report, { verbose: argv.includes("--verbose") }));
   return report;
 }

package/src/commands/explain.js

@@ -5,9 +5,11 @@
  * That is the only reason the exit code is not always 0 — a denial is an answer,
  * not a failure, but a shell has one channel for both.
  */
-import { toRepoRelative } from "../paths.js";
+import { toRepoRelative, fromCwd } from "../paths.js";
 import { isAbsolute } from "node:path";
-import { explain } from "../owners.js";
+import { explain, explainFileRead, readTarget } from "../owners.js";
+import { CREDENTIAL_HOMES, expand } from "../grants.js";
+import { unknownRole } from "../suggest.js";
 import { twinsOf, whereIs } from "../worktree.js";
 import { renderVerdict, C, out } from "../render.js";
 
@@ -15,7 +17,11 @@ export function explainCommand(config, argv = []) {
   const [role, action, target] = argv;
   if (!role || !action || !target)
     throw new Error("usage: seisin explain <role> <read|write|mcp> <path, key or MCP server>");
-  if (!config.roles[role]) throw new Error(`unknown role "${role}"`);
+  if (!config.roles[role]) throw unknownRole(config, role);
+  // Anything else used to be answered as a write, confidently, to a question
+  // nobody asked. An unknown action is a usage error, like an unknown flag.
+  if (!["read", "write", "mcp"].includes(action))
+    throw new Error(`unknown action "${action}" — use read, write or mcp`);
 
   if (action === "mcp") {
     const verdict = explain(config, role, "mcp", target);
@@ -23,7 +29,16 @@ export function explainCommand(config, argv = []) {
     return { ...verdict, worktree: [] };
   }
 
-  const verb = action.startsWith("r") ? "read" : "write";
+  const verb = action;
+
+  if (verb === "read") {
+    const asked = readTarget(config, target);
+    const verdict = asked.key
+      ? explain(config, role, "read", asked.target)
+      : explainFileRead(config, role, asked.target, CREDENTIAL_HOMES.map(expand));
+    out(renderVerdict(role, verb, asked.target, verdict));
+    return { ...verdict, worktree: [] };
+  }
 
   /**
    * An absolute path inside the repo is the same question as the relative one.
@@ -36,17 +51,23 @@ export function explainCommand(config, argv = []) {
    * check a boundary was the one that was wrong.
    *
    * Wrong in the direction that matters, too: it reported a path as unowned and
-   * refused while the kernel allowed it — see "Refusing beats widening" in
+   * denied while the kernel allowed it — see "Refusing beats widening" in
    * docs/decisions.md. A path outside the root is left exactly as written,
    * because that is a question about somewhere else and it still deserves its
    * honest "no owner".
    */
-  const asked = toRepoRelative(config, target);
+  //
+  // A relative path is relative to where you are standing, as in every other
+  // command line tool: from frontend/src, `app.js` is frontend/src/app.js. It
+  // was read against the policy's root, so the same question asked from a
+  // subdirectory came back "no owner". The answer prints the path the policy
+  // was asked about, so the reader sees which file was meant.
+  const asked = toRepoRelative(config, fromCwd(config, target));
 
   const verdict = explain(config, role, verb, asked);
-  out(renderVerdict(role, verb, target, verdict));
+  out(renderVerdict(role, verb, asked, verdict));
 
-  const worktree = verb === "write" ? elsewhere(config, role, target, verdict) : [];
+  const worktree = elsewhere(config, role, isAbsolute(target) ? target : asked, verdict);
   for (const w of worktree) out(renderElsewhere(w));
   return { ...verdict, worktree };
 }
@@ -55,7 +76,7 @@ export function explainCommand(config, argv = []) {
  * The same question, asked about the same file in the other checkouts.
  *
  * Only a twin that gets a DIFFERENT answer is worth a line. A worktree where
- * the role is equally allowed, or equally refused, changes nothing about what
+ * the role is equally allowed, or equally denied, changes nothing about what
  * was just printed, and a diagnosis that mentions it anyway is the noise this
  * tool keeps having to remove.
  *
@@ -73,7 +94,7 @@ function elsewhere(config, role, target, verdict) {
 
 /**
  * Three lines: where the other checkout is, what the answer is there, and
- * which of the two the policy names — the sentence the refusal never carried.
+ * which of the two the policy names — the sentence the denial never carried.
  */
 function renderElsewhere(t) {
   const there = t.verdict.allowed
@@ -82,12 +103,12 @@ function renderElsewhere(t) {
   const named = t.asked.allowed ? t.here : t;
   const other = t.asked.allowed ? t : t.here;
   // "allowed" is the answer that misleads, so it is the one that gets told
-  // where the refusal is. After "denied" that clause would only repeat it.
-  const refused = t.asked.allowed ? ` — a write in ${kind(other)} is refused` : "";
+  // where the denial is. After "denied" that clause would only repeat it.
+  const denied = t.asked.allowed ? ` — a write in ${kind(other)} is denied` : "";
   return (
     `  ${C.yellow}worktree${C.off}  ${t.where}\n` +
     `  ${C.dim}          the same file there is ${C.off}${C.b}${t.rel}${C.off}${C.dim}, and it ${there}.\n` +
-    `            The policy names ${kind(named)}, not ${kind(other)}${refused}.${C.off}\n\n`
+    `            The policy names ${kind(named)}, not ${kind(other)}${denied}.${C.off}\n\n`
   );
 }
 

package/src/commands/hook.js

@@ -4,7 +4,7 @@
  * Claude Code runs this once per tool call, so every path through it is short
  * and every failure is silent-and-permissive. That asymmetry is deliberate: the
  * hook explains, the kernel enforces. A hook that crashes should cost you an
- * explanation, never a blocked turn — and it cannot cost you a boundary,
+ * explanation, never a stopped tool call — and it cannot cost you a boundary,
  * because it was never the boundary.
  */
 import { findConfig, loadConfig } from "../config.js";
@@ -15,7 +15,7 @@ import { flush } from "../spool.js";
 
 export async function hook(stdin = process.stdin, env = process.env) {
   const role = env.SEISIN_ROLE;
-  if (!role) return null;            // not launched by seisin: say nothing, block nothing
+  if (!role) return null;            // not launched by seisin: say nothing, stop nothing
 
   let raw = "";
   for await (const chunk of stdin) raw += chunk;
@@ -24,7 +24,7 @@ export async function hook(stdin = process.stdin, env = process.env) {
   try {
     event = JSON.parse(raw || "{}");
   } catch {
-    return null;                     // an unreadable event is not grounds to block work
+    return null;                     // an unreadable event is not grounds to stop work
   }
 
   let config;
@@ -44,7 +44,17 @@ export async function hook(stdin = process.stdin, env = process.env) {
   if (event_ === "SessionStart") {
     try { return atSessionStart(config, role, event, { file: logPath(config.root) }); } catch { return null; }
   }
-  const decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1" });
+  // Caught like the two halves above, and for a sharper reason: PreToolUse is
+  // the one event where a crash is not silent. cli.js turns a throw into exit
+  // 2, and Claude Code reads exit 2 from this hook as "block the tool". A bug
+  // here would stop the agent's work — the one thing this command promises
+  // never to do. Said on stderr so the bug is still findable.
+  let decision = null;
+  try {
+    decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1" });
+  } catch (e) {
+    process.stderr.write(`seisin hook: ${e?.message ?? e} — no decision, the tool call goes ahead\n`);
+  }
   // The entries went to a socket, and cli.js exits as soon as we return. An
   // exit does not drain a socket, so the record would be lost precisely on the
   // turns that produced one.

package/src/commands/init.js

@@ -11,7 +11,7 @@
  * The second is better and needs a run first. Neither writes a policy you did
  * not read: `--from-observations` lands as `.observed`, not as the config.
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync, statSync, copyFileSync, appendFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { CONFIG_NAME, tomlString, tomlName } from "../layout.js";
 import { read, logPath, observed, generalise } from "../log.js";
@@ -22,43 +22,104 @@ import { C, out } from "../render.js";
  * actually means. None is a policy, so all of them are proposals.
  */
 export function discover(root) {
+  const keyDir = KEY_DIRS.find((d) => isDir(join(root, d))) ?? null;
   const agents = join(root, ".claude", "agents");
   if (existsSync(agents)) {
     const roles = readdirSync(agents)
       .filter((f) => f.endsWith(".md"))
       .map((f) => ({ name: f.replace(/\.md$/, ""), writes: [], keys: [] }));
-    if (roles.length) return { source: ".claude/agents/", roles };
+    if (roles.length) return { source: ".claude/agents/", roles, agents: roles.length, keyDir };
   }
 
   for (const p of ["CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"]) {
     const file = join(root, p);
     if (!existsSync(file)) continue;
-    const paths = readFileSync(file, "utf8")
-      .split(/\r?\n/)
-      .map((l) => l.replace(/#.*$/, "").trim())
-      .filter(Boolean)
-      .map((l) => l.split(/\s+/)[0])
-      .filter((g) => g && g !== "*");
-    if (paths.length)
-      return {
-        source: p,
-        roles: [...new Set(paths)].slice(0, 8).map((g, i) => ({
-          name: g.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "") || `role-${i + 1}`,
-          writes: [g.endsWith("/") ? g + "**" : g],
-          keys: [],
-        })),
-      };
+    const roles = fromCodeowners(readFileSync(file, "utf8"));
+    if (roles.length) return { source: p, roles, agents: 0, keyDir };
   }
 
+  const dirs = codeDirs(root);
   return {
-    source: "nothing to read — this is a blank start",
-    roles: [
-      { name: "frontend", writes: ["src/web/**"], keys: [] },
-      { name: "backend", writes: ["src/api/**"], keys: [] },
-    ],
+    source: dirs.length
+      ? "the top-level folders that hold code — one role each"
+      : "nothing to read — this is a blank start",
+    roles: dirs.length
+      ? dirs.map((d) => ({ name: roleName(d), writes: [`${d}/**`], keys: [] }))
+      : [{ name: "agent", writes: [], keys: [] }],
+    agents: 0,
+    keyDir,
   };
 }
 
+/** Where a repo keeps its keys by convention, in the order they are looked for. */
+const KEY_DIRS = [".secrets", "secrets", ".keys"];
+
+/**
+ * One role per owner, with every path that owner has.
+ *
+ * It was one role per LINE, named after the path, and cut at eight — so a
+ * team's ownership came back as eight roles called `apps-web`, `apps-api`… with
+ * the rest dropped and nothing said. An owner is the thing a role stands for.
+ * A line's first owner takes it: CODEOWNERS lets several share a path, and
+ * seisin would rather print one proposal a person corrects than invent an
+ * overlap. `*` is skipped — it is the fallback owner, not a territory.
+ */
+export function fromCodeowners(text) {
+  const byOwner = new Map();
+  for (const raw of text.split(/\r?\n/)) {
+    const [glob, owner] = raw.replace(/#.*$/, "").trim().split(/\s+/);
+    if (!glob || glob === "*" || !owner) continue;
+    // CODEOWNERS anchors a leading "/" at the repo root; seisin's writes
+    // are already repo-relative, so a literal "/apps/**" would ask the
+    // kernel for the machine's /apps and make `explain` (which reads it as
+    // outside the repo) disagree with what the profile grants. Strip the
+    // anchor. A trailing "/" means a directory, so it becomes "/**".
+    const rel = glob.replace(/^\/+/, "");
+    const path = rel.endsWith("/") ? rel + "**" : rel;
+    const name = roleName(owner.replace(/^@/, "").replace(/^.*\//, "")) || `role-${byOwner.size + 1}`;
+    const role = byOwner.get(name) ?? byOwner.set(name, { name, writes: [], keys: [] }).get(name);
+    if (!role.writes.includes(path)) role.writes.push(path);
+  }
+  return [...byOwner.values()];
+}
+
+const roleName = (s) => String(s).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+
+/**
+ * The top-level folders that hold code, for a repo that says nothing else.
+ *
+ * It proposed `src/web/**` and `src/api/**` whatever the repo looked like, so
+ * the first `check` was about folders that did not exist. Kept simple on
+ * purpose: a folder counts when some file under it (a few levels down) has a
+ * source extension. Dot-folders, dependencies and build output are skipped,
+ * and a folder of only documents or images proposes nothing — it is somebody's
+ * territory, but not the first thing a person wants to decide.
+ */
+const CODE = /\.(js|mjs|cjs|jsx|ts|tsx|py|rb|go|rs|java|kt|kts|swift|c|h|cc|cpp|hpp|cs|php|sh|sql|vue|svelte|astro|dart|scala|ex|exs|lua|pl|r|m|html|css|scss)$/i;
+const SKIP = new Set(["node_modules", "vendor", "dist", "build", "out", "target", "coverage", "__pycache__", "venv"]);
+
+function codeDirs(root) {
+  let top;
+  try { top = readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  return top
+    .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name) && roleName(e.name))
+    .map((e) => e.name)
+    .filter((d) => holdsCode(join(root, d), 4))
+    .sort();
+}
+
+function holdsCode(dir, depth) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  if (entries.some((e) => e.isFile() && CODE.test(e.name))) return true;
+  if (depth <= 1) return false;
+  return entries.some((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name) && holdsCode(join(dir, e.name), depth - 1));
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
 /** The proposed config, as TOML. Pure: takes what `discover` found. */
 export function renderConfig(found) {
   const lines = [
@@ -67,9 +128,14 @@ export function renderConfig(found) {
     `# Proposed from: ${found.source}`,
     "# Nothing here is enforced until you run the agent through `seisin run`.",
     "# Anything not listed is denied. There is no permissive default.",
+    "#",
+    "# Each role runs as its own process:  seisin run <role> -- <agent>",
+    "# A Claude Code subagent runs inside its parent's process, so it has its",
+    "# parent's role — give it its own by running it as its own `seisin run`.",
     "",
-    "# [keys]",
-    '# dir = ".secrets"      # every key lives here; roles name the files they may read',
+    ...(found.keyDir
+      ? ["[keys]", `dir = ${tomlString(found.keyDir)}      # every key lives here; roles name the files they may read`]
+      : ["# [keys]", '# dir = ".secrets"      # every key lives here; roles name the files they may read']),
     "",
     "[network]",
     "# The agent's own API comes first. Leave it out and the agent cannot even",
@@ -87,6 +153,7 @@ export function renderConfig(found) {
     "",
   ];
   for (const r of found.roles) {
+    if (!r.writes.length) lines.push("# writes nothing yet: add the folders this role owns, e.g. \"app/**\"");
     lines.push(`[roles.${tomlName(r.name)}]`);
     lines.push(`writes = [${r.writes.map(tomlString).join(", ")}]`);
     lines.push(`keys   = [${r.keys.map(tomlString).join(", ")}]`);
@@ -150,25 +217,54 @@ export function renderObserved(config, entries) {
   return { toml: lines.join("\n"), roles: roles.size };
 }
 
-export function init(cwd = process.cwd()) {
+export function init(cwd = process.cwd(), { force = false } = {}) {
   const target = join(cwd, CONFIG_NAME);
-  if (existsSync(target))
-    throw new Error(`${CONFIG_NAME} already exists here. Delete it first if you meant to start over.`);
+  const had = existsSync(target);
+  if (had && !force)
+    throw new Error(`${CONFIG_NAME} already exists here. seisin init --force replaces it, keeping the old one as ${CONFIG_NAME}.bak`);
 
   const found = discover(cwd);
+  if (had) copyFileSync(target, target + ".bak");
   writeFileSync(target, renderConfig(found));
+  const ignored = ignoreState(cwd);
   out(
     `\n  wrote ${C.b}${CONFIG_NAME}${C.off} with ${found.roles.length} role(s) from ${found.source}\n` +
-    `  ${C.dim}These are a proposal, not a policy. Read them before you run anything.${C.off}\n\n` +
-    `  next:  seisin check\n\n`
+    (had ? `  ${C.dim}the previous one is ${CONFIG_NAME}.bak${C.off}\n` : "") +
+    (found.keyDir ? `  ${C.dim}[keys] dir = "${found.keyDir}" — it is there, so it is declared${C.off}\n` : "") +
+    (ignored ? `  ${C.dim}added .seisin/ to .gitignore — the log and the request queue belong to this machine${C.off}\n` : "") +
+    `  ${C.dim}These are a proposal, not a policy. Read them before you run anything.${C.off}\n` +
+    // Said once, here, where someone with one agent decides whether to go on.
+    (found.agents <= 1
+      ? `  ${C.dim}one agent? its own sandbox covers most of this. seisin adds a built environment, a key dir no role reads\n` +
+        `  unless it is declared, and an owner named on every denial — it earns its setup at two roles.${C.off}\n`
+      : "") +
+    `\n  next:  seisin check\n\n`
   );
   return found;
 }
 
+/**
+ * `.seisin/` into the repo's .gitignore, when it has one and it is not there.
+ * The state directory is this machine's record; committed, every clone would
+ * start with somebody else's log and queue. No .gitignore, nothing written.
+ */
+function ignoreState(cwd) {
+  const file = join(cwd, ".gitignore");
+  if (!existsSync(file)) return false;
+  const text = readFileSync(file, "utf8");
+  if (/^\/?\.seisin\/?\s*$/m.test(text)) return false;
+  appendFileSync(file, `${text.endsWith("\n") || !text ? "" : "\n"}.seisin/\n`);
+  return true;
+}
+
 export function initFromObservations(config) {
   const entries = read(logPath(config.root), { verdict: "observed" });
   if (entries.length === 0)
-    throw new Error("nothing observed yet. Run: seisin run <role> --observe -- <command>");
+    throw new Error(
+      "nothing observed yet.\n" +
+      "  observations come from the hook: run `seisin wire` once, then observe an agent —\n" +
+      "    seisin run <role> --observe -- claude      (or codex, …)\n" +
+      "  a plain shell command goes through no hook and records nothing. keys stay denied while observing.");
 
   const { toml, roles } = renderObserved(config, entries);
   const file = join(config.root, CONFIG_NAME + ".observed");