seisin 0.5.0 → 0.6.0

package/src/help.js

@@ -8,23 +8,33 @@
  *
  * `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] -- <command...>"],
+    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]"],
-    flags: [["--verbose", "also print the protected paths, each warning's explanation and the standing limits"]],
-    examples: ["seisin check", "seisin check frontend --verbose"],
-    exits: [["0", "the policy can be enforced as written (warnings included)"], ["1", "a role cannot be enforced as written"], ["2", "usage or policy error"]],
+    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>"],
@@ -47,16 +57,17 @@ export const COMMAND_HELP = {
     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>]"],
-    values: ["--min"],
-    flags: [["--all", "every row, not the first ten per section"], ["--min <n>", "denials before a place counts as repeated (default 3)"]],
-    examples: ["seisin review", "seisin review --min 5 --all"],
+    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 <iso>] [--min <n>]"],
+    usage: ["seisin walls <role> [--all] [--since <when>] [--min <n>]"],
     values: ["--since", "--min"],
-    flags: [["--all", "include walls not hit in the last few runs"], ["--since <iso>", "only denials after this time"],
+    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"]],
@@ -69,17 +80,19 @@ export const COMMAND_HELP = {
     exits: [["0", "wired, or already wired"], ["2", "usage error, or settings.json is not valid JSON"]],
   },
   requests: {
-    usage: ["seisin requests"],
-    flags: [],
-    notes: ["#n is a position and shifts as requests are settled; the id under each one does not."],
-    examples: ["seisin 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> [--reason "…"]'],
+    usage: ['seisin grant <n|id> [--file] [--reason "…"]'],
     values: ["--reason"],
-    flags: [['--reason "…"', "recorded beside the grant in the policy"]],
-    examples: ["seisin grant 1", "seisin grant 'frontend:write:docs' --reason \"owns the docs now\""],
+    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: {
@@ -131,7 +144,14 @@ export const COMMAND_HELP = {
     exits: [["0", "always — the hook explains, the kernel enforces"]],
   },
 };
-COMMAND_HELP.deny = COMMAND_HELP.decline;
+
+/** `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) {

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 = {
@@ -38,7 +39,19 @@ const FILE_TOOLS = {
  * matcher as a regular expression and an unanchored `Write` matches
  * `TodoWrite`.
  */
-export const TOOL_MATCHER = `^(${[...Object.keys(FILE_TOOLS), "Bash"].join("|")}|mcp__.*)$`;
+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.
@@ -89,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 = [];
@@ -162,14 +180,10 @@ function kindOf(config, path) {
  * 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.
@@ -178,7 +192,7 @@ 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);
@@ -190,7 +204,7 @@ export function decide(config, role, event, { observe = false, now = append, ask
   // gets to it, so counting afterwards came out one behind there.
   let before = null;
   const priorOnce = (action, target) => {
-    if (before === null) before = timesHit(file, role, action, target);
+    if (before === null) before = hitsOf(file, role, action, target, run);
   };
 
   for (const t of targets) {
@@ -225,9 +239,12 @@ 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, {
@@ -243,14 +260,15 @@ 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 grant — there was no
-    // denial to answer. See docs/permission-requests.md.
+    // 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.
     // Nor a protected file: no grant opens one (the kernel keeps refusing it),
     // which is why `seisin run` never queued those either (intake.js).
-    if (!observe && !v.allowed && !v.neverWrites && !v.gitMetadata && !v.protected)
+    // 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
@@ -265,7 +283,6 @@ 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.
@@ -282,10 +299,23 @@ export function decide(config, role, event, { observe = false, now = append, ask
    * 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 ?? 0) + 1;
-  const again = times > 1
-    ? ` You have been denied this ${times} times now; it is not going to work on the ${ordinal(times + 1)} try.`
-    : "";
+  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 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
@@ -300,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.protected
-          ? `${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 something they grant from the queue.` + 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,
+          : 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>;

package/src/index.js

@@ -19,11 +19,10 @@ export { findConfig, loadConfig, parseToml } from "./config.js";
 export { CONFIG_NAME, STATE_DIR, LOG_NAME } from "./layout.js";
 
 /** Who owns a path, and the sentence to hand a denied agent. */
-export { covers, ownersOf, keyHolders, explain } from "./owners.js";
+export { covers, ownersOf, keyHolders, explain, explainFileRead, readTarget } from "./owners.js";
 
-/** A policy, resolved into sandbox settings and a child environment. */
-export { settingsFor, RUNTIME_WRITES, expand } from "./srt.js";
-export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
+/** A policy, resolved into sandbox settings. */
+export { settingsFor } from "./srt.js";
 
 /**
  * Keys that are references, and how a resolved value reaches a role.
@@ -32,16 +31,16 @@ export { buildEnv, BASE as BASE_ENV, DEFAULTS as DEFAULT_ENV } from "./env.js";
  * knowing whether an entry is a path or a reference; `resolveRef` is not,
  * because resolving is something seisin does and not something you ask it.
  */
-export { parseKey, defaultName, entriesOf, MODES, RESERVED_ENV } from "./keys.js";
+export { parseKey, defaultName, entriesOf, MODES } from "./keys.js";
 
 /** What a role keeps being denied, recomputed against the policy as it stands. */
-export { walls, wasted, MIN_HITS } from "./walls.js";
+export { walls, wasted } from "./walls.js";
 
 /** The report `check` prints, without the printing. */
 export { inspect, sharedPaths } from "./inspect.js";
 
 /** Credential-shaped content outside the declared key directories. */
-export { scan, SHAPES, DEFAULT_IGNORE } from "./scan.js";
+export { scan } from "./scan.js";
 
 /** The append-only record, and what can be learned from it. */
 export { read as readLog, logPath, observed, generalise } from "./log.js";
@@ -53,12 +52,21 @@ export { read as readLog, logPath, observed, generalise } from "./log.js";
  * proposal are things a caller — including an MCP server — legitimately does.
  * `settle` and `applyGrant` are NOT exported: granting is not a tool call, and
  * the surface should make that hard to get wrong rather than merely document
- * it. See docs/permission-requests.md.
+ * it. See docs/requests.md.
  */
-export { pending as pendingRequests, requestsPath, grantFor } from "./requests.js";
+export { pending as pendingRequests, requestsPath, grantFor, queueOf as requestQueue, recordHandoff } from "./requests.js";
+
+/**
+ * Where a denied write goes — decided, never executed.
+ *
+ * `requestQueue(config)` is the pending queue with each request's `handoff`
+ * decision against the policy as it stands. Something that starts roles reads
+ * it, starts `seisin run <handoff.role> --handoff <id>`, and may record with
+ * `recordHandoff` that it held one back; `decideHandoff` is there for the
+ * limits only that caller knows (how many chains a role has open, how many of
+ * the receiver are running). None of them grants anything.
+ */
+export { decideHandoff, MAX_DEPTH } from "./handoff.js";
 
 /** One PreToolUse decision. */
 export { decide, targetsOf } from "./hook.js";
-
-/** Masking a role's own secrets on the way out. */
-export { secretsOf, redactor } from "./redact.js";

package/src/inspect/codex.js

@@ -0,0 +1,64 @@
+import { join, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+
+/**
+ * How Codex is signed in on this machine: "chatgpt", "apikey", or null.
+ *
+ * Read from `auth.json` in `CODEX_HOME` or `~/.codex`, by the parent, which
+ * `check` is. Only the shape is looked at — which fields are set — and
+ * nothing from the file is kept or printed.
+ */
+export function codexSignIn(env = process.env) {
+  const home = env.CODEX_HOME && isAbsolute(env.CODEX_HOME) ? env.CODEX_HOME : join(homedir(), ".codex");
+  let auth;
+  try { auth = JSON.parse(readFileSync(join(home, "auth.json"), "utf8")); } catch { return null; }
+  if (!auth || typeof auth !== "object") return null;
+  if (typeof auth.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY) return "apikey";
+  if (auth.tokens && typeof auth.tokens === "object" && auth.tokens.refresh_token) return "chatgpt";
+  return null;
+}
+
+/**
+ * A role that looks set up for OpenAI and would leave Codex hanging.
+ *
+ * Signed in with ChatGPT, Codex talks to `chatgpt.com` for the model and to
+ * `auth.openai.com` to renew the sign-in — never to `api.openai.com` (measured
+ * 2026-09-30, codex 0.150.1: 0 connections). Without `chatgpt.com` it does not
+ * fail: it retries without end and prints nothing, which reads as an agent
+ * thinking. And the proxy's refusal does not reach seisin's log.
+ *
+ * `check` does not know which CLI a role runs, so the signal is the two facts
+ * it can see: this machine's Codex is signed in with ChatGPT, and the role's
+ * list names something under `openai.com` — a list written for OpenAI — but
+ * not `chatgpt.com`. A role whose `env` passes `OPENAI_API_KEY` is left out:
+ * it is set up for the API, where `api.openai.com` is right. Wrong costs a
+ * sentence, never a run, the same trade as the model-endpoint warning above.
+ */
+export function codexSignInWarnings(config, roles, env = process.env) {
+  if (codexSignIn(env) !== "chatgpt") return [];
+  const reaches = (list, host) => list.some((d) => d === "*" || d === host ||
+    (d.startsWith("*.") && host.endsWith(d.slice(1))));
+  const out = [];
+  for (const r of roles) {
+    const list = r.network ?? config.allowedDomains ?? [];
+    if (!list.some((d) => /(^|\.)openai\.com$/i.test(d))) continue;
+    if ((r.env ?? []).includes("OPENAI_API_KEY")) continue;
+    const missing = ["chatgpt.com", "auth.openai.com"].filter((h) => !reaches(list, h));
+    if (!missing.length) continue;
+    out.push({
+      kind: "codex-chatgpt-endpoint",
+      headline: `${r.name} allows ${list.filter((d) => /openai\.com$/i.test(d)).join(" ")} but not ${missing.join(" ")}`,
+      detail:
+        "Codex on this machine is signed in with ChatGPT, and with that sign-in it talks to " +
+        "chatgpt.com for the model and to auth.openai.com to renew the sign-in, never to " +
+        "api.openai.com. " +
+        (missing.includes("chatgpt.com")
+          ? "Without chatgpt.com a Codex run does not fail: it retries without end and prints " +
+            "nothing, and the proxy's denial does not reach seisin's log. "
+          : "Without auth.openai.com a Codex run works until the sign-in has to be renewed. ") +
+        `If ${r.name} runs Codex, add ${missing.join(" and ")}; if it does not, this is not about it.`,
+    });
+  }
+  return out;
+}