seisin 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "seisin",
+  "version": "0.1.0",
+  "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it blocks it tells you whose file it was.",
+  "keywords": [
+    "ai-agents",
+    "claude-code",
+    "sandbox",
+    "permissions",
+    "multi-agent",
+    "seatbelt",
+    "bubblewrap",
+    "codeowners",
+    "rbac",
+    "agent-permissions",
+    "code-ownership"
+  ],
+  "license": "MIT",
+  "author": "Carlos Tapia",
+  "homepage": "https://github.com/carlostapiaolguin3-stack/seisin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carlostapiaolguin3-stack/seisin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/carlostapiaolguin3-stack/seisin/issues"
+  },
+  "type": "module",
+  "bin": {
+    "seisin": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "ui",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.76"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  }
+}

package/src/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * seisin — give each agent its own folders and its own keys.
+ *
+ * This file is dispatch and nothing else: parse argv, load the config, call one
+ * command, turn a thrown error into an exit code. Every command lives in
+ * `commands/` and every decision lives in a module beside it, so that a change
+ * to how something is printed cannot change what is allowed.
+ *
+ * Enforcement is not ours. @anthropic-ai/sandbox-runtime asks the operating
+ * system — Seatbelt on macOS, bubblewrap on Linux — and the kernel does not
+ * care how a command was spelled. What seisin adds is the part a kernel can
+ * 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 { fileURLToPath } from "node:url";
+
+import { findConfig, loadConfig } from "./config.js";
+import { CONFIG_NAME } from "./layout.js";
+import { C, out, err } from "./render.js";
+
+import { run } from "./commands/run.js";
+import { check } from "./commands/check.js";
+import { explainCommand } from "./commands/explain.js";
+import { scanCommand } from "./commands/scan.js";
+import { init, initFromObservations } from "./commands/init.js";
+import { log, watch } from "./commands/log.js";
+import { hook } from "./commands/hook.js";
+import { ui } from "./commands/ui.js";
+import { requests, grant, deny } from "./commands/requests.js";
+import { whose } from "./commands/whose.js";
+import { reviewCommand } from "./commands/review.js";
+import { wire } from "./commands/wire.js";
+import { serveMcp } from "./mcp.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const [, , command, ...argv] = process.argv;
+
+const USAGE = `
+${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
+  seisin check [role]                   print the map, run nothing
+  seisin explain <role> read|write <path>
+  seisin whose <path>                   who owns it — safe to call from inside the box
+  seisin scan                           find secrets outside the declared key dirs
+  seisin review                         what the log says about the policy
+  seisin wire                           let the agent record what it does
+  seisin requests                       what the agents asked for and could not do
+  seisin grant <n> [--reason "…"]       approve one, with its provenance
+  seisin deny <n> [--reason "…"]        refuse one, and record why
+  seisin log [--role r] [--verdict denied]
+  seisin watch                          follow the log live
+  seisin init [--from-observations]     propose a ${CONFIG_NAME} for this repo
+  seisin ui [--port n]                  open the console, live
+  seisin mcp                            an MCP server on stdio — read-only
+
+Enforcement comes from @anthropic-ai/sandbox-runtime, 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() {
+  const path = findConfig();
+  if (!path) throw new Error(`no ${CONFIG_NAME} found here or above. Run "seisin init" to write one.`);
+  return loadConfig(path);
+}
+
+/**
+ * Commands that need a config get it; commands that make one do not.
+ *
+ * Each returns the exit code it wants, or nothing for zero. `run` and `ui` are
+ * the exceptions — they hand the process over and never come back here.
+ */
+const COMMANDS = {
+  run: async () => await run(config(), argv),
+  // Non-zero when the policy cannot be enforced as written, so `seisin check`
+  // composes in a pre-commit hook or CI the way `explain` and `scan` already do.
+  // Warnings about a config that WILL work still exit 0 — failing on those
+  // would make the command unusable within a week.
+  check: () => (check(config(), argv).warnings.some((w) => w.kind === "cannot-be-enforced") ? 1 : 0),
+  explain: () => (explainCommand(config(), argv).allowed ? 0 : 1),
+  scan: () => (scanCommand(config()).certain.length ? 1 : 0),
+  log: () => void log(config(), argv),
+  watch: () => void watch(config()),
+  init: () => void (argv.includes("--from-observations") ? initFromObservations(config()) : init()),
+  ui: () => ui(config(), argv),
+  whose: () => void whose(config(), argv),
+  wire: () => void wire(config()),
+  review: () => (reviewCommand(config(), argv).friction.length ? 1 : 0),
+  requests: () => (requests(config()).length ? 1 : 0),
+  grant: () => void grant(config(), argv),
+  deny: () => void deny(config(), argv),
+  mcp: async () => {
+    await serveMcp(version());
+    return 0;
+  },
+  hook: async () => {
+    const decision = await hook();
+    if (decision?.hookSpecificOutput) out(JSON.stringify(decision) + "\n");
+    return 0;
+  },
+  "--version": () => void out(version() + "\n"),
+  "-v": () => void out(version() + "\n"),
+};
+
+function version() {
+  return JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
+}
+
+const chosen = COMMANDS[command];
+if (!chosen) {
+  out(USAGE);
+  process.exit(command ? 2 : 0);
+}
+
+try {
+  const code = await chosen();
+  if (typeof code === "number") process.exit(code);
+} catch (e) {
+  err(`${C.red}seisin:${C.off} ${e.message}\n`);
+  process.exit(2);
+}

package/src/commands/check.js

@@ -0,0 +1,9 @@
+/** `seisin check` — print the map and every way it does not hold. Runs nothing. */
+import { inspect } from "../inspect.js";
+import { renderReport, out } from "../render.js";
+
+export function check(config, argv = []) {
+  const report = inspect(config, argv[0] ?? null, config.path);
+  out(renderReport(report));
+  return report;
+}

package/src/commands/explain.js

@@ -0,0 +1,87 @@
+/**
+ * `seisin explain` — ask one question, get the owner back.
+ *
+ * Exits 1 on a denial so it composes in a script: `seisin explain … || echo no`.
+ * That is the only reason the exit code is not always 0 — a denial is an answer,
+ * not a failure, but a shell has one channel for both.
+ */
+import { isAbsolute } from "node:path";
+import { explain } from "../owners.js";
+import { twinsOf, whereIs } from "../worktree.js";
+import { renderVerdict, C, out } from "../render.js";
+
+export function explainCommand(config, argv = []) {
+  const [role, action, target] = argv;
+  if (!role || !action || !target)
+    throw new Error("usage: seisin explain <role> <read|write> <path-or-key>");
+  if (!config.roles[role]) throw new Error(`unknown role "${role}"`);
+
+  const verb = action.startsWith("r") ? "read" : "write";
+
+  /**
+   * An absolute path inside the repo is the same question as the relative one.
+   *
+   * It was not being read that way: the policy is written in repo-relative
+   * paths, so an absolute target matched nothing and came back **denied — has
+   * no owner**, for a file its role could write perfectly well. `whose` has
+   * always stripped the root; the hook does too. Only this command did not, so
+   * the two answered differently about the same file, and the one people run to
+   * check a boundary was the one that was wrong.
+   *
+   * Wrong in the direction that matters, too: it reported a path as unowned and
+   * refused while the kernel allowed it — see "Refusing beats widening" in
+   * docs/decisions.md. A path outside the root is left exactly as written,
+   * because that is a question about somewhere else and it still deserves its
+   * honest "no owner".
+   */
+  const asked = target.startsWith(config.root + "/") ? target.slice(config.root.length + 1) : target;
+
+  const verdict = explain(config, role, verb, asked);
+  out(renderVerdict(role, verb, target, verdict));
+
+  const worktree = verb === "write" ? elsewhere(config, role, target, verdict) : [];
+  for (const w of worktree) out(renderElsewhere(w));
+  return { ...verdict, worktree };
+}
+
+/**
+ * The same question, asked about the same file in the other checkouts.
+ *
+ * Only a twin that gets a DIFFERENT answer is worth a line. A worktree where
+ * the role is equally allowed, or equally refused, changes nothing about what
+ * was just printed, and a diagnosis that mentions it anyway is the noise this
+ * tool keeps having to remove.
+ *
+ * The twin is asked about in the spelling the question used — root-relative
+ * for a root-relative question — so the two answers come from the same rule
+ * and differ only in where the file is.
+ */
+function elsewhere(config, role, target, verdict) {
+  const { here, twins } = twinsOf(config, target);
+  return twins
+    .map((t) => ({ ...t, verdict: explain(config, role, "write", isAbsolute(target) ? t.path : t.rel) }))
+    .filter((t) => t.verdict.allowed !== verdict.allowed)
+    .map((t) => ({ ...t, here, where: whereIs(config, here, t), asked: verdict }));
+}
+
+/**
+ * Three lines: where the other checkout is, what the answer is there, and
+ * which of the two the policy names — the sentence the refusal never carried.
+ */
+function renderElsewhere(t) {
+  const there = t.verdict.allowed
+    ? `is inside ${t.verdict.owners.join(", ")}'s territory`
+    : t.verdict.owners.length ? `belongs to ${t.verdict.owners.join(", ")}` : "has no owner";
+  const named = t.asked.allowed ? t.here : t;
+  const other = t.asked.allowed ? t : t.here;
+  // "allowed" is the answer that misleads, so it is the one that gets told
+  // where the refusal is. After "denied" that clause would only repeat it.
+  const refused = t.asked.allowed ? ` — a write in ${kind(other)} is refused` : "";
+  return (
+    `  ${C.yellow}worktree${C.off}  ${t.where}\n` +
+    `  ${C.dim}          the same file there is ${C.off}${C.b}${t.rel}${C.off}${C.dim}, and it ${there}.\n` +
+    `            The policy names ${kind(named)}, not ${kind(other)}${refused}.${C.off}\n\n`
+  );
+}
+
+const kind = (c) => (c.worktree ? "the worktree" : "the canonical checkout");

package/src/commands/hook.js

@@ -0,0 +1,42 @@
+/**
+ * `seisin hook` — the PreToolUse entry point.
+ *
+ * Claude Code runs this once per tool call, so every path through it is short
+ * and every failure is silent-and-permissive. That asymmetry is deliberate: the
+ * hook explains, the kernel enforces. A hook that crashes should cost you an
+ * explanation, never a blocked turn — and it cannot cost you a boundary,
+ * because it was never the boundary.
+ */
+import { findConfig, loadConfig } from "../config.js";
+import { decide } from "../hook.js";
+import { flush } from "../spool.js";
+
+export async function hook(stdin = process.stdin, env = process.env) {
+  const role = env.SEISIN_ROLE;
+  if (!role) return null;            // not launched by seisin: say nothing, block nothing
+
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+
+  let event;
+  try {
+    event = JSON.parse(raw || "{}");
+  } catch {
+    return null;                     // an unreadable event is not grounds to block work
+  }
+
+  let config;
+  try {
+    config = loadConfig(env.SEISIN_CONFIG ?? findConfig());
+  } catch {
+    return null;
+  }
+  if (!config.roles[role]) return null;
+
+  const decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1" });
+  // The entries went to a socket, and cli.js exits as soon as we return. An
+  // exit does not drain a socket, so the record would be lost precisely on the
+  // turns that produced one.
+  await flush();
+  return decision;
+}

package/src/commands/init.js

@@ -0,0 +1,181 @@
+/**
+ * `seisin init` — where the first policy comes from.
+ *
+ * Every permission tool dodges this question. Written by hand the first policy
+ * is a guess, and the first unjustified denial is when the tool gets
+ * uninstalled. So there are two ways in, and both of them **propose**:
+ *
+ *   init                      read what the repo already says about ownership
+ *   init --from-observations  read what the agents actually did
+ *
+ * The second is better and needs a run first. Neither writes a policy you did
+ * not read: `--from-observations` lands as `.observed`, not as the config.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CONFIG_NAME, tomlString, tomlName } from "../layout.js";
+import { read, logPath, observed, generalise } from "../log.js";
+import { C, out } from "../render.js";
+
+/**
+ * Three places a repo already says who does what, in order of how much it
+ * actually means. None is a policy, so all of them are proposals.
+ */
+export function discover(root) {
+  const agents = join(root, ".claude", "agents");
+  if (existsSync(agents)) {
+    const roles = readdirSync(agents)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => ({ name: f.replace(/\.md$/, ""), writes: [], keys: [] }));
+    if (roles.length) return { source: ".claude/agents/", roles };
+  }
+
+  for (const p of ["CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"]) {
+    const file = join(root, p);
+    if (!existsSync(file)) continue;
+    const paths = readFileSync(file, "utf8")
+      .split(/\r?\n/)
+      .map((l) => l.replace(/#.*$/, "").trim())
+      .filter(Boolean)
+      .map((l) => l.split(/\s+/)[0])
+      .filter((g) => g && g !== "*");
+    if (paths.length)
+      return {
+        source: p,
+        roles: [...new Set(paths)].slice(0, 8).map((g, i) => ({
+          name: g.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "") || `role-${i + 1}`,
+          writes: [g.endsWith("/") ? g + "**" : g],
+          keys: [],
+        })),
+      };
+  }
+
+  return {
+    source: "nothing to read — this is a blank start",
+    roles: [
+      { name: "frontend", writes: ["src/web/**"], keys: [] },
+      { name: "backend", writes: ["src/api/**"], keys: [] },
+    ],
+  };
+}
+
+/** The proposed config, as TOML. Pure: takes what `discover` found. */
+export function renderConfig(found) {
+  const lines = [
+    "# seisin — which folders each agent writes, and which keys it may read.",
+    "#",
+    `# Proposed from: ${found.source}`,
+    "# Nothing here is enforced until you run the agent through `seisin run`.",
+    "# Anything not listed is denied. There is no permissive default.",
+    "",
+    "# [keys]",
+    '# dir = ".secrets"      # every key lives here; roles name the files they may read',
+    "",
+    "[network]",
+    "# The agent's own API comes first. Leave it out and the agent cannot even",
+    "# authenticate — it fails with a 403 from the egress proxy before it does",
+    "# any work, which reads as a broken install rather than a strict policy.",
+    "#",
+    "# THE LIST BELOW IS CLAUDE'S. If a role runs a different agent, add that",
+    "# agent's host or the role will sit inside a perfect territory unable to",
+    "# reach its own model. Per role:  [roles.NAME]  network = [ ... ]",
+    "allow = [",
+    '  "api.anthropic.com", "*.anthropic.com",',
+    '  "github.com", "*.github.com",',
+    '  "registry.npmjs.org", "pypi.org", "files.pythonhosted.org"',
+    "]",
+    "",
+  ];
+  for (const r of found.roles) {
+    lines.push(`[roles.${tomlName(r.name)}]`);
+    lines.push(`writes = [${r.writes.map(tomlString).join(", ")}]`);
+    lines.push(`keys   = [${r.keys.map(tomlString).join(", ")}]`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/** The observed config, as TOML. Pure: takes the log entries. */
+export function renderObserved(config, entries) {
+  const roles = observed(entries);
+  const lines = [
+    `# ${CONFIG_NAME} — written from ${entries.length} observed action(s).`,
+    "#",
+    "# This is what your agents actually did, generalised to directories. Read it",
+    "# before you trust it: an agent that touched a file once by mistake asked for",
+    "# that directory here, and observation cannot tell intent from accident.",
+    "",
+  ];
+  if (config.keyDirs.length)
+    lines.push("[keys]", `dir = [${config.keyDirs.map(tomlString).join(", ")}]`, "");
+  lines.push("[network]", `allow = [${config.allowedDomains.map(tomlString).join(", ")}]`, "");
+
+  /**
+   * Every declared role appears, whether it acted or not.
+   *
+   * This used to emit only the roles the log had seen, and the file says "diff
+   * it, then move it" — so moving it deleted the territory of every role that
+   * happened to be idle during the observation window, silently. A role that
+   * did nothing is not a role that needs nothing; it is a role nobody watched.
+   *
+   * So observation *adds*. What was declared stays, what was seen is appended,
+   * and the comment beside each role says which part came from where — because
+   * the whole reason to read this file is to tell the two apart.
+   */
+  for (const name of new Set([...Object.keys(config.roles), ...roles.keys()])) {
+    const declared = config.roles[name];
+    const seen = roles.get(name);
+
+    const from = declared ? declared.writes : [];
+    const found = seen ? generalise([...seen.writes]).filter((w) => !from.includes(w)) : [];
+    const keys = [
+      ...(declared ? declared.keys : []),
+      ...(seen ? [...new Set([...seen.keys].map((k) => k.replace(/^.*\//, "")))] : []),
+    ];
+
+    // Every value below came out of the log, and the log records paths the
+    // agent chose. tomlString refuses what the format cannot hold rather than
+    // emitting a file that parses into something else.
+    lines.push(`[roles.${tomlName(name)}]`);
+    lines.push(`writes = [${[...from, ...found].map(tomlString).join(", ")}]`);
+    lines.push(`keys   = [${[...new Set(keys)].map(tomlString).join(", ")}]`);
+    lines.push(
+      seen
+        ? `# declared ${from.length}; observation added ${found.length} ` +
+          `(${seen.writes.size} path(s) written, ${seen.keys.size} key(s) read)`
+        : `# declared ${from.length}; this role did nothing while observing — kept as written`
+    );
+    lines.push("");
+  }
+  return { toml: lines.join("\n"), roles: roles.size };
+}
+
+export function init(cwd = process.cwd()) {
+  const target = join(cwd, CONFIG_NAME);
+  if (existsSync(target))
+    throw new Error(`${CONFIG_NAME} already exists here. Delete it first if you meant to start over.`);
+
+  const found = discover(cwd);
+  writeFileSync(target, renderConfig(found));
+  out(
+    `\n  wrote ${C.b}${CONFIG_NAME}${C.off} with ${found.roles.length} role(s) from ${found.source}\n` +
+    `  ${C.dim}These are a proposal, not a policy. Read them before you run anything.${C.off}\n\n` +
+    `  next:  seisin check\n\n`
+  );
+  return found;
+}
+
+export function initFromObservations(config) {
+  const entries = read(logPath(config.root), { verdict: "observed" });
+  if (entries.length === 0)
+    throw new Error("nothing observed yet. Run: seisin run <role> --observe -- <command>");
+
+  const { toml, roles } = renderObserved(config, entries);
+  const file = join(config.root, CONFIG_NAME + ".observed");
+  writeFileSync(file, toml);
+  out(
+    `\n  wrote ${C.b}${relative(process.cwd(), file)}${C.off} from ${entries.length} observation(s), ${roles} role(s)\n` +
+    `  ${C.dim}Not ${CONFIG_NAME} — a policy generated behind your back is not a policy. Diff it, then move it.${C.off}\n\n`
+  );
+  return { file, entries: entries.length, roles };
+}

package/src/commands/log.js

@@ -0,0 +1,68 @@
+/**
+ * `seisin log` and `seisin watch` — reading the record.
+ *
+ * Both are views of one append-only file and nothing else. `watch` is a tail:
+ * there is no daemon, because the file already is the shared state, so anything
+ * that can read it can follow it.
+ *
+ * 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 { dirname, relative } from "node:path";
+import { read, logPath, size } from "../log.js";
+import { renderEntry, C, out } from "../render.js";
+
+const flag = (argv, name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+};
+
+export function log(config, argv = []) {
+  const entries = read(logPath(config.root), {
+    role: flag(argv, "--role"),
+    verdict: flag(argv, "--verdict"),
+    limit: Number(flag(argv, "--limit") ?? 40),
+  });
+
+  if (entries.length === 0) {
+    out(`\n  ${C.dim}nothing recorded yet — run an agent through "seisin run"${C.off}\n\n`);
+    return entries;
+  }
+  out("\n" + entries.map(renderEntry).join(""));
+  const denied = entries.filter((e) => e.verdict === "denied").length;
+  out(`\n  ${C.dim}${entries.length} entries · ${denied} denied${C.off}\n\n`);
+  return entries;
+}
+
+/**
+ * Follows the log from wherever it is now.
+ *
+ * Watches the *directory*, not the file: the log may not exist yet when watch
+ * starts, and a watcher on a missing path is a watcher on nothing. The interval
+ * is the floor, because filesystem events are advisory on every platform that
+ * has them and absent on the ones that do not.
+ */
+export function watch(config, { interval = 500 } = {}) {
+  const file = logPath(config.root);
+  let at = size(file);
+  out(`\n  ${C.dim}watching ${relative(process.cwd(), file)} — ctrl-c to stop${C.off}\n\n`);
+
+  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 */ }
+      }
+    });
+  };
+
+  try { watchDir(dirname(file), () => drain()); } catch { /* platform without events */ }
+  return setInterval(drain, interval);
+}