seisin 0.3.0 → 0.4.2

package/src/log.js

@@ -13,9 +13,9 @@
  * 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, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { STATE_DIR, LOG_NAME } from "./layout.js";
 import { send } from "./spool.js";
 
@@ -39,17 +39,97 @@ export function append(file, entry) {
   try {
     mkdirSync(dirname(file), { recursive: true });
     withLock(file, () => {
+      // Rotate first, under the same lock: a full segment is renamed away and a
+      // fresh one seeded so the chain continues, then this line lands in the new
+      // segment. Done here so the size check and the append never race.
+      maybeRotate(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");
-    });
+    }, { waitMs: envInt("SEISIN_LOG_LOCK_WAIT_MS", 6000) });
     return true;
-  } catch {
+  } catch (e) {
+    // A line that could not get the lock is gone, and a missing line does not
+    // break the chain. Say so beside the log, so `verify` can.
+    if (e?.code === "ELOCKED") {
+      try { appendFileSync(droppedPath(file), JSON.stringify({ at: new Date().toISOString(), role: entry?.role, event: entry?.event }) + "\n"); } catch {}
+    }
     return false;
   }
 }
 
+/** Where entries that could not be written are counted. */
+export function droppedPath(file) {
+  return file + ".dropped";
+}
+
+function countLines(file) {
+  try { return readFileSync(file, "utf8").split("\n").filter((l) => l.trim()).length; } catch { return 0; }
+}
+
+/**
+ * When the current segment fills, retire it and start a fresh one that still
+ * chains.
+ *
+ * An append-only file that only grows is the right default and the wrong
+ * forever: a busy team writes megabytes of it, and `verify` walks all of them
+ * on every run. Rotation caps the size of the file three tools tail while
+ * keeping the property that made the chain worth having — that a deletion shows.
+ *
+ * The retired segment keeps its own chain intact; the new segment's first line
+ * is a `rotated` marker whose `prev` is the retired segment's last hash, so the
+ * two verify as one chain across the cut (`verifyLog`). The comment on GENESIS
+ * asked for exactly this. Segments are numbered upward, `.1` the oldest, and
+ * the oldest beyond the keep count are dropped — the only place seisin removes
+ * a record, and it removes whole retired segments, never a line.
+ */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;   // 8 MiB per segment
+const DEFAULT_KEEP = 5;                        // retired segments kept beside the current one
+
+function envInt(name, fallback) {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/** Every segment of the log, oldest → newest, current last. */
+export function logSegments(file) {
+  const dir = dirname(file);
+  const base = basename(file);
+  let names = [];
+  try { names = readdirSync(dir); } catch { return existsSync(file) ? [file] : []; }
+  const archives = names
+    .map((n) => {
+      if (!n.startsWith(base + ".")) return null;
+      const seq = Number(n.slice(base.length + 1));
+      return Number.isInteger(seq) && seq > 0 ? { seq, path: join(dir, n) } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.seq - b.seq)
+    .map((a) => a.path);
+  if (existsSync(file)) archives.push(file);
+  return archives;
+}
+
+function maybeRotate(file) {
+  let sz = 0;
+  try { sz = statSync(file).size; } catch { return; }
+  if (sz < envInt("SEISIN_LOG_MAX_BYTES", DEFAULT_MAX_BYTES)) return;
+
+  const tail = hashOf(lastLine(file));
+  const archives = logSegments(file).filter((p) => p !== file);
+  const seqs = archives.map((p) => Number(p.slice((file + ".").length))).filter(Number.isInteger);
+  const next = (seqs.length ? Math.max(...seqs) : 0) + 1;
+  renameSync(file, `${file}.${next}`);
+  // Seed the new current so the first real append chains from the retired tail.
+  const marker = JSON.stringify({ at: new Date().toISOString(), event: "rotated", from: `${basename(file)}.${next}`, prev: tail });
+  appendFileSync(file, marker + "\n");
+
+  const keep = envInt("SEISIN_LOG_KEEP", DEFAULT_KEEP);
+  const retired = logSegments(file).filter((p) => p !== file); // oldest → newest, includes the new archive
+  for (let i = 0; i < retired.length - keep; i++) { try { unlinkSync(retired[i]); } catch {} }
+}
+
 /**
  * The log is chained: every line carries `prev`, the hash of the line before it.
  *
@@ -90,23 +170,73 @@ function lastLine(file) {
 /**
  * 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.
+ *
+ * The lock names its holder (pid and a nonce). A lock whose holder is gone is
+ * taken over at once; one whose holder cannot be read is taken over once it is
+ * older than `staleMs`. The wait outlasts that age on purpose: a writer that
+ * died holding the lock can never make the next one give up, so the only entry
+ * ever dropped is one that waited on a writer still alive — and that drop is
+ * counted beside the log (see `append`), because a missing line does not break
+ * the chain and would otherwise not show.
  */
-function withLock(file, fn) {
+export function withLock(file, fn, { waitMs = 6000, staleMs = 5000 } = {}) {
   const lock = file + ".lock";
-  const deadline = Date.now() + 2000;
+  const deadline = Date.now() + waitMs;
+  const mine = `${process.pid} ${createHash("sha256").update(String(Math.random()) + Date.now()).digest("hex").slice(0, 12)}\n`;
+  let acquired = false;
   for (;;) {
     try {
-      closeSync(openSync(lock, "wx"));
+      const fd = openSync(lock, "wx");
+      try { writeSync(fd, mine); } finally { closeSync(fd); }
+      acquired = true;
       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
+      if (reapable(lock, staleMs)) continue;
+      // Never write without the lock. Doing so forks the hash chain; deleting
+      // the lock in `finally` then admits still more writers while its owner is
+      // active. The log is bookkeeping and append() may fail without taking the
+      // agent down, so dropping this entry is safer than fabricating evidence.
+      if (Date.now() > deadline) {
+        const error = new Error(`could not acquire log lock within ${waitMs} ms`);
+        error.code = "ELOCKED";
+        throw error;
+      }
       Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
     }
   }
-  try { return fn(); } finally { try { unlinkSync(lock); } catch {} }
+  try { return fn(); }
+  finally {
+    // Remove it only while it is still ours: if it was taken over, it now
+    // belongs to someone else.
+    if (acquired) try { if (readFileSync(lock, "utf8") === mine) unlinkSync(lock); } catch {}
+  }
+}
+
+/** True if the process is still there. EPERM means it is, and not ours to signal. */
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code !== "ESRCH"; }
+}
+
+/**
+ * Removes a lock whose holder is gone, and says whether it did.
+ *
+ * The content is read again just before removing it, so a waiter that decided
+ * on one lock does not remove a newer one another waiter has just taken.
+ */
+function reapable(lock, staleMs) {
+  let seen, mtime;
+  try { seen = readFileSync(lock, "utf8"); mtime = statSync(lock).mtimeMs; } catch { return true; }
+  const pid = Number(seen.split(" ")[0]);
+  const named = Number.isInteger(pid) && pid > 0;
+  // A named holder that is alive is waited on, however long it takes: its age
+  // says nothing about whether it is done. An unnamed one (an older seisin, or
+  // killed between creating the file and writing its name) goes by age.
+  const gone = named ? !alive(pid) : Date.now() - mtime > staleMs;
+  if (!gone) return false;
+  try { if (readFileSync(lock, "utf8") !== seen) return true; unlinkSync(lock); } catch {}
+  return true;
 }
 
 /**
@@ -116,8 +246,8 @@ function withLock(file, fn) {
  * 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: [] };
+function walk(file, { seed = GENESIS, startLine = 0 } = {}) {
+  const out = { lines: 0, unchained: 0, chained: 0, breaks: [], tail: null };
   if (!existsSync(file)) return out;
   let previous = null;
   let started = false;
@@ -129,15 +259,54 @@ export function verifyChain(file) {
     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 });
+    const first = out.chained === 0 && out.unchained === 0;
+    // A rotation marker leading a segment we have nothing to check it against —
+    // a file verified on its own, or the oldest segment left after the prefix
+    // was pruned for retention (seed still GENESIS) — is accepted rather than
+    // called a break. For any later segment the seed is the real previous tail,
+    // so the marker's `prev` IS checked, and a whole segment deleted or
+    // reordered in the middle shows.
+    const rotationStart = first && e?.event === "rotated" && seed === GENESIS;
+    const expected = first ? seed : hashOf(previous);
+    const ok = rotationStart || prev === expected || (first && prev === hashOf(previous));
+    if (!ok) out.breaks.push({ line: startLine + out.lines, expected, found: prev ?? null });
     out.chained++;
     previous = line;
   }
+  out.tail = previous;
   return out;
 }
 
+export function verifyChain(file, seed = GENESIS) {
+  const r = walk(file, { seed });
+  return { lines: r.lines, unchained: r.unchained, chained: r.chained, breaks: r.breaks };
+}
+
+/**
+ * Verify the whole log, across every rotated segment, as one chain.
+ *
+ * Each retired segment is walked in order, and its last hash becomes the seed
+ * the next segment's `rotated` marker must match — so deleting or reordering a
+ * whole segment shows, not only an edit inside one. With no rotation there is a
+ * single segment and this is exactly `verifyChain`. What it cannot see is a
+ * segment dropped off the *oldest* end by the keep limit: that is retention, not
+ * tampering, and the count of segments is reported so the drop is not silent.
+ */
+export function verifyLog(file) {
+  const segs = logSegments(file);
+  const agg = { lines: 0, unchained: 0, chained: 0, breaks: [], segments: segs.length, dropped: countLines(droppedPath(file)) };
+  let seed = GENESIS;
+  for (const seg of segs) {
+    const r = walk(seg, { seed, startLine: agg.lines });
+    agg.lines += r.lines;
+    agg.unchained += r.unchained;
+    agg.chained += r.chained;
+    agg.breaks.push(...r.breaks);
+    seed = hashOf(r.tail);
+  }
+  return agg;
+}
+
 /** Reads entries, newest last. A malformed line is skipped, never fatal. */
 export function read(file, { role, verdict, since, limit = 0 } = {}) {
   if (!existsSync(file)) return [];
@@ -150,6 +319,7 @@ export function read(file, { role, verdict, since, limit = 0 } = {}) {
     } catch {
       continue; // a half-written line from a killed process is not an error
     }
+    if (e.event === "rotated") continue; // a structural marker, not a decision
     if (role && e.role !== role) continue;
     if (verdict && e.verdict !== verdict) continue;
     if (since && e.at < since) continue;
@@ -179,6 +349,14 @@ export function observed(entries) {
   const roles = new Map();
   for (const e of entries) {
     if (!e.role || !e.target) continue;
+    // A line the parent flagged as `disputed` is one whose verdict did not
+    // match the policy the run started with — either the config changed under
+    // it, or the line was not written by the hook at all. Either way it is not
+    // evidence of what the role legitimately reached for, so it must not become
+    // policy: `init --from-observations` builds `writes`/`keys` from here, and a
+    // process inside the box could otherwise send `verdict:"observed"` lines for
+    // paths outside its territory and have them proposed as its own.
+    if (e.disputed) continue;
     const r = roles.get(e.role) ?? { writes: new Set(), keys: new Set() };
     if (e.action === "read" && e.kind === "key") r.keys.add(e.target);
     else if (e.action === "write") r.writes.add(e.target);

package/src/mcp.js

@@ -31,7 +31,7 @@ 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, refuseIfBarred, markStale } from "./requests.js";
+import { pending, requestsPath, grantFor, refuseIfBarred, markStale, shellId } from "./requests.js";
 import { read, logPath } from "./log.js";
 import { causesOf } from "./serve.js";
 import { walls, wasted } from "./walls.js";
@@ -100,13 +100,22 @@ 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" } } },
+      "the end of it — over the whole log, or since an ISO date. The counts are history: " +
+      "what was refused. What is measured against the policy as it stands is where each " +
+      "path is now — `standing`: unowned (a decision nobody has made), owned, protected " +
+      "(closed to every role on purpose, nothing to grant) or outside (a port, a key, or " +
+      "outside the repository) — and, per cause, `stillRefused`, how many of the roles " +
+      "that hit it would hit it today. `seisin_activity` has the raw events; this has " +
+      "them read against the policy. 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 unowned paths is a question about who owns what. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number" },
+        since: { type: "string", description: "ISO date; only refusals at or after it" },
+      },
+    },
   },
   {
     name: "seisin_walls",
@@ -127,8 +136,10 @@ const TOOLS = [
       "does not grant. The approval is a human action in another channel.",
     inputSchema: {
       type: "object",
-      properties: { number: { type: "number", description: "position in seisin_requests" } },
-      required: ["number"],
+      properties: {
+        id: { type: "string", description: "the request's id from seisin_requests — preferred: it does not move when the queue does" },
+        number: { type: "number", description: "position in seisin_requests (legacy; the draft still names the id)" },
+      },
     },
   },
 ];
@@ -166,6 +177,8 @@ const HANDLERS = {
     // not enforced is documentation.
     if (action !== "read" && action !== "write" && action !== "mcp")
       throw new Error(`action must be "read", "write" or "mcp", got ${JSON.stringify(action)}`);
+    if (typeof role !== "string" || !role)
+      throw new Error("role must be a non-empty string");
     if (typeof target !== "string" || !target)
       throw new Error("target must be a non-empty path");
     const cfg = config();
@@ -182,14 +195,14 @@ const HANDLERS = {
     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,
+        number: i + 1, id: r.key, 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.
       note: queue.length
-        ? "Approving is not available through MCP. Tell the operator to run: seisin grant <number>"
+        ? "Approving is not available through MCP. Tell the operator to run: seisin grant '<id>'"
         : "nothing waiting",
     };
   },
@@ -203,13 +216,21 @@ const HANDLERS = {
    * and asks it to re-derive the grouping — without the policy, which is the
    * half that makes the grouping mean anything.
    */
-  seisin_causes({ limit }) {
+  seisin_causes({ limit, since }) {
     const cfg = config();
-    const c = causesOf(cfg, read(logPath(cfg.root), { limit: 4000 }));
+    // The whole log, as the console reads it. This read the last 4000 lines
+    // after the console had stopped doing so, and the two then disagreed about
+    // the same log — 3,999 refusals here against 6,630 there, measured — with
+    // nothing telling the agent its window was half of the person's.
+    const t = since ? Date.parse(since) : NaN;
+    const from = Number.isNaN(t) ? null : new Date(t).toISOString();
+    const c = causesOf(cfg, read(logPath(cfg.root), from ? { since: from } : {}));
     return {
       total: c.total,
       distinct: c.distinct,
+      ...(from && { since: from }),
       unowned: c.unowned,
+      standing: c.standing,
       families: c.families,
       causes: typeof limit === "number" ? c.causes.slice(0, limit) : c.causes,
     };
@@ -237,12 +258,23 @@ const HANDLERS = {
     return { entries: read(logPath(cfg.root), { role, verdict, limit: n }) };
   },
 
-  seisin_draft_grant({ number }) {
-    if (!Number.isInteger(Number(number)) || Number(number) < 1)
-      throw new Error("number must be a positive integer from seisin_requests");
+  seisin_draft_grant({ id, number } = {}) {
     const cfg = config();
-    const req = pending(requestsPath(cfg.root))[Number(number) - 1];
-    if (!req) throw new Error(`no pending request #${number}`);
+    const queue = pending(requestsPath(cfg.root));
+    let req;
+    if (typeof id === "string" && id) {
+      req = queue.find((r) => r.key === id);
+      if (!req) throw new Error(`request ${id} is not pending`);
+    } else {
+      if (!Number.isInteger(Number(number)) || Number(number) < 1)
+        throw new Error("id (preferred) or number from seisin_requests is required");
+      req = queue[Number(number) - 1];
+      if (!req) throw new Error(`no pending request #${number}`);
+    }
+    // The command is written against the id, whatever was asked with: a
+    // number is a position in a queue agents keep writing to, and the person
+    // runs this later, against the queue as it is then.
+    const ref = shellId(req.key);
 
     // The same refusal `seisin grant` and the console apply, asked here first.
     // Without it this drafted, as approvable, a request that `never_writes`
@@ -255,7 +287,7 @@ const HANDLERS = {
         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.`,
+          `\`seisin decline ${ref}\`, or remove the never_writes entry if the subtraction is wrong.`,
       };
     }
     const field = req.action === "read" ? "keys" : "writes";
@@ -263,7 +295,8 @@ const HANDLERS = {
       wouldAdd: { role: req.role, field, value: req.grant },
       preview: `[roles.${req.role}]\n${field} = [ …, "${req.grant}" ]   # asked ${req.times}×`,
       ownedBy: req.owners,
-      applyWith: `seisin grant ${number} --reason "<why>"`,
+      id: req.key,
+      applyWith: `seisin grant ${ref} --reason "<why>"`,
       note: "Not applied. seisin's MCP server writes nothing — a person runs the command above.",
     };
   },
@@ -284,7 +317,10 @@ function handle(message, { write, version }) {
   const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
   const fail = (id, code, msg) => send({ jsonrpc: "2.0", id, error: { code, message: msg } });
 
-  const { id, method, params = {} } = message;
+  const { id, method } = message;
+  // `?? {}` so an explicit null params (not just missing) does not crash the
+  // dispatcher and leave the request unanswered.
+  const params = message.params ?? {};
 
   // A notification has no id and takes no answer. Replying to one is a protocol
   // error that some clients tolerate and others hang on.
@@ -310,8 +346,11 @@ function handle(message, { write, version }) {
     case "tools/list":
       return reply(id, { tools: TOOLS });
     case "tools/call": {
-      const fn = HANDLERS[params.name];
-      if (!fn) return fail(id, -32602, `unknown tool "${params.name}"`);
+      // hasOwn, not a bare lookup: `params.name` of "constructor" or
+      // "hasOwnProperty" would otherwise resolve to a function on Object's
+      // prototype and be invoked as a tool.
+      const fn = Object.hasOwn(HANDLERS, params.name) ? HANDLERS[params.name] : null;
+      if (typeof fn !== "function") return fail(id, -32602, `unknown tool ${JSON.stringify(params.name)}`);
       try {
         const result = fn(params.arguments ?? {});
         // Content, not a bare object: every client renders `content`, and only

package/src/notify.js

@@ -24,7 +24,7 @@
  */
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { keyOf, pending, requestsPath, grantFor } from "./requests.js";
+import { keyOf, pending, requestsPath, grantFor, shellId } from "./requests.js";
 
 export const FORMATS = ["text", "json", "slack"];
 export const ENV_URL = "SEISIN_NOTIFY_URL";
@@ -46,13 +46,13 @@ 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}`;
+    `Approve: seisin grant ${shellId(keyOf(req))} · decline: seisin decline ${shellId(keyOf(req))}`;
   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,
+        text, repo: basename(config.root), number, id: keyOf(req), role: req.role, action: req.action,
         target: req.target, owners: req.owners ?? [], grant: grantFor(req),
       }),
     };