seisin 0.4.2 → 0.6.0

package/src/surface.js

@@ -3,7 +3,7 @@
  *
  * The sandbox confines the agent. It does not confine the process that decides
  * what the agent gets: `seisin run` reads the policy, runs the key providers,
- * reads `file://` secrets and starts the runtime, all of it outside the box and
+ * reads `file://` secrets and starts the runtime, all of it outside the sandbox and
  * as you. Every file that process reads or executes is therefore part of the
  * boundary, and a role that can write one of them does not need to escape — it
  * waits for the next run, or for you to type the command yourself.
@@ -19,7 +19,7 @@
  *   - a role swapped a `file://` target for a symlink to another role's key,
  *     and the next run read that key and handed it over;
  *   - every role could create files in `~/.local/share/claude/versions/`, where
- *     the Claude Code binary you run outside the box lives, because the shared
+ *     the Claude Code binary you run outside the sandbox lives, because the shared
  *     runtime scratch includes `~/.local/share`.
  *
  * So this module answers the question once, for the family: **which paths does
@@ -28,7 +28,7 @@
  * with the reason for each entry.
  */
 import { readdirSync, statSync, accessSync, existsSync, realpathSync, constants } from "node:fs";
-import { join, isAbsolute, delimiter, dirname, resolve, basename } from "node:path";
+import { join, isAbsolute, delimiter, dirname, resolve, basename, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { writePathsOf, realOrSelf } from "./grants.js";
@@ -46,12 +46,25 @@ const under = (p, root) => p === root || p.startsWith(root.endsWith("/") ? root
  * provider script can still wait for the role that can. The repo root is in
  * it because `--observe` grants the whole repo to whichever role it runs.
  */
+const ROOTS_OF = new WeakMap();          // config -> writable roots
+
 export function writableRoots(config) {
+  // Once per config: protectedBy asks for it through parentInputs on every
+  // call, and on a multi-repo workspace that was 1.7 ms each — 50 ms for a hook call
+  // with two providers. A config is reloaded whenever the policy can have
+  // changed (hook, console, MCP), so a memory per object is never stale for
+  // longer than the object lives.
+  let roots = ROOTS_OF.get(config);
+  if (!roots) ROOTS_OF.set(config, (roots = computeWritableRoots(config)));
+  return roots;
+}
+
+function computeWritableRoots(config) {
   const root = realOrSelf(config.root);
   const out = new Set([root]);
   // A grant inside the repo is covered by the repo root already, so only the
   // ones outside it are resolved. Resolving all of them was most of the cost:
-  // 301 paths for the portfolio's 32 roles, most of them sidecars that do not
+  // 301 paths for a policy with 32 roles, most of them sidecars that do not
   // exist, 200 ms of failed realpath calls to learn nothing.
   for (const role of Object.values(config.roles ?? {}))
     for (const p of writePathsOf(config, role)) {
@@ -140,8 +153,8 @@ function fileRefTargets(config) {
  * root. With nothing recognisable on the way, the binary's own directory.
  *
  * The first version protected the top-level entry under the writable root
- * instead, and on the portfolio that was `01-activos/`: every project, denied
- * to every role, because seisin itself lives in one of them.
+ * instead, and in a multi-repo workspace that was the folder holding every
+ * project: all of them, denied to every role, because seisin itself lives in one.
  */
 function packageRoot(p, root) {
   let dir = dirname(p);
@@ -154,7 +167,7 @@ function packageRoot(p, root) {
 }
 
 /**
- * Programs that run outside the box and live where a role can write.
+ * Programs that run outside the sandbox and live where a role can write.
  *
  * Two ways in. A PATH directory inside a writable area: anything a role drops
  * there shadows a real command the next time anybody types it. And a PATH
@@ -170,7 +183,7 @@ const SURFACES = new WeakMap();          // config -> PATH -> entries
 
 export function executionSurface(config, env = process.env, roots = null) {
   // Once per config and PATH: `check` asks for every role's denies, and the
-  // PATH scan is the same answer 32 times on the portfolio.
+  // PATH scan is the same answer 32 times for a policy with 32 roles.
   const byPath = SURFACES.get(config) ?? SURFACES.set(config, new Map()).get(config);
   const key = env.PATH ?? "";
   if (!roots && byPath.has(key)) return byPath.get(key);
@@ -233,17 +246,32 @@ function dedupe(entries) {
  * was: these are cheap to list and a role that can write one of them has no
  * policy.
  */
+const INPUTS = new WeakMap();            // config -> PATH -> entries
+
 export function parentInputs(config, { env = process.env } = {}) {
+  const byPath = INPUTS.get(config) ?? INPUTS.set(config, new Map()).get(config);
+  const key = env.PATH ?? "";
+  if (!byPath.has(key)) byPath.set(key, computeParentInputs(config, env));
+  return byPath.get(key);
+}
+
+/**
+ * `always` marks the three that are denied whatever the territory — the
+ * policy, `.seisin/` and the key directories. It is a field, not a comparison
+ * against the wording of `why`: that sentence is for people, and rewording it
+ * would have quietly moved a key directory out of every profile.
+ */
+function computeParentInputs(config, env) {
   const abs = (p) => (isAbsolute(p) ? p : join(config.root, p));
   const policy = abs(config.path ?? CONFIG_NAME);
   const out = [
-    { path: policy, why: "the policy" },
+    { path: policy, why: "the policy", always: true },
     // `seisin.toml.observed` is the proposal `init --from-observations` writes
     // for a person to diff and move onto the policy; a role that could write it
     // could plant a policy the operator then promotes in good faith.
-    { path: policy + ".observed", why: "the policy" },
-    { path: abs(STATE_DIR), why: "seisin's log and request queue" },
-    ...(config.keyDirs ?? []).map((d) => ({ path: abs(d), why: "a key directory" })),
+    { path: policy + ".observed", why: "the policy", always: true },
+    { path: abs(STATE_DIR), why: "seisin's log and request queue", always: true },
+    ...(config.keyDirs ?? []).map((d) => ({ path: abs(d), why: "a key directory", always: true })),
   ];
   for (const [scheme, p] of Object.entries(config.keyProviders ?? {})) {
     const cmd = p.command?.[0];
@@ -252,7 +280,7 @@ export function parentInputs(config, { env = process.env } = {}) {
     // A provider that does not resolve here is not denied here: the run that
     // needs it fails at resolution, with the message resolveExecutable gives.
     try { path = resolveExecutable(cmd, config, env); } catch { continue; }
-    out.push({ path, why: `the ${scheme}:// key provider, run outside the box` });
+    out.push({ path, why: `the ${scheme}:// key provider, run outside the sandbox` });
   }
   for (const { path, raw } of fileRefTargets(config))
     out.push({ path, why: `read by the parent for key "${raw}"` });
@@ -267,13 +295,14 @@ export function parentInputs(config, { env = process.env } = {}) {
 }
 
 /**
- * Files that tell a program running outside the box what to execute.
+ * Files that tell a program running outside the sandbox what to execute.
  *
  * 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
- * not escape the box; it leaves a command for you to run the next time you
+ * 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.
  *
@@ -287,36 +316,114 @@ 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, "\\$&");
+
+/** `name` as a whole path segment run, anywhere in a path. */
+const segment = (name, flags = "") => new RegExp(`(^|/)${literal(name)}(/|$)`, flags);
 
 // Case-insensitive, because the disk is: on APFS `.CLAUDE/Settings.json` is
-// the same file, and the kernel was measured refusing it.
-const CONTROL_RE = new RegExp(
-  `(^|/)(${CONTROL_FILES.map((f) => f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(/|$)`, "i");
+// the same file, and the kernel was measured refusing it. Compiled once: this
+// used to build one RegExp per control file on every call to protectedBy.
+const CLAUDE_DIR = segment(".claude", "i");
+const CONTROL_RES = CONTROL_FILES.map((c) => [c, segment(c, "i")]);
 
-/** Does this path name a control file, at any depth? What `explain` asks. */
-export const isControlPath = (p) => CONTROL_RE.test(p);
+/**
+ * Two more families of control files, which a role may be let to edit.
+ *
+ * The ones above make a program outside the sandbox *execute* something, and no
+ * role writes them. These two are softer, and that is why a policy can hand
+ * them to a role (`control_files = ["ide"]`, `["instructions"]`) where the
+ * others cannot be handed to anybody:
+ *
+ * - **ide** — `.vscode/`, `.cursor/`, `.windsurf/`. The editor applies them as
+ *   soon as they change: tasks, terminal profiles, settings that turn on tool
+ *   auto-approval or add an MCP server. GitHub Security Lab showed an injected
+ *   agent doing exactly that to `.vscode/settings.json`; the editor reloads
+ *   before a person can choose Undo. Protected by default — but a front-end
+ *   role that maintains its project's launch configs has a real reason to edit
+ *   them, and a boundary with no way to say so gets switched off whole.
+ * - **instructions** — `CLAUDE.md`, `AGENTS.md` and their kin. Nothing runs
+ *   them; the next agent session *reads* them, as instructions. One role
+ *   writing them is how it reaches another role's context. Off by default
+ *   (`[protect] instructions = true` turns it on), because keeping them current
+ *   is ordinary work for most teams, and git then fights the protection: a
+ *   role's `git checkout` cannot update a file it may not write, git exits 0,
+ *   and the old version stays behind as a modification.
+ */
+export const FAMILIES = {
+  ide: [".vscode", ".cursor", ".windsurf"],
+  instructions: ["CLAUDE.md", "AGENTS.md", "GEMINI.md", ".cursorrules", ".windsurfrules",
+    ".github/copilot-instructions.md", ".github/instructions"],
+};
+
+const EDITOR = { ".vscode": "VS Code", ".cursor": "Cursor", ".windsurf": "Windsurf" };
+// The families, compiled once per case rule (see protectedBy).
+const FAMILY_RES = {
+  fold: Object.fromEntries(Object.entries(FAMILIES).map(([f, names]) => [f, names.map((n) => [n, segment(n, "i")])])),
+  exact: Object.fromEntries(Object.entries(FAMILIES).map(([f, names]) => [f, names.map((n) => [n, segment(n)])])),
+};
+
+const familyWhy = (family, name) => family === "ide"
+  ? `${name}, whose settings and tasks ${EDITOR[name]} applies outside the sandbox`
+  : `${name}, which the next agent session reads as its instructions`;
+
+/** The families this role's profile protects: the defaults, minus what the policy hands it. */
+export function familiesFor(config, role) {
+  const mine = new Set(role?.controlFiles ?? []);
+  const out = [];
+  if (!mine.has("ide")) out.push("ide");
+  if (config.protect?.instructions && !mine.has("instructions")) out.push("instructions");
+  return out;
+}
+
+/**
+ * A pattern that matches exactly `name` under `root`, and only there.
+ *
+ * `**\/.vscode` would also match inside `node_modules`, and npm would then
+ * drop those files from the packages it unpacks, with `EPERM` in a warning and
+ * exit 0. Anchored at the project root it cannot. The last character goes in a
+ * one-letter class so the runtime treats the entry as a pattern — which costs
+ * nothing at start-up — and not as a literal, which costs a rule for each of
+ * its ancestors and would be paid for every project whether the file is there
+ * or not.
+ */
+const exactly = (root, name) => `${root}/${name.slice(0, -1)}[${name.slice(-1)}]`;
 
 /** Where no control file is looked for: dependencies and build output. */
 const PRUNE = new Set(["node_modules", ".git", "vendor", "dist", "build", ".venv", "venv",
   "__pycache__", ".next", "target", ".turbo", ".cache", "Pods", ".gradle", ".dart_tool"]);
 
 /** A directory holding one of these is where somebody opens a project. */
-const MARKERS = new Set([".git", ".claude", ".mcp.json", ".envrc", ".codex"]);
+const MARKERS = new Set([".git", ".claude", ".mcp.json", ".envrc", ".codex",
+  ...FAMILIES.ide, ...FAMILIES.instructions.filter((f) => !f.includes("/"))]);
 
 /**
  * How deep under a territory to look for projects.
  *
- * Measured on the portfolio over every territory at once: depth 3 finds 128
+ * Measured on a multi-repo workspace over every territory at once: depth 3 finds 128
  * project roots reading 2.6k directories (~0.4 s under load); depth 4 finds
  * 130 reading 5.5k (0.9 s); depth 6, 132 and 2.1 s. The four below depth 3
  * are `.claude` folders agents left inside source trees (`features/…`,
  * `tests/Feature/Api`), not projects anybody opens — and on macOS the pattern
- * layer still refuses writing into them. The whole portfolio at depth 8 is
+ * layer still denies writing into them. The whole workspace at depth 8 is
  * 23k directories, which is why the walk is per role and never over the repo.
  */
 const SCAN_DEPTH = 3;
@@ -344,14 +451,14 @@ function projectRoots(dir, depth = SCAN_DEPTH) {
  * (never_writes has the measurement). A `.git` that is a file is a worktree
  * pointing at its repository, and the pointer is what gets protected.
  */
-function controlsOf(dir, platform) {
+function controlsOf(dir, platform, families = []) {
   const out = [];
   let git = null;
   try { git = statSync(join(dir, ".git")); } catch {}
   if (git?.isFile()) out.push({ path: join(dir, ".git"), why: "a worktree's pointer to its repository, read by git" });
   if (git?.isDirectory())
     for (const f of [".git/hooks", ".git/config"])
-      out.push({ path: join(dir, f), why: `${f}, run by git outside the box` });
+      out.push({ path: join(dir, f), why: `${f}, run by git outside the sandbox`, ifPresent: true });
   /**
    * `.claude` whole, as one entry, rather than its seven control files.
    *
@@ -364,13 +471,21 @@ function controlsOf(dir, platform) {
    * directory Claude Code reads its instructions to itself from.
    */
   if (platform !== "linux" || existsSync(join(dir, ".claude")))
-    out.push({ path: join(dir, ".claude"), why: ".claude, whose settings, hooks and skills Claude Code runs outside the box" });
+    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 box` });
+    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
+  // Linux gets nothing: bubblewrap would create the path to mount over it.
+  for (const family of families)
+    for (const f of FAMILIES[family]) {
+      const p = join(dir, f);
+      if (existsSync(p)) out.push({ path: p, why: familyWhy(family, f), family });
+    }
   return out;
 }
 
@@ -378,21 +493,80 @@ function controlsOf(dir, platform) {
  * The home's control files, one by one — never `~/.claude` whole.
  *
  * That directory is also where Claude Code keeps its sessions, todos and
- * history, and it writes them from inside the box on every turn. Denying the
+ * history, and it writes them from inside the sandbox on every turn. Denying the
  * directory would stop the agent; denying what it executes does not (checked
  * 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 box` }))
+    .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`.
  *
@@ -407,9 +581,9 @@ const ROOTS = new WeakMap();             // config -> dir -> project roots under
 
 export function denyFor(config, role, { env = process.env, platform = process.platform, observe = false } = {}) {
   // Memoised per config: `check` builds every role's settings and then asks
-  // for the same list again to show it; on the portfolio that was 2.6 s twice.
+  // 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);
@@ -432,9 +606,18 @@ 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 controls = repoDirs.flatMap((d) => rootsUnder(config, d)).flatMap((d) => controlsOf(d, platform));
+  const families = familiesFor(config, role);
+  // 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));
 
@@ -449,28 +632,47 @@ 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
         // own config and hooks, and the files that redirect a worktree to
         // another gitdir or config. Ordinary commits never write these, so
         // denying them costs a working role nothing; a role that could write
-        // one would leave a command for the next `git` outside the box. The
+        // one would leave a command for the next `git` outside the sandbox. The
         // subtree of `.git` stays writable on purpose, so the agent can commit.
         `${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 (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
   // territory, as they always were. What the providers and `file://` keys
   // point at is denied where this role can write it: `/usr/bin/security` in
   // every profile would be a rule about the machine, and no role reaches it.
-  const always = new Set(["the policy", "seisin's log and request queue", "a key directory"]);
-  const inputs = parentInputs(config, { env }).filter((e) => always.has(e.why) || inMine(e.path));
+  const inputs = parentInputs(config, { env }).filter((e) => e.always || inMine(e.path));
 
   return dedupe([...inputs, ...surface, ...controls, ...globs]);
 }
@@ -482,27 +684,83 @@ 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 } = {}) {
+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.
    */
-  const f = /(^|\/)\.claude(\/|$)/i.test(target)
+  /**
+   * 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_FILES.find((c) => new RegExp(`(^|/)${c.replace(/\./g, "\\.")}(/|$)`, "i").test(target));
-  if (f && (platform !== "linux" || existsSync(isAbsolute(target) ? target : join(config.root, target)))) {
+    : CONTROL_RES.find(([, re]) => re.test(target))?.[0];
+  const re = f === ".claude" ? CLAUDE_DIR : CONTROL_RES.find(([name]) => name === f)?.[1];
+  if (f && (platform !== "linux" || heldOnLinux(config, target, re))) {
     const why = f === ".claude"
-      ? ".claude, whose settings, hooks and skills Claude Code runs outside the box"
-      : `${f}, run by ${RUNNER(f)} outside the box`;
+      ? ".claude, whose settings, hooks and skills Claude Code runs outside the sandbox"
+      : controlWhy(f);
     return { path: target, why };
   }
+  /**
+   * The two families, as the kernel is given them. Case-insensitive on macOS
+   * only: APFS folds case and the kernel refuses `.VSCODE/`, ext4 does not, and
+   * saying "protected" about a spelling the kernel lets through is the one
+   * direction this project refuses. With a role, what the policy hands that
+   * role is not protected for it; without one, the answer carries the family
+   * so the caller can ask whose it is.
+   */
+  const active = role ? familiesFor(config, config.roles?.[role]) : familiesFor(config, null);
+  const compiled = platform === "darwin" ? FAMILY_RES.fold : FAMILY_RES.exact;
+  for (const family of active)
+    for (const [name, re] of compiled[family]) {
+      if (!re.test(target)) continue;
+      if (platform === "linux" && !heldOnLinux(config, target, re)) continue;
+      return { path: target, why: familyWhy(family, name), family };
+    }
   const full = realOrSelf(isAbsolute(target) ? target : join(config.root, target));
   return parentInputs(config)
     .find((e) => under(full, realOrSelf(e.path)) || under(join(config.root, target), e.path)) ?? null;
 }
 
+/**
+ * Whether the Linux kernel holds `target`: the path itself, or a directory
+ * above it that the same rule names, exists — bubblewrap denies what exists,
+ * and a denied directory takes everything created inside it. Checking only the
+ * target called `web/.vscode/settings.json` unprotected while `web/.vscode` was
+ * denied whole, so a grant for it went through and changed nothing.
+ */
+function heldOnLinux(config, target, re) {
+  const full = isAbsolute(target) ? target : join(config.root, target);
+  for (let at = full; ; at = dirname(at)) {
+    const rel = at.startsWith(config.root + sep) ? at.slice(config.root.length + 1) : at;
+    if (re.test(rel) && existsSync(at)) return true;
+    if (at === config.root || dirname(at) === at || !re.test(rel)) return false;
+  }
+}
+
 /**
  * What `seisin check` shows: every protection that takes something away from a
  * role — a path inside its territory that it will not be able to write — with
@@ -514,19 +772,21 @@ export function protectedBy(config, target, { platform = process.platform } = {}
  * surface.js.
  */
 export function protections(config, roles = Object.values(config.roles), opts = {}) {
-  const always = new Set(["the policy", "seisin's log and request queue", "a key directory"]);
   const byPath = new Map();
   for (const role of roles) {
     let entries;
     try { entries = denyFor(config, role, opts); } catch { continue; }
     for (const e of entries) {
-      if (always.has(e.why) || e.path.includes("*")) continue;
+      if (e.always || /[*?[\]]/.test(e.path)) continue;
       // Only what the role could otherwise write: a literal control-file path
       // is listed for every project in the territory whether it exists or not,
       // and the ones that do not exist are shown only if their project does.
-      const hit = byPath.get(e.path) ?? byPath.set(e.path, { path: e.path, why: e.why, roles: [] }).get(e.path);
+      const hit = byPath.get(e.path) ??
+        byPath.set(e.path, { path: e.path, why: e.why, roles: [], ifPresent: e.ifPresent === true }).get(e.path);
       hit.roles.push(role.name);
     }
   }
-  return [...byPath.values()].filter((e) => existsSync(e.path) || !e.why.includes(" run by "));
+  return [...byPath.values()]
+    .filter((e) => !e.ifPresent || existsSync(e.path))
+    .map(({ ifPresent, ...e }) => e);
 }