seisin 0.5.0 → 0.6.0

package/src/rundir.js

@@ -1,15 +1,15 @@
 /**
  * One private directory per run, for everything that belongs to that run only:
- * the audit socket, the sandbox settings, and `scratch` keys.
+ * the audit socket, the sandbox settings, and `run-file` keys.
  *
  * ── Why ──
  * These lived in two places and both leaked. The settings were written to
  * `.seisin/<role>.json`, one file per ROLE, so two runs of the same role — an
  * orchestrator does that all day — wrote the same file with different socket
- * paths, and one could start with the other's. The socket and the scratch keys
+ * paths, and one could start with the other's. The socket and the run-file keys
  * lived in `$TMPDIR/seisin-XXXX/`, private by mode, but every role runs as the
  * same user and every role can read the temp dir: measured on 2026-09-23, one
- * role read another's `scratch` key while it ran (`cat …/keys/S` → the value).
+ * role read another's `run-file` key while it ran (`cat …/keys/S` → the value).
  *
  * ── How ──
  * All runs live under one root, `$TMPDIR/snr/`, and each role's profile denies
@@ -28,6 +28,14 @@ import { channelName } from "./spool.js";
 import { alive } from "./log.js";
 
 export const RUNS_NAME = "snr";
+/**
+ * Where a run's temp directory lives when the role may write no other: beside
+ * the runs root, not inside it. The runs root is denied to writes as a whole
+ * (srt.js), and a deny wins over any grant beneath it.
+ */
+export const TMP_NAME = "snt";
+/** The settings file inside a run's directory. srt.js denies it to the run by this name. */
+export const SETTINGS_NAME = "settings.json";
 
 /**
  * The root every run lives under, created private, and checked.
@@ -36,8 +44,8 @@ export const RUNS_NAME = "snr";
  * dir sits behind /var → /private/var. Refused rather than used when it is not
  * a directory of this user's with nobody else's bits on it: it holds keys.
  */
-export function runsRoot(base = tmpdir()) {
-  const root = join(realOrSelf(base), RUNS_NAME);
+export function runsRoot(base = tmpdir(), name = RUNS_NAME) {
+  const root = join(realOrSelf(base), name);
   try { mkdirSync(root, { mode: 0o700 }); } catch (e) { if (e.code !== "EEXIST") throw e; }
   const st = lstatSync(root);
   const mine = typeof process.getuid !== "function" || st.uid === process.getuid();
@@ -53,7 +61,7 @@ export function runsRoot(base = tmpdir()) {
  * Removes the directories of runs whose process is gone.
  *
  * A run cleans up after itself on exit. A run that is killed does not, and
- * its directory keeps its `scratch` keys on disk indefinitely — measured by
+ * its directory keeps its `run-file` keys on disk indefinitely — measured by
  * SIGKILL on a keyed run. Swept at the start of the next one; a directory
  * without a pid file is younger than the write that creates it, and is left.
  */
@@ -64,7 +72,10 @@ function sweep(root) {
     try { pid = Number(readFileSync(join(dir, "pid"), "utf8")); } catch { continue; }
     // Only a process the kernel says is gone: a directory kept one sweep too
     // long costs disk, one removed early takes a live run's socket and keys.
-    if (pid && !alive(pid)) rmSync(dir, { recursive: true, force: true });
+    if (pid && !alive(pid)) {
+      rmSync(dir, { recursive: true, force: true });
+      rmSync(join(dirname(root), TMP_NAME, name), { recursive: true, force: true });
+    }
   }
 }
 
@@ -88,17 +99,27 @@ export function openRun({ base = tmpdir(), id = randomUUID() } = {}) {
     // socket inside the sandbox (spool.js).
     sock: join(dir, channelName()),
     keys: join(dir, "keys"),
+    /**
+     * This run's own temp directory, made on first call: only a run whose role
+     * may write no temp directory of its own needs one (commands/run.js).
+     */
+    tmp() {
+      const at = join(runsRoot(base, TMP_NAME), basename(dir));
+      mkdirSync(at, { recursive: true, mode: 0o700 });
+      return at;
+    },
     /**
      * `wx`: created by this call or not at all. A settings file that already
      * exists is not this run's, and the runtime would read whatever it says.
      */
     writeSettings(settings) {
-      const file = join(dir, "settings.json");
+      const file = join(dir, SETTINGS_NAME);
       writeFileSync(file, JSON.stringify(settings, null, 2) + "\n", { flag: "wx", mode: 0o600 });
       return file;
     },
     close() {
       try { rmSync(dir, { recursive: true, force: true }); } catch {}
+      try { rmSync(join(dirname(root), TMP_NAME, basename(dir)), { recursive: true, force: true }); } catch {}
     },
   };
 }

package/src/sandboxes/command.js

@@ -0,0 +1,93 @@
+/**
+ * A sandbox declared in seisin.toml: a command with a placeholder.
+ *
+ *   [sandbox.providers.mybox]
+ *   command = ["mybox", "run", "--policy", "{policy}", "--"]
+ *
+ * The same shape as a key provider (keys.js), for the same reason: adding a
+ * sandbox is three lines of TOML and no code. seisin replaces `{policy}` with
+ * the path of the run's settings file and appends the command to run. The
+ * contract the provider takes on is in docs/sandboxes.md; the short form:
+ *
+ *   - the file is the settings seisin generates, in sandbox-runtime's schema;
+ *   - the provider enforces every field of it, or exits non-zero before
+ *     running anything — it never runs the command with less;
+ *   - it passes the command's exit status through.
+ *
+ * seisin cannot see inside a provider, so it asks: with a `check` command
+ *
+ *   check = ["mybox", "check", "--policy", "{policy}"]
+ *
+ * the provider says before anything runs whether it can hold a policy (exit 0)
+ * or not (anything else, the last line it prints saying why), and one that
+ * cannot is passed over like a built-in one. Without `check` there is nothing
+ * to ask, and `unmet` has nothing to say.
+ *
+ * Neither answer is taken on faith: every run starts with the canary
+ * (canary.js) under the same provider and the same file, and the agent starts
+ * only if the boundary held. A provider that ignores the file fails there.
+ */
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, delimiter, isAbsolute, basename } from "node:path";
+
+export const POLICY_PLACEHOLDER = "{policy}";
+
+function onPath(name, path = process.env.PATH) {
+  if (name.includes("/")) return isAbsolute(name) && existsSync(name) ? name : null;
+  for (const dir of (path ?? "").split(delimiter)) if (dir && existsSync(join(dir, name))) return join(dir, name);
+  return null;
+}
+
+/** Long enough for a sandbox to read a file and say no; short enough that a hung one is found out. */
+const CHECK_TIMEOUT_MS = 15000;
+
+const withPolicy = (args, file) => args.map((a) => a.split(POLICY_PLACEHOLDER).join(file));
+
+/**
+ * Runs a sandbox's own pre-check on the settings file.
+ *
+ * `unmet` is `[]` when it answered yes; otherwise one sentence, its own reason
+ * when it gave one. A check that cannot answer (not found, killed, timed out)
+ * is a no: an answer that never came is not a pass. `warnings` are the lines
+ * it printed that start with `warning:`, yes or no — what it holds, but not the
+ * way the role might expect (tartaros on Linux, a repo root it cannot let the
+ * role create entries in) — for `seisin check` to show.
+ */
+export function assessCheck(argv, file, label) {
+  const r = spawnSync(argv[0], withPolicy(argv.slice(1), file), { encoding: "utf8", timeout: CHECK_TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+  // Its own name off the front: "mybox: no domains" reads twice after "mybox says".
+  // stdout before stderr, so a report on stdout does not bury a refusal on stderr.
+  const self = `${basename(argv[0])}:`;
+  const said = `${r.stdout ?? ""}\n${r.stderr ?? ""}`.split("\n").map((l) => l.trim()).filter(Boolean)
+    .map((l) => (l.startsWith(self) ? l.slice(self.length).trim() : l));
+  const warnings = said.filter((l) => /^warning:/i.test(l)).map((l) => l.replace(/^warning:\s*/i, ""));
+  if (r.status === 0) return { unmet: [], warnings };
+  // The last line: what comes before it can be warnings about what it did hold
+  // (tartaros says which patterns its own set covers), and the no comes last.
+  const why = r.error?.code === "ETIMEDOUT" ? `it did not answer in ${CHECK_TIMEOUT_MS / 1000} s`
+    : r.error ? r.error.message
+    : said.length ? said.at(-1)
+    : r.signal ? `it was killed by ${r.signal}` : `it exited ${r.status} without saying why`;
+  return { unmet: [`${label} says it cannot hold this policy: ${why}`], warnings };
+}
+
+/** Only the answer: `[]` for yes, the reason for no. */
+export const askCheck = (argv, file, label) => assessCheck(argv, file, label).unmet;
+
+export function commandSandbox(name, command, check = null, { tagsDenials = false } = {}) {
+  const assess = (_settings, { file } = {}) => (check ? assessCheck(check, file, `its check (${check[0]})`) : { unmet: [], warnings: [] });
+  return {
+    name,
+    locate: () => onPath(command[0]),
+    missing: () => `${command[0]} (the command of [sandbox.providers.${name}]) was not found${command[0].includes("/") ? "" : " on PATH"}.`,
+    asksFile: Boolean(check),
+    assess,
+    unmet: (settings, ctx) => assess(settings, ctx).unmet,
+    wrap: (bin, file, _settings, inner) => [bin, ...withPolicy(command.slice(1), file), ...inner],
+    // Declared, not detected: `tags_denials = true` says its Seatbelt denials
+    // carry sandbox-runtime's tag (docs/sandboxes.md). Without it, on macOS,
+    // none of the kernel's refusals under it reach the log.
+    tagsDenials,
+  };
+}

package/src/sandboxes/index.js

@@ -0,0 +1,113 @@
+/**
+ * Which sandbox a role runs under.
+ *
+ * seisin decides the policy; a sandbox enforces it. There are three ways in:
+ *
+ *   - `srt` (built in, the default): @anthropic-ai/sandbox-runtime;
+ *   - `tartaros` (built in): reads the settings file itself (`--settings`);
+ *   - any name declared under `[sandbox.providers.<name>]`: a command that
+ *     takes the settings file (command.js, docs/sandboxes.md).
+ *
+ * `[sandbox] provider` names one, or several in order of preference:
+ *
+ *   [sandbox]
+ *   provider = ["tartaros", "srt"]
+ *
+ * The choice is a capability question, not a preference toggle
+ * (docs/decisions.md): each role gets the first one that is installed and
+ * enforces every part of that role's settings. One that would enforce less is
+ * passed over with the reason, and a role none of them can hold does not start.
+ * A single name means exactly that one, so a config that asks for tartaros
+ * never ends up somewhere else without having said so.
+ */
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { srt } from "./srt.js";
+import { machOf } from "../browsers.js";
+import { tartaros } from "./tartaros.js";
+import { commandSandbox } from "./command.js";
+
+export const BUILTIN_SANDBOXES = { srt, tartaros };
+export const DEFAULT_SANDBOX = "srt";
+
+/** The sandboxes the config names, in its order, as provider objects. */
+export function sandboxesOf(config) {
+  const names = config.sandbox?.provider ?? [DEFAULT_SANDBOX];
+  return names.map((n) => BUILTIN_SANDBOXES[n] ?? commandSandbox(n, config.sandbox.providers[n].command, config.sandbox.providers[n].check, { tagsDenials: config.sandbox.providers[n].tagsDenials }));
+}
+
+/**
+ * For each sandbox the config names, whether it could run these settings and
+ * why not. `chosen` is the first that can, or null.
+ *
+ * A sandbox that answers for itself (tartaros, a declared one with `check`) is
+ * asked about the file a run would hand it: `file` when the run has written
+ * one, otherwise a copy in a temp directory of its own, removed after. Only a
+ * sandbox that was found is asked; one that was not is passed over as missing.
+ */
+export function weigh(config, settings, { platform = process.platform, role = null, locate = true, file = null } = {}) {
+  const list = sandboxesOf(config);
+  const register = role ? machOf(config.roles?.[role]).register : [];
+  let scratch = null;
+  let copies = 0;
+  // The file a sandbox is asked about is the one it would be handed: the run's
+  // own when it takes the settings as they are, otherwise its own version of them.
+  const fileFor = (own) => {
+    if (file && own === settings) return file;
+    scratch ??= mkdtempSync(join(tmpdir(), "seisin-weigh-"));
+    const f = join(scratch, `settings-${copies++}.json`);
+    writeFileSync(f, JSON.stringify(own, null, 2), { mode: 0o600 });
+    return f;
+  };
+  try {
+    const options = list.map((sandbox) => {
+      const bin = locate ? sandbox.locate() : "(not looked up)";
+      const own = settingsOf(sandbox, settings, { machRegister: register });
+      const asked = sandbox.asksFile && locate && bin;
+      const ctx = { platform, role, bin, file: asked ? fileFor(own) : null };
+      const { unmet, warnings } = sandbox.asksFile && !asked ? { unmet: [], warnings: [] }
+        : sandbox.assess ? sandbox.assess(own, ctx) : { unmet: sandbox.unmet(own, ctx), warnings: [] };
+      // `browsers`: a Mach service to register. srt's schema has no field for it
+      // (srt-mach.mjs adds it); tartaros takes it as network.allowMachRegister
+      // (adapt). A sandbox that is given it neither way cannot hold the role.
+      const browser = register.length && !sandbox.machRegister
+        ? [`a Mach service to register (${register.join(", ")}, for browsers): ${sandbox.name} is not given it, only srt and tartaros are`]
+        : [];
+      return { sandbox, bin, unmet: [...unmet, ...browser], warnings, missing: bin ? null : sandbox.missing() };
+    });
+    const chosen = options.find((o) => o.bin && o.unmet.length === 0) ?? null;
+    return { chosen, options };
+  } finally {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The settings as this sandbox is handed them: as generated, or with what it
+ * takes in its own field (tartaros: network.allowMachRegister). The same
+ * object when nothing changes, so a caller can tell.
+ */
+export function settingsOf(sandbox, settings, ctx) {
+  return sandbox.adapt ? sandbox.adapt(settings, ctx) : settings;
+}
+
+/** The sandbox and binary for one run, or an Error that says why each was passed over. */
+export function chooseSandbox(config, settings, { platform = process.platform, role = null, file = null } = {}) {
+  const { chosen, options } = weigh(config, settings, { platform, role, file });
+  if (chosen) return { sandbox: chosen.sandbox, bin: chosen.bin, options };
+  // The one sandbox there is, missing: said exactly as it always was.
+  if (options.length === 1 && options[0].missing && options[0].sandbox.name === DEFAULT_SANDBOX)
+    return { error: new Error(options[0].missing), options };
+  return { error: new Error(refusal(role, options)), options };
+}
+
+export function refusal(role, options) {
+  const lines = options.map((o) => o.missing
+    ? `  - ${o.sandbox.name}: ${o.missing}`
+    : `  - ${o.sandbox.name} cannot enforce all of it:\n${o.unmet.map((u) => `      ${u}`).join("\n")}`);
+  return `no sandbox in [sandbox] provider can hold ${role ? `role ${role}` : "this role"} as its policy is written, so it was not started:\n` +
+    `${lines.join("\n")}\n` +
+    `  A sandbox that enforces less than the policy is never used in its place. Add one that can (provider = [..., "srt"]), ` +
+    `or change the role.`;
+}

package/src/sandboxes/mach-profile.js

@@ -0,0 +1,31 @@
+/**
+ * The splice srt-mach.mjs makes into srt's profile, kept apart so it can be
+ * tested without loading into srt. See srt-mach.mjs for why it exists.
+ */
+import { MACH_PREFIX } from "../browsers.js";
+
+export const MACH_FILE = "mach.json";
+const ANCHOR = "/usr/bin/sandbox-exec -p '";
+
+export function fail(why) {
+  throw new Error(`seisin: cannot add the browser's Mach rule to the sandbox profile: ${why}`);
+}
+
+/** The profile with the rules appended, or an Error: exported so the splice is tested without srt. */
+export function withRules(line, register) {
+  for (const name of register) if (!MACH_PREFIX.test(name)) fail(`"${name}" is not a Mach name prefix`);
+  const at = line.indexOf(ANCHOR);
+  if (at === -1) fail("srt no longer runs sandbox-exec with an inline profile");
+  if (line.indexOf(ANCHOR, at + 1) !== -1) fail("the command holds more than one profile");
+  const start = at + ANCHOR.length;
+  // Single-quoted by srt's quote(), which writes a quote inside it as '"'"'
+  // (a comment in the profile says "doesn't"). The quote that ends it is the
+  // first one that does not open that sequence, and the shell's path follows.
+  let end = line.indexOf("'", start);
+  while (end !== -1 && line.startsWith(`'"'"'`, end)) end = line.indexOf("'", end + 5);
+  if (end === -1 || line[end + 1] !== " ") fail("the profile is not quoted the way it was");
+  if (!line.slice(start, end).startsWith("(version 1)")) fail("the profile does not start with (version 1)");
+  const rules = register.map((p) => `(allow mach-register (global-name-prefix "${p}"))`).join("\n");
+  return `${line.slice(0, end)}\n; seisin: browsers (src/browsers.js)\n${rules}\n${line.slice(end)}`;
+}
+

package/src/sandboxes/srt-mach.mjs

@@ -0,0 +1,43 @@
+/**
+ * Loaded into the `srt` process with `node --import`, for a role whose
+ * `browsers` need a Mach service registered (browsers.js).
+ *
+ * sandbox-runtime lets a policy name Mach services to look up
+ * (`allowMachLookup`) and has no field for registering one, which is what a
+ * Chromium browser process does first. So for those roles, and only those,
+ * this adds the one rule the profile cannot otherwise carry:
+ *
+ *   (allow mach-register (global-name-prefix "org.chromium.Chromium.MachPortRendezvousServer."))
+ *
+ * It wraps `SandboxManager.wrapWithSandbox` — the module instance srt's own CLI
+ * uses, loaded from beside it — and appends the rule to the profile that call
+ * returns, before srt runs it. Nothing else in the profile is touched, and
+ * every run still starts with the canary under the result.
+ *
+ * Fails closed. The names come from `mach.json` in the run's directory, which
+ * seisin writes; each is checked against the shape a prefix may have before
+ * it goes into the profile. And the profile must be where and what it was
+ * when this was written — `/usr/bin/sandbox-exec -p '(version 1)…'`, once. If
+ * a later srt builds its command another way, this throws, srt does not run
+ * the command, and the canary reports a sandbox that did not start (exit 86).
+ * A role that asked for a browser gets no browser; it never gets less sandbox.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { MACH_FILE, withRules, fail } from "./mach-profile.js";
+
+const at = process.argv.indexOf("--settings");
+const settings = at === -1 ? null : process.argv[at + 1];
+if (!settings) fail("srt was not given --settings");
+const { register } = JSON.parse(readFileSync(join(dirname(settings), MACH_FILE), "utf8"));
+if (!Array.isArray(register) || register.length === 0) fail(`${MACH_FILE} names nothing to register`);
+
+// The same file srt's CLI imports as "./index.js", so the same module instance.
+const cli = realpathSync(process.argv[1]);
+const { SandboxManager } = await import(pathToFileURL(join(dirname(cli), "index.js")).href);
+if (typeof SandboxManager?.wrapWithSandbox !== "function") fail("srt has no SandboxManager.wrapWithSandbox");
+const wrap = SandboxManager.wrapWithSandbox;
+SandboxManager.wrapWithSandbox = async function (...args) {
+  return withRules(await wrap.apply(this, args), register);
+};

package/src/sandboxes/srt.js

@@ -0,0 +1,163 @@
+/**
+ * `srt`: @anthropic-ai/sandbox-runtime, the sandbox seisin was built on.
+ *
+ * The default, and the reference every other provider is measured against:
+ * the settings seisin generates (srt.js, one level up) ARE this runtime's
+ * settings file, so it enforces all of them by construction and `unmet` is
+ * always empty. What a run hands it is the file and the command, nothing else.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, dirname, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 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";
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * The directory of the runtime's own `apply-seccomp`, or null.
+ *
+ * On Linux the runtime runs that binary INSIDE the sandbox, from wherever the
+ * package is installed, before the command. With `read = "territory"` a home
+ * directory is shut, and seisin installed under it — nvm, a user npm prefix,
+ * a CI checkout in /home/runner — left the binary unmountable: every run died
+ * with `apply-seccomp: No such file or directory` before the canary (measured
+ * on ubuntu-latest and in Debian with the checkout in /root, srt 0.0.81).
+ * Found from the srt that runs (its real path, up to the package), so a
+ * global srt keeps its own.
+ */
+export function seccompDir(bin = resolveSrt()) {
+  if (!bin) return null;
+  let dir;
+  try { dir = dirname(realpathSync(bin)); } catch { return null; }
+  for (;;) {
+    const pkg = join(dir, "package.json");
+    if (existsSync(pkg)) {
+      try {
+        if (JSON.parse(readFileSync(pkg, "utf8")).name === RUNTIME) {
+          const vendor = join(dir, "vendor", "seccomp");
+          return existsSync(vendor) ? vendor : null;
+        }
+      } catch { /* not the runtime's */ }
+    }
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/**
+ * 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`;
+}
+
+const MACH_PRELOAD = join(HERE, "srt-mach.mjs");
+
+/**
+ * srt with srt-mach.mjs loaded into it, for a role whose browsers register a
+ * Mach service. Run by this node, so the preload is in the process: the runtime
+ * is a node script, and one that is not (a binary on PATH) cannot take it —
+ * refused here rather than run without the rule the role asked for, which
+ * would start the browser just to watch it die.
+ */
+export function withMachPreload(bin, file, inner) {
+  const cli = realpathSync(bin);
+  if (!/\.(c|m)?js$/.test(cli))
+    throw new Error(`the sandbox runtime at ${bin} is not a node script, so the browser's Mach rule cannot be added to it ` +
+      `(browsers in seisin.toml). Use the runtime seisin installs with it.`);
+  return [process.execPath, "--import", MACH_PRELOAD, cli, "--settings", file, "--", ...inner];
+}
+
+export const srt = {
+  name: "srt",
+  locate: () => resolveSrt(),
+  missing: () => `sandbox runtime not found. ${installHint()}`,
+  unmet: () => [],
+  // `--` before the command, and it is not cosmetic. Without it the runtime's
+  // own argument parser reaches into what the agent was invoked with and eats
+  // anything resembling one of its flags: `claude --settings`, `claude -c`.
+  wrap: (bin, file, _settings, inner, { machRegister = [] } = {}) =>
+    machRegister.length ? withMachPreload(bin, file, inner) : [bin, "--settings", file, "--", ...inner],
+  // Takes the `browsers` Mach rule, through srt-mach.mjs.
+  machRegister: true,
+  // Each Seatbelt denial carries this runtime's tag with the wrapped command,
+  // which is how violations.js tells this run's denials from another's.
+  tagsDenials: true,
+};

package/src/sandboxes/tartaros.js

@@ -0,0 +1,80 @@
+/**
+ * `tartaros`: the Seatbelt / Landlock sandbox, driven by its own CLI.
+ *
+ * tartaros reads seisin's settings file itself (`--settings`, the schema of
+ * sandbox-runtime) and holds itself to the contract in docs/sandboxes.md:
+ * every field enforced, or it refuses to start. So seisin does not translate
+ * anything and does not keep its own list of what tartaros can do — a list
+ * like that is out of date the day tartaros learns something. It asks:
+ *
+ *   tartaros explain --settings <file>
+ *
+ * reads the same file through the same code as `run` and exits 78, with the
+ * reason, on a field it cannot guarantee (2 before 0.1.0-alpha.6, which keeps
+ * 2 for a bad command line). seisin takes any exit but 0 as that no, so the
+ * code is not read. That answer is what `unmet` returns,
+ * so a role tartaros cannot hold is passed over before it starts (or `seisin
+ * check` says so), and the canary still checks every run that it can.
+ */
+import { existsSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { assessCheck } from "./command.js";
+
+/** `tartaros` on PATH, or null. */
+export function resolveTartaros(path = process.env.PATH) {
+  for (const dir of (path ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, "tartaros");
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The command line for one run: the settings as they are, the role as a label. */
+export function tartarosArgv(bin, file, inner, { role = null, machRegister = [] } = {}) {
+  // A browser role gets tartaros's browser grants — the shared memory, IOKit
+  // classes and sysctls a headless Chromium dies without (f7edae1) — and a
+  // run-private TMPDIR, the only place it may open a unix socket (bcb0c69):
+  // where @playwright/mcp publishes its browser.
+  const browser = machRegister.length ? ["--browser", "--private-tmp"] : [];
+  // --inherit-env: the environment seisin hands tartaros is already the one
+  // the role gets — built from the role's own list (env.js), with the hook's
+  // socket, the role's name and its env-mode keys. tartaros's own scrub
+  // (7f9925f) would drop those, and the hook would go silent.
+  return [bin, "run", ...(role ? ["--role", role] : []), "--inherit-env", ...browser, "--settings", file, "--", ...inner];
+}
+
+/** What tartaros says of this file: what it cannot hold, and its warnings. Only asked of a binary that was found. */
+export function tartarosAssess(bin, file, { platform = process.platform } = {}) {
+  if (platform !== "darwin" && platform !== "linux") return { unmet: [`tartaros runs on macOS and Linux, not ${platform}`], warnings: [] };
+  return assessCheck([bin, "explain", "--settings", "{policy}"], file, "tartaros");
+}
+
+export const tartarosUnmet = (bin, file, ctx) => tartarosAssess(bin, file, ctx).unmet;
+
+/**
+ * `browsers`: tartaros takes the Mach names to register in its settings, as
+ * network.allowMachRegister with sandbox-runtime's trailing `*` for a prefix
+ * (tartaros 99b0117). Only when there is one: an unchanged role is handed the
+ * same file as before, and srt, whose schema is strict, never sees the field.
+ */
+export function tartarosSettings(settings, { machRegister = [] } = {}) {
+  if (!machRegister.length) return settings;
+  return { ...settings, network: { ...settings.network, allowMachRegister: machRegister.map((p) => `${p}*`) } };
+}
+
+export const tartaros = {
+  name: "tartaros",
+  locate: () => resolveTartaros(),
+  missing: () => "tartaros not found on PATH. Build it (cargo build --release -p tartaros-cli) and put its target directory on PATH.",
+  asksFile: true,
+  adapt: tartarosSettings,
+  machRegister: true,
+  assess: (_settings, { bin, file, platform } = {}) => tartarosAssess(bin, file, { platform }),
+  unmet: (_settings, { bin, file, platform } = {}) => tartarosUnmet(bin, file, { platform }),
+  wrap: (bin, file, _settings, inner, ctx) => tartarosArgv(bin, file, inner, ctx),
+  // Every deny in its Seatbelt profile carries sandbox-runtime's tag
+  // (`CMD64_<command>_END_<suffix>_SBX`), so violations.js attributes them
+  // exactly as it does srt's. Measured 2026-10-13 with tartaros ad85515.
+  tagsDenials: true,
+};

package/src/scan.js

@@ -18,7 +18,7 @@
  * to skip. Three things were wrong and all three are handled below.
  */
 import { readdirSync, readFileSync, statSync, realpathSync, existsSync } from "node:fs";
-import { join, relative, sep, dirname } from "node:path";
+import { join, resolve, relative, sep, dirname } from "node:path";
 import { covers } from "./owners.js";
 import { toWritePath } from "./grants.js";
 
@@ -151,7 +151,12 @@ export function scan(root, protectedDirs = [], ignore = [], limit = 500, { roots
   try { root = realpathSync.native(root); } catch { /* scanned as written */ }
   // `.secrets/` and `.secrets` are one directory. With the slash kept, the
   // prefix test below never matched and the protected directory was scanned.
-  const safe = protectedDirs.map((d) => join(root, d.replace(/\/+$/, "") || "."));
+  const safe = protectedDirs.map((d) => {
+    const path = resolve(root, d);
+    // The root was canonicalised above. Match the same spelling for absolute
+    // directories, including macOS's /var -> /private/var ancestor.
+    try { return realpathSync.native(path); } catch { return path; }
+  });
   const patterns = [...DEFAULT_IGNORE, ...ignore];
   const hits = [];
   const skipped = { ignored: 0, protectedDirs: 0, reference: 0, placeholder: 0, nested: 0 };
@@ -330,4 +335,3 @@ function repositoryOf(p, root) {
 function isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
-