seisin 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -17,13 +17,13 @@
   ],
   "license": "MIT",
   "author": "Carlos Tapia",
-  "homepage": "https://github.com/carlostapiaolguin3-stack/seisin#readme",
+  "homepage": "https://carlostapiacl.github.io/seisin/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/carlostapiaolguin3-stack/seisin.git"
+    "url": "git+https://github.com/carlostapiacl/seisin.git"
   },
   "bugs": {
-    "url": "https://github.com/carlostapiaolguin3-stack/seisin/issues"
+    "url": "https://github.com/carlostapiacl/seisin/issues"
   },
   "type": "module",
   "bin": {
@@ -39,10 +39,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.76"
+    "@anthropic-ai/sandbox-runtime": "0.0.77"
   },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
   },
   "main": "./src/index.js",
   "exports": {

package/src/cli.js

@@ -30,6 +30,7 @@ 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 { wallsCommand } from "./commands/walls.js";
 import { reviewCommand } from "./commands/review.js";
 import { wire } from "./commands/wire.js";
 import { serveMcp } from "./mcp.js";
@@ -46,12 +47,14 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
   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 review [--all]                 what the log says about the policy
+  seisin walls <role> [--all]           what that role keeps being denied, and what it cost
   seisin wire                           let the agent record what it does
-  seisin requests                       what the agents asked for and could not do
+  seisin requests                       what the agents asked for and cannot have
   seisin grant <n> [--reason "…"]       approve one, with its provenance
-  seisin deny <n> [--reason "…"]        refuse one, and record why
+  seisin decline <n> [--reason "…"]     turn one down, and record why
   seisin log [--role r] [--verdict denied]
+  seisin log verify                     does the log's hash chain hold
   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
@@ -90,8 +93,19 @@ const COMMANDS = {
   whose: () => void whose(config(), argv),
   wire: () => void wire(config()),
   review: () => (reviewCommand(config(), argv).friction.length ? 1 : 0),
+  walls: () => (wallsCommand(config(), argv).length ? 1 : 0),
   requests: () => (requests(config()).length ? 1 : 0),
   grant: () => void grant(config(), argv),
+  /**
+   * A person DECLINES a request; the boundary DENIES a write. One word each,
+   * because they are opposite events and `deny` used to name both — a queue
+   * entry said `first refused on …` (the kernel) and the answer said
+   * `refused frontend ✕ …` (you).
+   *
+   * `deny` stays and is not documented. Renaming a published command over a
+   * word is not worth breaking somebody's script; teaching the new one is.
+   */
+  decline: () => void deny(config(), argv),
   deny: () => void deny(config(), argv),
   mcp: async () => {
     await serveMcp(version());

package/src/commands/explain.js

@@ -5,6 +5,7 @@
  * 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 { toRepoRelative } from "../paths.js";
 import { isAbsolute } from "node:path";
 import { explain } from "../owners.js";
 import { twinsOf, whereIs } from "../worktree.js";
@@ -13,9 +14,15 @@ 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>");
+    throw new Error("usage: seisin explain <role> <read|write|mcp> <path, key or MCP server>");
   if (!config.roles[role]) throw new Error(`unknown role "${role}"`);
 
+  if (action === "mcp") {
+    const verdict = explain(config, role, "mcp", target);
+    out(renderVerdict(role, "mcp", target, verdict));
+    return { ...verdict, worktree: [] };
+  }
+
   const verb = action.startsWith("r") ? "read" : "write";
 
   /**
@@ -34,7 +41,7 @@ export function explainCommand(config, argv = []) {
    * 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 asked = toRepoRelative(config, target);
 
   const verdict = explain(config, role, verb, asked);
   out(renderVerdict(role, verb, target, verdict));

package/src/commands/hook.js

@@ -9,6 +9,8 @@
  */
 import { findConfig, loadConfig } from "../config.js";
 import { decide } from "../hook.js";
+import { afterTool, atSessionStart } from "../diagnose.js";
+import { logPath } from "../log.js";
 import { flush } from "../spool.js";
 
 export async function hook(stdin = process.stdin, env = process.env) {
@@ -33,6 +35,15 @@ export async function hook(stdin = process.stdin, env = process.env) {
   }
   if (!config.roles[role]) return null;
 
+  // One command for every event it is wired to, so `seisin wire` adds one name.
+  // The after-the-fact and session-start halves only explain; neither decides.
+  const event_ = event.hook_event_name;
+  if (event_ === "PostToolUse" || event_ === "PostToolUseFailure") {
+    try { return await afterTool(config, role, event, { file: logPath(config.root) }); } catch { return null; }
+  }
+  if (event_ === "SessionStart") {
+    try { return atSessionStart(config, role, event, { file: logPath(config.root) }); } catch { 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

package/src/commands/init.js

@@ -126,7 +126,7 @@ export function renderObserved(config, entries) {
     const declared = config.roles[name];
     const seen = roles.get(name);
 
-    const from = declared ? declared.writes : [];
+    const from = declared ? declared.writesDeclared ?? declared.writes : [];
     const found = seen ? generalise([...seen.writes]).filter((w) => !from.includes(w)) : [];
     const keys = [
       ...(declared ? declared.keys : []),

package/src/commands/log.js

@@ -10,7 +10,7 @@
  */
 import { createReadStream, watch as watchDir } from "node:fs";
 import { dirname, relative } from "node:path";
-import { read, logPath, size } from "../log.js";
+import { read, logPath, size, verifyChain } from "../log.js";
 import { renderEntry, C, out } from "../render.js";
 
 const flag = (argv, name) => {
@@ -19,6 +19,7 @@ const flag = (argv, name) => {
 };
 
 export function log(config, argv = []) {
+  if (argv[0] === "verify") return verify(config);
   const entries = read(logPath(config.root), {
     role: flag(argv, "--role"),
     verdict: flag(argv, "--verdict"),
@@ -35,6 +36,31 @@ export function log(config, argv = []) {
   return entries;
 }
 
+/**
+ * `seisin log verify` — does the chain hold?
+ *
+ * Exit 1 when it does not, so it can sit in CI or a pre-commit hook. Lines from
+ * before the chain existed are reported as such, not as tampering.
+ */
+function verify(config) {
+  const r = verifyChain(logPath(config.root));
+  if (r.lines === 0) {
+    out(`\n  ${C.dim}nothing recorded yet${C.off}\n\n`);
+    return r;
+  }
+  const head = r.unchained ? `${r.unchained} line(s) from before the chain, then ` : "";
+  if (!r.breaks.length) {
+    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)\n\n`);
+    return r;
+  }
+  out(`\n  ${C.red}broken${C.off}  ${head}${r.chained} chained line(s), ${r.breaks.length} break(s):\n`);
+  for (const b of r.breaks.slice(0, 10))
+    out(`    line ${b.line}: expected prev ${b.expected}, found ${b.found ?? "none"}\n`);
+  out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n\n`);
+  process.exitCode = 1;
+  return r;
+}
+
 /**
  * Follows the log from wherever it is now.
  *

package/src/commands/requests.js

@@ -7,7 +7,8 @@
  * whole feature rests on — see docs/permission-requests.md.
  */
 import { readFileSync, writeFileSync } from "node:fs";
-import { pending, settle, applyGrant, requestsPath } from "../requests.js";
+import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale } from "../requests.js";
+import { read, logPath } from "../log.js";
 import { C, out } from "../render.js";
 
 /**
@@ -52,7 +53,7 @@ function pick(config, n) {
 }
 
 export function requests(config) {
-  const queue = pending(requestsPath(config.root));
+  const queue = markStale(pending(requestsPath(config.root)), read(logPath(config.root)));
   out(renderQueue(queue));
   return queue;
 }
@@ -70,10 +71,13 @@ export function renderQueue(queue) {
       // The stable way to name it: a number is a position in a queue that agents
       // are still writing to, and this does not move when the queue does.
       lines.push(`        ${C.dim}id ${r.key}${C.off}\n`);
+    // Marked, not moved: the number above is what `grant <n>` is typed against.
+    if (r.stale)
+      lines.push(`        ${C.dim}not asked again in ${r.stale.runs} runs of ${r.role} since — likely no longer needed${C.off}\n`);
     const note = handoffNote(r.handoff);
     if (note) lines.push(`        ${C.yellow}${note}${C.off}\n`);
   });
-  lines.push(`\n    ${C.dim}seisin grant <n> [--reason "…"]   ·   seisin deny <n> [--reason "…"]${C.off}\n\n`);
+  lines.push(`\n    ${C.dim}seisin grant <n> [--reason "…"]   ·   seisin decline <n> [--reason "…"]${C.off}\n\n`);
   return lines.join("");
 }
 
@@ -118,6 +122,7 @@ export function grant(config, argv = []) {
   const i = argv.indexOf("--reason");
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
 
+  refuseIfBarred(config, req);
   const before = readFileSync(config.path, "utf8");
   const { toml, changed } = applyGrant(before, req, reason);
   if (!changed) throw new Error(`${req.role} already has ${req.grant} — nothing to add`);

package/src/commands/review.js

@@ -20,6 +20,15 @@ import { C, out } from "../render.js";
 export function reviewCommand(config, argv = []) {
   const i = argv.indexOf("--min");
   const r = review(config, { minDenials: i === -1 ? 3 : Number(argv[i + 1]) });
+  // 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");
+  const TOP = 10;
+  const cap = (list) => (all ? list : list.slice(0, TOP));
+  const more = (list) => {
+    if (!all && list.length > TOP) out(`    ${C.dim}… ${list.length - TOP} more: seisin review --all${C.off}\n`);
+  };
+  const who = (owners) => owners.length > 3 ? `${owners.slice(0, 3).join(", ")} +${owners.length - 3}` : owners.join(", ");
 
   if (!r.entries) {
     out(`\n  ${C.dim}nothing recorded yet. Run an agent through seisin first.${C.off}\n\n`);
@@ -33,10 +42,11 @@ export function reviewCommand(config, argv = []) {
     out(`\n  ${C.b}Stopped, repeatedly${C.off}\n`);
     out(`  ${C.dim}a role blocked on the same place over and over is a policy that is wrong,${C.off}\n`);
     out(`  ${C.dim}not an agent that is misbehaving${C.off}\n\n`);
-    for (const f of r.friction) {
-      const whose = f.owners.length ? ` ${C.dim}— belongs to ${f.owners.join(", ")}${C.off}` : "";
+    for (const f of cap(r.friction)) {
+      const whose = f.owners.length ? ` ${C.dim}— belongs to ${who(f.owners)}${C.off}` : "";
       out(`    ${C.yellow}${String(f.times).padStart(4)}×${C.off}  ${C.b}${f.role}${C.off} ${f.action} ${f.where}${whose}\n`);
     }
+    more(r.friction);
     out(`\n  ${C.dim}seisin grant, or move the territory. Either way it is a decision, not noise.${C.off}\n`);
   }
 
@@ -49,12 +59,28 @@ export function reviewCommand(config, argv = []) {
    * two roles the credential directory*. Separated, the same lines read as
    * confirmation instead of as a recommendation, which is what they are.
    */
+  /**
+   * Connections, apart from both of the above: a port is not a territory, so
+   * "grant, or move the territory" does not answer it, and it is not the policy
+   * working either when the service is one the role was meant to reach.
+   */
+  if (r.connects?.length) {
+    out(`\n  ${C.b}Refused connections${C.off}\n`);
+    out(`  ${C.dim}a local port or socket the role kept dialling. Not a grant: a port goes in${C.off}\n`);
+    out(`  ${C.dim}local_ports, and a socket stays closed${C.off}\n\n`);
+    for (const c of cap(r.connects))
+      out(`    ${C.yellow}${String(c.times).padStart(4)}×${C.off}  ${C.b}${c.role}${C.off} ${c.where}\n`);
+    more(r.connects);
+    out(`\n  ${C.dim}seisin walls <role> says, per target, which of the two it is.${C.off}\n`);
+  }
+
   if (r.guarded.length) {
     out(`\n  ${C.b}Held at the keys${C.off}\n`);
     out(`  ${C.dim}a [keys] dir is closed to every role, so this is the policy working${C.off}\n`);
     out(`  ${C.dim}— not a territory drawn wrong, and never a thing to grant${C.off}\n\n`);
-    for (const g of r.guarded)
+    for (const g of cap(r.guarded))
       out(`    ${C.dim}${String(g.times).padStart(4)}×${C.off}  ${C.b}${g.role}${C.off} ${g.action} ${g.where}\n`);
+    more(r.guarded);
     out(`\n  ${C.dim}Worth a look only if a role genuinely needs one of these: that is a${C.off}\n`);
     out(`  ${C.dim}\`keys\` line for the file, never a write grant on the directory.${C.off}\n`);
   }
@@ -76,14 +102,16 @@ export function reviewCommand(config, argv = []) {
     out(`\n  ${C.b}Granted, never used${C.off}\n`);
     out(`  ${C.dim}nothing was written here in the window above. This is the only evidence${C.off}\n`);
     out(`  ${C.dim}anyone will ever have for making a permission file smaller${C.off}\n\n`);
-    for (const u of r.unused) out(`    ${C.b}${u.role}${C.off}  ${u.glob}\n`);
+    for (const u of cap(r.unused)) out(`    ${C.b}${u.role}${C.off}  ${u.glob}\n`);
+    more(r.unused);
     out(`\n  ${C.dim}A short window proves nothing. Check the dates before you delete a line.${C.off}\n`);
   }
 
   if (r.unowned.length) {
     out(`\n  ${C.b}Owned by nobody${C.off}\n`);
     out(`  ${C.dim}touched by an agent, claimed by no role — holes in the map${C.off}\n\n`);
-    for (const u of r.unowned.slice(0, 10)) out(`    ${String(u.times).padStart(4)}×  ${u.where}\n`);
+    for (const u of cap(r.unowned)) out(`    ${String(u.times).padStart(4)}×  ${u.where}\n`);
+    more(r.unowned);
   }
 
   if (!r.friction.length && !r.guarded.length && !r.unused.length && !r.unowned.length && r.unusedKnowable)