seisin 0.5.0 → 0.6.0

package/src/commands/init.js

@@ -12,10 +12,15 @@
  * not read: `--from-observations` lands as `.observed`, not as the config.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync, statSync, copyFileSync, appendFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve, isAbsolute } 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";
+import { loadConfig } from "../config.js";
+import { applyGrant } from "../requests.js";
+import { setKey } from "../controls.js";
+import { keyName } from "../owners.js";
+import { toRepoRelative } from "../paths.js";
 
 /**
  * Three places a repo already says who does what, in order of how much it
@@ -133,6 +138,9 @@ export function renderConfig(found) {
     "# A Claude Code subagent runs inside its parent's process, so it has its",
     "# parent's role — give it its own by running it as its own `seisin run`.",
     "",
+    "# [runtime]",
+    '# read = "territory"   # opt-in: keep data roots shut; roles declare reads/toolchain/verify',
+    "",
     ...(found.keyDir
       ? ["[keys]", `dir = ${tomlString(found.keyDir)}      # every key lives here; roles name the files they may read`]
       : ["# [keys]", '# dir = ".secrets"      # every key lives here; roles name the files they may read']),
@@ -157,64 +165,63 @@ export function renderConfig(found) {
     lines.push(`[roles.${tomlName(r.name)}]`);
     lines.push(`writes = [${r.writes.map(tomlString).join(", ")}]`);
     lines.push(`keys   = [${r.keys.map(tomlString).join(", ")}]`);
+    lines.push('# reads = ["path/**"]       # data outside the repo this role must read');
+    lines.push('# toolchain = ["~/.venvs/app"] # stack under a home or another data root');
+    lines.push('# verify = ["npm", "test"]  # seisin check --verify runs this inside the role');
     lines.push("");
   }
   return lines.join("\n");
 }
 
-/** The observed config, as TOML. Pure: takes the log entries. */
-export function renderObserved(config, entries) {
+/** A proposal that adds observed permissions to the current policy text. */
+export function renderObserved(config, entries, text = readFileSync(config.path, "utf8")) {
+  // Start from the policy being proposed for promotion. Rebuilding writes and
+  // keys alone discarded isolate, never_writes, providers, per-role network,
+  // MCP and every other setting, including those of roles that did not act.
+  config = loadConfig(config.path, text);
   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];
+  let toml = text;
+  const notes = [];
+  for (const name of Object.keys(config.roles)) {
     const seen = roles.get(name);
-
-    const from = declared ? declared.writesDeclared ?? 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(/^.*\//, "")))] : []),
+    if (!seen) {
+      notes.push(`# ${name}: this role did nothing while observing — kept as written`);
+      continue;
+    }
+    // A host path is not a repo-relative grant. Unknown roles and outside
+    // paths from older logs cannot silently become territory in the proposal.
+    const paths = [...seen.writes].map((p) => toRepoRelative(config, resolve(config.root, p)))
+      .filter((p) => !isAbsolute(p) && p !== ".." && !p.startsWith("../"));
+    const additions = [
+      ...generalise(paths).map((grant) => ({ action: "write", grant })),
+      ...[...seen.keys].map((target) => ({ action: "read", grant: keyName(config, target) })),
     ];
-
-    // 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("");
+    let added = 0;
+    for (const request of additions) {
+      const field = request.action === "read" ? "keys" : "writes";
+      // A valid role can omit either list. Insert only a missing list and
+      // retry the same grant; existing values and comments stay untouched.
+      let result;
+      try {
+        result = applyGrant(toml, { ...request, role: name, times: 1 }, "observation proposal");
+      } catch (e) {
+        if (!e.message.includes(`has no ${field} list`)) throw e;
+        toml = setKey(toml, `roles.${name}`, field, "[]", "", "from observation");
+        result = applyGrant(toml, { ...request, role: name, times: 1 }, "observation proposal");
+      }
+      toml = result.toml;
+      if (result.changed) added++;
+    }
+    notes.push(`# ${name}: observation added ${added}; all other settings kept as written`);
   }
-  return { toml: lines.join("\n"), roles: roles.size };
+  loadConfig(config.path, toml);
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const heading = [
+    `# ${CONFIG_NAME} — proposal from ${entries.length} observed action(s).`,
+    "# Observation adds territory and keys; read the diff before promoting this file.",
+    ...notes, "",
+  ].join(eol);
+  return { toml: heading + eol + toml, roles: [...roles.keys()].filter((name) => config.roles[name]).length };
 }
 
 export function init(cwd = process.cwd(), { force = false } = {}) {

package/src/commands/requests.js

@@ -4,10 +4,12 @@
  * 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, withDeclarers, shellId } 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";
 
@@ -17,7 +19,7 @@ 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
- * `seisin deny 1` (now `decline`) 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 request, and it happened twice in one session.
  *
@@ -56,14 +58,11 @@ function pick(config, n, verb = "grant") {
       : "  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 { queueOf };
 
-export function requests(config) {
-  const queue = markStale(queueOf(config), read(logPath(config.root)));
-  out(renderQueue(queue));
+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;
 }
 
@@ -73,7 +72,7 @@ export function renderQueue(queue) {
 
   const lines = [`\n  ${C.yellow}${queue.length} pending request(s)${C.off}\n\n`];
   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`);
+  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("");
@@ -107,68 +106,44 @@ function entryLines(r, 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`);
+    // 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`);
   }
   return lines;
 }
 
-/**
- * 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 handoff chain — needs a person to split the work`;
-    case "depth":
-      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":
-      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}`;
-  }
-}
-
-/** The limit names are internal; what a person reads should not be a field name. */
-function limitWords(limit, 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 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];
 
   // 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);
+    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) }));
+  }, { 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\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 };
@@ -182,7 +157,7 @@ export function grant(config, argv = []) {
     `\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`
   );
   out(remaining(config));
@@ -200,7 +175,7 @@ function underLock(fn) {
   }
 }
 
-export function deny(config, argv = []) {
+export function decline(config, argv = []) {
   const i = argv.indexOf("--reason");
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
 
@@ -210,7 +185,7 @@ export function deny(config, argv = []) {
   underLock(() => editPolicy(config, (before) => {
     req = pick(config, argv[0], "decline");
     return { toml: before, changed: false };
-  }, { after: () => settle(requestsPath(config.root), req.key, "denied", reason) }));
+  }, { 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`

package/src/commands/review.js

@@ -15,12 +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");
@@ -31,13 +41,16 @@ 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} entries, ${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}Denied repeatedly${C.off}\n`);
@@ -51,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.
    *
@@ -139,7 +166,7 @@ export function reviewCommand(config, argv = []) {
       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)
+  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");