seisin 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it denies something it tells you whose file it was.",
   "keywords": [
     "ai-agents",
@@ -45,7 +45,7 @@
     "@anthropic-ai/sandbox-runtime": "0.0.81"
   },
   "optionalDependencies": {
-    "@carlostapiacl/tartaros": "0.1.0-alpha.16"
+    "@carlostapiacl/tartaros": "0.1.0-alpha.18"
   },
   "scripts": {
     "test": "node --test test/*.test.js",

package/src/canary.js

@@ -75,7 +75,7 @@ export async function runCanary({ srt, wrap = null, settingsFile, settings, env,
   // exists when the sandbox starts is one of them.
   const insideDir = writable ? join(writable, `.seisin-canary-${nonce}`) : null;
   const inside = insideDir ? join(insideDir, "in") : null;
-  // The runtime's shared temp directory (srt.js, SHARED_TMP): granted by the
+  // The runtime's shared temp directory (srt-settings.js, SHARED_TMP): granted by the
   // runtime to every sandbox, taken back by seisin. Probed where it exists;
   // where it does not, there is nothing beside which to write.
   const shared = isDir(SHARED_TMP_DIR) ? join(SHARED_TMP_DIR, `.seisin-canary-${nonce}`) : null;

package/src/cli.js

@@ -13,11 +13,12 @@
  * never know: which role a path belongs to, and therefore who to ask next.
  */
 import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { findConfig, loadConfig } from "./config.js";
 import { CONFIG_NAME } from "./layout.js";
+import { setStateDir } from "./state.js";
 import { C, out, err } from "./render.js";
 import { COMMAND_HELP, flagsOf, renderHelp, renderLimits } from "./help.js";
 import { nearest, checkFlags } from "./suggest.js";
@@ -36,8 +37,46 @@ import { nearest, checkFlags } from "./suggest.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const [, , command, ...argv] = process.argv;
 
+/**
+ * `--policy <file>` and `--state-dir <dir>`, for a launcher that keeps both out
+ * of the repo it runs in (an orchestrator with a folder per run). The policy is
+ * read from the file and rooted at the working directory; the log and the
+ * request queue go to the state directory. Both are taken out of seisin's own
+ * part of the line before the command reads it (after `--`, or after `run
+ * <role> <command>`, the words are the agent's), and both reach everything a
+ * run starts through the environment (SEISIN_CONFIG, SEISIN_ROOT,
+ * SEISIN_STATE_DIR).
+ */
+function ownEnd() {
+  const split = argv.indexOf("--");
+  if (split !== -1) return split;
+  if (command !== "run") return argv.length;
+  let i = 1;
+  const values = new Set([...(flagsOf("run")?.values ?? []), "--policy", "--state-dir"]);
+  while (i < argv.length && argv[i].startsWith("-")) i += values.has(argv[i]) ? 2 : 1;
+  return i;
+}
+function takeGlobal(name) {
+  const i = argv.indexOf(name);
+  if (i === -1 || i >= ownEnd()) return null;
+  const v = argv[i + 1];
+  if (v === undefined || v.startsWith("-")) {
+    err(`${C.red}seisin:${C.off} ${name} needs a value\n`);
+    process.exit(2);
+  }
+  argv.splice(i, 2);
+  return v;
+}
+const policyFlag = takeGlobal("--policy");
+const stateFlag = takeGlobal("--state-dir");
+if (stateFlag) setStateDir(stateFlag);
+const rootFlag = policyFlag ? process.cwd() : null;
+if (policyFlag) {
+  process.env.SEISIN_ROOT = rootFlag;
+}
+
 const USAGE = `
-${C.b}seisin${C.off} — give each agent its own folders and its own keys
+${C.b}seisin${C.off}: give each agent its own folders and its own keys
 
   seisin run <role> -- <command...>     run a command as that role
   seisin run <role> --observe -- <cmd>  open the repo and watch — the network stays shut
@@ -61,14 +100,18 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
   seisin mcp                            an MCP server on stdio — read-only
 
 seisin <command> --help lists a command's flags, examples and exit codes.
+Any command takes --policy <file> (the policy, rooted at the working directory) and
+--state-dir <dir> (where the log and the request queue go) for a launcher that keeps
+both outside the repo (docs/runs.md).
 seisin help limits says what seisin cannot do, in any repo.
 
-Enforcement comes from @anthropic-ai/sandbox-runtime, which asks the OS.
+Enforcement comes from the sandbox (sandbox-runtime by default, or tartaros), which asks the OS.
 seisin decides what to ask for, and says whose file it was when the answer is no.
 `;
 
 /** Loads the policy, or explains where to get one. */
 function config() {
+  if (policyFlag) return loadConfig(resolve(policyFlag), undefined, { root: rootFlag });
   const path = findConfig();
   if (!path) throw new Error(`no ${CONFIG_NAME} found here or above. Run "seisin init" to write one.`);
   return loadConfig(path);
@@ -76,6 +119,7 @@ function config() {
 
 /** The policy here, or null — for a command that can answer without one. */
 function maybeConfig() {
+  if (policyFlag) return config();
   const path = findConfig();
   return path ? loadConfig(path) : null;
 }

package/src/commands/check.js

@@ -3,22 +3,42 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { inspect } from "../inspect.js";
 import { renderReport, out, C } from "../render.js";
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stateDir } from "../state.js";
+
+const say = out;
 import { measureSystemLog } from "../violations.js";
 import { join } from "node:path";
-import { settingsFor } from "../srt.js";
+import { settingsFor } from "../srt-settings.js";
 import { weigh } from "../sandboxes/index.js";
 import { runsRoot } from "../rundir.js";
 import { channelName } from "../spool.js";
 
+/**
+ * What this seisin can be asked to do, for a launcher deciding which flags to
+ * pass: one list, instead of a version compared against minimums or a search
+ * through `--help`. A name is added when the feature ships and never removed
+ * while it works.
+ */
+export const CAPABILITIES = [
+  "policy-flag", "state-dir", "run-id", "expect-denied", "agent-flag", "handoff", "handoff-false",
+  "browsers", "local-ports", "key-mode-inject", "check-json", "ui-runs",
+];
+
 export async function check(config, argv = []) {
   if (argv.includes("--parallel") && !argv.includes("--verify"))
     throw new Error("--parallel is experimental and requires --verify");
+  const json = argv.includes("--json");
   const role = argv.find((a) => !a.startsWith("-")) ?? null;
   const report = inspect(config, role, config.path);
-  out(renderReport(report, { verbose: argv.includes("--verbose") }));
-  if (config.sandbox?.provider) report.sandboxes = sandboxes(config, role);
-  if (argv.includes("--verify")) report.verify = await verify(config, role, argv.includes("--parallel"));
-  if (argv.includes("--system-log")) report.systemLog = await systemLog();
+  if (!json) out(renderReport(report, { verbose: argv.includes("--verbose") }));
+  if (config.sandbox?.provider || json) report.sandboxes = sandboxes(config, role, { quiet: json });
+  // What a flag asked for runs in --json too, quietly, and lands in the JSON:
+  // skipping it answered "ok" about a check that never ran.
+  if (argv.includes("--verify")) report.verify = await verify(config, role, argv.includes("--parallel"), { quiet: json });
+  if (argv.includes("--system-log")) report.systemLog = await systemLog({ quiet: json });
+  if (json) out(JSON.stringify(asJson(config, report), null, 2) + "\n");
   return report;
 }
 
@@ -30,7 +50,8 @@ export async function check(config, argv = []) {
  * it before, with who is writing the most — the only lead to a fix. A flag,
  * because it takes seconds and `check` otherwise answers at once.
  */
-async function systemLog() {
+async function systemLog({ quiet = false } = {}) {
+  const out = quiet ? () => {} : say;
   const m = await measureSystemLog({ seconds: SYSTEM_LOG_SECONDS });
   if (!m.available) {
     out(`\n${C.dim}system log: not measured — ${m.reason}${C.off}\n`);
@@ -56,16 +77,17 @@ const SYSTEM_LOG_SECONDS = 3;
  * too. Printed only when `[sandbox] provider` is set: without it every role
  * runs under srt, as it always has, and there is nothing to choose.
  */
-export function sandboxes(config, only = null, { platform = process.platform } = {}) {
+export function sandboxes(config, only = null, { platform = process.platform, quiet = false } = {}) {
+  const out = quiet ? () => {} : say;
   const sock = join(runsRoot(), "check", channelName(platform));
   const rows = [];
-  out(`\n${C.b}sandboxes${C.off} (${config.sandbox.provider.join(" → ")})\n`);
+  out(`\n${C.b}sandboxes${C.off} (${(config.sandbox?.provider ?? ["srt"]).join(" → ")})\n`);
   for (const r of Object.values(config.roles)) {
     if (only && r.name !== only) continue;
     let settings;
     try { settings = settingsFor(config, r.name, sock); } catch (e) { rows.push({ role: r.name, chosen: null, error: e.message }); continue; }
     const { chosen, options } = weigh(config, settings, { platform, role: r.name });
-    rows.push({ role: r.name, chosen: chosen?.sandbox.name ?? null,
+    rows.push({ role: r.name, chosen: chosen?.sandbox.name ?? null, bin: chosen?.bin ?? null,
       options: options.map((o) => ({ name: o.sandbox.name, missing: o.missing, unmet: o.unmet, warnings: o.warnings })) });
     out(chosen ? `  ${C.green}✓${C.off} ${r.name}: ${chosen.sandbox.name}\n` : `  ${C.red}✗${C.off} ${r.name}: no sandbox can hold it\n`);
     // Held, but not the way the role may expect: the sandbox's own words.
@@ -82,6 +104,34 @@ export function sandboxes(config, only = null, { platform = process.platform } =
   return rows;
 }
 
+/** `--version`'s first line from a sandbox binary, or null: what a launcher would otherwise parse itself. */
+function versionOf(bin) {
+  if (!bin || bin === "(not looked up)") return null;
+  const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 5000 });
+  return r.status === 0 ? (r.stdout || "").split("\n")[0].trim() || null : null;
+}
+
+/** `check --json`: the same answer as the text, for a program. */
+function asJson(config, report) {
+  const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"));
+  return {
+    seisin: pkg.version,
+    platform: process.platform,
+    capabilities: CAPABILITIES,
+    policy: config.path,
+    root: config.root,
+    stateDir: stateDir(config.root),
+    roles: (report.sandboxes ?? []).map((s) => ({
+      role: s.role, sandbox: s.chosen, bin: s.bin ?? null, version: versionOf(s.bin), error: s.error ?? null,
+      unmet: (s.options ?? []).filter((o) => o.name !== s.chosen).map((o) => ({ sandbox: o.name, missing: o.missing, unmet: o.unmet })),
+    })),
+    warnings: report.warnings.map((w) => ({ kind: w.kind, role: w.role ?? null, headline: w.headline ?? w.message ?? null })),
+    ...(report.verify ? { verify: report.verify.map((v) => ({ role: v.role, ok: v.ok, status: v.status ?? null })) } : {}),
+    ...(report.systemLog ? { systemLog: { available: report.systemLog.available, dropped: report.systemLog.dropped ?? 0, reason: report.systemLog.reason ?? null } } : {}),
+    ok: checkStatus(report) === 0,
+  };
+}
+
 /**
  * The exit status: 1 when a role cannot be enforced as written, or when what a
  * flag asked for failed. `--system-log` is asked for like `--verify` and fails
@@ -105,15 +155,21 @@ export function checkStatus(report) {
  * The one thing `check` executes, which is why it is a flag: without it
  * `check` still runs nothing.
  */
-async function verify(config, only, parallel = false) {
+async function verify(config, only, parallel = false, { quiet = false } = {}) {
+  const out = quiet ? () => {} : say;
   const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
   const roles = Object.values(config.roles).filter((r) => (only ? r.name === only : true) && r.verify);
   const results = [];
   if (!roles.length) out(`\n${C.yellow}verify: no role ${only ? `"${only}" ` : ""}declares a verify command${C.off}\n`);
+  // The policy check read, passed on by name: one given with --policy (a JSON
+  // file outside the repo) is not where the child would look for seisin.toml.
+  // The state directory already travels as SEISIN_STATE_DIR.
+  const policy = config.path ? ["--policy", config.path] : [];
   const run = async (r) => {
+    const argv = [cli, "run", ...policy, r.name, "--agent", "none", "--", ...r.verify];
     const res = parallel
-      ? await runParallel(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], config.root)
-      : spawnSync(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], {
+      ? await runParallel(process.execPath, argv, config.root)
+      : spawnSync(process.execPath, argv, {
         cwd: config.root, encoding: "utf8", timeout: 300_000, env: process.env,
       });
     const ok = res.status === 0;

package/src/commands/hook.js

@@ -30,7 +30,7 @@ export async function hook(stdin = process.stdin, env = process.env) {
 
   let config;
   try {
-    config = loadConfig(env.SEISIN_CONFIG ?? findConfig());
+    config = loadConfig(env.SEISIN_CONFIG ?? findConfig(), undefined, { root: env.SEISIN_ROOT || null });
   } catch {
     return null;
   }

package/src/commands/log.js

@@ -8,7 +8,9 @@
  * Reading is the easy half. Writing goes through spool.js when the writer is
  * inside a sandbox, so that the record is not editable by what it records.
  */
-import { createReadStream, watch as watchDir } from "node:fs";
+import { closeSync, openSync, readSync, watch as watchDir } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { lineReader } from "../lines.js";
 import { dirname, relative } from "node:path";
 import { read, logPath, size, verifyLog, LOG_NAME } from "../log.js";
 import { renderEntry, C, out } from "../render.js";
@@ -120,21 +122,26 @@ export function watch(config, { interval = 500 } = {}) {
   let at = size(file);
   out(`\n  ${C.dim}watching ${relative(process.cwd(), file)} — ctrl-c to stop${C.off}\n\n`);
 
+  // One reader across reads: a line that arrives in two pieces is shown once
+  // it is whole, instead of being dropped as half-written. Read synchronously,
+  // so a filesystem event and the interval never interleave two reads.
+  const show = (line) => { try { out(renderEntry(JSON.parse(line))); } catch { /* not a log line */ } };
+  let reader = lineReader(show), text = new StringDecoder("utf8");
   const drain = () => {
     const end = size(file);
-    if (end <= at) { at = end; return; }   // truncated, or nothing new
-    const stream = createReadStream(file, { start: at, end: end - 1, encoding: "utf8" });
-    at = end;
-    let buf = "";
-    stream.on("data", (d) => (buf += d));
-    stream.on("end", () => {
-      for (const line of buf.split("\n")) {
-        if (!line.trim()) continue;
-        try { out(renderEntry(JSON.parse(line))); } catch { /* half-written line */ }
-      }
-    });
+    if (end < at) { reader = lineReader(show); text = new StringDecoder("utf8"); }   // truncated or rotated: start over
+    if (end <= at) { at = end; return; }
+    const fd = openSync(file, "r");
+    try {
+      const chunk = Buffer.alloc(end - at);
+      readSync(fd, chunk, 0, chunk.length, at);
+      at = end;
+      reader(text.write(chunk));
+    } finally { closeSync(fd); }
   };
 
-  try { watchDir(dirname(file), () => drain()); } catch { /* platform without events */ }
-  return setInterval(drain, interval);
+  let dir = null;
+  try { dir = watchDir(dirname(file), () => drain()); } catch { /* platform without events */ }
+  const timer = setInterval(drain, interval);
+  return { stop: () => { clearInterval(timer); dir?.close(); } };
 }

package/src/commands/requests.js

@@ -6,10 +6,10 @@
  * person acting in a channel the agent does not have. That is the invariant the
  * whole feature rests on — see docs/requests.md.
  */
-import { settle, applyGrant, refuseIfBarred, requestsPath, editPolicy, queueOf, queueData, shellId, asFileGrant, lastAgentOf, fileOnlyNote } from "../requests.js";
+import { queueOf, queueData, shellId, lastAgentOf, fileOnlyNote } from "../requests.js";
 import { describeHandoff } from "../handoff.js";
 import { keyHolders } from "../owners.js";
-import { loadConfig } from "../config.js";
+import { decideRequest } from "../decide-request.js";
 import { read, logPath } from "../log.js";
 import { C, out, safe } from "../render.js";
 
@@ -125,14 +125,10 @@ export function grant(config, argv = []) {
   // Looked up, applied and settled under one lock — the one the console's
   // decide takes too. Picking before the lock let this and the console both
   // find the same request open and act on it twice.
-  let req;
-  const { changed } = underLock(() => editPolicy(config, (before) => {
-    const current = loadConfig(config.path, before);
-    req = pick(current, which, "grant");
-    if (only) req = asFileGrant(req);
-    refuseIfBarred(current, req);
-    return applyGrant(before, req, reason);
-  }, { after: () => settle(requestsPath(config.root), req.key, "granted", reason, { only: req.only }) }));
+  const { request: req, changed } = underLock(() => decideRequest(config, {
+    decision: "granted", reason, only,
+    select: (current) => pick(current, which, "grant"),
+  }));
   // Said once, beside the grant it is about: a literal file is useless to an
   // agent that saves through a temporary beside it.
   const caveat = only ? fileOnlyNote(req.role, lastAgentOf(read(logPath(config.root)), req.role)) : "";
@@ -181,11 +177,10 @@ export function decline(config, argv = []) {
 
   // The policy is not edited, but the lock is still the policy's: it is the one
   // every decision takes, so a decline cannot settle what a grant is applying.
-  let req;
-  underLock(() => editPolicy(config, (before) => {
-    req = pick(config, argv[0], "decline");
-    return { toml: before, changed: false };
-  }, { after: () => settle(requestsPath(config.root), req.key, "declined", reason) }));
+  const { request: req } = underLock(() => decideRequest(config, {
+    decision: "declined", reason, reload: false, includeOnly: false,
+    select: (current) => pick(current, argv[0], "decline"),
+  }));
   out(
     `\n  ${C.yellow}declined${C.off}  ${req.role} ✕ ${req.grant}\n` +
     `  ${C.dim}${reason || "no reason recorded"}${C.off}\n\n`

package/src/commands/review.js

@@ -15,6 +15,7 @@
  * would mean a correct policy cannot go green.
  */
 import { review } from "../review.js";
+import { positiveInt } from "../suggest.js";
 import { parseSince } from "../views.js";
 import { C, out, safe } from "../render.js";
 import { wired } from "./wire.js";
@@ -30,7 +31,7 @@ export function reviewCommand(config, argv = []) {
   const since = s === -1 ? null : parseSince(argv[s + 1]);
   if (s !== -1 && !since)
     throw new Error(`--since takes a date (2026-10-01) or a duration back from now (7d, 12h, 2w), not "${safe(argv[s + 1] ?? "")}"`);
-  const r = review(config, { minDenials: i === -1 ? 3 : Number(argv[i + 1]), since });
+  const r = review(config, { minDenials: i === -1 ? 3 : positiveInt("--min", argv[i + 1]), since });
   // Ten rows per section unless --all: on a real 32-role log the full report
   // was 1,557 lines, which nobody reads.
   const all = argv.includes("--all");