seisin 0.4.2 → 0.6.0

package/src/commands/run.js

@@ -10,25 +10,35 @@
 import { spawn } from "node:child_process";
 import { finished } from "node:stream/promises";
 import { constants as osConstants } from "node:os";
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
-import { join, dirname, delimiter } from "node:path";
-import { fileURLToPath } from "node:url";
-import { settingsFor, roleHome, loopbackVia } from "../srt.js";
+import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { join, dirname, delimiter, resolve } from "node:path";
+import { settingsFor, roleHome, loopbackVia, agentOf, AGENTS, AGENT_HOMES } from "../srt.js";
 import { buildEnv } from "../env.js";
+import { traceFields } from "../trace.js";
 import { resolveKeys } from "../keys.js";
 import { nestedSandboxWarning } from "../nested.js";
-import { spool, SOCK_ENV } from "../spool.js";
+import { spool, SOCK_ENV, FIFO_SUFFIX } 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, queueOf, recordHandoff } from "../requests.js";
+import { chainFrom, describeHandoff, MAX_DEPTH, CHAIN_ENV } from "../handoff.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";
+import { EXPECTED } from "../kinds.js";
+import { toolchainBins } from "../territory.js";
+import { writePathsOf, realOrSelf, SOCKET_MAX } from "../grants.js";
+import { runCanary, CANARY_EXIT } from "../canary.js";
+import { append, logPath } from "../log.js";
+import { flagsOf } from "../help.js";
+import { WILD } from "../paths.js";
+import { chooseSandbox, settingsOf, DEFAULT_SANDBOX } from "../sandboxes/index.js";
+import { machOf } from "../browsers.js";
+import { MACH_FILE } from "../sandboxes/mach-profile.js";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**
  * The ceiling on waiting for the kernel's last word when a run ends.
@@ -40,30 +50,29 @@ const HERE = dirname(fileURLToPath(import.meta.url));
  */
 const DRAIN_MS = 250;
 
+// Moved with the rest of what is particular to sandbox-runtime (sandboxes/srt.js);
+// exported from here still, where callers and the tests have always found them.
+export { resolveSrt, dependencySrt, installHint } from "../sandboxes/srt.js";
+
 /**
- * The bundled runtime first, a global one second, and nothing third.
- *
- * 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.
+ * Which agent this run is: `--agent <name>` when given, else read off the
+ * command. It decides whose home is scratch and whose sign-in is closed (see
+ * AGENT_HOMES in grants.js). `--agent none` says "no agent", for a run that
+ * must get neither home whatever its command looks like.
  */
-export function resolveSrt() {
-  const bundled = join(HERE, "..", "..", "node_modules", ".bin", "srt");
-  if (existsSync(bundled)) return bundled;
-
-  // 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)) {
-    if (!dir) continue;
-    const candidate = join(dir, "srt");
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
+export function agentFor(mine, cmd) {
+  const at = mine.lastIndexOf("--agent");
+  if (at === -1) return agentOf(cmd);
+  const given = mine[at + 1];
+  if (given === "none") return null;
+  if (!AGENTS.includes(given))
+    throw new Error(
+      `--agent ${given ?? ""}: seisin knows ${AGENTS.join(", ")} and none.\n` +
+      `  It decides whose home a run may write (${AGENTS.map((a) => AGENT_HOMES[a]).join(", ")}) ` +
+      `and whose sign-in it cannot read.`);
+  return given;
 }
 
-
 export async function run(config, argv) {
   /**
    * Ours before the `--`, theirs after it.
@@ -86,13 +95,14 @@ export async function run(config, argv) {
     // `--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++;
+    const values = flagsOf("run").values;
+    while (i < argv.length && argv[i].startsWith("-")) i += values.includes(argv[i]) ? 2 : 1;
     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);
+  const agent = agentFor(mine, cmd);
 
   /**
    * seisin does not run inside seisin, and says so here rather than later.
@@ -101,27 +111,30 @@ 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.`,
     );
 
+  const handed = handoffOf(config, role, mine);
+  const expectDenied = expectedDenials(mine);
+
   /**
    * 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
@@ -129,24 +142,103 @@ 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
+  // Everything that belongs to this run alone — socket, settings, run-file 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 `run-file` 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);
+  // The program, as the role's PATH will find it: `read = "territory"` keeps
+  // that one file readable (territory.js). Same order run uses below — the
+  // declared toolchain first, then the parent's PATH.
+  const isDir = (d) => { try { return statSync(d).isDirectory(); } catch { return false; } };
+  const searchPath = config.read === "territory"
+    ? [...toolchainBins(config, config.roles[role], isDir), process.env.PATH ?? ""].join(delimiter)
+    : process.env.PATH;
+  const program = whichOn(cmd[0], searchPath);
+  /**
+   * The run's temp directory: one the role may write, never the runtime's.
+   *
+   * sandbox-runtime hands every child `/tmp/claude` as TMPDIR, and that
+   * directory is now denied (srt.js, SHARED_TMP). It takes CLAUDE_CODE_TMPDIR
+   * instead when set, so that is where the run's goes: the role's own tmp under
+   * `isolate = "home"`, else the parent's TMPDIR when the role may already write
+   * it, else one made for this run beside the runs root, granted to it alone. A caller's
+   * own CLAUDE_CODE_TMPDIR is kept only if the role may write it: an
+   * environment variable is not a way to widen the policy.
+   */
+  const granted = writePathsOf(config, config.roles[role], { observe, agent });
+  const writable = (p) => !!p && [p, realOrSelf(p)].some((q) =>
+    granted.some((g) => q === g || q === realOrSelf(g) || q.startsWith(g + "/") || q.startsWith(realOrSelf(g) + "/")));
+  const isolatedHome = config.isolate === "home" || config.isolate === true;
+  let runTmp = [process.env.CLAUDE_CODE_TMPDIR,
+    isolatedHome ? join(roleHome(config, role), "tmp") : process.env.TMPDIR].find(writable);
+  if (!runTmp) runTmp = theRun.tmp();
+  const generated = settingsFor(config, role, sockPath, observe, { agent, program, tmp: runTmp, forRun: true });
+
+  /**
+   * The sandbox this role runs under: the first one `[sandbox] provider` names
+   * that is installed and enforces every part of these settings
+   * (sandboxes/index.js). None is an error that names what each one lacked —
+   * never a run under one that enforces less. Chosen before the settings are
+   * written, because the file is the chosen sandbox's version of them
+   * (settingsOf: tartaros takes a browser's Mach names in a field of its own).
+   */
+  // `browsers`: the Mach names to register (browsers.js).
+  const { register: machRegister } = machOf(config.roles[role]);
+  const box = chooseSandbox(config, generated, { role });
+  if (box.error) throw box.error;
+  const { sandbox, bin } = box;
+  const settings = settingsOf(sandbox, generated, { machRegister });
   // Per run, never per role: `.seisin/<role>.json` was one file for every run
   // of that role, and two at once wrote each other's socket path into it.
   const file = theRun.writeSettings(settings);
 
   // 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);
+  // The launcher's W3C trace, read from the parent's environment once: every line
+  // this run writes carries it, so the log joins the launcher's trace (trace.js).
+  const trace = traceFields(process.env);
+  const take = intake({ config, role, runId: theRun.id, observe, settings, notify, chain: handed?.chain ?? null, expectDenied, trace });
+  // The channel is a unix socket on macOS, and a socket path is capped. Past
+  // the cap the listen dies on `EINVAL` and a path, which says nothing about
+  // TMPDIR — the one thing that decides how long it is.
+  if (!sockPath.endsWith(FIFO_SUFFIX) && Buffer.byteLength(sockPath) >= SOCKET_MAX)
+    throw new Error(
+      `TMPDIR is too long for this run's socket: ${Buffer.byteLength(sockPath)} bytes, and a unix socket ` +
+      `path is capped near ${SOCKET_MAX}.\n  Run seisin with a shorter TMPDIR (TMPDIR=/tmp/<short> seisin run …).`);
+  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");
+  // srt's settings have no field for the Mach names to register: beside them,
+  // where srt-mach.mjs looks for them.
+  if (machRegister.length && sandbox.name === "srt")
+    writeFileSync(join(dirname(file), MACH_FILE), JSON.stringify({ register: machRegister }), { mode: 0o600 });
+  const wrap = (inner) => sandbox.wrap(bin, file, settings, inner, { role, machRegister });
 
   // 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.
@@ -154,13 +246,29 @@ export async function run(config, argv) {
   env.SEISIN_ROLE = role;
   env.SEISIN_CONFIG = config.path;
   env[SOCK_ENV] = sockPath;
+  // The handoff chain, for the hook's words only (handoff.js, CHAIN_ENV): set
+  // from the decision checked above, and removed otherwise, so a value the
+  // parent happened to have never reaches a run that was not handed work.
+  delete env[CHAIN_ENV];
+  if (handed) env[CHAIN_ENV] = JSON.stringify(handed.chain);
+  /**
+   * The declared toolchain goes first on PATH, under `read = "territory"`.
+   *
+   * Declaring `~/.venvs/api` and then having `python` resolve to whatever the
+   * parent's PATH found first is not having the toolchain. Only in that mode:
+   * under "all" the PATH is the parent's, as it has always been.
+   */
+  if (config.read === "territory") {
+    const bins = toolchainBins(config, config.roles[role], isDir);
+    if (bins.length) env.PATH = [...bins, ...(env.PATH ? [env.PATH] : [])].join(delimiter);
+  }
 
   /**
    * Reference keys: resolved here, by the parent, before anything is spawned.
    *
    * 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.
@@ -169,18 +277,44 @@ export async function run(config, argv) {
    * name, not a skipped key: a role that starts without a credential it
    * declared fails later, somewhere else, looking like something it is not.
    */
-  const resolved = resolveKeys(config, config.roles[role]);
-  const scratchKeys = theRun.keys;
-  if (resolved.some((r) => r.mode === "scratch")) mkdirSync(scratchKeys, { recursive: true, mode: 0o700 });
+  /**
+   * Each resolution is a line in the log: which key, which provider, which
+   * mode, whether it resolved. Never the value — the log is the record of what
+   * the policy did, and a secret in it would be a second plaintext copy with
+   * worse access control than the first. Shaped like the canary's line, a
+   * run-level event beside the verdicts, so readers that count verdicts skip it.
+   */
+  const resolved = resolveKeys(config, config.roles[role], {
+    record: ({ entry, mode, ok }) => append(logPath(config.root), {
+      // The variable's name and the provider, never the reference: a reference
+      // can carry what it points at (a provider that echoes it, a path that
+      // names the secret), and the log is read by more people than the policy.
+      event: "key", role, run: theRun.id.slice(0, 8), ...trace, key: entry.name, provider: entry.scheme, mode, ok,
+    }),
+  });
+  const runFileKeys = theRun.keys;
+  if (resolved.some((r) => r.mode === "run-file")) mkdirSync(runFileKeys, { recursive: true, mode: 0o700 });
   for (const { entry, mode, value } of resolved) {
     if (mode === "env") { env[entry.name] = value; continue; }
-    // `scratch`: the value lands in the per-run directory this process already
+    /**
+     * `inject`: the real value goes into the environment of `srt` — not the
+     * agent's. The settings this run already generated declare it under
+     * `credentials.envVars` with `mode: "mask"`, so the runtime reads the real
+     * value from its own environment, hands the sandboxed child a sentinel, and
+     * substitutes the real value back only on egress to the credential's hosts.
+     * `srt` runs outside the sandbox, and the sandboxed child gets the sentinel.
+     * This mode is Linux-only for now — see injectGate in keys.js. The value is
+     * still masked on stdout/stderr below, so a sentinel the agent reflects into
+     * its own output is covered too.
+     */
+    if (mode === "inject") { env[entry.name] = value; continue; }
+    // `run-file`: 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.
-    const file = join(scratchKeys, entry.name);
+    const file = join(runFileKeys, entry.name);
     writeFileSync(file, value, { mode: 0o600 });
     /**
      * Both names, because the world has two conventions and neither is ours.
@@ -195,7 +329,7 @@ export async function run(config, argv) {
      * the file was there and correct, and the variable it was announced under
      * was one kubectl has never heard of.
      *
-     * Setting both costs nothing and leaks nothing: in `scratch` mode the
+     * Setting both costs nothing and leaks nothing: in `run-file` mode the
      * value is deliberately not in the environment, so both variables hold a
      * path and neither holds a secret.
      */
@@ -229,14 +363,43 @@ export async function run(config, argv) {
     env.XDG_STATE_HOME = join(home, ".local", "state");
     env.XDG_CACHE_HOME = join(home, ".cache");
     env.TMPDIR = join(home, "tmp");
+    // zsh writes its heredocs to $TMPPREFIX, not $TMPDIR, and defaults it to
+    // /tmp/zsh — which the role cannot write. Every heredoc in every zsh script
+    // failed with the role's own tmp a directory away (measured by an orchestrator running zsh scripts).
+    env.TMPPREFIX = join(home, "tmp", "zsh");
   }
+  env.TMPDIR = runTmp;
+  env.CLAUDE_CODE_TMPDIR = runTmp;
+  // zsh writes heredocs to $TMPPREFIX (default /tmp/zsh), not $TMPDIR: see
+  // the isolated-home note above. Same answer for every run now.
+  env.TMPPREFIX = join(runTmp, "zsh");
+  delete env.CLAUDE_TMPDIR;
   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) · ` +
-    `env ${Object.keys(env).length} kept, ${dropped.length} dropped` +
+    `${C.dim}seisin: ${role} · writes ${territory}${scratch > 0 ? ` (+${scratch} scratch)` : ""} · ` +
+    `keys ${r.keys.length ? r.keys.join(" ") : "none"} · ` +
+    `${agent ? `runs ${agent}` : "runs no agent seisin knows"} · ` +
+    `env ${Object.keys(env).length} kept, ${dropped.length} dropped · read ${config.read}` +
     `${observe ? ` · ${C.yellow}OBSERVING — the repo is writable, the network is NOT${C.off}${C.dim}` : ""}${C.off}\n`
   );
 
@@ -267,11 +430,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.
    *
@@ -281,12 +444,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
@@ -296,8 +459,73 @@ export async function run(config, argv) {
   // one request per role, and a denial logged against the role that owns the
   // 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 });
+  /**
+   * Linux, `read = "territory"`: the runtime's own temp directory moves into
+   * this run's, and the agent gets its TMPDIR back.
+   *
+   * sandbox-runtime makes the sockets its in-sandbox bridge reaches the proxy
+   * through in `os.tmpdir()` — of the runtime's process. With /tmp a data root
+   * and denied, the bridge found nothing and the whole network died in
+   * silence: every allowed host and `local_ports` refused like the rest
+   * (measured in Docker, Debian 12, bwrap 0.8.0). The run's directory is
+   * already readable from inside, so the sockets go there; the `env` the
+   * command runs through puts the agent's TMPDIR back as it was.
+   */
+  const agentTmp = env.TMPDIR;
+  const restoreTmp = [];
+  if (sandbox.name === "srt" && process.platform === "linux" && config.read === "territory") {
+    const srtTmp = join(theRun.dir, "srt");
+    mkdirSync(srtTmp, { recursive: true, mode: 0o700 });
+    env.TMPDIR = srtTmp;
+    restoreTmp.push(...(agentTmp ? [`TMPDIR=${agentTmp}`] : ["-u", "TMPDIR"]));
+  }
+
+  /**
+   * The canary, before anything of the agent's starts — and before the kernel
+   * watcher below, so its own denials are not recorded as the agent's. See
+   * canary.js. A failure stops the run with its own exit code and a line in
+   * the log; there is no flag to skip it.
+   */
+  const probe = await runCanary({
+    wrap, settingsFile: file, settings, env, cwd: process.cwd(),
+    runDir: theRun.dir, runsRoot: theRun.root, role: config.roles[role],
+    granted: writePathsOf(config, config.roles[role], { observe, agent }),
+  });
+  if (!probe.ok) {
+    append(logPath(config.root), {
+      event: "canary", role, run: theRun.id.slice(0, 8), ...trace, agent: agent ?? null, confined: false, reasons: probe.failed,
+      ...(sandbox.name === DEFAULT_SANDBOX ? {} : { sandbox: sandbox.name }),
+    });
+    err(`${C.red}seisin: ${role} was NOT started — the sandbox failed its canary:${C.off}\n` +
+      probe.failed.map((f) => `  - ${f}\n`).join("") +
+      `  The policy as generated does not hold on this machine, so no agent runs under it. ` +
+      `This is recorded in the log (confined=false). Exit 86 means the boundary did not hold; ` +
+      `run seisin check, fix the reported policy or machine setup, and try again. There is no flag to skip it.\n`);
+    process.exit(CANARY_EXIT);
+  }
+  append(logPath(config.root), {
+    event: "canary", role, run: theRun.id.slice(0, 8), ...trace, agent: agent ?? null, confined: true, reasons: [],
+    ...(sandbox.name === DEFAULT_SANDBOX ? {} : { sandbox: sandbox.name }),
+  });
+  // Said once, only when it is not the default: which sandbox holds this run
+  // is a fact a reader of the terminal would otherwise have to guess.
+  if (sandbox.name !== DEFAULT_SANDBOX) err(`${C.dim}seisin: ${role} runs under ${sandbox.name}${C.off}\n`);
+  // Said at the start, not discovered from a log that stayed empty.
+  if (!sandbox.tagsDenials && process.platform === "darwin")
+    err(`${C.yellow}seisin: ${sandbox.name} does not tag its denials, so none of the kernel's denials in this run are recorded ` +
+      `(tags_denials in docs/sandboxes.md)${C.off}\n`);
+  // Recorded once the receiver is confined and about to start, not before: a
+  // run that failed its canary did not take the work.
+  if (handed) {
+    recordHandoff(requestsPath(config.root), handed.request.key, handed.request.handoff);
+    err(`${C.dim}seisin: ${role} took ${handed.request.key} — handoff chain ${handed.chain.visited.join(" → ")}, ` +
+        `${handed.chain.depth} of ${MAX_DEPTH}${C.off}\n`);
+  }
+
+  const boxed = ["env", ...restoreTmp, `SEISIN_RUN_ID=${theRun.id}`, ...loopbackVia(config.roles[role], cmd, sandbox.name)];
+  // The tag is sandbox-runtime's: under any other sandbox there is none to
+  // match, and attribution goes by the process tree alone (violations.js).
+  denials = watchDenials(take.fromKernel, { argv: sandbox.tagsDenials ? boxed : null });
 
   // 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
@@ -316,7 +544,8 @@ export async function run(config, argv) {
   const nested = nestedSandboxWarning(cmd);
   if (nested) err(`${C.yellow}seisin: ${nested}${C.off}\n`);
 
-  const child = spawn(srt, ["--settings", file, "--", ...boxed], {
+  const [runner, ...runnerArgs] = wrap(boxed);
+  const child = spawn(runner, runnerArgs, {
     stdio: outStream ? ["inherit", "pipe", "pipe"] : "inherit",
     env,
   });
@@ -372,8 +601,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;
 
@@ -387,32 +619,65 @@ 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.
-    const { attributed, foreign } = denials.stats;
-    const { offPolicy, walks } = take.stats;
+    const { attributed, dropped } = denials.stats;
+    // The one loss the filter above does not explain: the system log could not
+    // keep up and threw lines away before seisin saw them. The boundary held;
+    // the record did not. Said every time, and written down, because a denial
+    // that never arrived files no request and nothing else would show it.
+    if (dropped) {
+      append(logPath(config.root), { event: "log-dropped", role, run: theRun.id.slice(0, 8), ...trace, batches: dropped });
+      err(`${C.yellow}seisin: the system log dropped ${dropped} batch(es) of messages during this run: ` +
+          `kernel denials may be missing from the log and the queue. ` +
+          `\`seisin check --system-log\` says what is flooding it.${C.off}\n`);
+    }
+    const { offPolicy, walks, expected, probes, atomic, browsers } = take.stats;
+    // A browser that died at start on its Mach rendezvous: the crash the agent
+    // saw does not say why, and this is the line that does.
+    for (const b of browsers)
+      err(`${C.yellow}seisin: ${role} started ${b} and the sandbox denied the Mach service it registers at start, so it ` +
+        `exited. Add browsers = ["${b}"] to [roles.${role}] in seisin.toml (docs/browsers.md).${C.off}\n`);
+    // A save refused at its temporary file, beside a file this role may write:
+    // the file was not saved, and nothing was queued because there is nothing
+    // to grant (the temporary name changes every time). Said whether or not
+    // anything else was recorded, because the agent's error said neither.
+    if (atomic.length) {
+      const files = [...new Set(atomic)];
+      err(`${C.yellow}seisin: ${files.length} file(s) ${role} may write were not saved: the save's temporary file beside ` +
+          `${files.slice(0, 3).join(", ")}${files.length > 3 ? ` and ${files.length - 3} more` : ""} was denied ` +
+          `(Claude Code's Edit and Write). \`seisin check ${role}\` says whether a grant can fix it.${C.off}\n`);
+    }
     const recorded = attributed - offPolicy - walks;
     if (recorded > 0)
       err(`${C.dim}seisin: ${recorded} kernel denial(s) recorded` +
           `${walks ? `, ${walks} directory scan(s)` : ""}` +
-          `${offPolicy ? `, ${offPolicy} outside the policy's paths` : ""}` +
-          `${foreign ? `, ${foreign} from other sandboxes` : ""}${C.off}\n`);
+          `${offPolicy ? `, ${offPolicy} outside the policy's paths` : ""}${C.off}\n` +
+          // Claude Code's plugin updater, refused correctly: said as expected so
+          // it does not read as the run failing (kinds.js expectedOf).
+          (expected ? `${C.dim}seisin: ${expected} of them expected: ${EXPECTED.plugins}${C.off}\n` : "") +
+          // The caller's own probes: denied as it asked, and nothing to grant.
+          (probes ? `${C.dim}seisin: ${probes} of them expected by the caller (--expect-denied) — nothing queued${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 = queueOf(config);
+    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
@@ -427,11 +692,90 @@ export async function run(config, argv) {
     // Every run with a key paid it — measured 3.0 s against 1.2 s without keys.
     // `finished()` settles at once for a stream that is already done.
     const guard = setTimeout(() => process.exit(status), 2000);
-    outStream.end();
-    errStream.end();
+    // A child's exit is not its pipes' EOF. Let pipe() end the redactors
+    // after the remaining stdout/stderr arrives; ending them here lost that
+    // output. The guard still bounds a descendant that keeps a pipe open.
     await Promise.all([finished(outStream), finished(errStream)]).catch(() => {});
     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);
+  });
+}
+
+/**
+ * `--handoff <id>`: this run is the role a pending request was handed to.
+ *
+ * The flag names a request, never a role. Which role takes it is the decision
+ * handoff.js makes from the policy as it stands, and a run of any other role
+ * is refused — so whatever starts roles can act on `handoff.role` but cannot
+ * substitute its own choice, and a model upstream of it choosing "backend"
+ * changes nothing. What the run carries forward is the chain the decision
+ * extends; every request it files is recorded in that chain, which is how a
+ * cycle back to a role the work came from, or a chain past its depth, is
+ * caught instead of routed.
+ */
+export function handoffOf(config, role, mine) {
+  const at = mine.indexOf("--handoff");
+  if (at === -1) return null;
+  // Said before the request is looked up: whatever the id, this role is not
+  // one the policy hands work to, and that is the answer.
+  if (config.roles[role]?.handoff === false)
+    throw new Error(`${role} does not take handed work (handoff = false in its role): no request is handed to it. Nothing was started.`);
+  const id = mine[at + 1];
+  if (!id || id.startsWith("-")) throw new Error("usage: seisin run <role> --handoff <id> -- <command...> (the id from seisin requests)");
+  const request = queueOf(config).find((r) => r.key === id);
+  if (!request) throw new Error(`no pending request has the id "${id}" — seisin requests lists them`);
+  const d = request.handoff;
+  if (d.type !== "route")
+    throw new Error(`${id} is not handed to anybody: ${describeHandoff(d, request.attempt)}. Nothing was started.`);
+  if (d.role !== role)
+    throw new Error(`${id} is handed to ${d.role}, not ${role}: the policy decides who takes it. Nothing was started.`);
+  return { request, chain: chainFrom(d) };
+}
+
+/**
+ * `--expect-denied <path>`, as many times as given: the paths whose denial the
+ * caller is waiting for (intake.js). Read from this process's argv and nowhere
+ * else — not the environment, not a file in the repo — because everything
+ * else is something the sandboxed side could reach, and a list it could add
+ * to would be a way to keep its own denials out of the queue.
+ *
+ * A path, exactly. A glob is refused rather than read literally: `*` meaning
+ * "this one file" is not what anyone who typed it meant, and meaning "every
+ * file" would make a probe a way to silence a whole directory.
+ */
+export function expectedDenials(mine) {
+  const out = [];
+  for (let i = 0; i < mine.length; i++) {
+    if (mine[i] !== "--expect-denied") continue;
+    const p = mine[++i];
+    if (!p || p.startsWith("-") || !p.trim())
+      throw new Error("usage: seisin run <role> --expect-denied <path> -- <command...> (a path, relative to the repo or absolute)");
+    if (WILD.test(p))
+      throw new Error(`--expect-denied ${p}: a path, not a pattern. Only a denial of exactly that path is expected; ` +
+        `name each one with its own --expect-denied.`);
+    out.push(p);
+  }
+  return out;
+}
+
+/** Is `name` a program the role can start with this PATH? */
+/** Where `name` resolves on `path`, absolute, or null. */
+function whichOn(name, path) {
+  if (!name) return null;
+  if (name.includes("/")) return existsSync(name) ? resolve(name) : null;
+  for (const d of (path ?? "").split(delimiter)) if (d && existsSync(join(d, name))) return join(d, name);
+  return null;
+}
+
+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)));
 }