seisin 0.4.0 → 0.5.0

package/src/commands/run.js

@@ -21,10 +21,10 @@ import { spool, SOCK_ENV } from "../spool.js";
 import { openRun } from "../rundir.js";
 import { secretsOf, redactor } from "../redact.js";
 import { C, err } from "../render.js";
-import { pending, requestsPath, markStale } from "../requests.js";
+import { pending, requestsPath, withDeclarers } from "../requests.js";
 import { notifier } from "../notify.js";
-import { logPath, read } from "../log.js";
-import { renderQueue } from "./requests.js";
+import { renderAdded } from "./requests.js";
+import { unknownRole } from "../suggest.js";
 import { watchDenials } from "../violations.js";
 import { intake } from "../intake.js";
 
@@ -41,21 +41,32 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const DRAIN_MS = 250;
 
 /**
- * The bundled runtime first, a global one second, and nothing third.
+ * The runtime seisin depends on first, one on PATH second, and nothing third.
+ *
+ * "The one seisin depends on" is found the way Node finds a dependency — up
+ * from this file, through every `node_modules` — not at one spelled-out path.
+ * `<seisin>/node_modules/.bin/srt` is only where it lands in a checkout. In a
+ * project that installs seisin as a dependency, npm hoists the runtime to the
+ * project's own `node_modules`, and that path does not exist. Measured with
+ * 0.5.0 packed and installed into a project: `npx seisin` still worked, because
+ * npx puts the project's `.bin` on PATH; `./node_modules/.bin/seisin` and
+ * `node node_modules/seisin/src/cli.js` did not — they said "not found", or,
+ * with a global srt 0.0.75 installed, ran under THAT one instead of the 0.0.78
+ * this version pins, with none of its fixes.
  *
  * There is deliberately no fallback to running unsandboxed. A permission tool
  * that quietly becomes a no-op when its enforcer is missing is worse than one
  * that refuses, because you keep trusting it.
  */
-export function resolveSrt() {
-  const bundled = join(HERE, "..", "..", "node_modules", ".bin", "srt");
-  if (existsSync(bundled)) return bundled;
+export function resolveSrt({ from = HERE, path = process.env.PATH } = {}) {
+  const local = dependencySrt(from);
+  if (local) return local;
 
   // Walk PATH rather than asking a shell. `spawnSync(..., { shell: true })`
   // prints a deprecation warning on every single run — Node's DEP0190 — which
   // is a line of noise in front of every user for the sake of finding one file.
   // It is also the concatenation hazard the warning is about.
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+  for (const dir of (path ?? "").split(delimiter)) {
     if (!dir) continue;
     const candidate = join(dir, "srt");
     if (existsSync(candidate)) return candidate;
@@ -63,6 +74,38 @@ export function resolveSrt() {
   return null;
 }
 
+const RUNTIME = "@anthropic-ai/sandbox-runtime";
+
+/**
+ * The `srt` of the sandbox-runtime that resolves from `from`, or null.
+ *
+ * The `.bin/srt` npm linked beside the package when there is one — that is the
+ * file npm made executable — and otherwise the package's own `bin` entry.
+ * The package's `package.json` is found by walking up rather than through
+ * `require.resolve`, which a package's `exports` map is free to refuse.
+ */
+export function dependencySrt(from = HERE) {
+  let dir = from;
+  for (;;) {
+    const nm = join(dir, "node_modules");
+    const pkg = join(nm, RUNTIME, "package.json");
+    if (existsSync(pkg)) {
+      const linked = join(nm, ".bin", "srt");
+      if (existsSync(linked)) return linked;
+      try {
+        const bin = JSON.parse(readFileSync(pkg, "utf8")).bin;
+        const rel = typeof bin === "string" ? bin : bin?.srt;
+        if (rel) {
+          const target = join(nm, RUNTIME, rel);
+          if (existsSync(target)) return target;
+        }
+      } catch { /* an unreadable package.json is not a runtime */ }
+    }
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
 
 export async function run(config, argv) {
   /**
@@ -75,11 +118,23 @@ export async function run(config, argv) {
    */
   const split = argv.indexOf("--");
   const role = argv[0];
-  const mine = split === -1 ? argv.slice(1) : argv.slice(1, split);
-  const cmd = split === -1 ? argv.slice(1) : argv.slice(split + 1);
+  let mine, cmd;
+  if (split !== -1) {
+    mine = argv.slice(1, split);
+    cmd = argv.slice(split + 1);
+  } else {
+    // No `--`: seisin's own flags are the leading `-options` only. From the
+    // first token that is not an option, everything is the command — its own
+    // flags are its business. `seisin run x echo hi --observe` used to read
+    // `--observe` as seisin's and put the run in observe mode; now that flag
+    // belongs to `echo`, and observe needs `seisin run x --observe -- echo hi`.
+    let i = 1;
+    while (i < argv.length && argv[i].startsWith("-")) i++;
+    mine = argv.slice(1, i);
+    cmd = argv.slice(i);
+  }
   if (!role || cmd.length === 0) throw new Error("usage: seisin run <role> -- <command...>");
-  if (!config.roles[role])
-    throw new Error(`unknown role "${role}". Known: ${Object.keys(config.roles).join(", ")}`);
+  if (!config.roles[role]) throw unknownRole(config, role);
 
   /**
    * seisin does not run inside seisin, and says so here rather than later.
@@ -88,27 +143,27 @@ export async function run(config, argv) {
    * than the outer one: the inner run dies in the runtime with rc=13 and a Node
    * warning about an unsettled await — no role named, no boundary named, and it
    * reads as seisin crashing rather than as a refusal. Before that it failed
-   * even earlier, on a $TMPDIR the outer box had already reshaped.
+   * even earlier, on a $TMPDIR the outer sandbox had already reshaped.
    *
    * This is the refusal, not a fix, because the shape it is usually reached for
-   * is wrong anyway: a dispatcher that starts roles from inside one role's box
-   * makes every worker a descendant of the box that should hold the least. Such
+   * is wrong anyway: a dispatcher that starts roles from inside one role's sandbox
+   * makes every worker a descendant of the sandbox that should hold the least. Such
    * a dispatcher belongs above the roles and gets asked, rather than running
    * inside one of them.
    */
   const outer = process.env.SEISIN_ROLE;
   if (outer)
     throw new Error(
-      `already inside the box as "${outer}" — seisin does not nest.\n` +
+      `already inside a seisin sandbox as "${outer}" — seisin does not nest.\n` +
       `  Starting "${role}" from in here does not give it its own territory: the run dies in the\n` +
-      `  sandbox runtime, and what territory a second box would even hold is undefined.\n` +
+      `  sandbox runtime, and what territory a second sandbox would even hold is undefined.\n` +
       `  Run roles as siblings from outside instead. Something that needs to start roles belongs\n` +
       `  above them — asked by the role that wants the work done, not run inside it.`,
     );
 
   /**
    * The audit spool: this process holds the log and the queue, and the hook
-   * inside the box gets a socket instead of a directory. That is the whole
+   * inside the sandbox gets a socket instead of a directory. That is the whole
    * reason `.seisin/` is no longer in anybody's allowWrite — see spool.js.
    *
    * Entries arrive with their own `at` already set by the sender, so what lands
@@ -116,11 +171,36 @@ export async function run(config, argv) {
    */
   const observe = mine.includes("--observe");
   // Built before the first request can arrive; the POST leaves from here, the
-  // parent, never from inside the box (notify.js).
+  // parent, never from inside the sandbox (notify.js).
   const notify = notifier(config);
   // Everything that belongs to this run alone — socket, settings, scratch keys
   // — in one private directory, with one id. See rundir.js.
   const theRun = openRun();
+  /**
+   * From here on, every way out removes what this run made.
+   *
+   * The happy path closed the spool, the kernel watcher and the directory; the
+   * failures did not. A key provider that failed, a spool that would not bind,
+   * a runtime that would not start — each left the directory behind with its
+   * socket and, past the key step, its `scratch` keys on disk until some later
+   * run swept it, and the `log stream` process running. An `exit` handler,
+   * because every one of those ends in `process.exit`, from cli.js or from here,
+   * and everything it has to do is synchronous. Idempotent: the normal exit
+   * below runs it first and the handler finds nothing left.
+   */
+  let audit = null;
+  let denials = null;
+  let closed = false;
+  const cleanup = () => {
+    if (closed) return;
+    closed = true;
+    try { audit?.close(); } catch {}
+    try { denials?.close(); } catch {}
+    theRun.close();
+  };
+  process.once("exit", cleanup);
+  // What was already waiting, so the end of the run can say what it added.
+  const before = new Set(pending(requestsPath(config.root)).map((q) => q.key));
   const sockPath = theRun.sock;
   const settings = settingsFor(config, role, sockPath, observe);
   // Per run, never per role: `.seisin/<role>.json` was one file for every run
@@ -130,10 +210,10 @@ export async function run(config, argv) {
   // What arrives from the hook and from the kernel, checked against the policy
   // this run started with and written with the run's id on it. See intake.js.
   const take = intake({ config, role, runId: theRun.id, observe, settings, notify });
-  const audit = await spool(take.fromHook, sockPath);
+  audit = await spool(take.fromHook, sockPath);
 
   const srt = resolveSrt();
-  if (!srt) throw new Error("sandbox runtime not found. Install it with: npm i -g @anthropic-ai/sandbox-runtime");
+  if (!srt) throw new Error(`sandbox runtime not found. ${installHint()}`);
 
   // The hook runs inside the child and has to know which role it is. These are
   // the only variables seisin injects, and none carries a secret.
@@ -147,7 +227,7 @@ export async function run(config, argv) {
    *
    * The ordering is the security property, not a convenience. The provider
    * command holds the vault's own credential — the keychain prompt, the
-   * 1Password session — and running it inside the box would mean putting that
+   * 1Password session — and running it inside the sandbox would mean putting that
    * credential in there too, which is the thing this feature exists to avoid.
    * The confined side cannot reach the parent; the parent can reach the vault;
    * so the parent resolves and hands over the result.
@@ -163,7 +243,7 @@ export async function run(config, argv) {
     if (mode === "env") { env[entry.name] = value; continue; }
     // `scratch`: the value lands in the per-run directory this process already
     // makes for the spool and already removes on exit, so its lifetime is the
-    // turn's by construction rather than by a cleanup somebody has to remember.
+    // run's by construction rather than by a cleanup somebody has to remember.
     // The variable carries the PATH, which is the convention every tool that
     // wants a secret from a file already reads (`_FILE`), and it means the
     // value itself is not in the environment of a process that may print it.
@@ -220,9 +300,27 @@ export async function run(config, argv) {
   if (observe) env.SEISIN_OBSERVE = "1";
   if (mine.includes("--debug-env")) err(`${C.dim}seisin: dropped ${dropped.join(" ")}${C.off}\n`);
 
+  /**
+   * A command the role cannot find, said as that — before the sandbox starts.
+   *
+   * It used to reach the runtime, which runs it through `env`, and the only
+   * word on screen was `env: nosuchcmd: No such file or directory`: seisin's
+   * own wrapper named as the thing that failed. 127, the shell's code for it.
+   */
+  if (!onPath(cmd[0], env.PATH)) {
+    const e = new Error(`"${cmd[0]}" not found on the role's PATH`);
+    e.exitCode = 127;
+    throw e;
+  }
+
+  // What the role gets, in the policy's own words: `writes 8 path(s)` counted
+  // the runtime's scratch directories as territory and named none of it.
+  const r = config.roles[role];
+  const territory = observe ? "the whole repo" : r.writes.length ? r.writes.join(" ") : "nothing";
+  const scratch = settings.filesystem.allowWrite.length - (observe ? 1 : r.writes.length);
   err(
-    `${C.dim}seisin: ${role} · writes ${settings.filesystem.allowWrite.length} path(s) · ` +
-    `reads ${settings.filesystem.allowRead.length} key(s) · ` +
+    `${C.dim}seisin: ${role} · writes ${territory}${scratch > 0 ? ` (+${scratch} scratch)` : ""} · ` +
+    `keys ${r.keys.length ? r.keys.join(" ") : "none"} · ` +
     `env ${Object.keys(env).length} kept, ${dropped.length} dropped` +
     `${observe ? ` · ${C.yellow}OBSERVING — the repo is writable, the network is NOT${C.off}${C.dim}` : ""}${C.off}\n`
   );
@@ -254,11 +352,11 @@ export async function run(config, argv) {
   // `claude -c`, `claude --debug`. Found by passing --settings to claude and
   // watching the sandbox reject it as its own malformed config.
   /**
-   * The kernel's own refusals, alongside the hook's.
+   * The kernel's own denials, alongside the hook's.
    *
    * Started BEFORE the spawn, and that ordering is the whole difference between
    * this working and this recording nothing. `log stream` is a separate process
-   * with its own startup; a `sh -c` that gets refused is over in single-digit
+   * with its own startup; a `sh -c` that gets denied is over in single-digit
    * milliseconds. Started after the spawn, the first version of this caught
    * zero denials on exactly the short commands an agent runs most.
    *
@@ -268,12 +366,12 @@ export async function run(config, argv) {
    *
    * What each denial becomes — a log line, a request, or a count — is decided
    * in intake.js, beside the hook's lines: the kernel is the thing that
-   * actually refused, so when the two disagree, it is the one that is right.
+   * actually denied, so when the two disagree, it is the one that is right.
    */
-  // What actually runs inside the box, computed once and used by both ends. The
+  // What actually runs inside the sandbox, computed once and used by both ends. The
   // watcher recognises a denial by comparing the runtime's command tag with this
   // argv; handed `cmd` while `srt` was handed `env NO_PROXY=… cmd`, it recognised
-  // nothing for a role with `local_ports`, and every short refusal of those roles
+  // nothing for a role with `local_ports`, and every short denial of those roles
   // — writes included — left no line (measured: 0 of 5, and 5 of 5 without the key).
   //
   // And a nonce in front, because the tag alone does not tell runs apart: an
@@ -284,7 +382,7 @@ export async function run(config, argv) {
   // path (measured: 3 lines and 3 requests for one write by one of 3 roles).
   // The nonce makes each run's command unique, so the tag names one run.
   const boxed = ["env", `SEISIN_RUN_ID=${theRun.id}`, ...loopbackVia(config.roles[role], cmd)];
-  const denials = watchDenials(take.fromKernel, { argv: boxed });
+  denials = watchDenials(take.fromKernel, { argv: boxed });
 
   // Deliberately NOT announced here. On Linux this branch is taken every time,
   // so saying it per run puts a line the reader cannot act on in front of every
@@ -359,8 +457,11 @@ export async function run(config, argv) {
    * Seen once in a full suite run under load; by the end of the drains below
    * the pending signal has been handled.
    */
+  // A runtime that itself dies of a signal (SIGKILL, the OOM killer) exits
+  // the shell's way, 128 + n, the same as a run seisin was told to stop — it
+  // was reported as 1, a plain failure, which hides that it was killed.
   const statusOf = (code, signal) => stoppedBy ? 128 + osConstants.signals[stoppedBy]
-    : signal ? 1
+    : signal ? 128 + (osConstants.signals[signal] ?? 0)
     : interrupted && !code ? 130
     : code ?? 0;
 
@@ -374,18 +475,18 @@ export async function run(config, argv) {
     // one entry behind is how a request goes unnoticed for a day.
     audit.close();
     // Same reason, one layer further out: the kernel writes its line through a
-    // separate process, so the last refusal of a run can still be in flight
+    // separate process, so the last denial of a run can still be in flight
     // here. This is the only wait the mechanism adds and it is per run — it
-    // returns as soon as the stream goes quiet, so a run that was refused
+    // returns as soon as the stream goes quiet, so a run that was denied
     // nothing pays a tick.
     await denials.close({ drain: DRAIN_MS });
     // The run made this directory, so the run removes it.
-    theRun.close();
+    cleanup();
 
     // Say what was dropped rather than only what was kept. A filter nobody can
     // see is indistinguishable from a monitor that is not working, and this one
     // drops the majority of what the kernel says on a busy run.
-    // Only when something was actually recorded. A run where every refusal was
+    // Only when something was actually recorded. A run where every denial was
     // filtered out has nothing to contextualise, and `0 recorded, 1 outside the
     // policy's paths` is a line that answers a question nobody asked — the
     // counts exist to explain a filter, not to announce that one ran.
@@ -398,8 +499,12 @@ export async function run(config, argv) {
           `${offPolicy ? `, ${offPolicy} outside the policy's paths` : ""}` +
           `${foreign ? `, ${foreign} from other sandboxes` : ""}${C.off}\n`);
 
-    const queue = pending(requestsPath(config.root));
-    if (queue.length) err(renderQueue(markStale(queue, read(logPath(config.root)))));
+    // Only what this run added, with the numbers `grant` takes, and one line
+    // for the rest. The whole queue after every run buried the new request
+    // under the ones already seen; nothing new, nothing said.
+    const queue = withDeclarers(config, pending(requestsPath(config.root), { keyDirs: config.keyDirs }));
+    const added = queue.map((q, i) => ({ ...q, n: i + 1 })).filter((q) => !before.has(q.key));
+    if (added.length) err(renderAdded(added, queue.length - added.length));
     const failed = await notify.settle();
     if (failed.length) err(`${C.yellow}seisin: could not notify about a new request (${failed[0]})${C.off}\n`);
     // One more turn of the loop, so a signal that arrived with the child's exit
@@ -420,5 +525,35 @@ export async function run(config, argv) {
     clearTimeout(guard);
     process.exit(status);
   });
-  child.on("error", (e) => { throw new Error(`could not start the sandbox: ${e.message}`); });
+  // Not a `throw`: in a listener it is an uncaught exception — exit 1, a
+  // stack trace, and none of the cleanup. Said the way cli.js says any other
+  // failure, with its code; the `exit` handler above removes the run.
+  child.on("error", (e) => {
+    err(`${C.red}seisin:${C.off} could not start the sandbox: ${e.message}\n`);
+    process.exit(2);
+  });
+}
+
+/** Is `name` a program the role can start with this PATH? */
+function onPath(name, path) {
+  if (!name) return false;
+  if (name.includes("/")) return existsSync(name);
+  return (path ?? "").split(delimiter).some((d) => d && existsSync(join(d, name)));
+}
+
+/**
+ * How to put the runtime back, for the way this seisin was installed.
+ *
+ * It is a dependency, so it is missing only from a broken install — and the
+ * fix differs: a project's own node_modules, a global install, or a checkout.
+ * `npm i -g` was suggested to everyone, which for a project-local seisin
+ * installs a second runtime somewhere seisin does not look first.
+ */
+export function installHint(from = HERE) {
+  const at = from.split("/node_modules/seisin/")[0];
+  if (at === from) return `Install it in this checkout with: npm install (in ${dirname(dirname(from))})`;
+  // npm's global layout is <prefix>/lib/node_modules on unix, …/npm/node_modules on Windows.
+  if (/\/lib$/.test(at) || /[\\/]npm$/.test(at))
+    return "seisin is installed globally; reinstall it with: npm install -g seisin";
+  return `seisin is installed in ${at}; reinstall it there with: npm install seisin`;
 }

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,14 +1,14 @@
-/** `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 { 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 (!config.roles[role]) throw unknownRole(config, role);
   const at = (flag, fallback) => {
     const i = argv.indexOf(flag);
     return i === -1 ? fallback : argv[i + 1];
@@ -24,7 +24,26 @@ export function wallsCommand(config, argv = []) {
   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));
+  if (list.length) out(renderForPerson(role, list));
   if (old && !all) out(`  (${old} older wall(s) not hit in the last ${STALE_RUNS}+ runs: seisin walls ${role} --all)\n`);
   return list;
 }
+
+/**
+ * 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) {
+    const why = w.owners?.length ? `belongs to ${w.owners.map(safe).join(", ")}` : 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,9 +14,9 @@
  *
  * 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 { twinsOf, whereIs } from "../worktree.js";
 import { C, out } from "../render.js";
@@ -25,7 +25,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,7 +52,7 @@ 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`
         : "\n")
@@ -64,7 +65,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.