seisin 0.4.2 → 0.6.0

package/src/commands/scan.js

@@ -3,18 +3,33 @@
  *
  * Exits 1 only on a `certain` finding. A `review` line is a prompt to look, and
  * failing a build on those would make the command unusable in CI within a week.
+ *
+ * Where it looks: the repository the policy is in, or — when the policy sits
+ * in a folder of repositories — the repositories its territories live in (see
+ * territoryRoots). `--all` walks the whole folder either way.
  */
-import { scan } from "../scan.js";
+import { relative } from "node:path";
+import { scan, insideRepo, territoryRoots } from "../scan.js";
+import { ownersOf } from "../owners.js";
 import { renderScan, out } from "../render.js";
 
-export function scanCommand(config) {
-  const { hits, skipped, truncated } = scan(config.root, config.keyDirs, config.scanIgnore);
+export function scanCommand(config, argv = []) {
+  const all = argv.includes("--all");
+  const roots = all || insideRepo(config.root) ? null : territoryRoots(config);
+  const { hits, skipped, nestedPaths, truncated, omitted } =
+    scan(config.root, config.keyDirs, config.scanIgnore, 500, { roots });
+  // Whose territory a finding is in: the role that will come across it first.
+  for (const h of hits) if (h.level !== "link") h.owners = ownersOf(config, h.file);
   const result = {
     certain: hits.filter((h) => h.level === "certain"),
+    named: hits.filter((h) => h.level === "named"),
     review: hits.filter((h) => h.level === "review"),
     links: hits.filter((h) => h.level === "link"),
     skipped,
+    nestedPaths,
     truncated,
+    omitted,
+    scope: roots ? roots.map((r) => relative(config.root, r) || ".") : null,
   };
   out(renderScan(result, config.keyDirs));
   return result;

package/src/commands/ui.js

@@ -14,7 +14,6 @@
  * failing. See uilink.js.
  */
 import { spawnSync } from "node:child_process";
-import { relative } from "node:path";
 import { serve } from "../serve.js";
 import { writeUiLink, readUiLink, clearUiLink } from "../uilink.js";
 import { C, out } from "../render.js";
@@ -33,7 +32,8 @@ export async function ui(config, argv = []) {
   if (argv.includes("--link")) {
     const found = readUiLink(port);
     if (found && found.alive !== false) {
-      out(`\n  ${C.b}${found.url}${C.off}\n  ${C.dim}the link a seisin ui on ${port} is serving. open it here, do not paste it anywhere.${C.off}\n\n`);
+      out(`\n  ${C.b}${found.url}${C.off}\n  ${C.dim}the link a seisin ui on ${port} is serving. open it here, do not paste it anywhere.${C.off}\n` +
+        servesWhich(found.policy, config?.path) + "\n");
       open(found.url);
       return;
     }
@@ -53,7 +53,8 @@ export async function ui(config, argv = []) {
       if (found && found.alive !== false) {
         out(
           `\n  ${C.b}${found.url}${C.off}\n` +
-          `  ${C.dim}a seisin ui is already running on ${port}; reopening its link. ctrl-c that terminal to stop it.${C.off}\n\n`
+          `  ${C.dim}a seisin ui is already running on ${port}; reopening its link. ctrl-c that terminal to stop it.${C.off}\n` +
+          servesWhich(found.policy, config.path) + "\n"
         );
         open(found.url);
         return;
@@ -69,7 +70,7 @@ export async function ui(config, argv = []) {
   const bound = server.address().port;
   const url = `http://127.0.0.1:${bound}/#t=${server.seisinToken}`;
   // Recorded before we print, so `--link` and a second `seisin ui` can find it.
-  writeUiLink(bound, url);
+  writeUiLink(bound, url, undefined, config.path);
 
   // local_binding opens every port (macOS); local_ports opens the ones it
   // names, on every platform — so only a role that names THIS port counts.
@@ -79,7 +80,7 @@ export async function ui(config, argv = []) {
 
   out(
     `\n  ${C.b}${url}${C.off}\n` +
-    `  ${C.dim}reading ${relative(process.cwd(), config.path)} and the log, live. ctrl-c to stop.${C.off}\n` +
+    `  ${C.dim}reading ${config.path} and the log, live. ctrl-c to stop.${C.off}\n` +
     `  ${C.dim}the link carries this run's token: open it here, do not paste it anywhere.${C.off}\n` +
     `  ${C.dim}lost it? this terminal has it above, or run: seisin ui --link${bound === 4178 ? "" : ` --port ${bound}`}${C.off}\n` +
     (reach.length
@@ -95,3 +96,15 @@ export async function ui(config, argv = []) {
   process.on("SIGTERM", stop);
   return server;
 }
+
+/**
+ * Which policy a running console serves, and a warning when it is not the one
+ * this directory would use. `here` is null when there is no policy here.
+ */
+export function servesWhich(served, here) {
+  if (!served) return `  ${C.dim}(started by an older seisin: which seisin.toml it serves is not recorded)${C.off}\n`;
+  if (here && served !== here)
+    return `  ${C.yellow}it serves ${served} — not ${here}, the policy for this directory.${C.off}\n` +
+      `  ${C.dim}for this one, start another: seisin ui --port <n>${C.off}\n`;
+  return `  ${C.dim}serving ${served}${C.off}\n`;
+}

package/src/commands/walls.js

@@ -1,30 +1,81 @@
-/** `seisin walls <role>` — what that role keeps being refused, and what it cost. */
-import { walls, render } from "../walls.js";
+/** `seisin walls <role>` — what that role keeps being denied, and what it cost. */
+import { unknownRole } from "../suggest.js";
+import { walls, wasted } from "../walls.js";
 import { STALE_RUNS } from "../requests.js";
 import { logPath } from "../log.js";
-import { out } from "../render.js";
+import { standingOf } from "../owners.js";
+import { kindsOf } from "../kinds.js";
+import { parseSince } from "../views.js";
+import { C, out, safe } from "../render.js";
 
 export function wallsCommand(config, argv = []) {
   const role = argv[0];
-  if (!role) throw new Error("usage: seisin walls <role> [--since <iso>] [--min <n>] [--all]");
-  if (!config.roles[role])
-    throw new Error(`unknown role "${role}". Known: ${Object.keys(config.roles).join(", ")}`);
+  if (!role) throw new Error("usage: seisin walls <role> [--since <date|duration>] [--min <n>] [--all]");
+  if (!config.roles[role]) throw unknownRole(config, role);
   const at = (flag, fallback) => {
     const i = argv.indexOf(flag);
     return i === -1 ? fallback : argv[i + 1];
   };
+  // The same reading of `--since` as review and the MCP: a date or `7d`.
+  const since = argv.includes("--since") ? parseSince(at("--since", null)) : null;
+  if (argv.includes("--since") && !since)
+    throw new Error(`--since takes a date (2026-10-01) or a duration back from now (7d, 12h, 2w), not "${safe(at("--since", "") ?? "")}"`);
   const every = walls(config, role, {
     file: logPath(config.root),
     min: Number(at("--min", 2)),
-    since: at("--since", null),
+    since,
     limit: 0,
   });
   const all = argv.includes("--all");
   const list = (all ? every : every.filter((w) => !w.stale)).slice(0, 6);
   const old = every.filter((w) => w.stale).length;
-  // Nothing to say prints nothing, the way `scan` does when a repo is clean.
-  // A command that always speaks is one whose output stops being read.
-  if (list.length) out(render(list));
+  const shown = withKinds(config, list);
+  if (shown.length) out(renderForPerson(role, shown));
+  else if (!every.length)
+    out(`\n  ${C.dim}${safe(role)} has no repeated denials in the recorded runs. A path becomes a wall after ${at("--min", 2)} denials.${C.off}\n\n`);
+  else if (!all)
+    out(`\n  ${C.dim}${safe(role)} has no recent walls; older ones are hidden. Use seisin walls ${safe(role)} --all.${C.off}\n\n`);
   if (old && !all) out(`  (${old} older wall(s) not hit in the last ${STALE_RUNS}+ runs: seisin walls ${role} --all)\n`);
-  return list;
+  return shown;
+}
+
+/**
+ * An unowned path gets the kind and hint the console gives it (kinds.js).
+ *
+ * The bare reason said "has no owner — no role can write it until one claims
+ * it" about `dist/` and `.env` alike: an invitation to give a build folder or a
+ * credential an owner, while the console said what kind of thing each was and
+ * what to do instead. Same classifier, same sentence, on both screens.
+ */
+function withKinds(config, list) {
+  const stand = standingOf(config);
+  const unowned = list.filter((w) => w.action === "write" && !w.owners?.length &&
+    stand({ kind: "file", target: w.target }).kind === "unowned");
+  const natures = kindsOf(unowned.map((w) => w.target), { keyDirs: config.keyDirs ?? [] });
+  return list.map((w) => (unowned.includes(w) ? { ...w, ...natures.get(w.target) } : w));
+}
+
+/**
+ * The same walls, said to the person at the terminal.
+ *
+ * `render` speaks to the agent — "you have already been denied these… do not
+ * retry" — because the hook and the MCP server put it in a prompt. Printed at
+ * a terminal, that voice addressed the person reading it as if they were the agent.
+ */
+export function renderForPerson(role, list) {
+  const lines = [`\n  ${C.b}${safe(role)}${C.off} keeps hitting:\n\n`];
+  for (const w of list) {
+    if (w.expected) {
+      lines.push(`    ${C.dim}${String(w.times).padStart(3)}×  ${w.action} ${safe(w.target)}  expected · ${safe(w.expected.hint)}${C.off}\n`);
+      continue;
+    }
+    const why = w.owners?.length ? `belongs to ${w.owners.map(safe).join(", ")}`
+      : w.kind ? `unowned · ${w.kind === "territory" ? "ownable" : w.kind}: ${safe(w.hint)}`
+      : safe(w.reason);
+    lines.push(`    ${C.yellow}${String(w.times).padStart(3)}×${C.off}  ${w.action} ${safe(w.target)}  ${C.dim}${why}${C.off}\n`);
+  }
+  const n = wasted(list);
+  if (n > 0) lines.push(`\n  ${C.dim}${n} of its calls went into retrying these.${C.off}\n`);
+  lines.push("\n");
+  return lines.join("");
 }

package/src/commands/whose.js

@@ -1,7 +1,7 @@
 /**
  * `seisin whose <path>` — the lookup a confined process is allowed to run.
  *
- * The README's opening claim is that a refusal names an owner. That is true
+ * The README's opening claim is that a denial names an owner. That is true
  * through the hook, and false for anyone who only wraps a process: the kernel
  * carries no reason, so the child sees `Operation not permitted` and guesses.
  * Measured in the field twice — an agent diagnosed a territory denial as
@@ -14,10 +14,11 @@
  *
  * It reads and prints. There is deliberately nothing here that could make it
  * worth attacking, because unlike everything else in this tool it is meant to
- * be called *from inside* the box.
+ * be called *from inside* the sandbox.
  */
-import { toRepoRelative } from "../paths.js";
+import { toRepoRelative, fromCwd } from "../paths.js";
 import { ownersOf, keyHolders } from "../owners.js";
+import { decideHandoff, nextStep, chainFromEnv } from "../handoff.js";
 import { twinsOf, whereIs } from "../worktree.js";
 import { C, out } from "../render.js";
 
@@ -25,7 +26,8 @@ export function whose(config, argv = []) {
   const target = argv[0];
   if (!target) throw new Error("usage: seisin whose <path>");
 
-  const rel = toRepoRelative(config, target);
+  // Relative to where you stand, like explain — see fromCwd.
+  const rel = toRepoRelative(config, fromCwd(config, target));
   const isKey = (config.keyDirs ?? []).some((d) => rel === d || rel.startsWith(d + "/"));
   const owners = isKey ? keyHolders(config, rel) : ownersOf(config, rel);
 
@@ -51,9 +53,9 @@ export function whose(config, argv = []) {
   out(
     `\n  ${C.b}${rel}${C.off} ${verb} ${C.b}${owners.join(", ")}${C.off}\n` +
     (mine
-      ? `  ${C.green}that is you${C.off}${C.dim} — if it was refused, the reason is not ownership.${C.off}\n\n`
+      ? `  ${C.green}that is you${C.off}${C.dim} — if it was denied, the reason is not ownership.${C.off}\n\n`
       : asking
-        ? `  ${C.dim}you are ${asking}. Hand it over rather than working around it.${C.off}\n\n`
+        ? `  ${C.dim}you are ${asking}. ${nextStep(decideHandoff({ request: { role: asking, action: isKey ? "read" : "write", target: rel }, config, chain: chainFromEnv() }), asking)}${C.off}\n\n`
         : "\n")
   );
   for (const w of worktree) out(renderElsewhere(w, asking));
@@ -64,7 +66,7 @@ export function whose(config, argv = []) {
  * The same file in the other checkouts of this repo, when it is owned
  * differently there.
  *
- * This is the line the EPERM was missing. An agent refused inside a worktree
+ * This is the line the EPERM was missing. An agent denied inside a worktree
  * asks whose the file is, hears "nobody", and concludes the map has a hole —
  * when the map is fine and names the canonical checkout. A twin owned exactly
  * the same way says nothing new and gets no line.

package/src/commands/wire.js

@@ -13,18 +13,76 @@
  * config: a permission tool that edits your machine's settings to install
  * itself has misread the room.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from "node:fs";
+import { join, dirname, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { C, out } from "../render.js";
+import { TOOL_MATCHER } from "../hook.js";
 
 const SETTINGS = join(".claude", "settings.json");
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
 
-/** Where the PreToolUse entry lives, and what it has to say. */
-export function hookEntry(command = "seisin hook") {
-  return {
-    matcher: "*",
-    hooks: [{ type: "command", command }],
-  };
+/** A hook command that is seisin's, however it was spelled when it was wired. */
+const isOurs = (c) => typeof c === "string" && /\bhook"?\s*$/.test(c) && (c.includes("seisin") || runsSeisinScript(c));
+
+/**
+ * A hook written by its full path (`"<node>" "<…>/src/cli.js" hook`) names no
+ * `seisin` when the checkout sits in a folder called something else. It is
+ * ours when the script it runs belongs to a package named seisin.
+ */
+function runsSeisinScript(command) {
+  const script = /"([^"]+\.js)"\s+hook\s*$/.exec(command)?.[1];
+  if (!script) return false;
+  try { return JSON.parse(readFileSync(join(dirname(script), "..", "package.json"), "utf8")).name === "seisin"; } catch { return false; }
+}
+
+/**
+ * The command that reaches THIS seisin from a hook, and how it was found.
+ *
+ * `seisin hook` was written for everyone. With seisin installed in a project
+ * rather than globally there is no `seisin` on PATH, the hook exits 127, and
+ * Claude Code carries on without it — nothing on screen, nothing in the log.
+ * So: the one on PATH when it is this version; the project's own
+ * node_modules/.bin when there is one; otherwise this file, by absolute path.
+ */
+export function hookCommand(root, { path = process.env.PATH, cli = CLI, version = ownVersion() } = {}) {
+  const found = (path ?? "").split(delimiter).map((d) => d && join(d, "seisin")).find((p) => p && existsSync(p));
+  let onPath = null;
+  if (found) {
+    const same = realOrSelf(found) === realOrSelf(cli);
+    const v = same ? version : spawnSync(found, ["--version"], { encoding: "utf8", timeout: 5000 }).stdout?.trim();
+    onPath = { at: found, version: v };
+    if (v === version) return { command: "seisin hook", via: "path", onPath };
+  }
+  const local = join(root, "node_modules", ".bin", "seisin");
+  if (existsSync(local)) return { command: '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/seisin hook', via: "local", onPath };
+  return { command: `"${process.execPath}" "${realOrSelf(cli)}" hook`, via: "absolute", onPath };
+}
+
+function ownVersion() {
+  try { return JSON.parse(readFileSync(join(dirname(CLI), "..", "package.json"), "utf8")).version; } catch { return null; }
+}
+
+/** Is `dir` inside a git checkout? Kept here so wire does not load the scanner. */
+function insideRepo(dir) {
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(join(d, ".git"))) return true;
+    if (dirname(d) === d) return false;
+  }
+}
+
+function realOrSelf(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+/** One sentence: which seisin the hook runs, and why that one. */
+function saysWhich(h) {
+  const other = h.onPath && h.onPath.version !== ownVersion()
+    ? ` (the seisin on your PATH is ${h.onPath.version || "another version"}, not ${ownVersion()})` : "";
+  if (h.via === "path") return `the hook runs "seisin hook" — seisin ${ownVersion()} is on your PATH`;
+  if (h.via === "local") return `the hook runs this project's node_modules/.bin/seisin${other || " — seisin is not on your PATH"}`;
+  return `the hook runs this seisin by its full path${other || " — seisin is not on your PATH"}`;
 }
 
 /**
@@ -39,7 +97,7 @@ export function hookEntry(command = "seisin hook") {
 export function hookEntries(command = "seisin hook") {
   const h = [{ type: "command", command }];
   return {
-    PreToolUse: [{ matcher: "*", hooks: h }],
+    PreToolUse: [{ matcher: TOOL_MATCHER, hooks: h }],
     PostToolUse: [{ matcher: "Bash", hooks: h }],
     PostToolUseFailure: [{ matcher: "*", hooks: h }],
     SessionStart: [{ matcher: "startup|resume|compact", hooks: h }],
@@ -55,14 +113,59 @@ export function wired(root) {
     // session-start hooks existed has only PreToolUse, and "already wired" there
     // would keep it from ever getting the rest.
     const hooks = JSON.parse(readFileSync(file, "utf8")).hooks ?? {};
-    return Object.keys(hookEntries()).every((ev) => JSON.stringify(hooks[ev] ?? []).includes("seisin hook"));
+    return Object.keys(hookEntries()).every((ev) =>
+      (hooks[ev] ?? []).some((e) => (e?.hooks ?? []).some((h) => isOurs(h?.command))));
   } catch {
     return false;                       // unreadable settings is not "wired"
   }
 }
 
+/**
+ * Narrows seisin's own `"*"` PreToolUse entry to {@link TOOL_MATCHER}. True if
+ * it changed anything.
+ *
+ * Only an entry that holds nothing but `seisin hook`: a `"*"` entry that also
+ * runs somebody else's command is theirs as much as ours, and narrowing it
+ * would silently stop their hook on every other tool.
+ */
+function narrow(settings) {
+  let changed = false;
+  for (const entry of settings.hooks?.PreToolUse ?? []) {
+    if (broadOurs(entry)) {
+      entry.matcher = TOOL_MATCHER;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/** A PreToolUse entry that runs only `seisin hook`, on every tool. */
+function broadOurs(entry) {
+  const ours = Array.isArray(entry?.hooks) && entry.hooks.length > 0 &&
+    entry.hooks.every((h) => isOurs(h?.command));
+  return ours && (entry.matcher === "*" || entry.matcher === "" || entry.matcher === undefined);
+}
+
+/**
+ * Does this repo still run the hook on every tool call — the `"*"` matcher that
+ * versions before 0.5.0 installed? Correct, just slow: every Read, Glob and
+ * TodoWrite pays for a process start that answers nothing. `seisin wire` narrows
+ * it in place; this is how `check` knows to say so.
+ */
+export function broadlyWired(root) {
+  const file = join(root, SETTINGS);
+  if (!existsSync(file)) return false;
+  try {
+    const pre = JSON.parse(readFileSync(file, "utf8")).hooks?.PreToolUse;
+    return Array.isArray(pre) && pre.some(broadOurs);
+  } catch {
+    return false;                       // unreadable settings is reported elsewhere, if at all
+  }
+}
+
 export function wire(config) {
   const file = join(config.root, SETTINGS);
+  const how = hookCommand(config.root);
 
   // Merged, never replaced. Someone's hooks are their own and a tool that
   // overwrites them to add itself does not get a second chance.
@@ -76,24 +179,60 @@ export function wire(config) {
   }
 
   if (wired(config.root)) {
-    out(`\n  ${C.dim}already wired — ${SETTINGS} runs "seisin hook"${C.off}\n\n`);
+    // A bare `seisin hook` where no seisin is on PATH fails on every call
+    // without a word. Rewritten in place to the command that works here.
+    // Both repairs in one pass: an install from before 0.5.0 on a machine
+    // without seisin on PATH needs the command repointed AND the matcher
+    // narrowed, and returning after the first left it half-fixed.
+    const repointed = how.via !== "path" && repoint(settings, how.command);
+    // Wired before the matcher was narrowed: still correct, just slow, so
+    // `wired()` keeps saying yes and nobody is told to redo anything. Running
+    // `wire` again is the way to pick up the narrower one, in place.
+    const narrowed = narrow(settings);
+    if (repointed || narrowed) {
+      writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+      if (repointed)
+        out(`\n  ${C.green}repointed${C.off}  ${SETTINGS}\n  ${C.dim}"seisin hook" is not on your PATH, so it never ran. ${saysWhich(how)}.${C.off}\n\n`);
+      if (narrowed)
+        out(`\n  ${C.green}narrowed${C.off}  ${SETTINGS}\n` +
+          `  ${C.dim}PreToolUse now runs seisin's hook only for the tools it reads, not for every tool${C.off}\n\n`);
+      return { changed: true, file, ...(repointed && { how }) };
+    }
+    out(`\n  ${C.dim}already wired — ${SETTINGS} runs seisin's hook${C.off}\n\n`);
     return { changed: false, file };
   }
 
   settings.hooks ??= {};
-  for (const [ev, entries] of Object.entries(hookEntries())) {
+  for (const [ev, entries] of Object.entries(hookEntries(how.command))) {
     settings.hooks[ev] ??= [];
-    if (!JSON.stringify(settings.hooks[ev]).includes("seisin hook")) settings.hooks[ev].push(...entries);
+    if (!settings.hooks[ev].some((e) => (e?.hooks ?? []).some((h) => isOurs(h?.command)))) settings.hooks[ev].push(...entries);
   }
+  narrow(settings);                     // an older PreToolUse entry that was kept
 
   mkdirSync(join(config.root, ".claude"), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
 
   out(
     `\n  ${C.green}wired${C.off}  ${SETTINGS}\n` +
-    `  ${C.dim}the agent now runs "seisin hook" before each tool call, which is what fills${C.off}\n` +
-    `  ${C.dim}the log. Without it the boundary still holds — you just cannot see it work.${C.off}\n\n` +
-    `  ${C.dim}Commit this file if the rest of your team should get it too.${C.off}\n\n`
+    `  ${C.dim}the agent now runs seisin's hook before each tool call, which is what fills${C.off}\n` +
+    `  ${C.dim}the log. Without it the boundary still holds — you just cannot see it work.${C.off}\n` +
+    `  ${C.dim}${saysWhich(how)}.${C.off}\n\n` +
+    // Only in a repository: outside one there is nothing to commit it to.
+    (insideRepo(config.root)
+      ? how.via === "absolute"
+        ? `  ${C.dim}The command names a path on this machine; teammates should run seisin wire themselves.${C.off}\n\n`
+        : `  ${C.dim}Commit this file if the rest of your team should get it too.${C.off}\n\n`
+      : "")
   );
-  return { changed: true, file };
+  return { changed: true, file, how };
+}
+
+/** Replaces a bare `seisin hook` command with `command`. True if it changed anything. */
+function repoint(settings, command) {
+  let changed = false;
+  for (const entries of Object.values(settings.hooks ?? {}))
+    for (const e of Array.isArray(entries) ? entries : [])
+      for (const h of e?.hooks ?? [])
+        if (h?.command === "seisin hook") { h.command = command; changed = true; }
+  return changed;
 }