seisin 0.6.3 → 0.6.5

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/requests.js

@@ -33,7 +33,8 @@ import { protectedBy } from "./surface.js";
 import { appendFileSync, chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
-import { STATE_DIR, tomlString } from "./layout.js";
+import { tomlString } from "./layout.js";
+import { stateDir } from "./state.js";
 import { send } from "./spool.js";
 import { withLock, readEntries } from "./log.js";
 import { loadConfig, policyId } from "./config.js";
@@ -41,7 +42,7 @@ import { loadConfig, policyId } from "./config.js";
 const REQUESTS_NAME = "requests.jsonl";
 
 export function requestsPath(root) {
-  return join(root, STATE_DIR, REQUESTS_NAME);
+  return join(stateDir(root), REQUESTS_NAME);
 }
 
 /**
@@ -663,6 +664,10 @@ export function refuseIfBarred(config, request) {
  * one step to anyone else taking this lock.
  */
 export function editPolicy(config, mutate, { waitMs = 10000, after = null } = {}) {
+  // A JSON policy (`--policy x.json`) is generated by whoever launches the run;
+  // an edit here would be overwritten there, so it is made there.
+  if (String(config.path).endsWith(".json"))
+    throw new Error(`${config.path} is a generated JSON policy: change it where it is generated, not with grant`);
   return withLock(policyLockBase(config), () => {
     const before = readFileSync(config.path, "utf8");
     const result = mutate(before);
@@ -686,7 +691,7 @@ export function editPolicy(config, mutate, { waitMs = 10000, after = null } = {}
  * nothing confined can hold this one. withLock adds the `.lock`.
  */
 export function policyLockBase(config) {
-  const dir = join(config.root, STATE_DIR);
+  const dir = stateDir(config.root);
   mkdirSync(dir, { recursive: true });
   return join(dir, "policy");
 }
@@ -708,7 +713,7 @@ export function policyLockBase(config) {
 function writePolicy(config, text) {
   const mode = statSync(config.path).mode & 0o777;
   const name = `seisin.toml.tmp-${randomBytes(12).toString("hex")}`;
-  const stateTmp = join(config.root, STATE_DIR, name);
+  const stateTmp = join(stateDir(config.root), name);
   writeFileSync(stateTmp, text, { flag: "wx", mode });
   try {
     chmodSync(stateTmp, mode);

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/runs.js

@@ -17,11 +17,21 @@
  * seconds over hundreds of runs re-reads a directory listing and some stats,
  * not every log.
  */
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadConfig } from "./config.js";
-import { read, logPath } from "./log.js";
-import { requestsPath } from "./requests.js";
+import { read } from "./log.js";
+import { STATE_DIR, LOG_NAME } from "./layout.js";
+import { expectedOf } from "./kinds.js";
+
+/**
+ * An archived run's own files, always at `<run>/.seisin/`: a run folder is read
+ * as it was written, whatever `--state-dir` this process was given. A launcher
+ * that runs with `--policy <run>/seisin.toml --state-dir <run>/.seisin` writes
+ * each run straight into this shape, and has nothing to copy at the end.
+ */
+const logPath = (root) => join(root, STATE_DIR, LOG_NAME);
+const requestsPath = (root) => join(root, STATE_DIR, "requests.jsonl");
 
 /** The name a run's folder may have: what becomes `run=` in a link. */
 const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -51,9 +61,11 @@ export function runFolders(dir) {
   return names.filter((d) => d.isDirectory() && isRunId(d.name)).map((d) => d.name).sort();
 }
 
-/** Where a run's policy is. */
+/** Where a run's policy is: `seisin.toml`, or `seisin.json` for a launcher that generates JSON. */
 export function runPolicy(dir, id) {
-  return join(dir, id, "seisin.toml");
+  const toml = join(dir, id, "seisin.toml");
+  const json = join(dir, id, "seisin.json");
+  return existsSync(toml) || !existsSync(json) ? toml : json;
 }
 
 /**
@@ -66,7 +78,7 @@ function signatureOf(dir, id) {
   const root = join(dir, id);
   const log = logPath(root);
   return [
-    statSig(join(root, "seisin.toml")),
+    statSig(runPolicy(dir, id)),
     statSig(join(root, "run.json")),
     statSig(requestsPath(root)),
     statSig(log),
@@ -114,8 +126,8 @@ function summarize(dir, id) {
   let cfg;
   try { cfg = loadConfig(runPolicy(dir, id)); }
   catch (e) {
-    return { ...base, outcome: "unread", error: e.code === "ENOENT" ? "no seisin.toml in this run's folder" : e.message,
-      roles: [], denied: 0, byKind: {}, expected: 0, retried: 0, causes: [], hosts: [], entries: 0, canary: null };
+    return { ...base, outcome: "unread", error: e.code === "ENOENT" ? "no seisin.toml (or seisin.json) in this run's folder" : e.message,
+      roles: [], denied: 0, byKind: {}, expected: 0, retried: 0, causes: [], hosts: [], entries: 0, canary: null, dropped: 0 };
   }
   const all = read(logPath(cfg.root));
   /**
@@ -131,7 +143,9 @@ function summarize(dir, id) {
   const groups = new Map();
   for (const e of all) {
     if (e.verdict !== "denied") continue;
-    if (e.expected === true) { expected++; continue; }
+    // macOS framework housekeeping counts as expected even in a log written
+    // before seisin said so (kinds.js expectedOf).
+    if (e.expected === true || (e.kind === "system" && expectedOf(e.target))) { expected++; continue; }
     const k = e.kind ?? "file";
     byKind[k] = (byKind[k] ?? 0) + 1;
     if (k !== "system") denied++;
@@ -144,6 +158,9 @@ function summarize(dir, id) {
   const causes = [...groups.values()].sort((a, b) => b.times - a.times);
   const retried = causes.reduce((n, g) => n + (g.about === "system" ? 0 : g.times - 1), 0);
   const hosts = causes.filter((g) => g.about === "network").slice(0, 10).map(({ target, times }) => ({ target, times }));
+  // Batches of kernel messages the system log threw away during the run: its
+  // walls may be missing some. The boundary held; the record did not.
+  const dropped = all.filter((e) => e.event === "log-dropped").reduce((n, e) => n + (Number(e.batches) || 0), 0);
   const canaries = all.filter((e) => e.event === "canary");
   const canary = canaries.length ? canaries[canaries.length - 1] : null;
   const outcome = canaries.some((e) => e.confined === false) ? "refused" : denied ? "denied" : "clean";
@@ -164,6 +181,7 @@ function summarize(dir, id) {
     // Kept whole for the sum across runs, cut to RUN_CAUSES when sent.
     causes,
     canary: canary ? { confined: canary.confined !== false, reasons: canary.reasons ?? [] } : null,
+    dropped,
   };
 }
 
@@ -267,13 +285,14 @@ export function runsView(dir, filters = {}, { scanned = scanRuns(dir) } = {}) {
 function viewOf(dir, filters, every) {
   const shown = every.filter((r) => matches(r, filters))
     .sort((a, b) => cmp(b.started_at ?? "", a.started_at ?? "") || cmp(b.id, a.id));
-  const totals = { runs: shown.length, denied: 0, retried: 0, expected: 0, byKind: {}, outcome: {} };
+  const totals = { runs: shown.length, denied: 0, retried: 0, expected: 0, byKind: {}, outcome: {}, incomplete: 0 };
   for (const r of shown) {
     totals.denied += r.denied;
     totals.retried += r.retried;
     totals.expected += r.expected;
     for (const [k, n] of Object.entries(r.byKind)) totals.byKind[k] = (totals.byKind[k] ?? 0) + n;
     totals.outcome[r.outcome] = (totals.outcome[r.outcome] ?? 0) + 1;
+    if (r.dropped) totals.incomplete++;
   }
   return {
     mode: "runs",

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/index.js

@@ -49,6 +49,8 @@ export function sandboxesOf(config) {
 export function weigh(config, settings, { platform = process.platform, role = null, locate = true, file = null } = {}) {
   const list = sandboxesOf(config);
   const register = role ? machOf(config.roles?.[role]).register : [];
+  const exempt = role ? (config.roles?.[role]?.handoffExempt ?? []).map((e) => join(config.root, e)) : [];
+  const requests = role ? (config.roles?.[role]?.requests ?? []) : [];
   let scratch = null;
   let copies = 0;
   // The file a sandbox is asked about is the one it would be handed: the run's
@@ -63,7 +65,7 @@ export function weigh(config, settings, { platform = process.platform, role = nu
   try {
     const options = list.map((sandbox) => {
       const bin = locate ? sandbox.locate() : "(not looked up)";
-      const own = settingsOf(sandbox, settings, { machRegister: register });
+      const own = settingsOf(sandbox, settings, { machRegister: register, handoffExempt: exempt, requests });
       const asked = sandbox.asksFile && locate && bin;
       const ctx = { platform, role, bin, file: asked ? fileFor(own) : null };
       const { unmet, warnings } = sandbox.asksFile && !asked ? { unmet: [], warnings: [] }
@@ -78,7 +80,18 @@ export function weigh(config, settings, { platform = process.platform, role = nu
       const browser = register.length && !sandbox.machRegister
         ? [`a Mach service to register (${register.join(", ")}, for browsers): ${sandbox.name} is not given it, only srt and tartaros are`]
         : [];
-      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser], warnings, missing: bin ? null : sandbox.missing() };
+      // `handoff_exempt`: a folder where trust-handoff is not protected. Only a
+      // sandbox that opens exactly that is handed the role; srt protects its
+      // own surfaces with no way to exempt a subtree.
+      const exemption = exempt.length && !sandbox.handoffExempt
+        ? [`handoff_exempt (${config.roles[role].handoffExempt.join(", ")}): ${sandbox.name} cannot leave a folder out of its trust-handoff protection, tartaros can`]
+        : [];
+      // `requests`: methods and paths per host. srt takes them only as a library
+      // callback, so seisin cannot hand them to it.
+      const ruled = requests.length && !sandbox.requestRules
+        ? [`requests (${requests.map((q) => q.host).join(", ")}): ${sandbox.name} cannot limit the methods and paths of a host from its settings, tartaros can`]
+        : [];
+      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser, ...exemption, ...ruled], warnings, missing: bin ? null : sandbox.missing() };
     });
     const chosen = options.find((o) => o.bin && o.unmet.length === 0) ?? null;
     return { chosen, options };

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

@@ -17,6 +17,7 @@
  * check` says so), and the canary still checks every run that it can.
  */
 import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { join, dirname, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -27,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
@@ -58,7 +59,17 @@ export function dependencyTartaros(from = HERE) {
 }
 
 /** The command line for one run: the settings as they are, the role as a label. */
-export function tartarosArgv(bin, file, inner, { role = null, machRegister = [] } = {}) {
+/** Whether this tartaros takes `--egress-log` (0.1.0-alpha.18): asked once per binary. */
+const egressLog = new Map();
+export function supportsEgressLog(bin) {
+  if (!egressLog.has(bin)) {
+    const r = spawnSync(bin, ["--help"], { encoding: "utf8", timeout: 5000 });
+    egressLog.set(bin, `${r.stdout ?? ""}${r.stderr ?? ""}`.includes("--egress-log"));
+  }
+  return egressLog.get(bin);
+}
+
+export function tartarosArgv(bin, file, inner, { role = null, machRegister = [], log = null } = {}) {
   // A browser role gets tartaros's browser grants — the shared memory, IOKit
   // classes and sysctls a headless Chromium dies without (f7edae1) — and a
   // run-private TMPDIR, the only place it may open a unix socket (bcb0c69):
@@ -68,7 +79,13 @@ export function tartarosArgv(bin, file, inner, { role = null, machRegister = []
   // the role gets — built from the role's own list (env.js), with the hook's
   // socket, the role's name and its env-mode keys. tartaros's own scrub
   // (7f9925f) would drop those, and the hook would go silent.
-  return [bin, "run", ...(role ? ["--role", role] : []), "--inherit-env", ...browser, "--settings", file, "--", ...inner];
+  // --egress-log: tartaros's record of its egress broker's decisions, read back
+  // into seisin's log at the end of the run (commands/run.js, brokerDenials).
+  // Not --log, which also starts the effect collectors (more than a second a
+  // run, measured). A tartaros older than the flag gets nothing: an unknown
+  // option would refuse the run.
+  const record = log && supportsEgressLog(bin) ? ["--egress-log", log] : [];
+  return [bin, "run", ...(role ? ["--role", role] : []), "--inherit-env", ...browser, ...record, "--settings", file, "--", ...inner];
 }
 
 /** What tartaros says of this file: what it cannot hold, and its warnings. Only asked of a binary that was found. */
@@ -85,9 +102,15 @@ export const tartarosUnmet = (bin, file, ctx) => tartarosAssess(bin, file, ctx).
  * (tartaros 99b0117). Only when there is one: an unchanged role is handed the
  * same file as before, and srt, whose schema is strict, never sees the field.
  */
-export function tartarosSettings(settings, { machRegister = [] } = {}) {
-  if (!machRegister.length) return settings;
-  return { ...settings, network: { ...settings.network, allowMachRegister: machRegister.map((p) => `${p}*`) } };
+export function tartarosSettings(settings, { machRegister = [], handoffExempt = [], requests = [] } = {}) {
+  if (!machRegister.length && !handoffExempt.length && !requests.length) return settings;
+  let out = settings;
+  if (machRegister.length) out = { ...out, network: { ...out.network, allowMachRegister: machRegister.map((p) => `${p}*`) } };
+  // tartaros's own field (its --handoff-exempt), absolute: srt never sees it.
+  if (handoffExempt.length) out = { ...out, filesystem: { ...out.filesystem, handoffExempt } };
+  // tartaros's own field (its --allow-request): the only requests an allowed host gets.
+  if (requests.length) out = { ...out, network: { ...out.network, requestRules: requests } };
+  return out;
 }
 
 export const tartaros = {
@@ -100,6 +123,11 @@ export const tartaros = {
   masks: () => null,
   adapt: tartarosSettings,
   machRegister: true,
+  // Takes filesystem.handoffExempt (tartaros 0.1.0-alpha.18): a folder left out of
+  // its trust-handoff protection.
+  handoffExempt: true,
+  // Takes network.requestRules (0.1.0-alpha.18): methods and paths per host.
+  requestRules: true,
   assess: (_settings, { bin, file, platform } = {}) => tartarosAssess(bin, file, { platform }),
   unmet: (_settings, { bin, file, platform } = {}) => tartarosUnmet(bin, file, { platform }),
   wrap: (bin, file, _settings, inner, ctx) => tartarosArgv(bin, file, inner, ctx),

package/src/serve.js

@@ -16,10 +16,11 @@ import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadConfig } from "./config.js";
+import { decideRequest } from "./decide-request.js";
 import { read, logPath, logSegments } from "./log.js";
-import { settingsFor } from "./srt.js";
+import { settingsFor } from "./srt-settings.js";
 import { describeHandoff } from "./handoff.js";
-import { pending, requestsPath, settle, applyGrant, refuseIfBarred, editPolicy, cleanReason, asFileGrant, lastAgentOf, fileOnlyNote } from "./requests.js";
+import { pending, requestsPath, editPolicy, settle, cleanReason, lastAgentOf, fileOnlyNote } from "./requests.js";
 import { causesOf, describeWalls, parseSince, queue, verdicts, wallsByRole } from "./views.js";
 import { planEdit, hashOf } from "./controls.js";
 import { inspect } from "./inspect.js";
@@ -263,29 +264,17 @@ function decide(configPath, { key, decision, reason, scope = "folder" }) {
   const cfg = loadConfig(configPath);
   const file = requestsPath(cfg.root);
 
-  /**
-   * 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.
-   */
   let req = null;
   let result = null;
   try {
-    result = editPolicy(cfg, (before) => {
-      const current = loadConfig(configPath, before);
-      req = pending(file, { keyDirs: current.keyDirs }).find((r) => r.key === key);
-      if (!req) throw bad(`request ${key} is no longer pending — reload to see the queue as it is now`);
-      if (decision !== "granted") return { toml: before, changed: false };
-      if (scope === "file") req = asFileGrant(req);
-      refuseIfBarred(current, req);
-      return applyGrant(before, req, reason);
-    }, { after: () => settle(file, req.key, decision, reason, { only: req.only }) });
+    ({ request: req, ...result } = decideRequest(cfg, {
+      decision, reason, only: scope === "file",
+      select: (current) => {
+        const request = pending(file, { keyDirs: current.keyDirs }).find((r) => r.key === key);
+        if (!request) throw bad(`request ${key} is no longer pending — reload to see the queue as it is now`);
+        return request;
+      },
+    }));
   } catch (e) {
     if (e.code === "ELOCKED") throw Object.assign(new Error("another grant is in progress — try again in a moment"), { status: 503 });
     throw e;

package/src/spool.js

@@ -7,7 +7,7 @@
  * request queue writable by the process they are a record of: an agent could
  * truncate `log.jsonl`, rewrite a decision, or invent a request that had never
  * been refused. The files said "append-only" in their own comments and nothing
- * enforced it. An external review named this and was right.
+ * enforced it. A review named this and was right.
  *
  * So the file moves out of reach and a socket takes its place:
  *

package/src/{srt.js → srt-settings.js}

@@ -33,7 +33,7 @@ import {
   CREDENTIAL_HOMES, toWritePath, writePathsOf, otherAgentsCredentials,
 } from "./grants.js";
 
-// Re-exported: these were srt.js's exports before grants.js existed, and
+// Re-exported: these were srt-settings.js's exports before grants.js existed, and
 // callers (the CLI, the tests, anyone embedding seisin) import them from here.
 export {
   expand, homeFits, roleHome, roleHomeRoot, CREDENTIAL_HOMES, RUNTIME_WRITES,
@@ -535,8 +535,11 @@ export function settingsFor(config, roleName, spool = null, observe = false, { a
      * Masked credentials: the real value reaches the runtime's own environment
      * (run.js), never the sandbox, which sees `fake_value_…`. `mode: "mask"`
      * and the per-credential `injectHosts` are all that is emitted — no
-     * `extract`, `decode`, files or SigV4, and never `allowPlaintextInject`,
+     * `extract`, `decode`, files or `awsPairs`, and never `allowPlaintextInject`,
      * which over HTTPS carries the sentinel and so is deny with extra steps.
+     * An AWS pair under its usual names (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+     * is paired by the sandbox itself and re-signed (srt; tartaros from
+     * 0.1.0-alpha.18).
      */
     ...(credentials ? { credentials } : {}),
   };

package/src/state.js

@@ -0,0 +1,25 @@
+/**
+ * Where this process keeps seisin's own files: the log, the request queue and
+ * their lock.
+ *
+ * `<root>/.seisin/` unless a launcher keeps them elsewhere with `--state-dir`
+ * (an orchestrator that archives each run in a folder of its own, and should
+ * not have to copy a directory out of a worktree it is about to delete). The
+ * choice travels to everything a run starts as SEISIN_STATE_DIR, so the hook
+ * inside the sandbox and the parent agree on one place.
+ */
+import { join, resolve } from "node:path";
+import { STATE_DIR } from "./layout.js";
+
+let override = process.env.SEISIN_STATE_DIR ? resolve(process.env.SEISIN_STATE_DIR) : null;
+
+/** The state directory for a policy rooted at `root`. */
+export function stateDir(root) {
+  return override ?? join(root, STATE_DIR);
+}
+
+/** `--state-dir`: from now on, and for everything this process starts. */
+export function setStateDir(dir) {
+  override = resolve(dir);
+  process.env.SEISIN_STATE_DIR = override;
+}

package/src/suggest.js

@@ -41,12 +41,37 @@ export function unknownRole(config, role) {
  * `--verbsoe` is a question answered as if it had not been asked.
  * `values` are the flags that take the next word as their value.
  */
+/**
+ * A count a person types (`--min 3`): a whole number from 1. Anything else is
+ * refused; `Number("banana")` made every comparison false and the answer
+ * "no walls" looked like a real one.
+ */
+export function positiveInt(flag, value) {
+  if (!/^[1-9][0-9]*$/.test(String(value ?? ""))) {
+    const e = new Error(`${flag} takes a whole number from 1, not "${value ?? ""}"`);
+    e.usage = true;
+    throw e;
+  }
+  return Number(value);
+}
+
 export function checkFlags(command, argv, known, values = []) {
   const all = [...known, ...values];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--") break;
-    if (values.includes(a)) { i++; continue; }
+    if (values.includes(a)) {
+      // A flag that takes a value and has none is refused: `log --role` read
+      // as no filter at all, and answered for every role.
+      const v = argv[i + 1];
+      if (v === undefined || v === "--" || (v.startsWith("-") && v !== "-")) {
+        const e = new Error(`${a} needs a value\n  seisin ${command} --help lists its flags`);
+        e.usage = true;
+        throw e;
+      }
+      i++;
+      continue;
+    }
     if (!a.startsWith("-") || a === "-") continue;
     if (all.includes(a)) continue;
     const near = nearest(a, all);

package/src/surface.js

@@ -32,7 +32,8 @@ import { join, isAbsolute, delimiter, dirname, resolve, basename, sep } from "no
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { writePathsOf, realOrSelf } from "./grants.js";
-import { STATE_DIR, CONFIG_NAME } from "./layout.js";
+import { CONFIG_NAME } from "./layout.js";
+import { stateDir } from "./state.js";
 
 /** seisin's own package: the code the next `seisin run` executes. */
 const SEISIN_HOME = realOrSelf(join(dirname(fileURLToPath(import.meta.url)), ".."));
@@ -270,7 +271,7 @@ function computeParentInputs(config, env) {
     // 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 },
+    { path: stateDir(config.root), 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 ?? {})) {

package/src/territory.js

@@ -50,7 +50,7 @@
  * nothing else in a data root is.
  */
 import { readdirSync, lstatSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { realOrSelf, writePathsOf, expand } from "./grants.js";
 import { realAncestor } from "./paths.js";
 
@@ -59,6 +59,24 @@ export const READ_MODES = ["all", "territory"];
 /** Files an agent reads at start that live outside its home directory. */
 export const AGENT_FILES = { claude: ["~/.claude.json"], codex: [] };
 
+/**
+ * Files in HOME every process on the platform reads at start, whatever it is,
+ * and that hold nothing about anybody. On macOS CoreFoundation reads
+ * `~/.CFUserTextEncoding` (a text-encoding code, `0x1F5:0x0:0x0`); shut, it was
+ * 278 of 409 denials in one orchestrator's runs, every one of them noise.
+ * The system reads it from the account's home, not from `$HOME`: an
+ * orchestrator that gives each run its own HOME still sees the real file read
+ * (measured), so these resolve against the account, see `accountHome`.
+ */
+export const PLATFORM_FILES = { darwin: ["~/.CFUserTextEncoding"], linux: [] };
+
+/** The home directory of the account, from the user database, whatever `$HOME` says. */
+export function accountHome() {
+  try { return userInfo().homedir || homedir(); } catch { return homedir(); }
+}
+
+const expandAccount = (p) => (p.startsWith("~/") ? `${accountHome()}/${p.slice(2)}` : expand(p));
+
 /**
  * Where data lives, per platform. Whole roots: what is under them belongs to
  * somebody. `/opt/homebrew/var` and `/usr/local/var` hold the databases a
@@ -225,6 +243,7 @@ export function keptFor(config, role, { observe = false, agent, program } = {})
     // starts and says "Not logged in" (measured, 2026-10-09). A run of no
     // agent, or of another, does not get it.
     ...(agent ? (AGENT_FILES[agent] ?? []).map(expand) : []),
+    ...(PLATFORM_FILES[process.platform] ?? []).map(expandAccount),
     ...writePathsOf(config, role, { observe, agent }),
     ...(role.reads ?? []).map((p) => readPath(config.root, p)),
     ...(role.toolchain ?? []).map((p) => readPath(config.root, p)),