seisin 0.4.2 → 0.6.0

package/src/commands/check.js

@@ -1,9 +1,161 @@
-/** `seisin check` — print the map and every way it does not hold. Runs nothing. */
+/** `seisin check` — print the map and every way it does not hold. Runs nothing, unless `--verify`. */
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { inspect } from "../inspect.js";
-import { renderReport, out } from "../render.js";
+import { renderReport, out, C } from "../render.js";
+import { measureSystemLog } from "../violations.js";
+import { join } from "node:path";
+import { settingsFor } from "../srt.js";
+import { weigh } from "../sandboxes/index.js";
+import { runsRoot } from "../rundir.js";
+import { channelName } from "../spool.js";
 
-export function check(config, argv = []) {
-  const report = inspect(config, argv[0] ?? null, config.path);
-  out(renderReport(report));
+export async function check(config, argv = []) {
+  if (argv.includes("--parallel") && !argv.includes("--verify"))
+    throw new Error("--parallel is experimental and requires --verify");
+  const role = argv.find((a) => !a.startsWith("-")) ?? null;
+  const report = inspect(config, role, config.path);
+  out(renderReport(report, { verbose: argv.includes("--verbose") }));
+  if (config.sandbox?.provider) report.sandboxes = sandboxes(config, role);
+  if (argv.includes("--verify")) report.verify = await verify(config, role, argv.includes("--parallel"));
+  if (argv.includes("--system-log")) report.systemLog = await systemLog();
   return report;
 }
+
+/**
+ * `--system-log`: is the log a run reads denials from dropping messages now?
+ *
+ * A flooded unified log loses lines before they are filtered, and a kernel
+ * denial lost there files nothing: the run says so afterwards, and this says
+ * it before, with who is writing the most — the only lead to a fix. A flag,
+ * because it takes seconds and `check` otherwise answers at once.
+ */
+async function systemLog() {
+  const m = await measureSystemLog({ seconds: SYSTEM_LOG_SECONDS });
+  if (!m.available) {
+    out(`\n${C.dim}system log: not measured — ${m.reason}${C.off}\n`);
+    return m;
+  }
+  const top = m.top.map((t) => `${t.who} ${t.perSecond}/s`).join(", ");
+  out(m.dropped
+    ? `\n${C.yellow}⚠ system log: ${m.dropped} batch(es) of messages dropped in ${m.seconds} s — kernel denials can go unrecorded now.${C.off}\n` +
+      `  ${m.perSecond} messages/s; most from ${top}. Stop or quiet the busiest writer, then measure again.\n`
+    : `\n${C.green}✓${C.off} system log: nothing dropped in ${m.seconds} s (${m.perSecond} messages/s; most from ${top})\n`);
+  return m;
+}
+
+const SYSTEM_LOG_SECONDS = 3;
+
+/**
+ * `[sandbox] provider`: which sandbox each role would get, and why the others not.
+ *
+ * Said before anything starts, because the alternative is finding out at
+ * `seisin run` that a role cannot be held by the sandbox the config asked for.
+ * The settings are the ones a run would build, down to a channel in the runs
+ * root, so a sandbox that cannot re-open this run's directory is caught here
+ * too. Printed only when `[sandbox] provider` is set: without it every role
+ * runs under srt, as it always has, and there is nothing to choose.
+ */
+export function sandboxes(config, only = null, { platform = process.platform } = {}) {
+  const sock = join(runsRoot(), "check", channelName(platform));
+  const rows = [];
+  out(`\n${C.b}sandboxes${C.off} (${config.sandbox.provider.join(" → ")})\n`);
+  for (const r of Object.values(config.roles)) {
+    if (only && r.name !== only) continue;
+    let settings;
+    try { settings = settingsFor(config, r.name, sock); } catch (e) { rows.push({ role: r.name, chosen: null, error: e.message }); continue; }
+    const { chosen, options } = weigh(config, settings, { platform, role: r.name });
+    rows.push({ role: r.name, chosen: chosen?.sandbox.name ?? null,
+      options: options.map((o) => ({ name: o.sandbox.name, missing: o.missing, unmet: o.unmet, warnings: o.warnings })) });
+    out(chosen ? `  ${C.green}✓${C.off} ${r.name}: ${chosen.sandbox.name}\n` : `  ${C.red}✗${C.off} ${r.name}: no sandbox can hold it\n`);
+    // Held, but not the way the role may expect: the sandbox's own words.
+    for (const w of chosen?.warnings ?? []) out(`      ${C.yellow}⚠ ${chosen.sandbox.name}: ${w}${C.off}\n`);
+    // Recorded nowhere otherwise: a run under it would still be held, and say nothing of what it refused.
+    if (chosen && !chosen.sandbox.tagsDenials && platform === "darwin")
+      out(`      ${C.yellow}⚠ ${chosen.sandbox.name} does not tag its denials, so none of the kernel's denials under it are recorded${C.off}\n`);
+    for (const o of options) {
+      if (o === chosen) break;
+      if (o.missing) out(`      ${o.sandbox.name}: ${o.missing}\n`);
+      else for (const u of o.unmet) out(`      ${o.sandbox.name}: ${u}\n`);
+    }
+  }
+  return rows;
+}
+
+/**
+ * The exit status: 1 when a role cannot be enforced as written, or when what a
+ * flag asked for failed. `--system-log` is asked for like `--verify` and fails
+ * the same way — a log dropping messages now is a run that would lose denials
+ * now, and a CI step has only the status to go on.
+ */
+export function checkStatus(report) {
+  return report.warnings.some((w) => w.kind === "cannot-be-enforced") || report.verify?.some((v) => !v.ok) ||
+    report.sandboxes?.some((s) => !s.chosen) ||
+    report.systemLog?.dropped > 0 ? 1 : 0;
+}
+
+/**
+ * `--verify`: each role's `verify` command, run inside that role's sandbox.
+ *
+ * Through `seisin run` itself and not a copy of its setup, so what passes here
+ * is what the agent will get: the same settings, environment and PATH. With
+ * `--agent none`, because the question is the toolchain, not the agent's home.
+ * In the repo root, where a test command expects to start.
+ *
+ * The one thing `check` executes, which is why it is a flag: without it
+ * `check` still runs nothing.
+ */
+async function verify(config, only, parallel = false) {
+  const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+  const roles = Object.values(config.roles).filter((r) => (only ? r.name === only : true) && r.verify);
+  const results = [];
+  if (!roles.length) out(`\n${C.yellow}verify: no role ${only ? `"${only}" ` : ""}declares a verify command${C.off}\n`);
+  const run = async (r) => {
+    const res = parallel
+      ? await runParallel(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], config.root)
+      : spawnSync(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], {
+        cwd: config.root, encoding: "utf8", timeout: 300_000, env: process.env,
+      });
+    const ok = res.status === 0;
+    const result = { role: r.name, ok, status: res.status };
+    const output = `${res.stderr ?? ""}${res.stdout ?? ""}`.trim().split("\n");
+    const tail = output.slice(-20).join("\n    ");
+    const denied = output.filter((line) => /denied|Operation not permitted|Permission denied|not readable/i.test(line));
+    const suggestion = denied.some((line) => (r.reads ?? []).some((p) => line.includes(p)))
+      ? "The command reached a declared reads path; check that the entry names the needed subtree and exists."
+      : `If the missing path is data, add the narrow path to reads; if it is an interpreter, runtime or library, add its stack to toolchain${r.toolchain?.length ? ` (currently ${r.toolchain.join(", ")})` : ""}.`;
+    out(`\n${ok ? C.green + "✓" : C.red + "✗"} verify ${r.name}${C.off}: ${r.verify.join(" ")}` +
+      (ok ? "\n" : ` — exit ${res.status ?? res.signal}\n    ${tail}\n` +
+        `  This role cannot run its own checks inside its sandbox. ${suggestion}\n`));
+    return result;
+  };
+  if (parallel) {
+    out(`\n${C.yellow}experimental: verify commands are running concurrently; shared builds, caches, ports, or generated files may race. Use plain --verify for serial checks.${C.off}\n`);
+    results.push(...await Promise.all(roles.map(run)));
+  } else {
+    for (const r of roles) results.push(await run(r));
+  }
+  return results;
+}
+
+function runParallel(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, env: process.env });
+    let stdout = "", stderr = "", timedOut = false, forceTimer;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      forceTimer = setTimeout(() => child.kill("SIGKILL"), 2_000);
+    }, 300_000);
+    child.stdout.setEncoding("utf8").on("data", (s) => { stdout += s; });
+    child.stderr.setEncoding("utf8").on("data", (s) => { stderr += s; });
+    child.on("error", (error) => {
+      clearTimeout(timer); clearTimeout(forceTimer);
+      resolve({ status: null, signal: null, stdout, stderr: `${stderr}${error.message}\n` });
+    });
+    child.on("close", (status, signal) => {
+      clearTimeout(timer); clearTimeout(forceTimer);
+      resolve({ status: timedOut ? null : status, signal: timedOut ? "SIGTERM (timeout)" : signal, stdout, stderr });
+    });
+  });
+}

package/src/commands/explain.js

@@ -5,9 +5,10 @@
  * 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, readTarget } from "../owners.js";
+import { unknownRole } from "../suggest.js";
 import { twinsOf, whereIs } from "../worktree.js";
 import { renderVerdict, C, out } from "../render.js";
 
@@ -15,7 +16,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 +28,14 @@ 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 = explain(config, role, "read", target, process.cwd());
+    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 +48,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 +73,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 +91,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 +100,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";
@@ -12,10 +12,11 @@ import { decide } from "../hook.js";
 import { afterTool, atSessionStart } from "../diagnose.js";
 import { logPath } from "../log.js";
 import { flush } from "../spool.js";
+import { chainFromEnv } from "../handoff.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 +25,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;
@@ -34,17 +35,30 @@ export async function hook(stdin = process.stdin, env = process.env) {
     return null;
   }
   if (!config.roles[role]) return null;
+  // Set by `seisin run --handoff`; it words the denial and decides nothing
+  // (handoff.js, CHAIN_ENV).
+  const chain = chainFromEnv(env);
 
   // One command for every event it is wired to, so `seisin wire` adds one name.
   // The after-the-fact and session-start halves only explain; neither decides.
   const event_ = event.hook_event_name;
   if (event_ === "PostToolUse" || event_ === "PostToolUseFailure") {
-    try { return await afterTool(config, role, event, { file: logPath(config.root) }); } catch { return null; }
+    try { return await afterTool(config, role, event, { file: logPath(config.root), chain }); } catch { return null; }
   }
   if (event_ === "SessionStart") {
-    try { return atSessionStart(config, role, event, { file: logPath(config.root) }); } catch { return null; }
+    try { return atSessionStart(config, role, event, { file: logPath(config.root), chain }); } catch { return null; }
+  }
+  // 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", chain });
+  } catch (e) {
+    process.stderr.write(`seisin hook: ${e?.message ?? e} — no decision, the tool call goes ahead\n`);
   }
-  const decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1" });
   // 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.