seisin 0.1.1 → 0.3.0

package/src/log.js

@@ -13,7 +13,8 @@
  * tries the parent's socket first for exactly that reason; writing the file
  * directly is what happens when there is no parent, outside the box.
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { STATE_DIR, LOG_NAME } from "./layout.js";
 import { send } from "./spool.js";
@@ -37,13 +38,106 @@ export function append(file, entry) {
   if (send("log", entry)) return true;
   try {
     mkdirSync(dirname(file), { recursive: true });
-    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n");
+    withLock(file, () => {
+      // `prev` goes last and is computed from the previous line exactly as it
+      // sits on disk, so verifying needs nothing but the file.
+      const line = JSON.stringify({ at: new Date().toISOString(), ...entry, prev: hashOf(lastLine(file)) });
+      appendFileSync(file, line + "\n");
+    });
     return true;
   } catch {
     return false;
   }
 }
 
+/**
+ * The log is chained: every line carries `prev`, the hash of the line before it.
+ *
+ * The log is the record of who touched what and who was refused what, and it
+ * could be edited without a trace. A chain does not stop anyone with write
+ * access from rewriting it — nothing inside a file can — but it makes an edit,
+ * a deletion or a reordering show, and `seisin log verify` says where. Taken
+ * from nono's audit trail; the Merkle root and the signature it adds on top
+ * are left for when someone asks for them.
+ *
+ * The first chained line of a file points at GENESIS. A file started by
+ * rotation should point at the last line of the one before it; there is no
+ * rotation yet, and when there is, that is what it has to do.
+ */
+export const GENESIS = "0".repeat(32);
+
+export function hashOf(line) {
+  return line == null ? GENESIS : createHash("sha256").update(line).digest("hex").slice(0, 32);
+}
+
+/** The last complete line of the file, or null when there is none. */
+function lastLine(file) {
+  if (!existsSync(file)) return null;
+  const { size } = statSync(file);
+  if (size === 0) return null;
+  const from = Math.max(0, size - 64 * 1024);
+  const fd = openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(size - from);
+    readSync(fd, buf, 0, buf.length, from);
+    const lines = buf.toString("utf8").split("\n").filter((l) => l.trim());
+    return lines.length ? lines[lines.length - 1] : null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * One writer at a time. Several roles of a round run at once and write this
+ * same file; two of them reading the same last line would fork the chain.
+ * A lock left by a killed process is taken over after a few seconds.
+ */
+function withLock(file, fn) {
+  const lock = file + ".lock";
+  const deadline = Date.now() + 2000;
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx"));
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      try { if (Date.now() - statSync(lock).mtimeMs > 5000) { unlinkSync(lock); continue; } } catch {}
+      if (Date.now() > deadline) break;          // never block the run over bookkeeping
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+    }
+  }
+  try { return fn(); } finally { try { unlinkSync(lock); } catch {} }
+}
+
+/**
+ * Walk the file and say where the chain breaks.
+ *
+ * Lines written before the chain existed have no `prev`; they are counted as an
+ * unchained prefix, not reported as tampering. After the first chained line,
+ * a line without `prev` is itself a break.
+ */
+export function verifyChain(file) {
+  const out = { lines: 0, unchained: 0, chained: 0, breaks: [] };
+  if (!existsSync(file)) return out;
+  let previous = null;
+  let started = false;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    out.lines++;
+    let e = null;
+    try { e = JSON.parse(line); } catch {}
+    const prev = e?.prev;
+    if (!started && prev === undefined) { out.unchained++; previous = line; continue; }
+    started = true;
+    const expected = out.chained === 0 && out.unchained === 0 ? GENESIS : hashOf(previous);
+    const ok = prev === expected || (out.chained === 0 && prev === hashOf(previous));
+    if (!ok) out.breaks.push({ line: out.lines, expected, found: prev ?? null });
+    out.chained++;
+    previous = line;
+  }
+  return out;
+}
+
 /** Reads entries, newest last. A malformed line is skipped, never fatal. */
 export function read(file, { role, verdict, since, limit = 0 } = {}) {
   if (!existsSync(file)) return [];

package/src/mcp.js

@@ -26,12 +26,15 @@
  * The cost of this choice is written down under PROTOCOLS below: we track the
  * spec by hand, and the spec moves.
  */
+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 { pending, requestsPath, grantFor } from "./requests.js";
+import { pending, requestsPath, grantFor, refuseIfBarred, markStale } from "./requests.js";
 import { read, logPath } from "./log.js";
+import { causesOf } from "./serve.js";
+import { walls, wasted } from "./walls.js";
 
 /**
  * Versions this server will agree to.
@@ -60,14 +63,14 @@ const TOOLS = [
   {
     name: "seisin_explain",
     description:
-      "Whether a role may read or write a path, and whose it is if not. " +
-      "Use this before suggesting an agent touch a file. Read-only.",
+      "Whether a role may read or write a path, and whose it is if not; or, with action mcp, " +
+      "whether it may load an MCP server. Use this before suggesting an agent touch a file. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
         role: { type: "string" },
-        action: { type: "string", enum: ["read", "write"] },
-        target: { type: "string", description: "path, or key filename for a read" },
+        action: { type: "string", enum: ["read", "write", "mcp"] },
+        target: { type: "string", description: "path; key filename for a read; server name for mcp" },
       },
       required: ["role", "action", "target"],
     },
@@ -93,13 +96,35 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "seisin_causes",
+    description:
+      "Denials grouped by what was denied — by path, and one level coarser by the name at " +
+      "the end of it — with how many are on paths no role owns. This is the question " +
+      "`seisin_activity` cannot answer: the raw log has the events, this has them counted " +
+      "against the policy as it stands, so a cause that has been granted since stops " +
+      "counting. Reach for it before proposing a change: a day that is three quarters one " +
+      "filename is a tooling problem, and the same volume spread across unrelated paths is " +
+      "a question about who owns what. Read-only.",
+    inputSchema: { type: "object", properties: { limit: { type: "number" } } },
+  },
+  {
+    name: "seisin_walls",
+    description:
+      "What a role keeps being denied AND would still be denied today, with the calls it " +
+      "spent retrying. Recomputed against the policy rather than read out of the log, so " +
+      "something granted since is not listed. Use it to find out whether an agent is stuck " +
+      "rather than slow. Omit `role` for every role that has one. Read-only.",
+    inputSchema: { type: "object", properties: { role: { type: "string" } } },
+  },
   {
     name: "seisin_draft_grant",
     description:
       "Draft the change a pending request would make, as text, plus the command a person " +
       "runs to apply it. Reach for this after a refusal: the denial is already in " +
       "seisin_requests, and this turns it into a concrete proposal someone can approve. " +
-      "Writes nothing: the approval is a human action in another channel.",
+      "Read-only, and it is the tool where that matters most: the name says grant and it " +
+      "does not grant. The approval is a human action in another channel.",
     inputSchema: {
       type: "object",
       properties: { number: { type: "number", description: "position in seisin_requests" } },
@@ -139,24 +164,27 @@ const HANDLERS = {
     // that was not "read" fell into the write branch — including a typo, which
     // would answer the wrong question confidently. A declared schema that is
     // not enforced is documentation.
-    if (action !== "read" && action !== "write")
-      throw new Error(`action must be "read" or "write", got ${JSON.stringify(action)}`);
+    if (action !== "read" && action !== "write" && action !== "mcp")
+      throw new Error(`action must be "read", "write" or "mcp", got ${JSON.stringify(action)}`);
     if (typeof target !== "string" || !target)
       throw new Error("target must be a non-empty path");
     const cfg = config();
     if (!cfg.roles[role])
       return { error: `unknown role "${role}"`, known: Object.keys(cfg.roles) };
-    const verdict = explain(cfg, role, action, target);
-    return { ...verdict, alsoOwnedBy: action === "write" ? ownersOf(cfg, target) : undefined };
+    if (action === "mcp") return explain(cfg, role, "mcp", target);
+    const rel = toRepoRelative(cfg, target);
+    const verdict = explain(cfg, role, action, rel);
+    return { ...verdict, alsoOwnedBy: action === "write" ? ownersOf(cfg, rel) : undefined };
   },
 
   seisin_requests() {
     const cfg = config();
-    const queue = pending(requestsPath(cfg.root));
+    const queue = markStale(pending(requestsPath(cfg.root)), read(logPath(cfg.root)));
     return {
       pending: queue.map((r, i) => ({
         number: i + 1, role: r.role, action: r.action,
         wants: r.grant, ownedBy: r.owners, asked: r.times, lastAsked: r.last,
+        ...(r.stale ? { stale: `not asked again in ${r.stale.runs} runs of ${r.role} since` } : {}),
       })),
       // Said in the payload and not only in the tool description, because a
       // model reading this is deciding what to do next.
@@ -166,6 +194,40 @@ const HANDLERS = {
     };
   },
 
+  /**
+   * The same arithmetic the console's front page does.
+   *
+   * It lives here as well as there because the two readers are different and
+   * neither can do the other's work: a person opens the console, an agent
+   * calls this. Giving the agent only `seisin_activity` hands it the raw log
+   * and asks it to re-derive the grouping — without the policy, which is the
+   * half that makes the grouping mean anything.
+   */
+  seisin_causes({ limit }) {
+    const cfg = config();
+    const c = causesOf(cfg, read(logPath(cfg.root), { limit: 4000 }));
+    return {
+      total: c.total,
+      distinct: c.distinct,
+      unowned: c.unowned,
+      families: c.families,
+      causes: typeof limit === "number" ? c.causes.slice(0, limit) : c.causes,
+    };
+  },
+
+  seisin_walls({ role }) {
+    const cfg = config();
+    const file = logPath(cfg.root);
+    const names = role ? [role] : Object.keys(cfg.roles);
+    if (role && !cfg.roles[role]) throw new Error(`unknown role "${role}"`);
+    const out = {};
+    for (const r of names) {
+      const w = walls(cfg, r, { file });
+      if (w.length) out[r] = { walls: w, spentRetrying: wasted(w) };
+    }
+    return { roles: out, spentRetrying: Object.values(out).reduce((n, x) => n + x.spentRetrying, 0) };
+  },
+
   seisin_activity({ role, verdict, limit }) {
     if (verdict !== undefined && !["allowed", "denied", "observed"].includes(verdict))
       throw new Error(`verdict must be allowed, denied or observed, got ${JSON.stringify(verdict)}`);
@@ -182,6 +244,20 @@ const HANDLERS = {
     const req = pending(requestsPath(cfg.root))[Number(number) - 1];
     if (!req) throw new Error(`no pending request #${number}`);
 
+    // The same refusal `seisin grant` and the console apply, asked here first.
+    // Without it this drafted, as approvable, a request that `never_writes`
+    // cancels — and `grant` then refused what the draft had offered.
+    try {
+      refuseIfBarred(cfg, req);
+    } catch (e) {
+      return {
+        barred: e.message,
+        ownedBy: req.owners,
+        applyWith: null,
+        note: "Not approvable as it stands: never_writes wins over writes. Decline it with " +
+          `\`seisin decline ${number}\`, or remove the never_writes entry if the subtraction is wrong.`,
+      };
+    }
     const field = req.action === "read" ? "keys" : "writes";
     return {
       wouldAdd: { role: req.role, field, value: req.grant },

package/src/nested.js

@@ -0,0 +1,86 @@
+/**
+ * Agents that sandbox themselves, and why seisin has to say so first.
+ *
+ * `codex` confines every command it runs with its own `sandbox-exec` profile.
+ * macOS will not apply a second Seatbelt profile to a process that already has
+ * one, so inside `seisin run` it fails with:
+ *
+ *     sandbox-exec: sandbox_apply: Operation not permitted
+ *
+ * Measured, twice: the README has it from the original run and the lab
+ * reproduced it — exit 71, and the inner command never produced a byte.
+ *
+ * Two things make it a special case in a tool that otherwise has none.
+ *
+ * **It does not fail at the start.** The agent launches, reads, thinks, and
+ * dies on the first command it tries to confine. So the operator sees a turn
+ * that did nothing, which reads exactly like an agent with nothing to do.
+ *
+ * **And the error explains nothing.** It names neither seisin, nor the agent,
+ * nor the fix. For a tool whose whole claim is that a refusal tells you what
+ * happened, shipping the one message that says nothing is the worst available
+ * outcome — so this is checked before the spawn and said in words.
+ *
+ * It is a closed list, not a detector. Guessing which binaries sandbox
+ * themselves from their name would be wrong in both directions, and being
+ * wrong here means printing a warning about a thing that is not happening.
+ */
+
+/**
+ * What each agent does by default, and what turns it off.
+ *
+ * `on: true` means the agent confines by default, so the warning is the
+ * normal case and silence needs a flag. codex is that. gemini is the other
+ * way round: off unless asked. Getting this backwards means warning about a
+ * thing that is not happening, which trains people to skip the line.
+ *
+ * `opencode` is absent. It has been run under seisin and the
+ * README describes its behaviour, but nothing here has measured whether it
+ * confines its own commands, and a closed list holds only what was checked.
+ */
+const SELF_SANDBOXING = {
+  codex: {
+    on: true,
+    off: ["--dangerously-bypass-approvals-and-sandbox"],
+    // The subcommand whose entire job is to confine. No flag turns that off.
+    never: ["sandbox"],
+  },
+  gemini: { on: false, onWith: ["-s", "--sandbox"], off: ["--sandbox=false"] },
+};
+
+/** The basename of a command, without its path. */
+const bare = (c) => String(c ?? "").split("/").pop();
+
+/**
+ * The warning for this command line, or null.
+ *
+ * Takes the argv `run` is about to spawn, and looks only at the first token
+ * and its flags. Anything cleverer would be guessing at a shell it cannot
+ * parse, and a wrong warning is worse than no warning.
+ */
+export function nestedSandboxWarning(cmd = []) {
+  const name = bare(cmd[0]);
+  const spec = Object.prototype.hasOwnProperty.call(SELF_SANDBOXING, name) ? SELF_SANDBOXING[name] : null;
+  if (!spec) return null;
+
+  const rest = cmd.slice(1);
+  if ((spec.never ?? []).includes(rest[0]))
+    return (
+      `\`${name} ${rest[0]}\` exists to run a command inside a sandbox, so it cannot run inside ` +
+      `one. The OS will not apply a second profile to a process that already has one.\n` +
+      `  Run the command directly — seisin is already the boundary here.`
+    );
+
+  const turnedOff = (spec.off ?? []).some((f) => rest.some((a) => a === f || a.startsWith(f + "=")));
+  if (turnedOff) return null;
+  const confining = spec.on || (spec.onWith ?? []).some((f) => rest.includes(f));
+  if (!confining) return null;
+
+  return (
+    `${name} confines the commands it runs with its own sandbox, and the OS will not apply a ` +
+    `second profile to a process that already has one.\n` +
+    `  This does not fail here — it fails on the first command ${name} tries to run, which ` +
+    `looks like an agent that did nothing.\n` +
+    `  Run it with its own sandbox off: \`${name} … ${(spec.off ?? ["--no-sandbox"])[0]}\`.`
+  );
+}

package/src/notify.js

@@ -0,0 +1,146 @@
+/**
+ * Tell a person when a request is filed.
+ *
+ * The queue is where a refusal becomes a handoff, and a queue only works if
+ * somebody looks at it. It was asynchronous with nothing to say it had moved:
+ * the handoff existed and the person did not know. This sends one message per
+ * new request — the role, the path, whose it is, and the command that answers
+ * it — to wherever the operator reads things (ntfy, Slack, a webhook).
+ *
+ * Approving is still a person at a terminal. This only notifies; it does not
+ * accept an answer, so it changes nothing about who decides. (Accepting one —
+ * nono's `approval-webhook-v1` — would, and is a separate decision.)
+ *
+ * Two rules, both from the review that found a role approving its own request
+ * through the console:
+ *   - the POST leaves from the parent, never from the role: the role's process
+ *     never holds the URL, and `SEISIN_NOTIFY_URL` is dropped from its
+ *     environment even if the role names it;
+ *   - the URL is not readable from any territory. A ntfy topic or a webhook is
+ *     a credential — whoever can read it can send the person a fake "approve
+ *     #3". So it lives in a key directory no role declares (`url_file`), or in
+ *     the parent's environment, and never as a plain value in seisin.toml,
+ *     which every role can read.
+ */
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { keyOf, pending, requestsPath, grantFor } from "./requests.js";
+
+export const FORMATS = ["text", "json", "slack"];
+export const ENV_URL = "SEISIN_NOTIFY_URL";
+
+/** The URL to notify, or null. Read in the parent only. */
+export function notifyUrl(config, env = process.env) {
+  if (env[ENV_URL]) return env[ENV_URL].trim();
+  if (!config.notify?.urlFile) return null;
+  try {
+    const url = readFileSync(join(config.root, config.notify.urlFile), "utf8").trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The body for one request, in the chosen format. */
+export function message(config, req, number, format = "text") {
+  const owner = req.owners?.length ? `It belongs to ${req.owners.join(", ")}.` : "Nobody owns it.";
+  const text =
+    `seisin (${basename(config.root)}): ${req.role} was refused ${req.action} on ${req.target}. ${owner} ` +
+    `Approve: seisin grant ${number} · decline: seisin decline ${number}`;
+  if (format === "slack") return { type: "application/json", body: JSON.stringify({ text }) };
+  if (format === "json")
+    return {
+      type: "application/json",
+      body: JSON.stringify({
+        text, repo: basename(config.root), number, role: req.role, action: req.action,
+        target: req.target, owners: req.owners ?? [], grant: grantFor(req),
+      }),
+    };
+  return { type: "text/plain; charset=utf-8", body: text };
+}
+
+/**
+ * One per run. `maybe(req)` after a request is recorded; `settle()` before the
+ * run exits, so a message still in flight is not cut off.
+ *
+ * Only the first time a request appears — the queue already counts repeats,
+ * and a person pinged on every retry stops reading the pings.
+ */
+export function notifier(config, { env = process.env, fetchImpl = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  const url = notifyUrl(config, env);
+  const format = env.SEISIN_NOTIFY_FORMAT && FORMATS.includes(env.SEISIN_NOTIFY_FORMAT)
+    ? env.SEISIN_NOTIFY_FORMAT
+    : config.notify?.format ?? "text";
+  const file = requestsPath(config.root);
+  const known = url ? new Set(pending(file).map((p) => p.key)) : new Set();
+  const inflight = [];
+  const failures = [];
+
+  function maybe(req) {
+    if (!url) return false;
+    const key = keyOf(req);
+    if (known.has(key)) return false;
+    known.add(key);
+    const queue = pending(file);
+    const number = queue.findIndex((p) => p.key === key) + 1;
+    if (number < 1) return false;
+    const { type, body } = message(config, { ...req, owners: req.owners ?? queue[number - 1].owners }, number, format);
+    inflight.push(
+      fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": type },
+        body,
+        // A redirect would send the request to a place nobody configured.
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+        .then((r) => { if (!r.ok) failures.push(`HTTP ${r.status}`); })
+        .catch((e) => failures.push(e.name === "TimeoutError" ? "timed out" : e.message)),
+    );
+    return true;
+  }
+
+  async function settle(capMs = timeoutMs + 500) {
+    if (!inflight.length) return failures;
+    await Promise.race([Promise.allSettled(inflight), new Promise((ok) => setTimeout(ok, capMs))]);
+    return failures;
+  }
+
+  return { enabled: !!url, maybe, settle };
+}
+
+/**
+ * `[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 inKeyDir = keyDirs.some((d) => urlFile.startsWith(d.replace(/\/+$/, "") + "/"));
+  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 resolve = (raw) => (raw.includes("/") ? raw : join(keyDirs[0] ?? "", raw));
+  const holders = Object.entries(roles)
+    .filter(([, r]) => r.keyEntries?.some((k) => k.kind === "file" && resolve(k.raw) === urlFile))
+    .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 "approve". No role may hold it.`);
+  return { urlFile, format };
+}