seisin 0.5.0 → 0.6.0

package/src/surface.js

@@ -300,7 +300,8 @@ function computeParentInputs(config, env) {
  * Git runs `.git/hooks/*` and whatever `.git/config` names (core.hooksPath,
  * core.fsmonitor). Claude Code runs the hooks, plugins and skills its settings
  * declare, and the MCP servers in `.mcp.json`. direnv runs `.envrc` on `cd`.
- * Codex starts what `config.toml` lists. A role that writes one of these does
+ * Codex starts what its `config.toml` and `hooks.json` list and lets its `rules`
+ * run without asking. A role that writes one of these does
  * not escape the sandbox; it leaves a command for you to run the next time you
  * open that project — measured on 2026-09-23: every role could open
  * `~/.claude/settings.json` for writing through the shared runtime scratch.
@@ -315,11 +316,22 @@ export const CONTROL_FILES = [
   ".git/hooks", ".git/config",
   ".claude/settings.json", ".claude/settings.local.json",
   ".claude/hooks", ".claude/plugins", ".claude/skills", ".claude/commands", ".claude/agents",
-  ".mcp.json", ".envrc", ".codex/config.toml",
+  ".mcp.json", ".envrc", ".codex",
 ];
 
 const RUNNER = (f) =>
-  f.startsWith(".git/") ? "git" : f === ".envrc" ? "direnv" : f.startsWith(".codex/") ? "Codex" : "Claude Code";
+  f.startsWith(".git/") ? "git" : f === ".envrc" ? "direnv" : f.startsWith(".codex") ? "Codex" : "Claude Code";
+
+/**
+ * A project's `.codex/` is protected whole, as `.claude/` is, and for the same
+ * reason plus one: it holds `config.toml` (MCP servers, profiles, and the trust
+ * a hook needs before Codex runs it), `hooks.json` and `rules/`, which Codex
+ * reads from any project the user has trusted. Codex itself keeps `.codex`
+ * read-only inside the directories its own sandbox lets it write, so a role
+ * loses nothing there that Codex would have given it.
+ */
+const CODEX_WHY = ".codex, whose config, hooks and rules Codex runs outside the sandbox";
+const controlWhy = (f) => f === ".codex" ? CODEX_WHY : `${f}, run by ${RUNNER(f)} outside the sandbox`;
 
 /** `s` as a literal inside a RegExp — every metacharacter, not only `.`. */
 const literal = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -462,9 +474,9 @@ function controlsOf(dir, platform, families = []) {
     out.push({ path: join(dir, ".claude"), why: ".claude, whose settings, hooks and skills Claude Code runs outside the sandbox" });
   // The single files only where they exist: where they do not, the patterns
   // refuse creating them, and a literal each would be start-up for nothing.
-  for (const f of [".mcp.json", ".envrc", ".codex/config.toml"]) {
+  for (const f of [".mcp.json", ".envrc", ".codex"]) {
     const p = join(dir, f);
-    if (existsSync(p)) out.push({ path: p, why: `${f}, run by ${RUNNER(f)} outside the sandbox`, ifPresent: true });
+    if (existsSync(p)) out.push({ path: p, why: controlWhy(f), ifPresent: true });
   }
   // The families literally only where they exist, on every platform. Where
   // they do not, macOS gets a pattern for creating them (computeDenies) and
@@ -486,16 +498,75 @@ function controlsOf(dir, platform, families = []) {
  * with `claude -p` under the new profile: it answered, and what it was refused
  * were lock and cache files under plugins/, which it tolerates).
  */
-function homeControls(platform) {
-  const home = homedir();
+function homeControls(platform, home = homedir()) {
   return [
     ".claude/settings.json", ".claude/settings.local.json", ".claude/hooks", ".claude/plugins",
-    ".claude/skills", ".claude/commands", ".claude/agents", ".codex/config.toml",
+    ".claude/skills", ".claude/commands", ".claude/agents",
+    ...CODEX_HOME_CONTROLS, ...codexProfiles(home),
   ]
     .map((f) => ({ path: join(home, f), why: `${f}, run by ${RUNNER(f)} outside the sandbox`, ifPresent: true }))
     .filter((e) => platform !== "linux" || existsSync(e.path));
 }
 
+/**
+ * What Codex runs or obeys from its home, file by file — never `~/.codex`
+ * whole, because Codex writes its sessions, logs and state databases there on
+ * every turn (measured 2026-09-30 with codex 0.150.1 under seisin: sessions/,
+ * logs_2.sqlite, state_5.sqlite, models_cache.json, cache/, plugins/cache/).
+ *
+ * - `config.toml`: MCP servers, profiles, and `hooks.state.*.trusted_hash`, the
+ *   trust Codex asks before running a hook. Codex tries to rewrite it at every
+ *   start and carries on when refused.
+ * - `hooks.json`: commands run on every tool call, outside any sandbox.
+ * - `rules/`: the commands Codex runs without asking.
+ * - `skills/`, `plugins/`: what the next session loads. Codex installs OpenAI's
+ *   curated plugins into `plugins/cache/` by itself and carries on when refused.
+ * - `managed_config.toml`: a layer that overrides `config.toml`.
+ * - `.tmp/plugins`: Codex's copy of OpenAI's curated plugin marketplace, a git
+ *   checkout it syncs at start. `codex plugin add` installs from it as it is on
+ *   disk — measured on 2026-09-30 with codex 0.150.1 in a scratch CODEX_HOME: a
+ *   file and an `.mcp.json` planted in the copy landed in `plugins/cache/` and
+ *   the plugin was enabled. Codex re-fetches the copy only when the upstream
+ *   commit differs from `.tmp/plugins.sha`, so an edit made while they match
+ *   stays until upstream moves. The `.sha` file is left writable: changing it
+ *   makes Codex fetch a clean copy, which repairs rather than plants.
+ */
+export const CODEX_HOME_CONTROLS = [
+  ".codex/config.toml", ".codex/hooks.json", ".codex/rules", ".codex/skills", ".codex/plugins",
+  ".codex/managed_config.toml", ".codex/.tmp/plugins",
+];
+
+/**
+ * `CODEX_HOME`, when it names somewhere other than `~/.codex`, absolute and
+ * resolved — or null. Codex takes it from the environment of whoever runs it,
+ * so the parent's environment is the one that says where your Codex looks.
+ */
+export function codexHomeOf(env = process.env) {
+  const v = env?.CODEX_HOME;
+  if (!v || !isAbsolute(v)) return null;
+  const real = realOrSelf(v);
+  return real === realOrSelf(join(homedir(), ".codex")) ? null : real;
+}
+
+/** The control entries of a Codex home that is not `~/.codex`, by the same list. */
+function codexControlsAt(dir, platform) {
+  let profiles = [];
+  try { profiles = readdirSync(dir).filter((f) => f.endsWith(".config.toml") && f !== "config.toml"); } catch {}
+  return [...CODEX_HOME_CONTROLS.map((c) => c.replace(/^\.codex\//, "")), ...profiles]
+    .map((f) => ({ path: join(dir, f), why: `CODEX_HOME/${f}, run by Codex outside the sandbox`, ifPresent: true }))
+    .filter((e) => platform !== "linux" || existsSync(e.path));
+}
+
+/** `codex -p <name>` layers `~/.codex/<name>.config.toml`: the ones there now. */
+function codexProfiles(home) {
+  try {
+    return readdirSync(join(home, ".codex")).filter((f) => f.endsWith(".config.toml") && f !== "config.toml")
+      .map((f) => `.codex/${f}`);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Everything this role's profile must deny beyond its own `never_writes`.
  *
@@ -512,7 +583,7 @@ export function denyFor(config, role, { env = process.env, platform = process.pl
   // Memoised per config: `check` builds every role's settings and then asks
   // for the same list again to show it; on a multi-repo workspace that was 2.6 s twice.
   const memo = DENIES.get(config) ?? DENIES.set(config, new Map()).get(config);
-  const key = `${role.name}\0${observe}\0${platform}\0${env.PATH ?? ""}`;
+  const key = `${role.name}\0${observe}\0${platform}\0${env.PATH ?? ""}\0${env.CODEX_HOME ?? ""}`;
   if (memo.has(key)) return memo.get(key);
   const result = computeDenies(config, role, { env, platform, observe });
   memo.set(key, result);
@@ -536,10 +607,17 @@ function computeDenies(config, role, { env, platform, observe }) {
   const dirs = mine.filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } });
   const repoDirs = dirs.filter((p) => under(p, config.root));
   const families = familiesFor(config, role);
-  const roots = [...new Set(repoDirs.flatMap((d) => rootsUnder(config, d)))];
-  const controls = roots.flatMap((d) => controlsOf(d, platform, families));
+  // Discover projects from the policy root, not from the territory. A territory
+  // may itself be .claude; starting the walk there called <repo>/.claude/.claude
+  // protected and left the real settings and hooks writable. A project's
+  // control files win over every grant that covers or sits inside the project.
+  const roots = [...new Set(rootsUnder(config, config.root)
+    .filter((d) => minePaths.some((p) => under(p, d) || under(d, p))))];
+  const controls = roots.flatMap((d) => controlsOf(d, platform, families))
+    .filter((e) => inMine(e.path) || minePaths.some((p) => under(p, e.path)));
   // The home is a project too, for Claude Code and Codex: ~/.claude/settings.json
   // is read by every session. Not walked — only its own control files.
+  const codexHome = join(homedir(), ".codex");
   if (["~/.claude", "~/.codex"].some((h) => inMine(join(homedir(), h.slice(2)))))
     controls.push(...homeControls(platform));
 
@@ -554,7 +632,7 @@ function computeDenies(config, role, { env, platform, observe }) {
    * files stay literal (homeControls).
    */
   const globs = platform === "darwin"
-    ? repoDirs.flatMap((d) => [
+    ? roots.flatMap((d) => [
         `${d}/**/.claude`, `${d}/**/.claude/**`,
         `${d}/**/.git/hooks/**`, `${d}/**/.git/config`,
         // What git runs that lives beside, not in, `.git/config`: a submodule's
@@ -566,16 +644,28 @@ function computeDenies(config, role, { env, platform, observe }) {
         `${d}/**/.git/config.worktree`,
         `${d}/**/.git/modules/**/config`, `${d}/**/.git/modules/**/hooks/**`,
         `${d}/**/.git/worktrees/**/config.worktree`, `${d}/**/.git/worktrees/**/commondir`,
-        `${d}/**/.mcp.json`, `${d}/**/.envrc`, `${d}/**/.codex/config.toml`,
+        `${d}/**/.mcp.json`, `${d}/**/.envrc`, `${d}/**/.codex`, `${d}/**/.codex/**`,
       ]).map((path) => ({ path, why: "any project's control files in this territory, by pattern" }))
     : [];
+  // A profile created after the walk: `codex -p x` reads `~/.codex/x.config.toml`.
+  if (platform === "darwin" && inMine(codexHome))
+    globs.push({ path: `${codexHome}/*.config.toml`, why: "a Codex profile, if it is created" });
+  // `CODEX_HOME` moves all of it. Codex run with it set — by you, outside the
+  // sandbox — reads its config, hooks, rules and plugins from there, so when a
+  // role can write that directory the same entries are taken back there.
+  const elsewhere = codexHomeOf(env);
+  if (elsewhere && inMine(elsewhere)) {
+    controls.push(...codexControlsAt(elsewhere, platform));
+    if (platform === "darwin")
+      globs.push({ path: `${elsewhere}/*.config.toml`, why: "a Codex profile under CODEX_HOME, if it is created" });
+  }
   // Creating one of the families where it is not there yet: one exact pattern
   // per project root, never `**` (see `exactly`).
   if (platform === "darwin")
     for (const root of roots)
       for (const family of families)
         for (const f of FAMILIES[family])
-          if (!existsSync(join(root, f)))
+          if (inMine(join(root, f)) && !existsSync(join(root, f)))
             globs.push({ path: exactly(root, f), why: `${familyWhy(family, f)}, if it is created`, family });
 
   // The policy, `.seisin/` and the key directories are denied whatever the
@@ -594,13 +684,36 @@ function computeDenies(config, role, { env, platform, observe }) {
  * to be filed as "belongs to dev" for a role with `writes = ["**"]`, and
  * granting it would have granted nothing.
  */
-export function protectedBy(config, target, { platform = process.platform, role = null } = {}) {
+export function protectedBy(config, target, { platform = process.platform, role = null, env = process.env } = {}) {
   /**
    * A project's `.claude/`, any file in it, and the other control files — the
    * same rule the kernel is given. On Linux the kernel only holds the ones
    * that exist, so only those are called protected there: a sentence stricter
    * than the boundary is the direction this project refuses.
    */
+  /**
+   * Codex's home is not a project's `.codex`: Codex writes its sessions there
+   * on every turn and the kernel lets it. Only the entries it runs or obeys are
+   * protected, so only those are called protected.
+   */
+  const codexHome = join(homedir(), ".codex");
+  const elsewhere = codexHomeOf(env);
+  if (elsewhere && isAbsolute(target) && under(target, elsewhere)) {
+    const rel = target.slice(elsewhere.length + 1);
+    const hit = CODEX_HOME_CONTROLS.map((c) => c.replace(/^\.codex\//, "")).find((c) => under(rel, c)) ??
+      (dirname(target) === elsewhere && target.endsWith(".config.toml") ? rel : null);
+    return hit && (platform !== "linux" || existsSync(join(elsewhere, hit)))
+      ? { path: target, why: `CODEX_HOME/${hit}, run by Codex outside the sandbox` }
+      : null;
+  }
+  if (isAbsolute(target) && under(target, codexHome)) {
+    const rel = target.slice(homedir().length + 1);
+    const hit = [...CODEX_HOME_CONTROLS].find((c) => under(rel, c)) ??
+      (dirname(target) === codexHome && target.endsWith(".config.toml") ? rel : null);
+    return hit && (platform !== "linux" || existsSync(join(homedir(), hit)))
+      ? { path: target, why: `${hit}, run by Codex outside the sandbox` }
+      : null;
+  }
   const f = CLAUDE_DIR.test(target)
     ? ".claude"
     : CONTROL_RES.find(([, re]) => re.test(target))?.[0];
@@ -608,7 +721,7 @@ export function protectedBy(config, target, { platform = process.platform, role
   if (f && (platform !== "linux" || heldOnLinux(config, target, re))) {
     const why = f === ".claude"
       ? ".claude, whose settings, hooks and skills Claude Code runs outside the sandbox"
-      : `${f}, run by ${RUNNER(f)} outside the sandbox`;
+      : controlWhy(f);
     return { path: target, why };
   }
   /**

package/src/territory.js

@@ -0,0 +1,261 @@
+/**
+ * `[runtime] read = "territory"`: reading denied where people keep their data,
+ * re-opened only along the paths a role needs.
+ *
+ * The default read model is a list of what not to read — key directories, the
+ * places credentials live, other agents' sign-in. It holds for agents you run
+ * yourself. Against one you would not trust it loses by one every time a new
+ * product leaves a folder of its own: measured on 2026-10-06 by an orchestrator that evaluates agents,
+ * a role confined that way could still list `~/.claude`, list the whole
+ * project tree of the person running it, and `cat` an evaluation check kept
+ * outside its worktree. None of the three was a credential, so none was on
+ * the list.
+ *
+ * So this mode turns the list around, but not all the way. Denying `/` and
+ * allowing back is the read allowlist decisions.md rejected, for a reason that
+ * still holds: every interpreter, library and cache a toolchain touches would
+ * have to be named. The data roots are what gets denied — homes, temp
+ * directories, mounted volumes — and the system stays readable, because there
+ * is nobody's data in `/usr`. What a role needs from inside a data root is
+ * finite and known before it starts: its repo, its territory, its run, its
+ * toolchain. That list is the short one, and it is the one written.
+ *
+ * **Denied whole, allowed back.** Each data root is one deny, and what the
+ * role keeps is an `allowRead` inside it. A deny covers what is created after
+ * it, so another run's directory made beside the repo an hour into this one
+ * is shut the moment it exists. That is the point of it.
+ *
+ * It was carved before — every sibling on the way to a kept path denied by
+ * name, which is a photograph: an entry created during the run beside a kept
+ * path was not covered, and read (measured, 2026-10-12). Two measured runtime
+ * behaviours kept the allow out then, and each is now handled where it bites:
+ *
+ *   - macOS: an allow is emitted after the denies, and a deny that sits inside
+ *     an allow is re-emitted after it whole (last match wins). For the key
+ *     directory inside the repo that re-emitted deny also shuts the key files
+ *     `[keys]` re-allows inside it. A deny spelt as a pattern is re-emitted
+ *     MINUS the allows inside it, so those denies are spelt as one
+ *     (outlastAllows, below).
+ *   - Linux: the runtime restores the write mounts a deny wiped and then the
+ *     read allows, read-only, on top of them — so a repo allowed back covers
+ *     the territory inside it and every write fails with "Read-only file
+ *     system" (srt 0.0.75/0.0.78). A kept path that holds a write path is
+ *     allowed back piece by piece around it (territoryReads, below).
+ *
+ * **What that costs, said where it is decided.** On Linux, inside a kept
+ * directory that is on the way to a write path, an entry created during the
+ * run is not there for the role until the next run: it fails closed, it does
+ * not leak. On both, the names of what the role keeps are visible where the
+ * runtime has to show them (a Linux `ls ~` lists the mount points), and
+ * nothing else in a data root is.
+ */
+import { readdirSync, lstatSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { realOrSelf, writePathsOf, expand } from "./grants.js";
+import { realAncestor } from "./paths.js";
+
+export const READ_MODES = ["all", "territory"];
+
+/** Files an agent reads at start that live outside its home directory. */
+export const AGENT_FILES = { claude: ["~/.claude.json"], codex: [] };
+
+/**
+ * Where data lives, per platform. Whole roots: what is under them belongs to
+ * somebody. `/opt/homebrew/var` and `/usr/local/var` hold the databases a
+ * package manager runs (Postgres, Redis); the rest of `/opt/homebrew` is the
+ * toolchain and stays readable.
+ */
+export const DATA_ROOTS = {
+  darwin: [
+    "/Users", "/private/tmp", "/private/var/folders", "/private/var/root", "/Volumes",
+    "/opt/homebrew/var", "/usr/local/var", "/Library/Keychains",
+  ],
+  linux: [
+    "/home", "/root", "/tmp", "/var/tmp", "/mnt", "/media", "/srv", "/run/user",
+    "/run/secrets", "/var/lib/docker",
+  ],
+};
+
+/** The data roots of this machine: the platform's, plus HOME and TMPDIR wherever they are. */
+export function dataRoots(platform = process.platform, home = homedir(), tmp = tmpdir(), real = realOrSelf) {
+  const base = DATA_ROOTS[platform] ?? DATA_ROOTS.linux;
+  return [...new Set([...base, home, tmp].map(real))];
+}
+
+/**
+ * The most entries one directory may have where a kept path is allowed back
+ * piece by piece (Linux, around a write path).
+ *
+ * Every piece is one allow, and one mount. The carving this replaced hit the
+ * same wall from the other side: a repo kept inside a Mac's TMPDIR, 9,105
+ * entries, made 9,163 denies, 815 KB of profile, and `spawn E2BIG` — no
+ * agent, and no reason anyone could read. Past this the answer is a refusal
+ * that names the directory, not a sandbox that cannot start.
+ */
+export const MAX_CARVE = 1000;
+
+/** What the runtime treats as glob syntax in a path (sandbox-utils containsGlobChars). */
+const GLOB = /[[\]*?]/;
+
+const under = (p, dir) => p === dir || p.startsWith(dir === "/" ? "/" : dir + "/");
+const inside = (p, dir) => p !== dir && under(p, dir);
+
+/**
+ * The read rules that leave exactly `keep` readable inside `roots`:
+ * `{ deny, allow }`, for denyRead and allowRead.
+ *
+ * Each root is denied whole, unless something kept covers it. Each kept path
+ * under a root is allowed back, in both spellings. On Linux a kept path that
+ * holds one of `writes` is not allowed back itself — its read mount would
+ * land on the write mount inside it — but walked toward the writes, and every
+ * child not on the way is allowed instead; the writes come back writable
+ * through the runtime's own restore. Nothing is denied by name, so nothing
+ * created later escapes the deny.
+ *
+ * Nothing at or under `denied` — the key directories, other roles' private
+ * folders, the credential homes — is allowed back: an allow there would win
+ * over the deny on macOS, and on Linux the deny's own mount restores it.
+ *
+ * `fs` is injectable for tests; it needs `readdir(dir) -> names`,
+ * `kind(path) -> "dir" | "link" | "other" | null` and `real(path) -> path`.
+ */
+export function territoryReads(roots, keep, { writes = [], denied = [], platform = process.platform, fs = realFs } = {}) {
+  // realAncestor, not realOrSelf: a territory not created yet still has to
+  // be spelt the way the kernel will meet it (`/tmp/x` is `/private/tmp/x`).
+  // Both spellings of each: where it resolves, and where its NAME lives (the
+  // directories above resolved, the last component as written). A kept
+  // symlink — `~/.local/bin/claude` — has to be reachable by name for a PATH
+  // lookup to find it, and by target for the read to land.
+  const nameOf = (k) => { const d = k.slice(0, k.lastIndexOf("/")) || "/"; const r = fs.real(d); return `${r === "/" ? "" : r}/${k.slice(k.lastIndexOf("/") + 1)}`; };
+  const no = [...new Set(denied.map(fs.real))];
+  const open = (p) => !no.some((d) => under(p, d));
+  const kept = [...new Set(keep.flatMap((k) => [fs.real(k), nameOf(k)]))].filter(open);
+  // Nested roots (`/private/var/folders/…/T` inside `/private/var/folders`)
+  // are covered by the outer deny; one kept whole needs no deny at all.
+  const real = [...new Set(roots.map(fs.real))].filter((r) => fs.kind(r) === "dir");
+  const deny = real.filter((r) => !real.some((o) => inside(r, o)) && !kept.some((k) => under(r, k)));
+  const shut = kept.filter((k) => deny.some((r) => inside(k, r)));
+  if (platform !== "linux") return { deny, allow: shut };
+
+  const w = [...new Set(writes.map(fs.real))];
+  const allow = [];
+  const walk = (dir) => {
+    let names;
+    try { names = fs.readdir(dir); } catch { return; }      // unreadable: nothing comes back
+    if (names.length > MAX_CARVE)
+      throw new Error(
+        `read = "territory" cannot keep ${dir} readable around what the role writes inside it: it holds ` +
+        `${names.length} entries, and on Linux each is one mount (the most it takes is ${MAX_CARVE} per directory).\n` +
+        `  Written inside it: ${w.filter((x) => inside(x, dir)).join(", ")}.\n` +
+        `  Move the repo to a directory with fewer neighbours, or narrow the reads entry that keeps this path.`);
+    for (const name of names.sort()) {
+      const child = dir === "/" ? `/${name}` : `${dir}/${name}`;
+      if (w.some((x) => under(child, x)) || !open(child)) continue;   // a write, or denied
+      if (fs.kind(child) === "dir" && w.some((x) => inside(x, child))) walk(child);
+      else allow.push(child);
+    }
+  };
+  for (const k of shut) {
+    if (w.some((x) => under(k, x))) continue;                // comes back as a write
+    if (w.some((x) => inside(x, k)) && fs.kind(k) === "dir") walk(k);
+    else allow.push(k);
+  }
+  return { deny, allow };
+}
+
+/**
+ * The denies, respelt so that each keeps its own allows open on macOS.
+ *
+ * A deny strictly inside an allow is re-emitted after the allows, because the
+ * last rule that matches wins and the allow would otherwise re-open it. A
+ * deny written as a path comes back whole, and that shuts every allow inside
+ * IT — the key files inside the key directory inside the repo. A deny written
+ * as a pattern comes back minus each allow its pattern covers (srt 0.0.78,
+ * macos-sandbox-utils lateReadDenyFilters). So those denies, and only those,
+ * are spelt as a pattern that matches exactly their own path: one character
+ * of the last name in brackets, `.secrets` as `.secret[s]`.
+ *
+ * A path that already holds glob syntax cannot be spelt that way without
+ * matching something else, and is refused.
+ */
+export function outlastAllows(denies, allows, real = (p) => p) {
+  const open = allows.map(real);
+  return denies.map((written) => {
+    const d = real(written);
+    if (!open.some((a) => inside(a, d)) || !open.some((a) => inside(d, a))) return written;
+    const slash = d.lastIndexOf("/");
+    let at = d.length - 1;
+    while (at > slash && !/[A-Za-z0-9_-]/.test(d[at])) at--;
+    if (GLOB.test(d) || at <= slash)
+      throw new Error(
+        `read = "territory" cannot keep ${d} shut around what is allowed inside it: its name holds ` +
+        `characters the sandbox reads as a pattern, or none it can bracket.\n  Rename it.`);
+    return `${d.slice(0, at)}[${d[at]}]${d.slice(at + 1)}`;
+  });
+}
+
+const realFs = {
+  real: realAncestor,
+  readdir: (d) => readdirSync(d),
+  kind: (p) => {
+    try {
+      const s = lstatSync(p);
+      return s.isSymbolicLink() ? "link" : s.isDirectory() ? "dir" : "other";
+    } catch { return null; }
+  },
+};
+
+/**
+ * What a role keeps readable: its repo, what it writes, its `reads` and its
+ * `toolchain`. One answer for the settings and for `check`, so the warning
+ * about an unreadable PATH entry and the kernel agree.
+ */
+export function keptFor(config, role, { observe = false, agent, program } = {}) {
+  return [
+    config.root,
+    // The program the run starts, and where its link points: without it there
+    // is no run. Measured: `claude` installs as ~/.local/bin/claude ->
+    // ~/.local/share/claude/versions/<v>, and the run died on `env: claude: No
+    // such file or directory`. The file, not its directory — the rest of
+    // ~/.local/bin stays shut.
+    ...(program ? [program, realOrSelf(program)] : []),
+    // The agent's own files that are not under its home directory. Its home
+    // (~/.claude) is scratch and kept with the writes; ~/.claude.json, its
+    // settings and session index, sits beside it, and without it Claude Code
+    // starts and says "Not logged in" (measured, 2026-10-09). A run of no
+    // agent, or of another, does not get it.
+    ...(agent ? (AGENT_FILES[agent] ?? []).map(expand) : []),
+    ...writePathsOf(config, role, { observe, agent }),
+    ...(role.reads ?? []).map((p) => readPath(config.root, p)),
+    ...(role.toolchain ?? []).map((p) => readPath(config.root, p)),
+  ];
+}
+
+/** Whether `p` is shut by the mode: under a data root, and under nothing kept. */
+export function shutByTerritory(p, keep, roots = dataRoots(), real = realAncestor) {
+  const r = real(p);
+  const kept = keep.map(real);
+  if (!roots.some((root) => under(r, root))) return false;
+  return !kept.some((k) => under(r, k));
+}
+
+/**
+ * The `bin` directory of each toolchain entry that has one, for the front of
+ * PATH. A venv, `~/.cargo`, a node install all keep their programs there;
+ * declaring the toolchain and then finding `python` resolves to another one
+ * would be a second way of not having it.
+ */
+export function toolchainBins(config, role, isDir) {
+  return (role.toolchain ?? []).map((p) => readPath(config.root, p))
+    .flatMap((p) => [p.endsWith("/bin") ? p : `${p}/bin`].filter(isDir));
+}
+
+/** `~` and relative spellings of a read entry, absolute. Missing paths are kept as written. */
+export function readPath(root, p) {
+  const trimmed = p.replace(/\/\*\*$/, "") || ".";
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/")) return `${homedir()}/${trimmed.slice(2)}`;
+  if (trimmed.startsWith("/")) return trimmed;
+  return `${root}/${trimmed}`.replace(/\/\.$/, "");
+}
+

package/src/trace.js

@@ -0,0 +1,33 @@
+/**
+ * The launcher's trace, carried into the log.
+ *
+ * A launcher that runs many agents (a team, a CI job) gives each run a W3C
+ * `TRACEPARENT`. Without it in the log, nothing says which of these lines belong
+ * to which of the launcher's runs, and the log cannot be joined with anything
+ * else that observed the same run (a tracer, the launcher's own spans). With it,
+ * any OpenTelemetry tool joins them by trace id; seisin does not need to know
+ * who else is looking.
+ *
+ * Only a well-formed value is used (W3C Trace Context, version 00): a malformed
+ * one is ignored rather than copied into a log that other tools will trust.
+ */
+
+const PART = { version: /^[0-9a-f]{2}$/, trace: /^[0-9a-f]{32}$/, span: /^[0-9a-f]{16}$/, flags: /^[0-9a-f]{2}$/ };
+
+/** `{ trace_id, span_id }` from a `TRACEPARENT` value, or null. */
+export function parseTraceparent(value) {
+  if (typeof value !== "string") return null;
+  const parts = value.trim().split("-");
+  if (parts.length < 4) return null;
+  const [version, trace, span, flags] = parts;
+  if (!PART.version.test(version) || version === "ff") return null;
+  if (version === "00" && parts.length !== 4) return null;
+  if (!PART.trace.test(trace) || !PART.span.test(span) || !PART.flags.test(flags)) return null;
+  if (/^0+$/.test(trace) || /^0+$/.test(span)) return null;
+  return { trace_id: trace, span_id: span };
+}
+
+/** The fields a log entry carries for the launcher's trace: `{}` when there is none. */
+export function traceFields(env = process.env) {
+  return parseTraceparent(env.TRACEPARENT) ?? {};
+}

package/src/uilink.js

@@ -18,9 +18,11 @@
  * The pid is stored so a file left by a crashed run is recognisable: a link
  * whose writer is gone is stale, not a running console.
  */
-import { writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { chmodSync, renameSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { runsRoot } from "./rundir.js";
+import { alive as processAlive } from "./log.js";
 
 function linkFile(port, base) {
   return join(runsRoot(base), `ui-${port}.url`);
@@ -34,7 +36,17 @@ function linkFile(port, base) {
  * with nothing on it to say so. The policy's path travels with the link now.
  */
 export function writeUiLink(port, url, base, policy = null) {
-  writeFileSync(linkFile(port, base), JSON.stringify({ url, pid: process.pid, policy }) + "\n", { mode: 0o600 });
+  const file = linkFile(port, base);
+  const temp = `${file}.tmp-${randomBytes(12).toString("hex")}`;
+  writeFileSync(temp, JSON.stringify({ url, pid: process.pid, policy }) + "\n", { flag: "wx", mode: 0o600 });
+  try {
+    // Replacing an existing record must neither inherit its mode nor follow
+    // its symlink. Readers see one complete record, including after a crash.
+    chmodSync(temp, 0o600);
+    renameSync(temp, file);
+  } finally {
+    try { unlinkSync(temp); } catch {}
+  }
 }
 
 /**
@@ -48,10 +60,7 @@ export function readUiLink(port, base) {
   try { e = JSON.parse(raw); } catch { return null; }
   if (!e || typeof e.url !== "string") return null;
   let alive = null;
-  if (typeof e.pid === "number") {
-    // Signal 0 tests for the process without touching it: it throws if gone.
-    try { process.kill(e.pid, 0); alive = true; } catch { alive = false; }
-  }
+  if (Number.isInteger(e.pid) && e.pid > 0) alive = processAlive(e.pid);
   return { url: e.url, pid: e.pid ?? null, alive, policy: typeof e.policy === "string" ? e.policy : null };
 }