seisin 0.4.0 → 0.5.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,12 +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: abs(config.path ?? CONFIG_NAME), 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, 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", 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];
@@ -247,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}"` });
@@ -262,13 +295,13 @@ 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
+ * 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.
  *
@@ -288,30 +321,97 @@ export const CONTROL_FILES = [
 const RUNNER = (f) =>
   f.startsWith(".git/") ? "git" : f === ".envrc" ? "direnv" : f.startsWith(".codex/") ? "Codex" : "Claude Code";
 
+/** `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;
@@ -339,14 +439,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.
    *
@@ -359,13 +459,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"]) {
     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: `${f}, run by ${RUNNER(f)} outside the sandbox`, 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;
 }
 
@@ -373,7 +481,7 @@ 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).
@@ -384,7 +492,7 @@ function homeControls(platform) {
     ".claude/settings.json", ".claude/settings.local.json", ".claude/hooks", ".claude/plugins",
     ".claude/skills", ".claude/commands", ".claude/agents", ".codex/config.toml",
   ]
-    .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));
 }
 
@@ -402,7 +510,7 @@ 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 ?? ""}`;
   if (memo.has(key)) return memo.get(key);
@@ -427,7 +535,9 @@ 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);
+  const roots = [...new Set(repoDirs.flatMap((d) => rootsUnder(config, d)))];
+  const controls = roots.flatMap((d) => controlsOf(d, platform, families));
   // 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.
   if (["~/.claude", "~/.codex"].some((h) => inMine(join(homedir(), h.slice(2)))))
@@ -447,16 +557,32 @@ function computeDenies(config, role, { env, platform, observe }) {
     ? repoDirs.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 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`,
       ]).map((path) => ({ path, why: "any project's control files in this territory, by pattern" }))
     : [];
+  // 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)))
+            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]);
 }
@@ -468,27 +594,60 @@ 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 } = {}) {
   /**
    * 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)
+  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"
+      : `${f}, run by ${RUNNER(f)} outside the sandbox`;
     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
@@ -500,19 +659,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);
 }

package/src/uilink.js

@@ -26,9 +26,15 @@ function linkFile(port, base) {
   return join(runsRoot(base), `ui-${port}.url`);
 }
 
-/** Records this run's live URL for the port it bound. */
-export function writeUiLink(port, url, base) {
-  writeFileSync(linkFile(port, base), JSON.stringify({ url, pid: process.pid }) + "\n", { mode: 0o600 });
+/**
+ * Records this run's live URL for the port it bound, and the policy it serves.
+ *
+ * The record is per port, not per repo, so `ui --link` in one repo found the
+ * console another repo had started — and opened a page about the wrong policy
+ * 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 });
 }
 
 /**
@@ -46,7 +52,7 @@ export function readUiLink(port, base) {
     // Signal 0 tests for the process without touching it: it throws if gone.
     try { process.kill(e.pid, 0); alive = true; } catch { alive = false; }
   }
-  return { url: e.url, pid: e.pid ?? null, alive };
+  return { url: e.url, pid: e.pid ?? null, alive, policy: typeof e.policy === "string" ? e.policy : null };
 }
 
 /** Removes the record. Called on exit, and when a stale one is found. */