seisin 0.4.2 → 0.6.0

package/src/commands/requests.js

@@ -1,12 +1,15 @@
 /**
- * `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.
+ * whole feature rests on — see docs/requests.md.
  */
-import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale, editPolicy } from "../requests.js";
+import { settle, applyGrant, refuseIfBarred, requestsPath, editPolicy, queueOf, queueData, shellId, asFileGrant, lastAgentOf, fileOnlyNote } from "../requests.js";
+import { describeHandoff } from "../handoff.js";
+import { keyHolders } from "../owners.js";
+import { loadConfig } from "../config.js";
 import { read, logPath } from "../log.js";
 import { C, out, safe } from "../render.js";
 
@@ -16,9 +19,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 decline 1` 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 +31,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,9 +58,11 @@ function pick(config, n) {
       : "  Use its number, or the id printed under it by `seisin requests`."));
 }
 
-export function requests(config) {
-  const queue = markStale(pending(requestsPath(config.root)), read(logPath(config.root)));
-  out(renderQueue(queue));
+export { queueOf };
+
+export function requests(config, argv = []) {
+  const queue = queueOf(config, read(logPath(config.root)));
+  out(argv.includes("--json") ? JSON.stringify(queueData(queue), null, 2) + "\n" : renderQueue(queue));
   return queue;
 }
 
@@ -64,10 +71,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> [--file] [--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.
@@ -75,84 +106,105 @@ export function renderQueue(queue) {
     // 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 decline <n> [--reason "…"]${C.off}\n\n`);
-  return lines.join("");
-}
-
-/**
- * One line saying why no worker is running for a request that is still open.
- *
- * Deliberately not a scheduler view. The failure this closes is narrow and
- * expensive: work that was refused admission, left the queue looking idle, and
- * was never done by anybody. A row that says which limit held it back is the
- * whole fix; deciding who retries and when is a separate question that this
- * does not have to answer first.
- */
-export function handoffNote(h) {
-  if (!h) return "";
-  switch (h.outcome) {
-    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`;
-    case "depth":
-      return `handoff stopped: 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":
-      return `handed to ${h.role}`;
-    case "resolved":
-      return `no handoff needed — the policy moved and ${h.role} owns it now`;
-    default:
-      return `handoff outcome: ${h.outcome}`;
+    // Where it goes, decided now. A route is the expected case and reads as
+    // information; anything that needs a person is said in yellow.
+    const note = describeHandoff(r.handoff, r.attempt, r.chainStopped);
+    if (note) lines.push(`        ${r.handoff?.type === "route" ? C.dim : C.yellow}${safe(note)}${C.off}\n`);
   }
-}
-
-/** 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 === "receiverConcurrent") return `${role ?? "the owner"} already running`;
-  return limit ?? "a limit";
+  return lines;
 }
 
 export function grant(config, argv = []) {
-  const req = pick(config, argv[0]);
   const i = argv.indexOf("--reason");
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
+  // `--file` grants the file the request was asked over, not the folder it is
+  // keyed by. The id stays first, as usage says; the flag may come after it.
+  const only = argv.includes("--file");
+  const which = argv[0] === "--file" ? argv[1] : argv[0];
 
-  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) => {
+    const current = loadConfig(config.path, before);
+    req = pick(current, which, "grant");
+    if (only) req = asFileGrant(req);
+    refuseIfBarred(current, req);
+    return applyGrant(before, req, reason);
+  }, { after: () => settle(requestsPath(config.root), req.key, "granted", reason, { only: req.only }) }));
+  // Said once, beside the grant it is about: a literal file is useless to an
+  // agent that saves through a temporary beside it.
+  const caveat = only ? fileOnlyNote(req.role, lastAgentOf(read(logPath(config.root)), req.role)) : "";
+  const warn = caveat ? `  ${C.yellow}${caveat}${C.off}\n` : "";
+  // 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` + warn + "\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`
+      : "") + warn +
     `  ${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]);
+export function decline(config, argv = []) {
   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, "declined", 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.
  *
@@ -15,11 +15,22 @@
  * would mean a correct policy cannot go green.
  */
 import { review } from "../review.js";
-import { C, out } from "../render.js";
+import { parseSince } from "../views.js";
+import { C, out, safe } from "../render.js";
+import { wired } from "./wire.js";
 
 export function reviewCommand(config, argv = []) {
   const i = argv.indexOf("--min");
-  const r = review(config, { minDenials: i === -1 ? 3 : Number(argv[i + 1]) });
+  /**
+   * `--since 2026-10-01` or `--since 7d`. The MCP ignores a filter it cannot
+   * read; a person typed this one, and a review of the whole log presented as
+   * the last week is the wrong answer said confidently — so it is refused.
+   */
+  const s = argv.indexOf("--since");
+  const since = s === -1 ? null : parseSince(argv[s + 1]);
+  if (s !== -1 && !since)
+    throw new Error(`--since takes a date (2026-10-01) or a duration back from now (7d, 12h, 2w), not "${safe(argv[s + 1] ?? "")}"`);
+  const r = review(config, { minDenials: i === -1 ? 3 : Number(argv[i + 1]), since });
   // 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");
@@ -30,17 +41,20 @@ export function reviewCommand(config, argv = []) {
   };
   const who = (owners) => owners.length > 3 ? `${owners.slice(0, 3).join(", ")} +${owners.length - 3}` : owners.join(", ");
 
+  const day = (s) => (s ?? "").slice(0, 10);
   if (!r.entries) {
-    out(`\n  ${C.dim}nothing recorded yet. Run an agent through seisin first.${C.off}\n\n`);
+    out(since
+      ? `\n  ${C.dim}nothing recorded since ${day(since)}.${C.off}\n\n`
+      : `\n  ${C.dim}nothing recorded yet. Run an agent through seisin first.${C.off}\n\n`);
     return r;
   }
 
-  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)}` +
+      `${since ? ` (since ${day(since)})` : ""}${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}` : "";
@@ -50,6 +64,20 @@ export function reviewCommand(config, argv = []) {
     out(`\n  ${C.dim}seisin grant, or move the territory. Either way it is a decision, not noise.${C.off}\n`);
   }
 
+  /**
+   * Repeated, refused correctly, and nothing to decide: Claude Code updating
+   * its plugins from inside the sandbox (kinds.js expectedOf). Under the
+   * heading above it read as a policy that is wrong, and the only grant that
+   * would quiet it is a write into what runs outside the sandbox.
+   */
+  if (r.expected?.length) {
+    out(`\n  ${C.b}Denied as expected${C.off}\n`);
+    out(`  ${C.dim}${r.expected[0].expected.hint}${C.off}\n\n`);
+    for (const f of cap(r.expected))
+      out(`    ${C.dim}${String(f.times).padStart(4)}×${C.off}  ${C.b}${f.role}${C.off} ${f.action} ${f.where}\n`);
+    more(r.expected);
+  }
+
   /**
    * The same repetition, and the opposite conclusion.
    *
@@ -65,7 +93,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 +103,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 +118,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`);
+  if (!r.friction.length && !r.expected?.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 denials, no unused grants, no unowned paths${C.off}\n`);
 
   out("\n");
   return r;