seisin 0.4.2 → 0.5.0

package/src/commands/log.js

@@ -18,15 +18,30 @@ const flag = (argv, name) => {
   return i === -1 ? undefined : argv[i + 1];
 };
 
+const VERDICTS = ["allowed", "denied", "observed"];
+
 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"),
-    limit: Number(flag(argv, "--limit") ?? 40),
-  });
+  const role = flag(argv, "--role");
+  const verdict = flag(argv, "--verdict");
+  const limit = flag(argv, "--limit") ?? "40";
+  // Checked, because a filter that matches nothing reads as an empty log.
+  if (verdict !== undefined && !VERDICTS.includes(verdict))
+    throw new Error(`unknown verdict "${verdict}" — use allowed, denied or observed`);
+  if (!/^[1-9]\d*$/.test(limit)) throw new Error(`--limit takes a positive number, got "${limit}"`);
+  // A role that is not in the policy is still a fair question: the log keeps
+  // the lines of a role that was renamed or removed. The empty answer says so.
+  const entries = read(logPath(config.root), { role, verdict, limit: Number(limit) });
 
   if (entries.length === 0) {
+    // Say which: nothing at all, or nothing for this filter.
+    const any = role || verdict ? read(logPath(config.root), { limit: 1000 }) : [];
+    if (any.length) {
+      const others = [...new Set(any.map((e) => e.role).filter(Boolean))];
+      out(`\n  ${C.dim}no entries for ${[role && `role ${role}`, verdict && `verdict ${verdict}`].filter(Boolean).join(", ")} — ` +
+        `the log has ${any.length === 1000 ? "1000+" : any.length} for ${others.join(", ") || "other filters"}${C.off}\n\n`);
+      return entries;
+    }
     out(`\n  ${C.dim}nothing recorded yet — run an agent through "seisin run"${C.off}\n\n`);
     return entries;
   }
@@ -56,14 +71,38 @@ function verify(config) {
   const dropped = r.dropped
     ? `  ${C.yellow}${r.dropped} entr${r.dropped === 1 ? "y was" : "ies were"} never written${C.off}  another writer held the lock too long; see ${LOG_NAME}.dropped\n`
     : "";
+  // Where the chain starts is only checked once it has been recorded. Until
+  // then a log whose chain was stripped or rewritten whole reads like an
+  // intact one — so with chained lines and no record this is a warning, not a
+  // footnote. A record made after chained lines already stood pins whatever
+  // they said by then, and says so.
+  let genesis = "";
+  if (r.genesis === "unrecorded" && r.chained)
+    genesis = `  ${C.yellow}where the chain starts is not recorded${C.off} — a chain stripped or rewritten from its first line would not show here.\n` +
+      `  ${C.dim}the next entry records it, marked late: tampering before that cannot be excluded${C.off}\n`;
+  else if (r.genesis === "unrecorded" && r.unchained)
+    genesis = `  ${C.dim}where the chain starts is not recorded yet — it will be on the next entry${C.off}\n`;
+  else if (r.genesis === "pruned")
+    genesis = `  ${C.dim}the oldest segments were rotated away; the chain is checked from the oldest one kept${C.off}\n`;
+  else if (r.late)
+    genesis = `  ${C.yellow}start recorded late${C.off}${r.late.at ? ` (${r.late.at})` : ""}, after ${r.late.after ?? "some"} chained line(s) — earlier tampering cannot be excluded\n`;
   if (!r.breaks.length) {
-    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)${segs}\n${dropped}\n`);
+    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)${segs}\n${genesis}${dropped}\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${dropped}\n`);
+  const foreign = r.breaks.find((b) => b.foreign);
+  for (const b of r.breaks.slice(0, 10)) {
+    if (b.foreign) out(`    the genesis record belongs to another log: it pins a different start (${LOG_NAME}.genesis)\n`);
+    else out(`    line ${b.line}: expected prev ${b.expected}, found ${b.found ?? "none"}\n`);
+  }
+  if (foreign)
+    out(`  ${C.dim}if ${LOG_NAME} was archived or replaced by hand, move ${LOG_NAME}.genesis along with the archived log;\n` +
+      `  or remove it, and the next entry records this log's start (marked late). If nobody replaced the log,\n` +
+      `  it was rewritten from its first line.${C.off}\n`);
+  if (r.breaks.some((b) => !b.foreign))
+    out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n`);
+  out(`${genesis}${dropped}\n`);
   process.exitCode = 1;
   return r;
 }

package/src/commands/requests.js

@@ -1,12 +1,13 @@
 /**
- * `seisin requests`, `grant` and `deny` — the human end of the loop.
+ * `seisin requests`, `grant` and `decline` — a person's end of the loop.
  *
  * These live in the CLI and in the console, and deliberately NOT in the MCP
  * server. An agent may ask and may draft; turning a request into policy takes a
  * person acting in a channel the agent does not have. That is the invariant the
  * whole feature rests on — see docs/permission-requests.md.
  */
-import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale, editPolicy } from "../requests.js";
+import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale, editPolicy, withDeclarers, shellId } from "../requests.js";
+import { keyHolders } from "../owners.js";
 import { read, logPath } from "../log.js";
 import { C, out, safe } from "../render.js";
 
@@ -16,9 +17,9 @@ import { C, out, safe } from "../render.js";
  * "Stable while you read it" was the old claim and it is false exactly where it
  * matters. The queue is filled by agents that are still running: on a live
  * repository it grew and shrank between a listing and the next command, and
- * `deny 1` settled a different request than the one printed as #1 seconds
+ * `seisin deny 1` (now `decline`) settled a different request than the one printed as #1 seconds
  * earlier. That is time-of-check-to-time-of-use in the one command whose whole
- * job is deciding a permission, and it happened twice in one session.
+ * job is deciding a request, and it happened twice in one session.
  *
  * A position is still accepted, because reading a list and typing a number is
  * how anyone will use this. An argument that is not a number is matched against
@@ -28,8 +29,10 @@ import { C, out, safe } from "../render.js";
  * An ambiguous match is refused rather than resolved. Choosing for you is the
  * failure being fixed.
  */
-function pick(config, n) {
-  const queue = pending(requestsPath(config.root));
+function pick(config, n, verb = "grant") {
+  if (n === undefined || n === "" || String(n).startsWith("--"))
+    throw new Error(`usage: seisin ${verb} <n|id> [--reason "…"] — the numbers and ids are in: seisin requests`);
+  const queue = queueOf(config);
   if (!queue.length) throw new Error("no pending requests");
 
   const arg = String(n).trim();
@@ -53,8 +56,13 @@ function pick(config, n) {
       : "  Use its number, or the id printed under it by `seisin requests`."));
 }
 
+/** The pending queue, with keys in the policy's own form and their declarers. */
+export function queueOf(config) {
+  return withDeclarers(config, pending(requestsPath(config.root), { keyDirs: config.keyDirs }));
+}
+
 export function requests(config) {
-  const queue = markStale(pending(requestsPath(config.root)), read(logPath(config.root)));
+  const queue = markStale(queueOf(config), read(logPath(config.root)));
   out(renderQueue(queue));
   return queue;
 }
@@ -64,10 +72,34 @@ export function renderQueue(queue) {
   if (queue.length === 0) return `\n  ${C.dim}no pending requests${C.off}\n\n`;
 
   const lines = [`\n  ${C.yellow}${queue.length} pending request(s)${C.off}\n\n`];
-  queue.forEach((r, i) => {
-    const owners = r.owners.length ? ` ${C.dim}(owned by ${r.owners.join(", ")})${C.off}` : ` ${C.dim}(unowned)${C.off}`;
+  queue.forEach((r, i) => lines.push(...entryLines(r, i + 1)));
+  lines.push(`\n    ${C.dim}seisin grant <n|id> [--reason "…"]   ·   seisin decline <n|id> [--reason "…"]${C.off}\n`);
+  // Said, because it bites: grant #1 and the old #2 is #1 now.
+  lines.push(`    ${C.dim}#n is a position and shifts as requests are settled; the id does not.${C.off}\n\n`);
+  return lines.join("");
+}
+
+/**
+ * What one run added to the queue, for the end of `seisin run`. Each entry
+ * carries `n`, its number in the whole queue, so `grant <n>` works from here.
+ */
+export function renderAdded(added, older) {
+  if (!added.length) return "";
+  const lines = ["\n"];
+  for (const r of added) lines.push(...entryLines(r, r.n));
+  lines.push(`\n  ${C.dim}this run: ${added.length} new request(s)` +
+    `${older ? ` · ${older} older pending` : ""} — seisin requests${C.off}\n\n`);
+  return lines.join("");
+}
+
+function entryLines(r, n) {
+  const lines = [];
+  {
+    const owners = r.declared
+      ? ` ${C.dim}(${r.owners.length ? `declared by ${r.owners.join(", ")}` : "declared by no role"})${C.off}`
+      : r.owners.length ? ` ${C.dim}(owned by ${r.owners.join(", ")})${C.off}` : ` ${C.dim}(unowned)${C.off}`;
     const times = r.times > 1 ? ` ${C.dim}· asked ${r.times}×${C.off}` : "";
-    lines.push(`    ${C.b}#${i + 1}${C.off}  ${safe(r.role)} wants ${r.action} on ${C.b}${safe(r.grant)}${C.off}${owners}${times}\n`);
+    lines.push(`    ${C.b}#${n}${C.off}  ${safe(r.role)} wants ${r.action} on ${C.b}${safe(r.grant)}${C.off}${owners}${times}\n`);
     lines.push(`        ${C.dim}first asked over ${safe(r.target)}${C.off}\n`);
       // 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.
@@ -77,9 +109,8 @@ export function renderQueue(queue) {
       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 decline <n> [--reason "…"]${C.off}\n\n`);
-  return lines.join("");
+  }
+  return lines;
 }
 
 /**
@@ -97,9 +128,9 @@ export function handoffNote(h) {
     case "throttled":
       return `handoff held: ${limitWords(h.limit, h.role)} ${h.max}/${h.max} — still to do`;
     case "cycle":
-      return `handoff stopped: ${h.role} is already in this chain — needs a person to split the work`;
+      return `handoff stopped: ${h.role} is already in this handoff chain — needs a person to split the work`;
     case "depth":
-      return `handoff stopped: chain reached ${h.depth} of ${h.max} — needs a person`;
+      return `handoff stopped: handoff chain reached ${h.depth} of ${h.max} — needs a person`;
     case "human":
       return `handoff stopped: ${h.reason === "ambiguous" ? "more than one role owns this" : "no role owns this"}`;
     case "route":
@@ -113,46 +144,92 @@ export function handoffNote(h) {
 
 /** The limit names are internal; what a person reads should not be a field name. */
 function limitWords(limit, role) {
-  if (limit === "senderChains") return "open chains for this role";
+  if (limit === "senderChains") return "open handoff chains for this role";
   if (limit === "receiverConcurrent") return `${role ?? "the owner"} already running`;
   return limit ?? "a limit";
 }
 
 export function grant(config, argv = []) {
-  const req = pick(config, argv[0]);
   const i = argv.indexOf("--reason");
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
 
-  refuseIfBarred(config, req);
-  // Under a lock, and written atomically: a concurrent grant (another terminal
-  // or the console) must not clobber this one. See editPolicy.
-  let changed;
-  try {
-    ({ changed } = editPolicy(config, (before) => applyGrant(before, req, reason)));
-  } catch (e) {
-    if (e.code === "ELOCKED")
-      throw new Error("another grant is in progress — run this again in a moment");
-    throw e;
+  // 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) => {
+    req = pick(config, argv[0], "grant");
+    refuseIfBarred(config, req);
+    return applyGrant(before, req, reason);
+  }, { after: () => settle(requestsPath(config.root), req.key, "granted", reason) }));
+  // Already in the policy: the request is answered all the same, as the
+  // console answers it. Throwing here left it pending forever — the person had
+  // said yes, the role had the path, and the queue kept asking.
+  if (!changed) {
+    out(
+      `\n  ${C.green}already granted${C.off}  ${req.role} → ${C.b}${req.grant}${C.off}\n` +
+      `  ${C.dim}${config.path} already gives it; nothing written, the request is closed.${C.off}\n\n`
+    );
+    out(remaining(config));
+    return { request: req, grant: req.grant, changed: false };
   }
-  if (!changed) throw new Error(`${req.role} already has ${req.grant} — nothing to add`);
 
-  settle(requestsPath(config.root), req.key, "granted", reason);
+  // A key another role declares is shared by this grant, not moved: both roles
+  // read it from now on. That is sometimes the point, and never a thing to find
+  // out later.
+  const others = req.action === "read" ? keyHolders(config, req.target).filter((r) => r !== req.role) : [];
   out(
     `\n  ${C.green}granted${C.off}  ${req.role} → ${C.b}${req.grant}${C.off}\n` +
+    (others.length
+      ? `  ${C.yellow}shared: ${req.grant} is also declared by ${others.join(", ")} — both roles read it now${C.off}\n`
+      : "") +
     `  ${C.dim}written into ${config.path} with its provenance. It applies on the next run.${C.off}\n\n`
   );
-  return { request: req, grant: req.grant };
+  out(remaining(config));
+  return { request: req, grant: req.grant, shared: others };
+}
+
+/** A held lock is another decision in flight, not a failure of this one. */
+function underLock(fn) {
+  try {
+    return fn();
+  } catch (e) {
+    if (e.code === "ELOCKED")
+      throw new Error("another decision is in progress — run this again in a moment");
+    throw e;
+  }
 }
 
 export function deny(config, argv = []) {
-  const req = pick(config, argv[0]);
   const i = argv.indexOf("--reason");
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
 
-  settle(requestsPath(config.root), req.key, "denied", reason);
+  // 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, "denied", reason) }));
   out(
     `\n  ${C.yellow}declined${C.off}  ${req.role} ✕ ${req.grant}\n` +
     `  ${C.dim}${reason || "no reason recorded"}${C.off}\n\n`
   );
+  out(remaining(config));
   return { request: req, reason };
 }
+
+/**
+ * The queue after a decision, numbered as it now is.
+ *
+ * Numbers are positions: settling #1 makes the old #2 the new #1, and the next
+ * `grant 2` — typed from the listing still on screen — lands on what used to
+ * be #3. One line with the new numbering, so the screen is right again.
+ */
+export function remaining(config) {
+  const queue = queueOf(config);
+  if (!queue.length) return `  ${C.dim}no requests left${C.off}\n\n`;
+  const shown = queue.slice(0, 5).map((r, i) => `#${i + 1} ${safe(r.role)} ${r.action} ${safe(r.grant)}`);
+  const more = queue.length > 5 ? ` · +${queue.length - 5} more` : "";
+  return `  ${C.dim}left, renumbered: ${shown.join(" · ")}${more}${C.off}\n\n`;
+}

package/src/commands/review.js

@@ -5,8 +5,8 @@
  * would do; this reads what actually happened and tells you where the config
  * was wrong about it. Both run nothing.
  *
- * Exits 1 when there is friction, so it composes — a role blocked over and over
- * is a thing to fix, and a CI job that says so beats a human noticing in a
+ * Exits 1 on repeated denials, so it composes — a role denied over and over
+ * is a thing to fix, and a CI job that says so beats a person noticing in a
  * month. Unused grants and unowned paths exit 0: they are worth reading, not
  * worth failing a build over.
  *
@@ -16,6 +16,7 @@
  */
 import { review } from "../review.js";
 import { C, out } from "../render.js";
+import { wired } from "./wire.js";
 
 export function reviewCommand(config, argv = []) {
   const i = argv.indexOf("--min");
@@ -36,11 +37,11 @@ export function reviewCommand(config, argv = []) {
   }
 
   const day = (s) => (s ?? "").slice(0, 10);
-  out(`\n  ${C.dim}${r.entries} decisions, ${day(r.window.from)} to ${day(r.window.to)}${C.off}\n`);
+  out(`\n  ${C.dim}${r.entries} entries, ${day(r.window.from)} to ${day(r.window.to)}${C.off}\n`);
 
   if (r.friction.length) {
-    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(`\n  ${C.b}Denied repeatedly${C.off}\n`);
+    out(`  ${C.dim}a role denied 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 cap(r.friction)) {
       const whose = f.owners.length ? ` ${C.dim}— belongs to ${who(f.owners)}${C.off}` : "";
@@ -65,7 +66,7 @@ export function reviewCommand(config, argv = []) {
    * 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(`\n  ${C.b}Denied 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))
@@ -75,7 +76,7 @@ export function reviewCommand(config, argv = []) {
   }
 
   if (r.guarded.length) {
-    out(`\n  ${C.b}Held at the keys${C.off}\n`);
+    out(`\n  ${C.b}Denied at the key directories${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 cap(r.guarded))
@@ -90,32 +91,56 @@ export function reviewCommand(config, argv = []) {
    *
    * Without the hook the log holds denials and nothing else, so every grant
    * looks dead. The old text called itself the only evidence anyone will ever
-   * have for making a permission file smaller, printed over the whole policy.
+   * have for making a policy smaller, printed over the whole policy.
    */
   if (!r.unusedKnowable) {
     out(`\n  ${C.b}Granted, never used${C.off} ${C.dim}— cannot be answered from this log${C.off}\n`);
-    out(`  ${C.dim}nothing here records what was ALLOWED, only what was refused. Every grant${C.off}\n`);
-    out(`  ${C.dim}would look dead, so nothing is listed. Run \`seisin wire\` and come back.${C.off}\n`);
+    out(`  ${C.dim}nothing here records what was ALLOWED, only what was denied. Every grant${C.off}\n`);
+    // Wired already: telling someone to run `seisin wire` again sends them
+    // looking for a fault in a setup that is fine and simply has not run.
+    if (wired(config.root))
+      out(`  ${C.dim}would look dead, so nothing is listed. wired, but no allowed action logged yet —${C.off}\n` +
+          `  ${C.dim}run an agent (claude, codex…) through seisin run and come back.${C.off}\n`);
+    else
+      out(`  ${C.dim}would look dead, so nothing is listed. Run \`seisin wire\` and come back.${C.off}\n`);
   }
 
   if (r.unused.length) {
     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`);
+    out(`  ${C.dim}anyone will ever have for making a policy smaller${C.off}\n\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 cap(r.unowned)) out(`    ${String(u.times).padStart(4)}×  ${u.where}\n`);
-    more(r.unowned);
+    out(`\n  ${C.b}Unowned${C.off}\n`);
+    out(`  ${C.dim}touched by an agent, claimed by no role. Only an ownable path (kind \`territory\`)${C.off}\n`);
+    out(`  ${C.dim}is a hole in the map; the rest is a kind of thing with its own answer, and none${C.off}\n`);
+    out(`  ${C.dim}of them is an owner${C.off}\n\n`);
+    // Territory first: it is the part that is a decision, and on a real log it
+    // was 22 paths under 279 of a test's scratch — past the ten-row cap.
+    const ordered = [...r.unowned.filter((u) => u.kind === "territory"), ...r.unowned.filter((u) => u.kind !== "territory")];
+    const shown = cap(ordered);
+    const width = Math.max(...shown.map((u) => (u.kind ?? "").length));
+    for (const u of shown)
+      out(`    ${String(u.times).padStart(4)}×  ${u.kind ? `${C.dim}${u.kind.padEnd(width)}${C.off}  ` : ""}${u.where}\n`);
+    more(ordered);
+    // The advice once per kind shown, not once per row: a hundred rows of
+    // `.git` do not need the same sentence a hundred times.
+    const hints = new Map(shown.filter((u) => u.hint).map((u) => [u.kind, u.hint]));
+    if (hints.size) out("\n");
+    for (const [kind, hint] of hints) out(`  ${C.dim}${kind}: ${hint}${C.off}\n`);
+    // All of it by kind, so the part past the cap is still said in one line.
+    const tally = new Map();
+    for (const u of r.unowned) if (u.kind) tally.set(u.kind, (tally.get(u.kind) ?? 0) + u.times);
+    if (tally.size > 1)
+      out(`  ${C.dim}by kind: ${[...tally].sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n.toLocaleString("en")}×`).join(" · ")}${C.off}\n`);
   }
 
   if (!r.friction.length && !r.guarded.length && !r.unused.length && !r.unowned.length && r.unusedKnowable)
-    out(`\n  ${C.green}nothing to report${C.off} ${C.dim}— no repeated blocks, no dead grants, no unowned paths${C.off}\n`);
+    out(`\n  ${C.green}nothing to report${C.off} ${C.dim}— no repeated denials, no unused grants, no unowned paths${C.off}\n`);
 
   out("\n");
   return r;