seisin 0.6.3 → 0.6.5

package/src/controls.js

@@ -19,7 +19,7 @@
  */
 import { createHash } from "node:crypto";
 import { loadConfig, CONTROL_FAMILIES, stripComment, closesArray } from "./config.js";
-import { settingsFor } from "./srt.js";
+import { settingsFor } from "./srt-settings.js";
 import { denyFor } from "./surface.js";
 import { cleanReason } from "./requests.js";
 

package/src/decide-request.js

@@ -0,0 +1,37 @@
+/** A person's decision, shared by the CLI and the console, never the MCP. */
+import { loadConfig } from "./config.js";
+import { editPolicy, requestsPath, asFileGrant, refuseIfBarred, applyGrant, settle } from "./requests.js";
+
+/**
+ * Looked up, applied and settled under one lock — the policy's, the one
+ * every grant takes (editPolicy). The lookup used to happen before it and
+ * the settle after it, so the console and `seisin grant` could both find the
+ * same request pending and both act on it. A decline takes the lock as well,
+ * though it writes no policy, for the same reason.
+ *
+ * The config is edited as text, so comments and order survive, and it is
+ * written before the queue is settled: if the write throws, the request is
+ * still open rather than marked done against a file that never changed.
+ *
+ * Selection stays with the interface: the CLI accepts positions and decorates
+ * the queue; the console accepts only a stable id and has its own errors.
+ * `reload: false` preserves CLI decline's use of its already loaded config;
+ * the console reloads even for a decline, so malformed policy still refuses it.
+ * `includeOnly: false` keeps CLI declines free of file-grant metadata, even
+ * when a sibling request reopened after an earlier one-file grant.
+ */
+export function decideRequest(config, { decision, reason, only = false, select, reload = true, includeOnly = true }) {
+  let request;
+  const result = editPolicy(config, (before) => {
+    const current = reload ? loadConfig(config.path, before) : config;
+    request = select(current);
+    if (decision !== "granted") return { toml: before, changed: false };
+    if (only) request = asFileGrant(request);
+    refuseIfBarred(current, request);
+    return applyGrant(before, request, reason);
+  }, {
+    // Keep settlement after the policy write, still under its lock.
+    after: () => settle(requestsPath(config.root), request.key, decision, reason, includeOnly ? { only: request.only } : undefined),
+  });
+  return { request, ...result };
+}

package/src/denial-attribution.js

@@ -0,0 +1,338 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * Split a POSIX shell word list, the way a shell would.
+ *
+ * This reads the runtime's attribution tag, which carries the wrapped command
+ * re-quoted for `sh -c` and truncated to 100 characters. Parsing it beats
+ * re-generating it: any correct quoting of the same argument list parses back to
+ * that list, so this keeps matching if the runtime changes how it quotes, which
+ * re-implementing its `quote()` would not.
+ *
+ * Truncation means the last word is usually a fragment and the closing quote is
+ * usually missing. That is expected, not an error — an unterminated word is
+ * returned as far as it got, and {@link isOurs} treats the final word as a
+ * prefix.
+ */
+export function shellSplit(line) {
+  const words = [];
+  let word = null;
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else word += c;
+      continue;
+    }
+    if (c === "'" || c === '"') { quote = c; word ??= ""; continue; }
+    if (c === "\\" && i + 1 < line.length) { word = (word ?? "") + line[++i]; continue; }
+    if (/\s/.test(c)) { if (word !== null) { words.push(word); word = null; } continue; }
+    word = (word ?? "") + c;
+  }
+  if (word !== null) words.push(word);
+  return words;
+}
+
+/**
+ * Was this tagged command the one this run launched?
+ *
+ * The second of two anchors, and it exists because the first one is racy: a
+ * refused `sh -c` can be dead before `ps` runs, and then a process tree proves
+ * nothing. This one does not depend on the process still existing.
+ *
+ * Compared as a *prefix*, because the tag holds only the first 100 characters:
+ * every complete word must match exactly, and the last word — the one the
+ * truncation cut — only has to start the same way. A command that agrees with
+ * ours for 100 characters and then differs would be credited to us, which is a
+ * wrong attribution we accept: it requires another sandbox on the same machine
+ * launching a command that matches ours to the byte for 100 bytes.
+ */
+export function isOurs(tagged, argv) {
+  if (!tagged) return false;
+  const words = shellSplit(tagged);
+  if (words.length === 0 || words.length > argv.length) return false;
+  for (let i = 0; i < words.length - 1; i++) if (words[i] !== argv[i]) return false;
+  const last = words[words.length - 1];
+  return argv[words.length - 1]?.startsWith(last) ?? false;
+}
+
+/**
+ * Is `pid` a descendant of `root`?
+ *
+ * This is the anchor for attribution, and it is the reason a denial from
+ * somebody else's sandbox never lands in this repo's log. The alternative was
+ * matching the decoded command against the one we launched, which would mean
+ * reimplementing the runtime's shell quoting and inheriting its bugs; a process
+ * tree is a fact the OS already holds.
+ *
+ * At most one `ps` per TREE_MS, and only until the session suffix is learned —
+ * after that the suffix alone is exact, because it is generated once per `srt`
+ * process. In practice that is one `ps` per run.
+ */
+export function descends(pid, root, snapshot) {
+  const parent = new Map(snapshot);
+  const seen = new Set();
+  let at = pid;
+  while (at && at !== 1 && !seen.has(at)) {
+    if (at === root) return true;
+    seen.add(at);
+    at = parent.get(at);
+  }
+  return false;
+}
+
+/**
+ * pid → ppid for every process this user can see, and in `tree.roots` the
+ * pids that are a sandbox run's root: an `srt`, or a `seisin run`.
+ *
+ * The roots are what makes "not ours" provable. A process outside our tree is
+ * someone else's only if its ancestry reaches another run; one whose ancestry
+ * ends at init was orphaned — `cmd &`, a build daemon, git's fsmonitor — and
+ * may well be ours, reparented when the shell that started it exited.
+ */
+export function processTree(run = execFileSync) {
+  const tree = new Map();
+  tree.roots = new Set();
+  try {
+    const out = run("/bin/ps", ["-Ao", "pid=,ppid=,args="], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    for (const line of out.split("\n")) {
+      const m = line.trim().match(/^(\d+)\s+(\d+)(?:\s+(.*))?$/);
+      if (!m) continue;
+      tree.set(Number(m[1]), Number(m[2]));
+      if (m[3] && RUN_ROOT.test(m[3])) tree.roots.add(Number(m[1]));
+    }
+  } catch {
+    // No tree means nothing can be attributed, which the caller handles by
+    // recording nothing. A permission tool does not invent an owner.
+  }
+  return tree;
+}
+
+/** The command line of an `srt` (however it was installed) or of `seisin run`. */
+const RUN_ROOT = /(?:^|[\s/])srt(?:\s|$)|sandbox-runtime\/dist\/cli\.js(?:\s|$)|(?:^|[\s/])(?:seisin|cli\.js)\s+run\s/;
+
+/**
+ * Does `pid` descend from a run root other than `root`?
+ *
+ * A table without command lines (`roots` absent) cannot tell an orphan from a
+ * stranger, and answers as before: alive and not ours is someone else's.
+ */
+export function underAnotherRun(pid, root, snapshot) {
+  if (!snapshot.roots) return true;
+  const seen = new Set();
+  for (let at = pid; at && at !== 1 && !seen.has(at); at = snapshot.get(at)) {
+    if (at !== root && snapshot.roots.has(at)) return true;
+    seen.add(at);
+  }
+  return false;
+}
+
+/**
+ * Attribution state for one run, independent of the log reader.
+ *
+ * The transport owns scheduling and shutdown. A refused snapshot requests a
+ * later look; revisiting held events must bypass arrival deduplication.
+ */
+export function createDenialAttribution(onDeny, {
+  pid = null, argv = null, treeFn = processTree, now = () => performance.now(),
+  stats = { attributed: 0, foreign: 0, unattributed: 0, dropped: 0 },
+  requestRecheck = () => {},
+} = {}) {
+  let suffix = null;               // learned once, exact from then on
+  let tree = null;                 // refreshed only while still learning
+  let treeAt = -Infinity;          // when `tree` was taken
+  let root = pid;                  // the srt pid; not known until after spawn
+  const mine = new Set();          // pids already proven to be ours
+  const held = [];                 // denials seen before they could be attributed
+  const foreignSuffixes = new Set(); // other sandboxes, proven while they were alive
+
+  /**
+   * One `ps` per TREE_MS at most, and a later look instead of a skipped one.
+   *
+   * `ps` is synchronous and it was taken for every denial from another sandbox
+   * while this run had not learned its own suffix — which, for a run that is
+   * never refused anything, is the whole run. Several cells at once is exactly
+   * that: 83 ms of blocked event loop per foreign line, measured. A line whose
+   * process may be younger than the last snapshot is not decided on it; it is
+   * held, and looked at again once the window has passed.
+   */
+  const snapshot = () => { tree = treeFn(); treeAt = now(); };
+
+  /**
+   * Two anchors, and either one is enough.
+   *
+   * Neither works alone. The process tree is exact while the process exists and
+   * proves nothing once it has exited — which, for the short commands that get
+   * refused most, is by the time the line arrives. The command tag survives the
+   * process but depends on the runtime's quoting staying recognisable.
+   *
+   * Whichever answers first hands over the session suffix, and from that point
+   * attribution is one string comparison: the suffix is generated once per `srt`
+   * process, so it separates this run from every other sandbox on the machine
+   * exactly. In practice the tag settles it on the first denial and the tree is
+   * never consulted.
+   */
+  const attribute = (d) => {
+    if (suffix) return d.suffix === suffix;
+    if (argv && isOurs(d.command, argv)) {
+      if (d.suffix) suffix = d.suffix;
+      return true;
+    }
+    if (root === null) return false;   // nothing to descend from yet
+    if (mine.has(d.pid)) return true;
+    // A suffix already proven foreign needs no `ps`: the suffix is per `srt`.
+    if (d.suffix && foreignSuffixes.has(d.suffix)) return false;
+    if (tree === null) snapshot();
+    if (!descends(d.pid, root, tree)) {
+      // A pid the snapshot does not have may simply be younger than it.
+      // Refresh once, then believe the answer — unless the last refresh was
+      // moments ago, and then look again later rather than refresh now. A pid
+      // it does have is answered: its parents do not change into ours.
+      if (treeAt < d.seen && !tree.has(d.pid)) {
+        if (now() - treeAt < TREE_MS) { requestRecheck(); return LATER; }
+        snapshot();
+      }
+      if (!descends(d.pid, root, tree)) {
+        // Alive, not ours by either anchor, and under another run — the tag
+        // did not match above. Every later line from that `srt` is someone
+        // else's without asking. Alive but under no run at all is an orphan
+        // (`cmd &`, a daemon): possibly ours, so its suffix stays undecided
+        // rather than turning this run's own later lines into strangers.
+        if (d.suffix && tree.has(d.pid) && underAnotherRun(d.pid, root, tree)) foreignSuffixes.add(d.suffix);
+        return false;
+      }
+    }
+    mine.add(d.pid);
+    // The first proven denial hands us the suffix for every later one.
+    if (d.suffix) suffix = d.suffix;
+    return true;
+  };
+
+  /**
+   * The same refusal, reported twice.
+   *
+   * macOS emits a violation from `kernel` and, for some of them, a second
+   * extended report from `sandboxd` carrying the identical `Sandbox:` line.
+   * They are one event and the log has to say so — `review` counts lines, and a
+   * denial that shows as two is a policy that looks twice as wrong as it is.
+   * Measured on the first real run: 31 doubled events out of 730.
+   *
+   * Keyed on what the kernel said, not on when we read it: two deliveries of one
+   * event agree on pid, operation and path and disagree on arrival time.
+   */
+  const recent = new Map();
+  const isRepeat = (d) => {
+    const key = `${d.pid}|${d.operation}|${d.path}`;
+    const now = Date.now();
+    for (const [k, t] of recent) if (now - t > REPEAT_MS) recent.delete(k); else break;
+    if (recent.has(key)) return true;
+    recent.set(key, now);
+    return false;
+  };
+
+  const consider = (d) => {
+    const verdict = attribute(d);
+    if (verdict === true) {
+      stats.attributed++;
+      // Report the deciding denial first: callbacks observe this replay order.
+      onDeny(d);
+      // Learning the suffix makes every held line decidable. Without this,
+      // denials that arrived while the first process was being identified —
+      // which on a fast command is all of them — are lost.
+      if (suffix && held.length) revisit();
+      return;
+    }
+    // Not ours *yet*. Two reasons, both temporary: the run has not spawned the
+    // child whose pid anchors attribution, or the process died before `ps`
+    // could see it. Either way a foreign sandbox and one of ours look the same
+    // from here, so hold the line rather than credit or discard it.
+    // A line put off to the next snapshot is held with or without a suffix:
+    // the look it is waiting for is the only thing that can decide it.
+    if (verdict === LATER || (!suffix && d.suffix && !foreignSuffixes.has(d.suffix))) {
+      stats.unattributed++;
+      held.push(d);
+      // Bounded, because the common case on a busy machine is a run that is
+      // never refused anything: it never learns its own suffix, so every
+      // denial from every other sandbox lands here and nothing ever drains it.
+      // Several cells running at once for hours is exactly that shape, and an
+      // unbounded array is how an instrument becomes the leak.
+      //
+      // Dropping the oldest is the right end to drop. What is still worth
+      // replaying is whatever arrived near the run's own first refusal; a
+      // denial from an hour ago that is still unattributed is not ours.
+      while (held.length > HELD_MAX) { held.shift(); stats.unattributed--; stats.foreign++; }
+      return;
+    }
+    stats.foreign++;
+  };
+
+  /** Re-examine what was held, now that something new is known. */
+  const revisit = () => {
+    for (const h of held.splice(0)) { stats.unattributed--; consider(h); }
+  };
+
+  return {
+    stats,
+
+    accept(d) {
+      d.seen = now();
+      // Deduplicated here and not in consider(), because a held denial goes
+      // through consider() a second time when it is finally attributed. Doing
+      // this there would drop every line that arrived before the child had a
+      // pid — which, on a short command, is all of them.
+      if (!isRepeat(d)) consider(d);
+    },
+
+    /**
+     * Name the process whose descendants count as ours.
+     *
+     * Separate from the constructor because the stream has to be listening
+     * *before* the child starts. A short command — the kind an agent runs
+     * hundreds of times — is refused and gone in single-digit milliseconds, so
+     * a monitor started after the spawn misses precisely the denials it exists
+     * to catch. Measured: with the stream started afterwards, a one-line `sh -c`
+     * refusal recorded nothing at all.
+     */
+    attributeTo(childPid) {
+      root = childPid;
+      if (held.length) revisit();
+    },
+
+    revisitPending() {
+      if (!suffix && held.length) revisit();
+    },
+  };
+}
+
+/**
+ * The shortest time between two `ps` snapshots while attribution is learning.
+ *
+ * Long enough that a burst of foreign denials costs one snapshot, not one
+ * each; short enough that a line held for a younger process is decided before
+ * anyone reads the log.
+ */
+export const TREE_MS = 250;
+
+/** What `attribute` answers for a line it has put off to the next snapshot. */
+const LATER = "later";
+
+/**
+ * How many undecided denials to keep while waiting to learn our own suffix.
+ *
+ * Generous enough to cover the startup window — where every denial arrives
+ * before there is anything to attribute it to — and small enough that a run
+ * which is never refused anything cannot accumulate another sandbox's traffic
+ * for the length of an agent session.
+ */
+const HELD_MAX = 500;
+
+/**
+ * How long two reports of one refusal can be apart and still be one event.
+ *
+ * The second copy — `sandboxd`'s extended report — follows the kernel's within
+ * milliseconds. Kept short so that a role genuinely retrying the same path a
+ * second later is still recorded as a second attempt, which is what makes
+ * `asked 3×` mean anything.
+ */
+const REPEAT_MS = 1000;

package/src/grants.js

@@ -1,7 +1,7 @@
 /**
  * What a line of policy grants on disk, as paths.
  *
- * Pulled out of srt.js, which used to hold both halves: translating a policy
+ * Pulled out of srt-settings.js, which used to hold both halves: translating a policy
  * into paths, and assembling the runtime's settings object out of them. The
  * first half has a second reader now — surface.js asks "what can ANY role
  * write?" to decide what the parent must not trust — and a module that needs

package/src/help.js

@@ -12,14 +12,15 @@ import { LIMITS } from "./inspect/limits.js";
 
 export const COMMAND_HELP = {
   run: {
-    usage: ["seisin run <role> [--observe] [--debug-env] [--agent <name>] [--handoff <id>] [--expect-denied <path>]... -- <command...>"],
-    values: ["--agent", "--handoff", "--expect-denied"],
+    usage: ["seisin run <role> [--observe] [--debug-env] [--agent <name>] [--handoff <id>] [--expect-denied <path>]... [--run-id <id>] -- <command...>"],
+    values: ["--agent", "--handoff", "--expect-denied", "--run-id"],
     flags: [
       ["--observe", "open the repo for this run and record what the agent writes; keys and network stay shut"],
       ["--debug-env", "print the environment variables the role does not get"],
       ["--agent <name>", "claude, codex or none: which agent the command runs, when seisin cannot tell from it (a wrapper script). Its home is the run's scratch; the other agents' sign-in is closed"],
       ["--handoff <id>", "this run takes a pending request handed to this role, and starts only if the policy routes that request here. Its own requests join the handoff chain"],
       ["--expect-denied <path>", "a path the caller will probe and expects to be denied (its own canary). That exact path is logged as expected and files no request; repeatable. Any other path is asked as usual"],
+      ["--run-id <id>", "the launcher's own id for this run, used in the log instead of a random one, so an orchestrator's records and seisin's join on it"],
     ],
     notes: ["Everything after -- is the command's own, flags included: `-- claude --settings x.json` goes to claude."],
     examples: ['seisin run frontend -- claude', 'seisin run backend --observe -- claude -p "…"'],
@@ -28,11 +29,12 @@ export const COMMAND_HELP = {
       ["128+n", "killed by signal n (130 for ctrl-c)"], ["2", "seisin could not start it (usage, policy, runtime)"]],
   },
   check: {
-    usage: ["seisin check [role] [--verbose] [--verify] [--parallel] [--system-log]"],
+    usage: ["seisin check [role] [--verbose] [--verify] [--parallel] [--system-log] [--json]"],
     flags: [["--verbose", "also print the protected paths and each warning's explanation (the limits of every repo: seisin help limits)"],
       ["--verify", "run each role's verify command inside its sandbox (the one thing check executes)"],
       ["--parallel", "experimental: with --verify, run role checks concurrently; shared resources may race"],
-      ["--system-log", "macOS: measure for 3 s whether the system log is dropping messages, and who writes the most; exits 1 when it is"]],
+      ["--system-log", "macOS: measure for 3 s whether the system log is dropping messages, and who writes the most; exits 1 when it is"],
+      ["--json", "the same answer for a program: seisin's version and capabilities, the sandbox each role gets (path and version), the warnings"]],
     examples: ["seisin check", "seisin check frontend --verbose", "seisin check backend --verify", "seisin check --verify --parallel"],
     exits: [["0", "the policy can be enforced as written (warnings included)"], ["1", "a role cannot be enforced as written, or its verify failed"], ["2", "usage or policy error"]],
   },

package/src/index.js

@@ -22,7 +22,7 @@ export { CONFIG_NAME, STATE_DIR, LOG_NAME } from "./layout.js";
 export { covers, ownersOf, keyHolders, explain, explainFileRead, readTarget } from "./owners.js";
 
 /** A policy, resolved into sandbox settings. */
-export { settingsFor } from "./srt.js";
+export { settingsFor } from "./srt-settings.js";
 
 /**
  * Keys that are references, and how a resolved value reaches a role.

package/src/inspect/enforce.js

@@ -1,4 +1,4 @@
-import { settingsFor } from "../srt.js";
+import { settingsFor } from "../srt-settings.js";
 
 export function enforceWarnings(config, roles) {
   const warnings = [];

package/src/inspect/files.js

@@ -4,7 +4,7 @@ import { lstatSync, readdirSync } from "node:fs";
 /**
  * A role's territory, sorted by what the kernel will do with each line.
  *
- * Three shapes get through `settingsFor` (see EXPRESSIBLE in srt.js): the whole
+ * Three shapes get through `settingsFor` (see EXPRESSIBLE in srt-settings.js): the whole
  * repo, a subtree `x/**`, and a literal path. The literal path is the one the
  * text cannot settle on its own — `data/base.sqlite` and `data` are both
  * literal, and to the kernel the second is a subtree because it is a directory.

package/src/inspect/home.js

@@ -1,4 +1,4 @@
-import { CREDENTIAL_HOMES } from "../srt.js";
+import { CREDENTIAL_HOMES } from "../srt-settings.js";
 
 /**
  * What a role can still read in YOUR home, which is the limit people are most

package/src/inspect/inject.js

@@ -12,7 +12,7 @@
  */
 import { injectKeysOf } from "../keys.js";
 import { sandboxesOf } from "../sandboxes/index.js";
-import { coversHost as covers } from "../srt.js";
+import { coversHost as covers } from "../srt-settings.js";
 
 export function injectWarnings(config, roles) {
   const out = [];

package/src/intake.js

@@ -47,10 +47,11 @@ export { policyId };
  * (`seisin run --expect-denied`): taken from the parent's own argv, never from
  * anything the sandbox can reach. See expectedByCaller below.
  */
-export function intake({ config, role, runId, observe = false, settings, notify, chain = null, expectDenied = [], trace = {} }) {
+export function intake({ config, role, runId, label = null, observe = false, settings, notify, chain = null, expectDenied = [], trace = {} }) {
   // `trace` is the launcher's (trace.js), read by the parent: in the stamp, so a
   // line the sandbox sends cannot claim another run's trace.
-  const stamp = { run: runId.slice(0, 8), policy: policyId(config), ...trace };
+  // The name the rest of the run's lines carry (the launcher's --run-id when it gave one).
+  const stamp = { run: label ?? runId.slice(0, 8), policy: policyId(config), ...trace };
   // No `at` from here or from the sandbox: append() stamps the parent's clock and
   // ignores any other. The confined process chose the time of its own lines —
   // it could date them into or out of every `since` window, or make its

package/src/keys.js

@@ -375,7 +375,7 @@ export function readFileRef(entry, root = ".", { exact = false } = {}) {
 export const RESERVED_ENV = new Set([
   // The last is handoff.js's CHAIN_ENV, spelled out: handoff.js reaches this
   // module through owners.js, and importing it back would be a cycle.
-  "SEISIN_ROLE", "SEISIN_CONFIG", SOCK_ENV, "SEISIN_HANDOFF_CHAIN",
+  "SEISIN_ROLE", "SEISIN_CONFIG", "SEISIN_ROOT", "SEISIN_STATE_DIR", SOCK_ENV, "SEISIN_HANDOFF_CHAIN",
   ...BASE, ...Object.keys(DEFAULTS),
 ]);
 
@@ -542,7 +542,7 @@ function injectGate(role) {
 
 /**
  * The role's `inject` keys as `{ entry, name, hosts }`, the single source both
- * the settings (srt.js) and `check` read. Throws when the policy is internally
+ * the settings (srt-settings.js) and `check` read. Throws when the policy is internally
  * inconsistent — an inject key with no `inject_hosts` entry, or an
  * `inject_hosts` entry naming a key that is not injected — because either one
  * is a masked credential that silently injects nowhere, or a host list that

package/src/kinds.js

@@ -85,6 +85,10 @@ const SCRATCH_FILE = [
   /^\.!\d+!/,                                  // `.!36165!file` — a copy in flight
   /^\.DS_Store$/,
   /^pytest-cache-files-/,
+  // Vite and Vitest bundle a TS config into `vite.config.ts.timestamp-<ms>-<hash>.mjs`
+  // beside it, load it and delete it: a name that never repeats, found asked for
+  // 28 times in one orchestrator's queue, owned by a phase that takes no work.
+  /\.timestamp-\d+(-[0-9a-f]+)?\.[cm]?js$/,
   /(^|[-_])logs?$/i,                           // `logs`, `latest_logs`: what a run leaves
 ];
 /**
@@ -230,8 +234,22 @@ export function kindsOf(targets, opts = {}) {
 export const EXPECTED = {
   plugins:
     "Claude Code updating its plugins from inside the sandbox: plugins run outside it and update there, so the denial is expected — nothing to grant",
+  "os-background":
+    "macOS frameworks reaching for shared state every program touches at start (preferences, notifications, a compatibility sysctl): denied, and nothing the agent does depends on it — nothing to grant",
 };
 
+/**
+ * The system denials macOS frameworks cause in any sandboxed program, whatever
+ * it is doing: counted in one orchestrator's runs, 280 lines of them against the
+ * handful that were the task's. Exact names, so a service the agent itself asks
+ * for still reads as a wall.
+ */
+const OS_BACKGROUND = new Set([
+  "apple.shm.notification_center", "apple.cfprefs.daemonv1", "com.apple.AppleDatabaseChanged",
+  "kcfpreferencesanyapplication", "kern.tcsm_enable", "kern.system_version_compat",
+]);
+const OS_BACKGROUND_RE = /^apple\.cfprefs\.\d+v1$/;   // the per-user cfprefs segment
+
 /**
  * `{ kind, hint }` when the refusal of `target` is expected, else null.
  *
@@ -240,6 +258,7 @@ export const EXPECTED = {
  */
 export function expectedOf(target, { home = homedir(), env = process.env } = {}) {
   const t = String(target ?? "").replace(/\\/g, "/");
+  if (OS_BACKGROUND.has(t) || OS_BACKGROUND_RE.test(t)) return { kind: "os-background", hint: EXPECTED["os-background"] };
   const roots = [
     env.CLAUDE_CONFIG_DIR,
     home && `${home.replace(/\/+$/, "")}/.claude`,

package/src/layout.js

@@ -2,7 +2,7 @@
  * Where seisin's own files live. Names only — no logic, no imports.
  *
  * These were spread across the modules that happened to create each file, and
- * that produced one dependency that points the wrong way: `srt.js`, whose job
+ * that produced one dependency that points the wrong way: `srt-settings.js`, whose job
  * is translating a policy into a sandbox, imported `log.js` purely to learn the
  * name of the state directory it has to keep writable. A module that decides
  * what the kernel may allow should not know that logging exists.

package/src/log.js

@@ -16,13 +16,14 @@
 import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, dirname, join } from "node:path";
-import { STATE_DIR, LOG_NAME } from "./layout.js";
+import { LOG_NAME } from "./layout.js";
+import { stateDir } from "./state.js";
 import { send } from "./spool.js";
 
 export { STATE_DIR, LOG_NAME } from "./layout.js";
 
 export function logPath(root) {
-  return join(root, STATE_DIR, LOG_NAME);
+  return join(stateDir(root), LOG_NAME);
 }
 
 /**

package/src/mcp.js

@@ -30,7 +30,7 @@ import { toRepoRelative } from "./paths.js";
 import { loadConfig, findConfig } from "./config.js";
 import { inspect } from "./inspect.js";
 import { explain, ownersOf } from "./owners.js";
-import { settingsFor } from "./srt.js";
+import { settingsFor } from "./srt-settings.js";
 import { queueOf, queueData, refuseIfBarred, shellId } from "./requests.js";
 import { read, logPath } from "./log.js";
 import { causesOf, parseSince, queue as requestQueue, verdicts, wallsByRole } from "./views.js";

package/src/notify-config.js

@@ -0,0 +1,58 @@
+/**
+ * `[notify]` as the config loader reads it: validation only, so loading a
+ * policy does not pull in the request queue the sender needs (notify.js).
+ * Why each rule exists is in notify.js.
+ */
+import { join, resolve, sep } from "node:path";
+import { realAncestor } from "./paths.js";
+
+export const FORMATS = ["text", "json", "slack"];
+export const ENV_URL = "SEISIN_NOTIFY_URL";
+
+/**
+ * `[notify]` from seisin.toml, refused rather than guessed when it would leak.
+ * Called by the config loader.
+ */
+export function readNotify(table, { path, root, keyDirs, roles, own }) {
+  if (table === undefined) return null;
+  if (own(table, "url") !== undefined)
+    throw new Error(
+      `${path}: [notify] url is readable by every role — seisin.toml is not a secret. ` +
+      `Put the URL in a file inside a key directory no role declares and name it with url_file, ` +
+      `or set ${ENV_URL} in the environment that starts seisin.`);
+  const urlFile = own(table, "url_file");
+  const format = own(table, "format") ?? "text";
+  if (!FORMATS.includes(format))
+    throw new Error(`${path}: [notify] format = "${format}" is not one of ${FORMATS.join(", ")}`);
+  if (urlFile === undefined) return { urlFile: null, format };
+  if (typeof urlFile !== "string" || !urlFile.trim() || urlFile.startsWith("/") || urlFile.split("/").includes(".."))
+    throw new Error(`${path}: [notify] url_file must be a path inside the repo`);
+  const canonical = (p) => realAncestor(resolve(root, p));
+  const file = canonical(urlFile);
+  const inKeyDir = keyDirs.some((d) => file.startsWith(canonical(d) + sep));
+  if (!inKeyDir)
+    throw new Error(
+      `${path}: [notify] url_file "${urlFile}" is not inside a key directory, so every role can read ` +
+      `it. Move it under ${keyDirs[0] ?? "a [keys] dir"}.`);
+  // A file key is written bare (`netlify.txt`, meaning the first key directory)
+  // or with its directory (`shared/api.txt`) — the same resolution settingsFor uses.
+  const fileKey = (raw) => canonical(raw.includes("/") ? raw : join(keyDirs[0] ?? "", raw));
+  const holders = Object.entries(roles)
+    .filter(([, r]) => r.keyEntries?.some((k) => {
+      if (k.kind === "file") {
+        const held = fileKey(k.raw);
+        return file === held || file.startsWith(held + sep);
+      }
+      if (k.kind !== "ref" || k.scheme !== "file") return false;
+      // Match the builtin resolver's last-fragment rule. A reference delivers
+      // the contents even though it opens no filesystem read for the role.
+      const hash = k.ref.lastIndexOf("#");
+      return canonical(hash === -1 ? k.ref : k.ref.slice(0, hash)) === file;
+    }))
+    .map(([n]) => n);
+  if (holders.length)
+    throw new Error(
+      `${path}: [notify] url_file "${urlFile}" is declared as a key by ${holders.join(", ")} — ` +
+      `that role could read it and send the person a fake "grant this". No role may hold it.`);
+  return { urlFile, format };
+}