seisin 0.5.0 → 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, withDeclarers } 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 { 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,71 +50,27 @@ const HERE = dirname(fileURLToPath(import.meta.url));
  */
 const DRAIN_MS = 250;
 
-/**
- * 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({ 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 (path ?? "").split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join(dir, "srt");
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-const RUNTIME = "@anthropic-ai/sandbox-runtime";
+// 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 `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.
+ * 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 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 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) {
@@ -129,12 +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 unknownRole(config, role);
+  const agent = agentFor(mine, cmd);
 
   /**
    * seisin does not run inside seisin, and says so here rather than later.
@@ -161,6 +129,9 @@ export async function run(config, argv) {
       `  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 sandbox gets a socket instead of a directory. That is the whole
@@ -173,7 +144,7 @@ export async function run(config, argv) {
   // Built before the first request can arrive; the POST leaves from here, the
   // 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();
   /**
@@ -182,7 +153,7 @@ export async function run(config, argv) {
    * 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
+   * 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
@@ -202,18 +173,72 @@ export async function run(config, argv) {
   // 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 });
+  // 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. ${installHint()}`);
+  // 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.
@@ -221,6 +246,22 @@ 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.
@@ -236,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
     // 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.
@@ -262,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.
      */
@@ -296,7 +363,17 @@ 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`);
 
@@ -321,7 +398,8 @@ export async function run(config, argv) {
   err(
     `${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` +
+    `${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`
   );
 
@@ -381,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)];
-  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
@@ -401,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,
   });
@@ -490,19 +634,48 @@ export async function run(config, argv) {
     // 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` : ""));
 
     // 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 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();
@@ -519,8 +692,9 @@ 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);
@@ -534,26 +708,74 @@ export async function run(config, argv) {
   });
 }
 
-/** 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)));
+/**
+ * `--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) };
 }
 
 /**
- * How to put the runtime back, for the way this seisin was installed.
+ * `--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.
  *
- * 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.
+ * 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 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`;
+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)));
 }