seisin 0.6.4 → 0.6.5

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/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

@@ -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/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/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 };
+}

package/src/notify.js

@@ -23,13 +23,13 @@
  *     which every role can read.
  */
 import { readFileSync } from "node:fs";
-import { basename, join, resolve, sep } from "node:path";
+import { basename, join } from "node:path";
 import { keyOf, pending, requestsPath, grantFor, shellId, queueOf, withHandoffs } from "./requests.js";
 import { describeHandoff } from "./handoff.js";
-import { realAncestor } from "./paths.js";
 
-const FORMATS = ["text", "json", "slack"];
-const ENV_URL = "SEISIN_NOTIFY_URL";
+import { ENV_URL, FORMATS } from "./notify-config.js";
+
+export { readNotify } from "./notify-config.js";
 
 /** The URL to notify, or null. Read in the parent only. */
 function notifyUrl(config, env = process.env) {
@@ -142,51 +142,3 @@ function notificationFailure(error) {
   if (code === "ECONNREFUSED") return "connection unavailable";
   return "request failed";
 }
-
-/**
- * `[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 };
-}

package/src/owners.js

@@ -23,7 +23,7 @@ import { keptFor, shutByTerritory } from "./territory.js";
  * Does this glob cover this path? Supports `**`, `*`, `?` and a trailing `/`.
  *
  * A wildcard-free pattern is a **prefix**, because that is what the kernel is
- * given. `toWritePath` in srt.js hands `src/api` to `allowWrite` unchanged, and
+ * given. `toWritePath` in srt-settings.js hands `src/api` to `allowWrite` unchanged, and
  * a sandbox grants a path and everything under it — so `src/api`, `src/api/`
  * and `src/api/**` are one grant to the OS, and reading the first of them as
  * "that path only" made seisin describe a boundary that was not there.
@@ -246,7 +246,7 @@ export function ownersOf(config, path) {
     path = path.slice(root.length);
   }
   // A private folder has one owner, whatever else covers it: every other role
-  // is given a denyWrite on it (srt.js), and denyWrite wins over any territory.
+  // is given a denyWrite on it (srt-settings.js), and denyWrite wins over any territory.
   const mine = privateOwner(config, path);
   return Object.values(config.roles)
     .filter((r) => r.writes.some((g) => covers(g, path)) && !neverWrites(r, path, config))

package/src/rundir.js

@@ -31,10 +31,10 @@ export const RUNS_NAME = "snr";
 /**
  * Where a run's temp directory lives when the role may write no other: beside
  * the runs root, not inside it. The runs root is denied to writes as a whole
- * (srt.js), and a deny wins over any grant beneath it.
+ * (srt-settings.js), and a deny wins over any grant beneath it.
  */
 export const TMP_NAME = "snt";
-/** The settings file inside a run's directory. srt.js denies it to the run by this name. */
+/** The settings file inside a run's directory. srt-settings.js denies it to the run by this name. */
 export const SETTINGS_NAME = "settings.json";
 
 /**

package/src/sandboxes/command.js

@@ -72,8 +72,6 @@ export function assessCheck(argv, file, label) {
   return { unmet: [`${label} says it cannot hold this policy: ${why}`], warnings };
 }
 
-/** Only the answer: `[]` for yes, the reason for no. */
-export const askCheck = (argv, file, label) => assessCheck(argv, file, label).unmet;
 
 export function commandSandbox(name, command, check = null, { tagsDenials = false } = {}) {
   const assess = (_settings, { file } = {}) => (check ? assessCheck(check, file, `its check (${check[0]})`) : { unmet: [], warnings: [] });

package/src/sandboxes/srt.js

@@ -2,7 +2,7 @@
  * `srt`: @anthropic-ai/sandbox-runtime, the sandbox seisin was built on.
  *
  * The default, and the reference every other provider is measured against:
- * the settings seisin generates (srt.js, one level up) ARE this runtime's
+ * the settings seisin generates (srt-settings.js, one level up) ARE this runtime's
  * settings file, so it enforces all of them by construction and `unmet` is
  * always empty. What a run hands it is the file and the command, nothing else.
  */

package/src/sandboxes/tartaros.js

@@ -28,7 +28,7 @@ export const TARTAROS_PACKAGE = "@carlostapiacl/tartaros";
 
 /**
  * The tartaros seisin depends on first, one on PATH second, and nothing third:
- * the order srt is found in (srt.js), for the same reason. A tartaros built
+ * the order srt is found in (resolveSrt in sandboxes/srt.js), for the same reason. A tartaros built
  * once and left on PATH goes on answering after the pinned one has its fixes.
  *
  * The pinned one is an optional dependency: a package per platform with the