seisin 0.6.5 → 0.7.1

package/README.md

@@ -168,12 +168,14 @@ own fixtures:
 
 Others are the sandbox's, and differ between the two built in:
 
-| | `srt` (the default) | `tartaros` |
+| | `tartaros` (the default) | `srt` |
 |---|---|---|
-| a process the agent leaves running | **macOS:** it outlives the run, whether it double-forks, ignores signals under `nohup` or calls `setsid` (measured 2026-10-16). **Linux:** the PID namespace ends with the run (read from its source) | **macOS:** the run's process group is killed; one that calls `setsid` outlives it (measured 2026-10-16). **Linux:** the run's cgroup is killed whole (read from its source) |
-| deleting inside the territory | write includes delete; the ask is upstream as [issue #545](https://github.com/anthropics/sandbox-runtime/issues/545) | not measured here |
-| `[network] deny_addresses` | enforced | not yet: a role that has it runs under `srt`, and `check` says why |
-| what it is | Anthropic's, described by its authors as a research preview | by the author of seisin, alpha |
+| a process the agent leaves running | **macOS:** the run's process group is killed; one that calls `setsid` outlives it (measured 2026-10-16). **Linux:** the run's cgroup is killed whole (read from its source) | **macOS:** it outlives the run, whether it double-forks, ignores signals under `nohup` or calls `setsid` (measured 2026-10-16). **Linux:** the PID namespace ends with the run (read from its source) |
+| deleting inside the territory | not measured here | write includes delete; the ask is upstream as [issue #545](https://github.com/anthropics/sandbox-runtime/issues/545) |
+| `[network] deny_addresses` | not yet: a role that has it runs under `srt` where it is installed, and `check` says why | enforced |
+| `local_binding = true` | refused (it grants ports one at a time): a role that has it runs under `srt` where it is installed | enforced |
+| `local_ports`, a client that skips the proxy (a database driver) | reaches the listed port: the kernel grants it | denied: only a client that honours the proxy gets there |
+| what it is | by the author of seisin, alpha | Anthropic's, described by its authors as a research preview |
 
 `seisin check` says which sandbox each role gets before anything runs.
 
@@ -196,18 +198,22 @@ or more.
 npm install -g seisin
 ```
 
-That pulls in [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime), the default sandbox: Seatbelt on macOS, bubblewrap on Linux. No containers, no VMs, no daemon. Its one other dependency is optional: [tartaros](https://github.com/carlostapiacl/tartaros), prebuilt for macOS and Linux, which can enforce instead, as can a sandbox of your own ([docs/sandboxes.md](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md)).
+That pulls in [tartaros](https://github.com/carlostapiacl/tartaros), the default sandbox, prebuilt for macOS and Linux: Seatbelt on macOS, Landlock and seccomp on Linux. No containers, no VMs, no daemon, and no other dependency. [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) (`srt`) is used where you install it apart, after tartaros: for a role tartaros cannot hold (a blanket `local_binding`, `deny_addresses`, a Linux host without Landlock), or anywhere `[sandbox] provider` names it. A sandbox of your own can enforce too ([docs/sandboxes.md](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md)).
 
-**On Linux you also need three system packages.** Without them the runtime refuses to start
+```bash
+npm install -g @anthropic-ai/sandbox-runtime@0.0.81   # optional: srt, for what tartaros cannot hold
+```
+
+**For srt on Linux you also need three system packages.** Without them srt refuses to start
 rather than run unconfined:
 
 ```bash
 apt install bubblewrap ripgrep socat      # or your distro's equivalent
 ```
 
-**On Ubuntu 24.04 and newer**, unprivileged user namespaces are off by default and
-bubblewrap needs one. Every run dies with `bwrap: No permissions to create new
-namespace`:
+**On Ubuntu 24.04 and newer**, unprivileged user namespaces are off by default. tartaros
+runs without them (with the limits in its docs/limits.md); bubblewrap, and so srt, needs one.
+Every srt run dies with `bwrap: No permissions to create new namespace`:
 
 ```bash
 sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
@@ -472,8 +478,8 @@ its own situation. **[The log, `review`, the console, the MCP server and walls
                                     explanation — never the boundary
 ```
 
-`sandbox-runtime` is the default enforcer, not the only one. `[sandbox] provider` picks another
-(`tartaros`, or any sandbox declared as a command) per role, and only where it enforces the whole
+tartaros is the default enforcer, not the only one. `[sandbox] provider` picks another
+(`srt`, or any sandbox declared as a command) per role, and only where it enforces the whole
 policy: see [docs/sandboxes.md](https://github.com/carlostapiacl/seisin/blob/main/docs/sandboxes.md).
 
 That split keeps seisin small. Because the kernel is the boundary, seisin does not have to be airtight, only *legible*. A leaky explainer costs you a confusing log line. A leaky enforcer costs you the repo.
@@ -508,7 +514,8 @@ writable: each run gets a temp directory of its own instead.
 
 ## Prior art
 
-[`sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) is the enforcement seisin sits on.
+[tartaros](https://github.com/carlostapiacl/tartaros) is the enforcement seisin sits on, and
+[`sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) the one it was built on.
 OpenShell, hazmat and nono isolate the agent from your machine; containers and microVMs isolate a
 process from the host. seisin separates roles from each other inside one repository, and names the
 owner when the kernel denies something. They compose: the agent seisin confines can run inside any
@@ -517,8 +524,8 @@ of them. **[Each one, and why not a container →](https://github.com/carlostapi
 ## Status
 
 CI runs the full suite on macOS and `ubuntu-latest`, Node 18/20/22/24, on every pull request and
-push to `main`. On 2026-11-02, on Node 24: macOS **1133 tests, 1124 passing, 9 skipped**;
-Linux **1132, 1103 passing, 29 skipped**. The skips are platform tests; the job fails if the 26
+push to `main`. On 2026-11-04, on Node 24: macOS **1135 tests, 1126 passing, 9 skipped**;
+Linux **1134, 1105 passing, 29 skipped**. The skips are platform tests; the job fails if the 26
 core boundary tests in `test/sandbox.test.js` skip. A release is published only from CI, after
 that passes, with npm provenance. [Which claim was measured where](https://github.com/carlostapiacl/seisin/blob/main/docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run),
 and [what running agents behind it cost](https://github.com/carlostapiacl/seisin/blob/main/docs/field-notes.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.6.5",
+  "version": "0.7.1",
   "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it denies something it tells you whose file it was.",
   "keywords": [
     "ai-agents",
@@ -42,10 +42,10 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.81"
+    "@carlostapiacl/tartaros": "0.1.0-alpha.24"
   },
-  "optionalDependencies": {
-    "@carlostapiacl/tartaros": "0.1.0-alpha.18"
+  "devDependencies": {
+    "@anthropic-ai/sandbox-runtime": "0.0.81"
   },
   "scripts": {
     "test": "node --test test/*.test.js",

package/src/cli.js

@@ -7,9 +7,9 @@
  * `commands/` and every decision lives in a module beside it, so that a change
  * to how something is printed cannot change what is allowed.
  *
- * Enforcement is not ours. @anthropic-ai/sandbox-runtime asks the operating
- * system — Seatbelt on macOS, bubblewrap on Linux — and the kernel does not
- * care how a command was spelled. What seisin adds is the part a kernel can
+ * Enforcement is not ours. The sandbox (tartaros by default, or
+ * sandbox-runtime) asks the operating system — Seatbelt on macOS, Landlock or
+ * bubblewrap on Linux — and the kernel does not care how a command was spelled. What seisin adds is the part a kernel can
  * never know: which role a path belongs to, and therefore who to ask next.
  */
 import { readFileSync } from "node:fs";
@@ -105,7 +105,7 @@ Any command takes --policy <file> (the policy, rooted at the working directory)
 both outside the repo (docs/runs.md).
 seisin help limits says what seisin cannot do, in any repo.
 
-Enforcement comes from the sandbox (sandbox-runtime by default, or tartaros), which asks the OS.
+Enforcement comes from the sandbox (tartaros by default, or sandbox-runtime), which asks the OS.
 seisin decides what to ask for, and says whose file it was when the answer is no.
 `;
 

package/src/commands/check.js

@@ -11,7 +11,7 @@ const say = out;
 import { measureSystemLog } from "../violations.js";
 import { join } from "node:path";
 import { settingsFor } from "../srt-settings.js";
-import { weigh } from "../sandboxes/index.js";
+import { weigh, DEFAULT_PROVIDERS } from "../sandboxes/index.js";
 import { runsRoot } from "../rundir.js";
 import { channelName } from "../spool.js";
 
@@ -81,7 +81,7 @@ export function sandboxes(config, only = null, { platform = process.platform, qu
   const out = quiet ? () => {} : say;
   const sock = join(runsRoot(), "check", channelName(platform));
   const rows = [];
-  out(`\n${C.b}sandboxes${C.off} (${(config.sandbox?.provider ?? ["srt"]).join(" → ")})\n`);
+  out(`\n${C.b}sandboxes${C.off} (${(config.sandbox?.provider ?? DEFAULT_PROVIDERS).join(" → ")})\n`);
   for (const r of Object.values(config.roles)) {
     if (only && r.name !== only) continue;
     let settings;

package/src/commands/run.js

@@ -32,6 +32,7 @@ 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 { scratchWarnings } from "../inspect/machine.js";
 import { append, logPath } from "../log.js";
 import { flagsOf } from "../help.js";
 import { WILD } from "../paths.js";
@@ -317,6 +318,12 @@ export async function run(config, argv) {
     `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`
   );
+  // `check` says this, and a run is where it costs: the role writes another role's
+  // files and the banner above reads as if it could not.
+  if (!observe) {
+    const around = scratchWarnings(config).find((w) => w.kind === "scratch");
+    if (around) err(`${C.yellow}seisin: ${around.headline}. ${around.detail}${C.off}\n`);
+  }
 
   // Redaction needs the output to pass through this process, and piping breaks
   // anything that draws its own screen. So it turns itself off on a terminal

package/src/config.js

@@ -526,7 +526,7 @@ const BUILTIN_SANDBOXES = ["srt", "tartaros"];
  * `[sandbox]`: which sandbox enforces the roles, and any declared by command.
  *
  * `provider` is one name or a list in order of preference; absent, it is
- * `srt`, as it always was. A name is one seisin ships or one declared under
+ * `["tartaros", "srt"]` (DEFAULT_PROVIDERS; `srt` alone before 0.7). A name is one seisin ships or one declared under
  * `[sandbox.providers.<name>]` — an unknown one is refused here, never read as
  * the default, because "the config asks for tartaros and the run used srt"
  * without a word is the silent substitution sandboxes/index.js exists to stop.

package/src/inspect/inject.js

@@ -29,15 +29,17 @@ export function injectWarnings(config, roles) {
     const allowed = r.network ?? config.allowedDomains ?? [];
 
     // Which sandbox masks is the sandbox's to say (sandboxes/, `masks`): on macOS
-    // only tartaros does, so a provider list without it cannot run the role here.
+    // only tartaros does without leaving the real value where the agent can read
+    // it, so a provider list without it cannot run the role here.
     const names = sandboxesOf(config).map((s) => s.name);
     if (process.platform === "darwin" && !names.includes("tartaros"))
       out.push({
         kind: "inject-platform",
         role: r.name,
         headline: `${r.name}: key_mode = "inject" needs tartaros on macOS — [sandbox] provider is ${names.join(", ")}`,
-        detail: `On macOS sandbox-runtime does not mask credentials yet (anthropics/sandbox-runtime#593), so ` +
-          `this role will not run here. Add tartaros: [sandbox] provider = ["tartaros", "srt"]. Or run it on ` +
+        detail: `On macOS sandbox-runtime masks credentials, but it holds the real value in its own environment, ` +
+          `which the agent can read from inside the sandbox (anthropics/sandbox-runtime#593 takes it out of ` +
+          `there). So this role will not run here. Add tartaros: [sandbox] provider = ["tartaros", "srt"]. Or run it on ` +
           `Linux, or use "env"/"run-file" here.`,
       });
     else if (process.platform !== "linux" && process.platform !== "darwin")

package/src/keys.js

@@ -30,8 +30,9 @@
  * policy holds a reviewable reference instead of a path, and every resolution
  * is logged without its value (`event: "key"`, see commands/run.js) — but it is not "the agent never sees it". That
  * is `inject`, which costs terminating the role's TLS with a CA of your own and
- * needs a sandbox that masks credentials: srt on Linux, tartaros on Linux and
- * macOS (see `injectGate` below, and `masks` on each sandbox).
+ * needs a sandbox that masks credentials without leaving the real value where
+ * the agent can read it: srt on Linux, tartaros on Linux and macOS (see
+ * `injectGate` below, and `masks` on each sandbox).
  *
  * ## Why the value is never written down
  *
@@ -526,7 +527,8 @@ export function modeOf(config, role, entry) {
  * the agent a sentinel and substitutes the real value on egress to the
  * credential's declared hosts. Which sandbox can do that is the sandbox's to
  * say (`masks` in sandboxes/): srt on Linux, tartaros on Linux and macOS
- * (srt's macOS path is tracked upstream, anthropics/sandbox-runtime#593). A
+ * (on macOS srt masks, but holds the real value in an environment the agent can
+ * read; anthropics/sandbox-runtime#593 takes it out of there). A
  * sandbox that does not mask is never handed the role, because the real value
  * is in the environment it is started with. Here only the platforms where no
  * sandbox masks are refused outright.

package/src/sandboxes/index.js

@@ -3,8 +3,9 @@
  *
  * 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`);
+ *   - `tartaros` (built in, the default, installed with seisin): reads the
+ *     settings file itself (`--settings`);
+ *   - `srt` (built in, installed apart): @anthropic-ai/sandbox-runtime;
  *   - any name declared under `[sandbox.providers.<name>]`: a command that
  *     takes the settings file (command.js, docs/sandboxes.md).
  *
@@ -23,17 +24,25 @@
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { srt } from "./srt.js";
+import { srt, SRT_PACKAGE, SRT_VERSION } 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";
+export const DEFAULT_SANDBOX = "tartaros";
+/**
+ * Without `[sandbox] provider`: tartaros, which installs with seisin, then srt
+ * where it is installed apart (it is not a dependency since 0.7). A role
+ * tartaros cannot hold (a blanket local binding, a host's missing Landlock)
+ * runs under srt if it is there and holds all of it, and otherwise does not
+ * run, with what each one lacked.
+ */
+export const DEFAULT_PROVIDERS = [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];
+  const names = config.sandbox?.provider ?? DEFAULT_PROVIDERS;
   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 }));
 }
 
@@ -91,7 +100,15 @@ export function weigh(config, settings, { platform = process.platform, role = nu
       const ruled = requests.length && !sandbox.requestRules
         ? [`requests (${requests.map((q) => q.host).join(", ")}): ${sandbox.name} cannot limit the methods and paths of a host from its settings, tartaros can`]
         : [];
-      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser, ...exemption, ...ruled], warnings, missing: bin ? null : sandbox.missing() };
+      // `control_files`: a family the policy hands a role that this sandbox
+      // protects whatever the settings say (tartaros's trust-handoff set holds
+      // `.vscode` at any depth), so the role could not do what it was given.
+      const families = role ? (config.roles?.[role]?.controlFiles ?? []) : [];
+      const kept = families.filter((f) => (sandbox.keepsControlFiles ?? []).includes(f));
+      const control = kept.length
+        ? [`control_files (${kept.join(", ")}): ${sandbox.name} protects those files at any depth whatever the policy says, so the role could not edit them`]
+        : [];
+      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser, ...exemption, ...ruled, ...control], warnings, missing: bin ? null : sandbox.missing() };
     });
     const chosen = options.find((o) => o.bin && o.unmet.length === 0) ?? null;
     return { chosen, options };
@@ -114,7 +131,7 @@ export function chooseSandbox(config, settings, { platform = process.platform, r
   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)
+  if (options.length === 1 && options[0].missing)
     return { error: new Error(options[0].missing), options };
   return { error: new Error(refusal(role, options)), options };
 }
@@ -125,6 +142,6 @@ export function refusal(role, options) {
     : `  - ${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.`;
+    `  A sandbox that enforces less than the policy is never used in its place. Install one that can ` +
+    `(srt: npm install -g ${SRT_PACKAGE}@${SRT_VERSION}), name it in [sandbox] provider, or change the role.`;
 }

package/src/sandboxes/srt.js

@@ -1,10 +1,15 @@
 /**
  * `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-settings.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.
+ * The reference every other provider is measured against: the settings seisin
+ * generates (srt-settings.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.
+ *
+ * Not a dependency since 0.7: tartaros is the default and installs with seisin.
+ * srt is used where it is installed apart (globally, or in the project), after
+ * tartaros or where `[sandbox] provider` names it, and the version it is tested
+ * with is the one in seisin's devDependencies.
  */
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { join, dirname, delimiter } from "node:path";
@@ -47,6 +52,15 @@ export function resolveSrt({ from = HERE, path = process.env.PATH } = {}) {
 }
 
 const RUNTIME = "@anthropic-ai/sandbox-runtime";
+export const SRT_PACKAGE = RUNTIME;
+/** The srt seisin is tested with (its devDependency), for the install hint. */
+export const SRT_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(HERE, "..", "..", "package.json"), "utf8")).devDependencies?.[RUNTIME] ?? "latest";
+  } catch {
+    return "latest";
+  }
+})();
 
 /**
  * The `srt` of the sandbox-runtime that resolves from `from`, or null.
@@ -148,11 +162,17 @@ export function withMachPreload(bin, file, inner) {
 export const srt = {
   name: "srt",
   locate: () => resolveSrt(),
-  missing: () => `sandbox runtime not found. ${installHint()}`,
+  missing: () => `sandbox-runtime (srt) not found: it is not installed with seisin since 0.7. ` +
+    `Install it with: npm install -g ${RUNTIME}@${SRT_VERSION}`,
   unmet: () => [],
-  // Masked credentials: on Linux; on macOS not yet (anthropics/sandbox-runtime#593).
+  // Masked credentials: on Linux. On macOS srt masks too, but it reads the real
+  // value from its own environment, and from inside its sandbox the agent can
+  // read that environment back (measured with 0.0.81).
+  // anthropics/sandbox-runtime#593 takes the value out of there.
   masks: (platform) => platform === "linux" ? null
-    : `masked credentials (key_mode = "inject") on ${platform}: sandbox-runtime does not mask them there yet (anthropics/sandbox-runtime#593); tartaros does`,
+    : platform === "darwin"
+      ? `masked credentials (key_mode = "inject") on darwin: sandbox-runtime masks them, but holds the real value in its own environment, which the agent can read from inside the sandbox (anthropics/sandbox-runtime#593 takes it out of there); tartaros does not keep it there`
+      : `masked credentials (key_mode = "inject") on ${platform}: sandbox-runtime does not mask them there; tartaros does`,
   // `--` 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`.

package/src/sandboxes/tartaros.js

@@ -31,11 +31,10 @@ export const TARTAROS_PACKAGE = "@carlostapiacl/tartaros";
  * the order srt is found in (resolveSrt in sandboxes/srt.js), for the same reason. A tartaros built
  * once and left on PATH goes on answering after the pinned one has its fixes.
  *
- * The pinned one is an optional dependency: a package per platform with the
- * binary in it, and a main package whose binaryPath() finds that one whether
+ * The pinned one is a dependency: a main package whose binaryPath() finds the
+ * binary of this platform's package (an optional dependency of its own) whether
  * npm nested it under the main package (a global install, measured) or hoisted
- * it. An install that left it out (`--omit=optional`, a platform without a
- * binary) falls through to PATH.
+ * it. A platform without a binary, or `--omit=optional`, falls through to PATH.
  */
 export function resolveTartaros({ from = HERE, path = process.env.PATH } = {}) {
   const pinned = dependencyTartaros(from);
@@ -116,7 +115,10 @@ export function tartarosSettings(settings, { machRegister = [], handoffExempt =
 export const tartaros = {
   name: "tartaros",
   locate: () => resolveTartaros(),
-  missing: () => `tartaros not found: neither ${TARTAROS_PACKAGE}, which installs with seisin unless optional dependencies are left out, nor tartaros on PATH.`,
+  missing: () => `tartaros not found: neither ${TARTAROS_PACKAGE}, which installs with seisin (it has no binary for ${process.platform}-${process.arch}), nor tartaros on PATH.`,
+  // Its trust-handoff set holds the editors' folders (`.vscode`, `.idea`) at any
+  // depth, whatever the settings say: a role given them cannot edit them here.
+  keepsControlFiles: ["ide"],
   asksFile: true,
   // Masked credentials: tartaros says whether it masks them, through explain
   // (0.1.0-alpha.16 and later do; earlier ones refuse the field).