seisin 0.4.2 → 0.6.0

package/src/help.js

@@ -0,0 +1,179 @@
+/**
+ * `seisin <command> --help` — one command's flags, examples and exit codes.
+ *
+ * The flags listed here are also the flags each command accepts: cli.js
+ * refuses any other, so a typo is an error instead of a question answered as
+ * if it had not been asked. One table, so the help and the check cannot
+ * disagree about what a command takes.
+ *
+ * `values` are flags that take the next word as their value.
+ */
+import { LIMITS } from "./inspect/limits.js";
+
+export const COMMAND_HELP = {
+  run: {
+    usage: ["seisin run <role> [--observe] [--debug-env] [--agent <name>] [--handoff <id>] [--expect-denied <path>]... -- <command...>"],
+    values: ["--agent", "--handoff", "--expect-denied"],
+    flags: [
+      ["--observe", "open the repo for this run and record what the agent writes; keys and network stay shut"],
+      ["--debug-env", "print the environment variables the role does not get"],
+      ["--agent <name>", "claude, codex or none: which agent the command runs, when seisin cannot tell from it (a wrapper script). Its home is the run's scratch; the other agents' sign-in is closed"],
+      ["--handoff <id>", "this run takes a pending request handed to this role, and starts only if the policy routes that request here. Its own requests join the handoff chain"],
+      ["--expect-denied <path>", "a path the caller will probe and expects to be denied (its own canary). That exact path is logged as expected and files no request; repeatable. Any other path is asked as usual"],
+    ],
+    notes: ["Everything after -- is the command's own, flags included: `-- claude --settings x.json` goes to claude."],
+    examples: ['seisin run frontend -- claude', 'seisin run backend --observe -- claude -p "…"'],
+    exits: [["n", "the command's own exit status"], ["127", "the command is not on the role's PATH"],
+      ["86", "the canary proved the generated boundary does not hold; the command was not started"],
+      ["128+n", "killed by signal n (130 for ctrl-c)"], ["2", "seisin could not start it (usage, policy, runtime)"]],
+  },
+  check: {
+    usage: ["seisin check [role] [--verbose] [--verify] [--parallel] [--system-log]"],
+    flags: [["--verbose", "also print the protected paths and each warning's explanation (the limits of every repo: seisin help limits)"],
+      ["--verify", "run each role's verify command inside its sandbox (the one thing check executes)"],
+      ["--parallel", "experimental: with --verify, run role checks concurrently; shared resources may race"],
+      ["--system-log", "macOS: measure for 3 s whether the system log is dropping messages, and who writes the most; exits 1 when it is"]],
+    examples: ["seisin check", "seisin check frontend --verbose", "seisin check backend --verify", "seisin check --verify --parallel"],
+    exits: [["0", "the policy can be enforced as written (warnings included)"], ["1", "a role cannot be enforced as written, or its verify failed"], ["2", "usage or policy error"]],
+  },
+  explain: {
+    usage: ["seisin explain <role> read|write <path>", "seisin explain <role> read <key>", "seisin explain <role> mcp <server>"],
+    flags: [],
+    notes: ["A relative path is relative to the directory you are in."],
+    examples: ["seisin explain frontend write src/app.js", "seisin explain backend read stripe.txt", "seisin explain frontend mcp github"],
+    exits: [["0", "allowed"], ["1", "denied"], ["2", "usage error"]],
+  },
+  whose: {
+    usage: ["seisin whose <path>"],
+    flags: [],
+    notes: ["Safe to call from inside the sandbox. A relative path is relative to the directory you are in."],
+    examples: ["seisin whose backend/src/server.py"],
+    exits: [["0", "answered"], ["2", "usage error"]],
+  },
+  scan: {
+    usage: ["seisin scan [--all]"],
+    flags: [["--all", "walk the whole folder, not only where the territories are"]],
+    examples: ["seisin scan", "seisin scan --all"],
+    exits: [["0", "no certain credential outside the key dirs"], ["1", "at least one certain credential"], ["2", "usage error"]],
+  },
+  review: {
+    usage: ["seisin review [--all] [--min <n>] [--since <date|duration>]"],
+    values: ["--min", "--since"],
+    flags: [["--all", "every row, not the first ten per section"], ["--min <n>", "denials before a place counts as repeated (default 3)"],
+      ["--since <when>", "only what was recorded since a date (2026-10-01) or a duration back from now (7d, 12h, 2w)"]],
+    examples: ["seisin review", "seisin review --since 7d", "seisin review --min 5 --all"],
+    exits: [["0", "no role denied repeatedly"], ["1", "a role was denied repeatedly"], ["2", "usage error"]],
+  },
+  walls: {
+    usage: ["seisin walls <role> [--all] [--since <when>] [--min <n>]"],
+    values: ["--since", "--min"],
+    flags: [["--all", "include walls not hit in the last few runs"], ["--since <when>", "only denials since a date (2026-09-01) or a duration back from now (7d)"],
+      ["--min <n>", "times denied before it is a wall (default 2)"]],
+    examples: ["seisin walls frontend", "seisin walls frontend --since 2026-09-01 --min 3"],
+    exits: [["0", "no walls"], ["1", "walls listed"], ["2", "usage error"]],
+  },
+  wire: {
+    usage: ["seisin wire"],
+    flags: [],
+    notes: ["Writes .claude/settings.json in this repo, merged with what is there."],
+    examples: ["seisin wire"],
+    exits: [["0", "wired, or already wired"], ["2", "usage error, or settings.json is not valid JSON"]],
+  },
+  requests: {
+    usage: ["seisin requests [--json]"],
+    flags: [["--json", "the queue as data, each request with its handoff decision — the shape seisin_requests returns"]],
+    notes: ["#n is a position and shifts as requests are settled; the id under each one does not.",
+      "The line under each request says where it goes, decided from the policy as it stands: handed to its owner, or a person decides."],
+    examples: ["seisin requests", "seisin requests --json"],
+    exits: [["0", "nothing pending"], ["1", "requests pending"], ["2", "usage error"]],
+  },
+  grant: {
+    usage: ['seisin grant <n|id> [--file] [--reason "…"]'],
+    values: ["--reason"],
+    flags: [['--reason "…"', "recorded beside the grant in the policy"],
+            ["--file", "grant the file that was asked for, not its folder (a write). Claude Code cannot edit a lone file: its temporary lands beside it"]],
+    examples: ["seisin grant 1", "seisin grant 2 --file", "seisin grant 'frontend:write:docs' --reason \"owns the docs now\""],
+    exits: [["0", "granted, or already granted"], ["2", "no such request, or it cannot be granted"]],
+  },
+  decline: {
+    usage: ['seisin decline <n|id> [--reason "…"]'],
+    values: ["--reason"],
+    flags: [['--reason "…"', "recorded with the decision"]],
+    examples: ["seisin decline 2 --reason \"not frontend's key\""],
+    exits: [["0", "declined"], ["2", "no such request"]],
+  },
+  log: {
+    usage: ["seisin log [--role <r>] [--verdict allowed|denied|observed] [--limit <n>]", "seisin log verify"],
+    values: ["--role", "--verdict", "--limit"],
+    flags: [["--role <r>", "only this role"], ["--verdict <v>", "allowed, denied or observed"], ["--limit <n>", "how many entries (default 40)"]],
+    examples: ["seisin log --role frontend --verdict denied", "seisin log verify"],
+    exits: [["0", "printed; for verify, the hash chain holds"], ["1", "verify: the hash chain is broken"], ["2", "usage error"]],
+  },
+  watch: {
+    usage: ["seisin watch"],
+    flags: [],
+    examples: ["seisin watch"],
+    exits: [["0", "stopped with ctrl-c"], ["2", "usage error"]],
+  },
+  init: {
+    usage: ["seisin init [--force]", "seisin init --from-observations"],
+    flags: [["--force", "overwrite an existing seisin.toml, keeping the old one as seisin.toml.bak"],
+      ["--from-observations", "write seisin.toml.observed from what observed runs recorded"]],
+    examples: ["seisin init", "seisin init --from-observations"],
+    exits: [["0", "written"], ["2", "a policy is already there, or nothing was observed"]],
+  },
+  ui: {
+    usage: ["seisin ui [--port <n>] [--link]"],
+    values: ["--port"],
+    flags: [["--port <n>", "port on 127.0.0.1 (default 4178)"], ["--link", "print the link of a console already running, start nothing"]],
+    examples: ["seisin ui", "seisin ui --link"],
+    exits: [["0", "stopped"], ["2", "could not start"]],
+  },
+  mcp: {
+    usage: ["seisin mcp"],
+    flags: [],
+    notes: ["An MCP server on stdio, read-only: it can explain and draft, never grant."],
+    examples: ["claude mcp add seisin -- seisin mcp"],
+    exits: [["0", "stdin closed"]],
+  },
+  hook: {
+    usage: ["seisin hook"],
+    flags: [],
+    notes: ["Claude Code's hook: one event on stdin, a decision on stdout. `seisin wire` installs it."],
+    examples: [],
+    exits: [["0", "always — the hook explains, the kernel enforces"]],
+  },
+};
+
+/** `seisin help limits`, as text: LIMITS lives in inspect/limits.js, which `inspect()` also returns. */
+export function renderLimits(C) {
+  const lines = ["", `${C.b}what seisin cannot do, in any repo${C.off}`, ""];
+  for (const l of LIMITS) lines.push(`  ${C.b}${l.headline}${C.off}`, `  ${l.detail}`, "");
+  lines.push(`  ${C.dim}seisin check lists what is wrong with this repo's policy${C.off}`, "", "");
+  return lines.join("\n");
+}
+
+/** The flag words a command accepts, for the unknown-flag check. */
+export function flagsOf(name) {
+  const h = COMMAND_HELP[name];
+  if (!h) return null;
+  const values = h.values ?? [];
+  const known = h.flags.map(([f]) => f.split(" ")[0]).filter((f) => !values.includes(f));
+  return { known, values };
+}
+
+/** The help for one command, as text. */
+export function renderHelp(name, C) {
+  const h = COMMAND_HELP[name];
+  const lines = ["", "usage:", ...h.usage.map((u) => `  ${u}`)];
+  if (h.flags.length) {
+    const w = Math.max(...h.flags.map(([f]) => f.length));
+    lines.push("", "flags:", ...h.flags.map(([f, d]) => `  ${f.padEnd(w)}  ${d}`));
+  }
+  if (h.notes?.length) lines.push("", ...h.notes.map((n) => `  ${n}`));
+  if (h.examples.length) lines.push("", "examples:", ...h.examples.map((e) => `  ${e}`));
+  const w = Math.max(...h.exits.map(([c]) => c.length));
+  lines.push("", "exit codes:", ...h.exits.map(([c, d]) => `  ${c.padEnd(w)}  ${d}`));
+  lines.push("", `  ${C.dim}seisin --help for every command${C.off}`, "", "");
+  return lines.join("\n");
+}

package/src/hook.js

@@ -17,10 +17,11 @@
  * What escapes this file goes unexplained, not unblocked.
  */
 import { toRepoRelative } from "./paths.js";
-import { explain, normalize } from "./owners.js";
+import { explain, normalize, privateOwner } from "./owners.js";
 import { append, logPath } from "./log.js";
-import { timesHit } from "./walls.js";
-import { record, requestsPath } from "./requests.js";
+import { hitsOf, againWords } from "./walls.js";
+import { record, requestsPath, keyOf } from "./requests.js";
+import { decideHandoff, toAgent, queuedLine, isStopped, ELSEWHERE } from "./handoff.js";
 
 /** Tools whose input names a file directly. */
 const FILE_TOOLS = {
@@ -28,6 +29,30 @@ const FILE_TOOLS = {
   Read: "read", NotebookRead: "read",
 };
 
+/**
+ * The tools {@link targetsOf} has anything to say about, as a hook matcher.
+ *
+ * `seisin wire` used to install PreToolUse with `"*"`, so Claude Code started
+ * this hook for Grep, Glob and TodoWrite too — a whole Node start-up, measured
+ * at 218 ms, to return nothing. Built from the same table targetsOf reads, so
+ * a tool added there is matched here. Anchored, because Claude Code reads a
+ * matcher as a regular expression and an unanchored `Write` matches
+ * `TodoWrite`.
+ */
+export const TOOL_MATCHER = `^(${[...Object.keys(FILE_TOOLS), "Bash", "apply_patch"].join("|")}|mcp__.*)$`;
+
+/**
+ * The files a Codex `apply_patch` call touches, from the patch's own headers.
+ *
+ * Codex sends its hooks the same event Claude Code does — `tool_name: "Bash"`
+ * with `tool_input.command` for the shell — but its file edits arrive as
+ * `apply_patch`, with the whole patch in `tool_input.command` (measured
+ * 2026-09-30, codex 0.150.1). The headers are a fixed grammar, so unlike a
+ * shell line they can be read exactly: Add, Update and Delete name the file,
+ * and `Move to` names where an update lands.
+ */
+const PATCH_HEADER = /^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+?)\s*$/gm;
+
 /**
  * Paths a shell command is going to write.
  *
@@ -44,7 +69,7 @@ const WRITERS = /(?:^|\s|;|&&|\|\|)(?:cp|mv|install|tee|touch|mkdir|rm|rmdir|tru
  * The split is on the double underscore: a server name carries single ones
  * (`claude_ai_Gmail`) and so does a tool name (`execute_sql`), so the server is
  * everything between `mcp__` and the next `__`. Shared with the parent's intake,
- * which recomputes the same verdict rather than trusting the line from the box.
+ * which recomputes the same verdict rather than trusting the line from the sandbox.
  */
 export function mcpServer(tool) {
   const m = typeof tool === "string" && /^mcp__(.+?)__(.+)$/.exec(tool);
@@ -52,15 +77,19 @@ export function mcpServer(tool) {
 }
 
 export function targetsOf(tool, input = {}) {
+  // The event is whatever the agent's harness sent. `tool_input: null` or a
+  // path that is a number used to throw below, and a throwing hook exits 2 —
+  // which Claude Code reads as "block". Malformed means "nothing to say".
+  if (!input || typeof input !== "object") input = {};
   const kind = FILE_TOOLS[tool];
   if (kind) {
-    const p = input.file_path ?? input.path ?? input.notebook_path;
-    return p ? [{ action: kind, path: p }] : [];
+    const p = [input.file_path, input.path, input.notebook_path].find((x) => x != null);
+    return typeof p === "string" && p ? [{ action: kind, path: p }] : [];
   }
   /**
    * An MCP tool call names a resource, not a path: `mcp__<server>__<tool>`.
    *
-   * The kernel never sees it — the MCP server runs outside the box — so a call
+   * The kernel never sees it — the MCP server runs outside the sandbox — so a call
    * that goes unrecorded here goes unrecorded everywhere. Measured 2026-09-24:
    * the event reaches PreToolUse with the tool's own arguments as `tool_input`,
    * which is exactly why the file-tool code above returns nothing for it. We
@@ -73,6 +102,11 @@ export function targetsOf(tool, input = {}) {
   if (typeof tool === "string" && tool.startsWith("mcp__")) {
     return [{ action: "use", tool, server: mcpServer(tool) }];
   }
+  if (tool === "apply_patch") {
+    const body = typeof input.command === "string" ? input.command : typeof input.patch === "string" ? input.patch : "";
+    const paths = [...new Set([...body.matchAll(PATCH_HEADER)].map((m) => m[1]))];
+    return paths.map((path) => ({ action: "write", path }));
+  }
   if (tool !== "Bash" || typeof input.command !== "string") return [];
 
   const out = [];
@@ -132,28 +166,24 @@ function kindOf(config, path) {
 }
 
 /**
- * The half of the refusal that nothing inside the box could otherwise know.
+ * The half of the refusal that nothing inside the sandbox could otherwise know.
  *
  * `ask()` has already filed a request by the time this sentence is built — and
  * until now it did so silently, so an agent could not tell the person who sent
  * it that anything was pending. It closes two loops the bare refusal leaves
  * open: retrying, because the queue deduplicates and a second attempt only
  * raises a counter; and waiting, because nothing inside the sandbox can
- * approve.
+ * grant.
  *
  * It deliberately says nothing about the MCP server. The hook cannot know
  * whether one is configured — `wire` writes `.claude/settings.json` and MCP
  * servers live elsewhere — and naming a tool the agent may not hold costs it a
  * turn to find out. An agent that does hold the tools discovers them the normal
  * way; that is what their descriptions are for.
+ *
+ * The words are handoff.js's queuedLine: a route ends on the role it goes to,
+ * everything else on a person.
  */
-const QUEUED = "Already queued for a person to answer — retrying or waiting will not move it.";
-
-/** 4 -> "fourth". Past a handful the numeral reads better than the word. */
-function ordinal(n) {
-  const words = ["", "first", "second", "third", "fourth", "fifth", "sixth", "seventh", "eighth", "ninth", "tenth"];
-  return words[n] ?? `${n}th`;
-}
 
 /**
  * Decides and records one tool call.
@@ -162,11 +192,20 @@ function ordinal(n) {
  * the same decisions and returns none of them, so a policy can be written from
  * what a real run did instead of from what someone imagined it would do.
  */
-export function decide(config, role, event, { observe = false, now = append, ask = record } = {}) {
+export function decide(config, role, event, { observe = false, now = append, ask = record, chain = null, run = process.env.SEISIN_RUN_ID ?? null } = {}) {
   const targets = targetsOf(event.tool_name, event.tool_input);
   const file = logPath(config.root);
   const queue = requestsPath(config.root);
   const verdicts = [];
+  // How many times the first refusal here was given BEFORE this attempt. Read
+  // before the entry is written, because where the entry goes decides whether
+  // a read afterwards sees it: to the file outside `seisin run`, but to the
+  // parent's socket inside it — and that line is not on disk until the parent
+  // gets to it, so counting afterwards came out one behind there.
+  let before = null;
+  const priorOnce = (action, target) => {
+    if (before === null) before = hitsOf(file, role, action, target, run);
+  };
 
   for (const t of targets) {
     // A tool call, resolved to its MCP server. "Whose is it" is the question
@@ -179,6 +218,7 @@ export function decide(config, role, event, { observe = false, now = append, ask
       const v = t.server
         ? explain(config, role, "mcp", t.server)
         : { allowed: false, owners: [], mcp: true, reason: `${t.tool} is not a recognisable mcp__<server>__<tool> name` };
+      if (!observe && !v.allowed) priorOnce("use", t.tool);
       now(file, {
         role, tool: event.tool_name, action: "use", kind: "tool", target: t.tool,
         verdict: observe ? "observed" : v.allowed ? "allowed" : "denied",
@@ -199,9 +239,13 @@ export function decide(config, role, event, { observe = false, now = append, ask
     // of a markdown file, the agent burned its turns unable to look at what it
     // had been asked to edit, and the log showed a tidy `denied` that looked
     // like the system working.
-    if (t.action === "read" && kind !== "key") continue;
+    // The one exception: another role's private folder, which the kernel shuts
+    // to reading as well, so the hook says so before the read is tried.
+    const shutRead = t.action === "read" && kind !== "key" && privateOwner(config, rel);
+    if (t.action === "read" && kind !== "key" && (!shutRead || shutRead.role === role)) continue;
 
-    const v = explain(config, role, kind === "key" ? "read" : "write", rel);
+    const v = explain(config, role, kind === "key" || shutRead ? "read" : "write", rel);
+    if (!observe && !v.allowed) priorOnce(kind === "key" ? "read" : t.action, rel);
 
     now(file, {
       role,
@@ -215,13 +259,16 @@ export function decide(config, role, event, { observe = false, now = append, ask
     });
     // A denial already carries everything a request needs, so leave one behind:
     // the refusal stops being a dead end and becomes something a person can act
-    // on in one command. Observing records nothing to approve — there was no
-    // denial to answer. See docs/permission-requests.md.
+    // on in one command. Observing records nothing to grant — there was no
+    // denial to answer. See docs/requests.md.
     //
     // Except a `never_writes` refusal. That one is the policy saying no on
     // purpose; a request for it asks a person to undo a subtraction somebody
     // wrote, and approving it is how the subtraction disappears unnoticed.
-    if (!observe && !v.allowed && !v.neverWrites && !v.gitMetadata)
+    // Nor a protected file: no grant opens one (the kernel keeps refusing it),
+    // which is why `seisin run` never queued those either (intake.js).
+    // Nor another role's private folder: no grant opens it either.
+    if (!observe && !v.allowed && !v.neverWrites && !v.gitMetadata && !v.protected && !v.privateTo)
       ask(queue, { role, action: kind === "key" ? "read" : t.action, target: rel, owners: v.owners ?? [] });
 
     // The action as it was RECORDED, not as the tool named it: a read of a key
@@ -236,26 +283,39 @@ export function decide(config, role, event, { observe = false, now = append, ask
 
   const denied = verdicts.find((v) => !v.allowed);
   if (!denied) return { decision: null, logged: verdicts.length };
-  const wasRead = denied.kind === "key";
 
   /**
    * How many times this exact denial has already been handed to this role.
    *
    * The sentence below is correct every time and that has not been enough:
-   * measured on a real team, 25% of all denials were a repeat of something the
-   * same role had already been refused, one of them nineteen times. Correct
+   * measured on a multi-repo workspace, 25% of all denials were a repeat of something the
+   * same role had already been denied, one of them nineteen times. Correct
    * and *heard* are different properties, and only the first was being
-   * measured. So the refusal carries its own history: the second time, it says
+   * measured. So the denial carries its own history: the second time, it says
    * it is the second time.
    *
-   * Counted from the log that was just written, so the count includes this
-   * attempt. Silent on the first — a counter that says "1×" on every first
-   * refusal is noise on the turn where the sentence is already doing its job.
+   * The earlier refusals, read before this one was recorded, plus this one —
+   * the same number whether the entry went to the file or to the socket. Silent
+   * on the first — a counter that says "1×" on every first refusal is noise on
+   * the turn where the sentence is already doing its job.
+   */
+  const times = (before?.total ?? 0) + 1;
+  const inRun = before?.inRun == null ? null : before.inRun + 1;
+
+  /**
+   * Whose it is and where the work goes, as the queue will say it: decided by
+   * handoff.js for the one path this sentence is about, in the run's handoff
+   * chain when it has one. Only for a denial that files a request — the
+   * branches above say why nothing was queued, which is not a handoff.
    */
-  const before = timesHit(logPath(config.root), role, denied.action, denied.target);
-  const again = before > 1
-    ? ` You have been denied this ${before} times now; it is not going to work on the ${ordinal(before + 1)} try.`
-    : "";
+  const queued = !denied.neverWrites && !denied.gitMetadata && !denied.protected && !denied.privateTo && !denied.mcp;
+  const handoff = queued
+    ? decideHandoff({ request: { role, action: denied.action, target: denied.target }, config, chain })
+    : null;
+  // A denied write that nothing will ever grant is still a change not to
+  // make under another path; a denied read is not a change at all.
+  const elsewhere = denied.action === "write" ? ` ${ELSEWHERE}` : "";
+  const again = againWords({ times, inRun });
 
   // The hook advises; it does not enforce. Returning `deny` here stops the call
   // early and — the part that matters — hands the agent a sentence it can act
@@ -270,16 +330,15 @@ export function decide(config, role, event, { observe = false, now = append, ask
         // The sentence has to name a next step, not just a refusal. An agent
         // told "no" retries; an agent told whose it is asks, or moves on.
         denied.neverWrites
-          ? `${denied.reason}. Do not ask for it: nothing was queued, because the answer is already written down.` + again
-          : denied.gitMetadata
-          ? `${denied.reason}. Nothing was queued.` + again
+          ? `${denied.reason}. Do not ask for it: nothing was queued, because the answer is already written down.` + elsewhere + again
+          : denied.gitMetadata || denied.protected || denied.privateTo
+          ? `${denied.reason}. Nothing was queued.` + elsewhere + again
           : denied.mcp
-          ? `${denied.reason}. Nothing was queued: which MCP servers a role may load is set in its mcp list, a policy change a person makes, not a grant they approve.` + again
-          : (denied.owners?.length
-          ? wasRead
-            ? `${denied.target} is declared for ${denied.owners.join(", ")}, not ${role}. Ask for what you need from it rather than reading the key.`
-            : `${denied.target} belongs to ${denied.owners.join(", ")}. It is not ${role}'s to change — hand it over rather than working around it.`
-          : `${denied.reason} (seisin)`) + again + " " + QUEUED,
+          ? `${denied.reason}. Nothing was queued: which MCP servers a role may load is set in its mcp list, a policy change a person makes, not something they grant from the queue.` + again
+          : toAgent(handoff, { target: denied.target, role, key: keyOf({ role, action: denied.action, target: denied.target }), again }) +
+            // Where a chain stops, the sentence to pass on already says the
+            // request is waiting, and is the last thing the agent reads.
+            (isStopped(handoff) ? "" : " " + queuedLine(handoff)),
     },
   };
 }

package/src/index.d.ts

@@ -0,0 +1,217 @@
+export type KeyMode = "env" | "run-file" | "inject";
+export type ReadMode = "all" | "territory";
+export type Isolation = false | "credentials" | "home";
+export type Action = "read" | "write" | "mcp";
+
+export interface KeyEntry {
+  kind: "file" | "ref";
+  raw: string;
+  scheme?: string;
+  ref?: string;
+  name?: string;
+}
+
+export interface RolePolicy {
+  name: string;
+  writes: string[];
+  writesDeclared: string[];
+  keys: string[];
+  keyEntries: KeyEntry[];
+  keyMode: KeyMode | null;
+  env: string[];
+  network: string[] | null;
+  neverWrites: string[];
+  neverWritesDeclared: string[];
+  /** Folders only this role reads and writes; also part of `writes`. */
+  private: string[];
+  reads: string[];
+  toolchain: string[];
+  verify: string[] | null;
+  localBinding: boolean;
+  localPorts: number[];
+  mcp: string[] | null;
+  trustd: boolean;
+  controlFiles: string[];
+  /** False for `handoff = false`: the role owns its territory but is never handed work. */
+  handoff: boolean;
+  [key: string]: unknown;
+}
+
+export interface KeyProvider {
+  name: string;
+  command: string[];
+  mode: KeyMode | null;
+}
+
+export interface SeisinConfig {
+  root: string;
+  path: string;
+  keyDirs: string[];
+  keyProviders: Record<string, KeyProvider>;
+  allowedDomains: string[];
+  runtimeWrites?: string[];
+  isolate: Isolation;
+  read: ReadMode;
+  redact: boolean | undefined;
+  scanIgnore: string[];
+  protect: Record<string, unknown>;
+  roles: Record<string, RolePolicy>;
+  [key: string]: unknown;
+}
+
+export interface Decision {
+  allowed: boolean;
+  owners: string[];
+  reason: string;
+  [key: string]: unknown;
+}
+
+export interface SandboxSettings {
+  network: {
+    allowedDomains?: string[];
+    deniedDomains: string[];
+    allowUnixSockets: string[];
+    allowLocalBinding: boolean;
+  };
+  filesystem: {
+    denyRead: string[];
+    allowRead: string[];
+    allowWrite: string[];
+    denyWrite: string[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface Wall {
+  action: string;
+  target: string;
+  times: number;
+  reason: string;
+  owners: string[];
+  firstAt: string;
+  lastAt: string;
+  /** Refused as expected — the agent program's own housekeeping, not friction. */
+  expected?: { kind: "plugins"; hint: string };
+}
+
+export interface ScanHit {
+  file: string;
+  line?: number;
+  shape: string;
+  level: "certain" | "review" | "named";
+}
+
+export interface ScanResult {
+  hits: ScanHit[];
+  skipped: Record<string, number>;
+  nestedPaths: string[];
+  truncated: boolean;
+  omitted: number;
+}
+
+export const CONFIG_NAME: "seisin.toml";
+export const STATE_DIR: ".seisin";
+export const LOG_NAME: "log.jsonl";
+
+export function findConfig(from?: string): string | null;
+export function loadConfig(path: string, text?: string): SeisinConfig;
+export function parseToml(text: string): Record<string, unknown>;
+
+export function covers(pattern: string, path: string): boolean;
+export function ownersOf(config: SeisinConfig, path: string): string[];
+export function keyHolders(config: SeisinConfig, key: string): string[];
+export function explain(config: SeisinConfig, role: string, action: Action, target: string, cwd?: string): Decision;
+export function explainFileRead(config: SeisinConfig, role: string, path: string, credentialHomes?: string[]): Decision;
+export function readTarget(config: SeisinConfig, target: string, cwd?: string): { key: boolean; target: string };
+
+export function settingsFor(config: SeisinConfig, role: string, spool?: string | null, observe?: boolean,
+  options?: { agent?: string; program?: string }): SandboxSettings;
+
+export function parseKey(entry: string): KeyEntry;
+export function defaultName(ref: string): string;
+export function entriesOf(role: Pick<RolePolicy, "keys" | "keyEntries">): KeyEntry[];
+export const MODES: readonly KeyMode[];
+
+export function walls(config: SeisinConfig, role: string, options: {
+  file: string; entries?: Record<string, unknown>[] | null; min?: number; since?: string | null;
+  limit?: number; fresh?: boolean; ask?: typeof explain;
+}): Wall[];
+export function wasted(walls: Wall[]): number;
+
+export function inspect(config: SeisinConfig, role?: string | null, where?: string): Record<string, unknown>;
+export function sharedPaths(config: SeisinConfig, roles?: RolePolicy[]): string[];
+export function scan(root: string, protectedDirs?: string[], ignore?: string[], limit?: number,
+  options?: { roots?: string[] | null }): ScanResult;
+
+export interface LogEntry {
+  role?: string;
+  action?: string;
+  target?: string;
+  verdict?: string;
+  at?: string;
+  [key: string]: unknown;
+}
+export function readLog(file: string, options?: {
+  role?: string; verdict?: string; since?: string; limit?: number;
+}): LogEntry[];
+export function logPath(root: string): string;
+export function observed(entries: LogEntry[]): Map<string, { writes: Set<string>; keys: Set<string> }>;
+export function generalise(paths: string[]): string[];
+
+export function pendingRequests(file: string, options?: { includeSettled?: boolean; keyDirs?: string[] | null; readOnly?: boolean }): unknown[];
+export function requestsPath(root: string): string;
+export function grantFor(request: { action: string; target: string }, keyDir?: string | null): string;
+
+/** Where a denied write goes, decided from the policy as it stands. Nothing executes it. */
+export type HandoffType = "route" | "human" | "resolved" | "cycle" | "depth" | "throttled";
+export interface HandoffDecision {
+  type: HandoffType;
+  /** The owners as the policy says now — for a key, the roles that declare it. */
+  owners: string[];
+  /** The role a route goes to; for cycle/depth/throttled, the one it would have gone to. */
+  role?: string;
+  /** For `human`: why a person decides. */
+  reason?: "unowned" | "ambiguous" | "no-receiver" | "key" | "read";
+  /** The owners that take handed work, when a `handoff = false` role left some out. */
+  receivers?: string[];
+  /** For `resolved`. */
+  resolution?: "policy_changed";
+  /** For a route: the receiver's depth in the handoff chain, and every role the chain has visited. */
+  depth?: number;
+  visited?: string[];
+  max?: number;
+  limit?: "senderChains" | "receiverConcurrent";
+  /** The handoff chain this decision extends: the id of the request that started it. */
+  chainId: string | null;
+  /** Hash of the policy file the decision was made against. */
+  revision: string | null;
+}
+export interface HandoffChain { id: string | null; depth: number; visited: string[] }
+export interface QueuedRequest {
+  key: string; role: string; action: "read" | "write"; target: string; grant: string;
+  owners: string[]; ownersThen?: string[]; declared?: boolean;
+  times: number; first: string; last: string; state: string;
+  handoff: HandoffDecision;
+  /** Present when the request was asked by a run started with `--handoff`. */
+  chain?: HandoffChain;
+  /** What whatever starts roles last recorded about it (recordHandoff). */
+  attempt?: { outcome: string; role?: string; limit?: string; max?: number; reason?: string; depth?: number; chainId?: string; at: string };
+  stale?: { runs: number; since: string };
+}
+export const MAX_DEPTH: number;
+export function decideHandoff(input: {
+  request: { role: string; target: string; action?: string; key?: string };
+  config: SeisinConfig | { roles: Record<string, unknown> };
+  chain?: Partial<HandoffChain> | null;
+  limits?: { depth?: number; senderChains?: number; receiverConcurrent?: number };
+  load?: { senderOpenChains?: number; receiverRunning?: number };
+  revision?: string | null;
+}): HandoffDecision;
+export function requestQueue(config: SeisinConfig, history?: LogEntry[] | null): QueuedRequest[];
+export function recordHandoff(file: string, key: string, decision: Partial<HandoffDecision> & { type: string }): boolean;
+
+export function targetsOf(tool: string, input?: Record<string, unknown>): unknown[];
+export function decide(config: SeisinConfig, role: string, event: Record<string, unknown>, options?: {
+  observe?: boolean; now?: (...args: unknown[]) => unknown; ask?: (...args: unknown[]) => unknown;
+}): Record<string, unknown>;