seisin 0.5.0 → 0.6.0

package/src/diagnose.js

@@ -28,10 +28,14 @@
  * On Linux the runtime's refusals cannot be read from outside (violations.js),
  * so the after-the-fact half finds nothing there and stays quiet.
  */
+import { isAbsolute } from "node:path";
 import { readEntries } from "./log.js";
 import { explain } from "./owners.js";
-import { timesHit, walls } from "./walls.js";
+import { hitsOf, againWords, walls } from "./walls.js";
 import { collapseSidecars } from "./render.js";
+import { decideHandoff, toAgent, isStopped, ELSEWHERE } from "./handoff.js";
+import { keyOf } from "./requests.js";
+import { destinationOf } from "./intake.js";
 
 /** What a refused write or read looks like in a tool's output. A trigger to look, not a verdict. */
 export const DENIAL_SIGNS = /Operation not permitted|EPERM|EACCES|Permission denied|Read-only file system/i;
@@ -75,6 +79,8 @@ export function recentKernelDenials(file, role, sinceMs) {
   const seen = new Map();
   for (const e of readEntries(file, { tail: TAIL_BYTES }).reverse()) {
     if (e.role !== role || e.verdict !== "denied" || e.source !== "kernel") continue;
+    // A system service is not a path the agent can act on, and the sentence below is about paths.
+    if (e.kind === "system") continue;
     if (!e.at || e.at < since || !e.target) continue;
     const k = `${e.action}\u0000${e.target}`;
     if (!seen.has(k)) seen.set(k, e);
@@ -83,16 +89,32 @@ export function recentKernelDenials(file, role, sinceMs) {
 }
 
 /** The sentence for one refusal, in the words the PreToolUse hook uses. */
-function sentence(config, role, file, e) {
+function sentence(config, role, file, e, chain = null, run = null) {
   const action = e.kind === "key" ? "read" : e.action === "read" || e.action === "connect" ? e.action : "write";
+  // An atomic save refused at its temporary file is about the file it was
+  // saving. Said about that file, or the agent goes looking for a missing
+  // directory (measured).
+  const destination = action === "write" ? destinationOf(e.target) : null;
+  if (destination) {
+    if (explain(config, role, "write", destination).allowed)
+      return `${destination} was not saved: it is ${role}'s to write, but the sandbox denied the temporary file ` +
+        `${e.target} that the save writes beside it, and no grant can name that file. Write ${destination} with the shell ` +
+        "instead (a redirect writes the file itself).";
+    e = { ...e, target: destination };
+  }
   const v = explain(config, role, action, e.target);
   if (v.allowed) return null;             // the policy moved since: nothing to say
-  const times = timesHit(file, role, action, e.target);
-  const again = times > 1 ? ` Refused ${times} times now; the next try ends the same way.` : "";
-  if (v.neverWrites) return `${v.reason}. Do not ask for it.${again}`;
-  if (v.owners?.length)
-    return `${e.target} belongs to ${v.owners.join(", ")}. It is not ${role}'s to change — ` +
-      `hand it over rather than working around it.${again}`;
+  // Read after the refusal was logged, so the counts include it.
+  const { total: times, inRun } = hitsOf(file, role, action, e.target, run);
+  const again = againWords({ times, inRun });
+  if (v.neverWrites) return `${v.reason}. Do not ask for it. ${ELSEWHERE}${again}`;
+  // A write, or a key: the denials that become requests, worded from the same
+  // handoff decision the hook and the queue use. Everything else — a protected
+  // file, a connection, a read the mode shuts — keeps the policy's own reason.
+  const handed = (action === "write" || e.kind === "key") && !v.gitMetadata && !v.protected && !v.privateTo;
+  if (handed)
+    return toAgent(decideHandoff({ request: { role, action, target: e.target }, config, chain }),
+      { target: e.target, role, key: keyOf({ role, action, target: e.target }), again });
   return `${e.target}: ${v.reason}.${again}`;
 }
 
@@ -129,7 +151,7 @@ function evidenceOf(event) {
  * refusal, and a loaded machine can be slower than the hook. Only when the tool
  * reported a failure — see {@link evidenceOf}.
  */
-export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300] } = {}) {
+export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300], chain = null, run = process.env.SEISIN_RUN_ID ?? null } = {}) {
   const { text: evidence, failed } = evidenceOf(event);
   if (!DENIAL_SIGNS.test(evidence)) return null;
   // JSON escapes what the program printed; the signatures are written against the text.
@@ -140,7 +162,7 @@ export async function afterTool(config, role, event, { file, now = Date.now, wai
     found = recentKernelDenials(file, role, now() - WINDOW_MS);
     if (found.length) break;
   }
-  const lines = [...known, ...found.map((e) => sentence(config, role, file, e)).filter(Boolean)].slice(0, MAX_NAMED);
+  const lines = [...known, ...found.map((e) => sentence(config, role, file, e, chain, run)).filter(Boolean)].slice(0, MAX_NAMED);
   if (!lines.length) return null;
   const total = known.length + found.length;
   const more = total > MAX_NAMED ? ` (and ${total - MAX_NAMED} more — \`seisin walls ${role}\`)` : "";
@@ -153,7 +175,7 @@ export async function afterTool(config, role, event, { file, now = Date.now, wai
 }
 
 /** When a session starts, resumes or is compacted: the map, before the first wall. */
-export function atSessionStart(config, role, event, { file } = {}) {
+export function atSessionStart(config, role, event, { file, chain = null } = {}) {
   const r = config.roles[role];
   const writes = collapseSidecars(r.writesDeclared ?? r.writes);
   const lines = [
@@ -162,13 +184,42 @@ export function atSessionStart(config, role, event, { file } = {}) {
   ];
   if ((r.neverWritesDeclared ?? r.neverWrites ?? []).length)
     lines.push(`Never, even inside that: ${(r.neverWritesDeclared ?? r.neverWrites).join(", ")}.`);
+  if (r.private?.length) lines.push(`Private to you (yours to read and write; no other role reads it): ${r.private.join(", ")}.`);
+  const theirs = Object.values(config.roles).filter((o) => o.name !== role && o.private?.length)
+    .map((o) => `${o.private.join(", ")} (${o.name})`);
+  if (theirs.length) lines.push(`Private to another role — you can neither read nor write it: ${theirs.join("; ")}.`);
   if (r.keys.length) lines.push(`Keys you hold: ${r.keys.join(", ")}.`);
-  const w = file ? walls(config, role, { file, limit: 5, fresh: true }) : [];
-  if (w.length) {
+  // An expected refusal (Claude Code's plugin updater) is not the agent's to
+  // stop trying, so it does not take one of the five lines.
+  const w = file ? walls(config, role, { file, limit: 0, fresh: true }).filter((x) => !x.expected).slice(0, 5) : [];
+  // Outside the repository nobody owns anything, so there is no one to hand
+  // it to: under "hand it over", ~/.npm/_logs read as work for somebody else.
+  const outside = (x) => isAbsolute(x.target) || x.target.startsWith("~");
+  // Where this run's handoff chain stops, the wall names no owner: measured,
+  // an agent told the owner here repeated it after the sentence its denial
+  // told it to pass on alone.
+  const stops = (x) => isStopped(decideHandoff({ request: { role, action: x.action, target: x.target }, config, chain }));
+  const inRepo = w.filter((x) => !outside(x)), out = w.filter(outside);
+  const stopped = inRepo.filter(stops), mine = inRepo.filter((x) => !stops(x));
+  const wall = (x) => `- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`;
+  if (mine.length) {
     lines.push("Already denied more than once, and still denied — do not try again, hand it over:");
-    for (const x of w)
-      lines.push(`- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`);
+    for (const x of mine) lines.push(wall(x));
+  }
+  if (stopped.length) {
+    lines.push("Already denied more than once, where this run's handoff chain stops — do not try again; a person decides, " +
+      "and the denial gives you the one sentence to pass on:");
+    for (const x of stopped) lines.push(`- ${x.action} ${x.target} (${x.times}×)`);
+  }
+  if (out.length) {
+    lines.push("Denied more than once outside the repository, where no role owns anything — nothing to hand over; leave it:");
+    for (const x of out) lines.push(`- ${x.action} ${x.target} (${x.times}×)`);
   }
-  lines.push("A file outside that is somebody else's: say whose it is and hand it over, rather than working around it.");
+  // In a handed run a denial can be where the chain stops, and there the agent
+  // is to say one sentence and not whose the file is: the map cannot ask the
+  // opposite.
+  lines.push(chain?.visited?.length
+    ? "A file outside that is not yours to change: do not work around it. Where a denial gives you a sentence to pass on, pass on that sentence and nothing else about the file."
+    : "A file outside that is somebody else's: say whose it is and hand it over, rather than working around it.");
   return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } };
 }

package/src/env.js

@@ -29,6 +29,9 @@ export const BASE = [
   "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME",
   "TERM", "TERM_PROGRAM", "COLORTERM", "LANG", "LC_ALL", "LC_CTYPE", "TZ",
   "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS",
+  // The launcher's W3C trace context: ids that join the agent's own telemetry to
+  // the launcher's trace (trace.js). By the spec they are not secrets.
+  "TRACEPARENT", "TRACESTATE",
 ];
 
 /**

package/src/grants.js

@@ -128,6 +128,111 @@ export const RUNTIME_WRITES = [
   "~/.cache", "$TMPDIR", "/tmp",
 ];
 
+/**
+ * The agents that keep their state — and their sign-in — under a directory of
+ * their own name, and where that sign-in sits when it is a file.
+ *
+ * `~/.claude` and `~/.codex` used to be granted to every run, whatever it ran.
+ * The cost was measured on 2026-09-30: a role running nothing but `cat` read
+ * `~/.codex/auth.json`, the ChatGPT tokens of whoever signed Codex in. The
+ * directory is the agent's scratch, so it goes to a run of that agent; and the
+ * other agents' sign-in files are denied to it, read and write, so a Claude
+ * run cannot read Codex's tokens or swap them for another account's.
+ *
+ * `~/.claude/.credentials.json` is where Claude Code keeps its sign-in when
+ * there is no keychain (Linux, and macOS when the keychain is unavailable).
+ * On macOS it is normally in the login keychain, which no file rule reaches.
+ *
+ * What this does NOT close, said where it is decided: a run of Codex can read
+ * its own `auth.json`, and so can every command Codex runs, because they share
+ * one sandbox. Only Codex storing its sign-in in the keychain closes that
+ * (`cli_auth_credentials_store = "keyring"`), and that is Codex's setting.
+ */
+export const AGENT_HOMES = { claude: "~/.claude", codex: "~/.codex" };
+export const AGENT_CREDENTIALS = {
+  claude: ["~/.claude/.credentials.json"],
+  codex: ["~/.codex/auth.json"],
+};
+export const AGENTS = Object.keys(AGENT_HOMES);
+
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "fish"]);
+const LAUNCHERS = new Set(["node", "npx", "bunx", "pnpx", "bun", "deno"]);
+
+/** Which agent a token names, by its basename or its package path, or null. */
+function agentNamed(token) {
+  const t = String(token ?? "");
+  const base = t.split("/").pop().replace(/\.(c|m)?js$/, "");
+  if (AGENTS.includes(base)) return base;
+  if (/@openai\/codex(\/|$)/.test(t)) return "codex";
+  if (/@anthropic-ai\/claude-code(\/|$)/.test(t)) return "claude";
+  return null;
+}
+
+/**
+ * The agent a command line runs, or null when it is none seisin knows.
+ *
+ * Reads what a person writes after `--`: the program, through `env` and
+ * `VAR=value`, through a launcher (`node …/@openai/codex/bin/codex.js`,
+ * `npx @anthropic-ai/claude-code`), and through `sh -c "codex exec …"` by the
+ * first word of the script. Nothing cleverer: a prompt that mentions "claude"
+ * must not turn a run into a Claude run. A wrapper script is not followed —
+ * `seisin run <role> --agent codex -- ./wrapper.sh` says it instead.
+ */
+export function agentOf(cmd = []) {
+  const argv = [...cmd];
+  for (let depth = 0; depth < 4 && argv.length; depth++) {
+    while (argv.length && (argv[0] === "env" || /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[0]) ||
+      (argv[0].startsWith("-") && depth > 0))) argv.shift();
+    if (!argv.length) return null;
+    const head = argv.shift();
+    const named = agentNamed(head);
+    if (named) return named;
+    const base = head.split("/").pop();
+    if (LAUNCHERS.has(base)) {
+      const next = argv.find((a) => !a.startsWith("-"));
+      return next ? agentNamed(next) : null;
+    }
+    if (SHELLS.has(base)) {
+      const i = argv.findIndex((a) => /^-[a-z]*c$/.test(a));
+      if (i === -1 || argv[i + 1] === undefined) return null;
+      argv.splice(0, argv.length, ...argv[i + 1].trim().split(/\s+/));
+      continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * The scratch list for a run of `agent`: every entry, minus the homes of the
+ * agents it is not.
+ *
+ * `agent === undefined` is "no command known" — check, console, explain, and
+ * the union surface.js needs — and answers with every home, which is the most
+ * any run of the role gets. `null` is a command that is no agent seisin knows,
+ * and gets neither home. An explicit `[runtime] writes` goes through the same
+ * filter: listing `~/.codex` there says what a Codex run may write, not that
+ * a `cat` may.
+ */
+export function runtimeWritesFor(config, agent) {
+  const list = (config.runtimeWrites ?? RUNTIME_WRITES).map(expand);
+  if (agent === undefined) return list;
+  const others = AGENTS.filter((a) => a !== agent).map((a) => expand(AGENT_HOMES[a]));
+  return list.filter((p) => !others.some((h) => p === h || p.startsWith(h + "/")));
+}
+
+/**
+ * The sign-in files of every agent this run is not, absolute, under `home`.
+ *
+ * Empty when no command is known: a role's settings without a command are the
+ * most it can get, and the most includes being run as either agent.
+ */
+export function otherAgentsCredentials(agent, home = homedir()) {
+  if (agent === undefined) return [];
+  const at = (p) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
+  return AGENTS.filter((a) => a !== agent).flatMap((a) => AGENT_CREDENTIALS[a].map(at)).map((p) => realOrSelf(p));
+}
+
 /**
  * `~` and `$TMPDIR` are the only expansions; everything else is a literal path.
  *
@@ -234,7 +339,7 @@ function unexpressible(glob, key = "writes") {
  * the real ~/.claude, ~/.cache and /tmp, which every role shares — convenient,
  * and the reason `isolate` exists.
  */
-export function writePathsOf(config, role, { observe = false } = {}) {
+export function writePathsOf(config, role, { observe = false, agent } = {}) {
   const abs = (p) => (p.startsWith("/") ? p : join(config.root, p));
   const level = config.isolate === true ? "home" : config.isolate;
   const home = level === "home" ? roleHome(config, role.name) : null;
@@ -242,6 +347,6 @@ export function writePathsOf(config, role, { observe = false } = {}) {
     ...(observe ? [abs(".")] : role.writes.map((g) => abs(toWritePath(g)))),
     ...(home
       ? [home, join(home, ".config"), join(home, ".local"), join(home, ".cache"), join(home, "tmp")]
-      : (config.runtimeWrites ?? RUNTIME_WRITES).map(expand)),
+      : runtimeWritesFor(config, agent)),
   ];
 }

package/src/handoff.js

@@ -16,8 +16,18 @@
  * *demand* for work. It may not determine authority, routing identity,
  * admission or policy. Every input below is either derived from the boundary
  * or supplied by the caller; none of them is a role name a model chose.
+ *
+ * ── Where the decision is made ──
+ * Where the request is read, not where it is written. Every reader of the
+ * queue — `seisin requests`, the end of `seisin run`, the notification, the
+ * console, the MCP — gets it from requests.js (withHandoffs), against the
+ * policy in front of it, so a grant made since changes it at once. What is
+ * written down is only history: the chain a request was asked in, set by the
+ * parent of a run started with `--handoff`, and what the execution plane did
+ * about it (recordHandoff). Reads go to a person: a key is shared by a grant,
+ * never handed over.
  */
-import { ownersOf } from "./owners.js";
+import { ownersOf, keyHolders, inKeyDir } from "./owners.js";
 
 /** Small on purpose: a fuse for a topology nobody predicted, not a budget. */
 export const MAX_DEPTH = 4;
@@ -44,10 +54,26 @@ export function decideHandoff({
   if (!config || !config.roles) throw new Error("decideHandoff: config needs roles");
 
   const depthMax = limits.depth ?? MAX_DEPTH;
-  const visited = chain?.visited ?? [request.role];
+  // A caller may provide incomplete history. The requester is always visited.
+  const visited = [...new Set([...(chain?.visited ?? []), request.role])];
   const depth = chain?.depth ?? 0;
   const at = (type, extra = {}) => ({ type, revision, chainId: chain?.id ?? null, ...extra });
 
+  /**
+   * A read is not handed to anybody. A key is declared, not owned, and the
+   * only thing that changes who reads it is a person sharing it; another
+   * role's private folder is the policy working. Who declares or owns it is
+   * still worked out here — the queue shows it — but the decision is a
+   * person's, unless the policy already moved and the asker has it now.
+   */
+  if (request.action === "read") {
+    const key = isKeyRequest(config, request);
+    const holders = key ? keyHolders(config, request.target) : ownersOf(config, request.target);
+    if (holders.includes(request.role))
+      return at("resolved", { resolution: "policy_changed", role: request.role, owners: holders });
+    return at("human", { reason: key ? "key" : "read", owners: holders });
+  }
+
   const owners = ownersOf(config, request.target);
 
   /**
@@ -61,9 +87,6 @@ export function decideHandoff({
    * wrong thing.
    */
   if (owners.length === 0) return at("human", { reason: "unowned", owners });
-  if (owners.length > 1) return at("human", { reason: "ambiguous", owners });
-
-  const [owner] = owners;
 
   /**
    * The policy moved and the asker owns it now. Nobody granted anything, so
@@ -71,8 +94,30 @@ export function decideHandoff({
    * so is what keeps the human queue readable. Sending this to a person would
    * be asking them to decide something already decided.
    */
+  if (owners.length === 1 && owners[0] === request.role)
+    return at("resolved", { resolution: "policy_changed", role: request.role, owners });
+
+  /**
+   * Only an owner that takes handed work can be handed it.
+   *
+   * A role marked `handoff = false` is a pipeline phase, not a worker: it owns
+   * its territory — often all of it, `**` — and starting it because some other
+   * role reached for a file there would run a phase for a reason that has
+   * nothing to do with it. So it is left out of the choice, and the existing
+   * rule runs over who is left: one receiver is a route, several are for a
+   * person, and none is a person's too, with a reason that says the owner is
+   * there and does not take the work. Ownership itself is untouched — the
+   * queue and the agent still hear whose it is.
+   */
+  const receivers = owners.filter((o) => config.roles[o]?.handoff !== false);
+  const narrowed = receivers.length < owners.length ? { receivers } : {};
+  if (receivers.length === 0) return at("human", { reason: "no-receiver", owners, receivers });
+  if (receivers.length > 1) return at("human", { reason: "ambiguous", owners, ...narrowed });
+
+  const [owner] = receivers;
+  // The asker is that one receiver: it owns the path now, whoever else does.
   if (owner === request.role)
-    return at("resolved", { resolution: "policy_changed", role: owner });
+    return at("resolved", { resolution: "policy_changed", role: owner, owners });
 
   /**
    * A role already in this chain does not get re-entered, even for a different
@@ -81,10 +126,10 @@ export function decideHandoff({
    * person should make on purpose.
    */
   if (visited.includes(owner))
-    return at("cycle", { role: owner, visited: [...visited] });
+    return at("cycle", { role: owner, owners, visited: [...visited] });
 
   if (depth + 1 > depthMax)
-    return at("depth", { role: owner, depth: depth + 1, max: depthMax });
+    return at("depth", { role: owner, owners, depth: depth + 1, max: depthMax });
 
   /**
    * Bounded invocation. A role cannot write another role's territory, but it
@@ -97,15 +142,245 @@ export function decideHandoff({
    */
   const senderMax = limits.senderChains ?? Infinity;
   if ((load.senderOpenChains ?? 0) >= senderMax)
-    return at("throttled", { role: owner, limit: "senderChains", max: senderMax });
+    return at("throttled", { role: owner, owners, limit: "senderChains", max: senderMax });
 
   const receiverMax = limits.receiverConcurrent ?? Infinity;
   if ((load.receiverRunning ?? 0) >= receiverMax)
-    return at("throttled", { role: owner, limit: "receiverConcurrent", max: receiverMax });
+    return at("throttled", { role: owner, owners, limit: "receiverConcurrent", max: receiverMax });
 
   return at("route", {
     role: owner,
+    owners,
+    ...narrowed,
     depth: depth + 1,
     visited: [...visited, owner],
   });
 }
+
+/**
+ * Whether a read request is for a key: inside a key directory, or a bare name,
+ * which is how a key in the first key directory is written.
+ */
+export function isKeyRequest(config, request) {
+  const t = request?.target;
+  return request?.action === "read" && typeof t === "string" && (inKeyDir(config, t) || !t.includes("/"));
+}
+
+/**
+ * The chain a request belongs to, as decideHandoff takes it.
+ *
+ * A request filed by a run that was itself handed work carries the chain that
+ * run was started with (see chainFrom); one filed by any other run starts a
+ * chain of its own, named by its own id. Never read from inside the sandbox:
+ * the parent writes it, from the decision it checked before starting the run.
+ */
+export function chainOf(request) {
+  const c = request?.chain;
+  const ok = c && typeof c.id === "string" && Number.isInteger(c.depth) && c.depth >= 0 &&
+    Array.isArray(c.visited) && c.visited.every((r) => typeof r === "string");
+  return ok ? { id: c.id, depth: c.depth, visited: [...c.visited] } : { id: request?.key ?? null, depth: 0, visited: [] };
+}
+
+/**
+ * What a run started for a routed decision carries into the requests it files.
+ * Null for anything but a route: only a route starts work.
+ */
+export function chainFrom(decision) {
+  if (decision?.type !== "route") return null;
+  return { id: decision.chainId, depth: decision.depth, visited: [...decision.visited] };
+}
+
+/**
+ * The variable `seisin run --handoff` sets in the receiver's environment, so
+ * the hook inside can word a denial with the chain the run belongs to.
+ *
+ * Words only. The chain a request is recorded in is the parent's, written by
+ * intake from the run it started (requests.js, record), and nothing read from
+ * here reaches the queue. A process inside that rewrote it would change the
+ * sentence it is told about its own denial, and nothing else. Reserved, so a
+ * policy cannot deliver a key under this name (keys.js, RESERVED_ENV).
+ */
+export const CHAIN_ENV = "SEISIN_HANDOFF_CHAIN";
+
+/** The run's chain from its environment, or null: absent and malformed are the same. */
+export function chainFromEnv(env = process.env) {
+  const raw = env?.[CHAIN_ENV];
+  if (!raw) return null;
+  let c;
+  try { c = JSON.parse(raw); } catch { return null; }
+  const ok = c && typeof c === "object" && typeof c.id === "string" && Number.isInteger(c.depth) && c.depth >= 0 &&
+    Array.isArray(c.visited) && c.visited.every((r) => typeof r === "string");
+  return ok ? { id: c.id, depth: c.depth, visited: [...c.visited] } : null;
+}
+
+/**
+ * The decision as the denied agent is told it: whose the path is, where the
+ * work goes, and what to do instead of retrying. One sentence, the same from
+ * the PreToolUse hook, after a failed tool call and from `seisin whose`.
+ *
+ * It informs and offers nothing to act with. Every role it names is one the
+ * policy named; it never asks the agent to pick one, and there is no answer
+ * the agent can give back that would change who takes the work — the queue
+ * decides that again, from the policy, whenever it is read.
+ */
+export function toAgent(decision, { target, role, key = null, again = "" }) {
+  const d = decision ?? {};
+  // Where a chain stops, the agent is not told whose the file is, or the chain
+  // it came along. Measured: with the owner in the message, two runs of three
+  // added whose file it was after the sentence they were told to say alone.
+  if (isStopped(d))
+    return `${target} is not ${role}'s to change, and its handoff chain stops here: ` +
+      (d.type === "cycle" ? "handing it on would send it back the way it came." : `${d.depth} of ${d.max} deep.`) +
+      ` A person decides. Do not work around it. ${ELSEWHERE}${again}` + stopped(d, target, key);
+  const owners = d.owners ?? [];
+  const whose = d.reason === "key"
+    ? (owners.length ? `${target} is declared for ${owners.join(", ")}, not ${role}.` : `No role declares ${target}.`)
+    : owners.length
+      ? `${target} belongs to ${owners.join(", ")}. It is not ${role}'s to change.`
+      : `${target} has no owner.`;
+  // A key or a read is not a change to put somewhere else.
+  const write = d.reason !== "key" && d.reason !== "read" && d.type !== "resolved";
+  return `${whose} ${nextStep(d, role)}` + (write ? ` ${ELSEWHERE}` : "") + again;
+}
+
+/** A chain that stops: a cycle, or one too deep. Its denial ends on the sentence to pass on. */
+export function isStopped(decision) {
+  return decision?.type === "cycle" || decision?.type === "depth";
+}
+
+/**
+ * Where a handoff chain stops, the words to pass on, given literally.
+ *
+ * Measured with real runs: told "not that frontend will make the change", an
+ * agent stopped saying frontend would make it and, in one run of two, told
+ * its user to go and coordinate with frontend instead. A negative instruction
+ * leaves the agent to compose the sentence; this one hands it over.
+ */
+function stopped(d, target, key) {
+  const waiting = key ? `the request ${key} is waiting in seisin requests` : "the request is waiting in seisin requests";
+  // Measured again with the literal words: passed on in three runs of three,
+  // and then contradicted in two, by an agent adding who should do it or where
+  // else it could go. So the sentence ends on that, too. Measured a third time:
+  // no run added either, but one added whose file it was, and one dropped the
+  // path from the front ("Not written. …"). So both are said as well. And
+  // nothing comes after the sentence: what not to add is said first, so the
+  // quote is the last thing the agent reads (hook.js ends the denial on it).
+  // Measured a fourth time: an agent that headed its line with the path ate
+  // the sentence's subject ("src/x — Not written. …"). So the path is no
+  // longer the subject, and the sentence is to be said whole regardless.
+  return " About this file, tell whoever sent you one sentence and add nothing to it: not whose file it is, " +
+    "who should do it or where else it could go. The sentence, word for word and whole, even where your line " +
+    `already names the file: "Not written: ${target}. A person has to decide who does it; ${waiting}."`;
+}
+
+/**
+ * What "working around it" means, said once. Measured: an agent that would
+ * never retry the write still offered, twice, to leave the file in a folder of
+ * its own — the same change, under a path nobody reviews.
+ */
+export const ELSEWHERE = "Do not put the change somewhere else instead (another path, a copy, /tmp).";
+
+/**
+ * How the denial ends: that it is already queued, and for whom. Said apart
+ * from toAgent because only a denial that files a request may say it — the
+ * note after a failed call and `seisin whose` file nothing.
+ *
+ * A route ends on the role it goes to. Ending it on "a person", as every
+ * denial once did, told the agent two owners in one sentence, and with a
+ * handoff chain in it the agent repeated the wrong one.
+ */
+export function queuedLine(decision) {
+  return decision?.type === "route"
+    ? `Already queued as a handoff to ${decision.role}: a run of ${decision.role}, or a person, picks it up — retrying or waiting will not move it.`
+    : "Already queued for a person to answer — retrying or waiting will not move it.";
+}
+
+/** What to do about it, from the decision alone: the second half of toAgent, and `seisin whose`. */
+export function nextStep(decision, role) {
+  const d = decision ?? {};
+  switch (d.type) {
+    case "route":
+      return `It is handed to ${d.role}` +
+        (d.depth > 1 ? ` (handoff chain ${(d.visited ?? []).join(" → ")}, ${d.depth} of ${MAX_DEPTH} deep)` : "") +
+        ": hand it over rather than working around it.";
+    case "human":
+      if (d.reason === "key") return "Ask for what you need from it rather than reading the key.";
+      if (d.reason === "no-receiver")
+        return `${(d.owners ?? []).join(", ") || "Its owner"} ${(d.owners ?? []).length > 1 ? "do" : "does"} not take handed work, ` +
+          "so a person decides who takes it. Do not work around it.";
+      return d.reason === "ambiguous"
+        ? "With more than one owner, a person decides who takes it. Do not pick one, and do not work around it."
+        : "A person decides who takes it. Do not work around it.";
+    // Measured: told only "not handed back", an agent still told its user
+    // that the owner would make the change. It has to hear that nothing is
+    // asked of the owner, and what to say instead.
+    case "cycle":
+      return `It is not handed back to ${d.role}: this work already came through ${d.role} ` +
+        `(handoff chain ${(d.visited ?? []).join(" → ")}), so nothing is asked of ${d.role}. ` +
+        "A person decides how to split it. Do not work around it.";
+    case "depth":
+      return `The handoff chain stops here, ${d.depth} of ${d.max} deep. A person decides. Do not work around it.`;
+    case "resolved":
+      return `The policy now gives it to ${role}: the next run has it.`;
+    default: {
+      const said = describeHandoff(d) || "a person decides";
+      return `${said[0].toUpperCase()}${said.slice(1)}. Do not work around it.`;
+    }
+  }
+}
+
+/**
+ * The decision in words a person reads, one line, no colour.
+ *
+ * `attempt` is what the execution plane last recorded about the request
+ * (requests.js, recordHandoff). It is shown only where seisin's own decision
+ * is a route to the same role: whether that role could be started is
+ * admission, which only whatever starts it knows. Every other outcome is the
+ * policy's, recomputed now, and a recorded attempt cannot overrule it.
+ */
+export function describeHandoff(decision, attempt = null, chainStopped = null) {
+  const said = describeDecision(decision, attempt);
+  // A run took it and its chain then stopped further on: the request is still
+  // pending, and without this it read as handed and done.
+  return said && chainStopped?.length
+    ? `${said}; its handoff chain stopped at ${chainStopped.join(", ")}, which needs a person`
+    : said;
+}
+
+function describeDecision(decision, attempt) {
+  const d = decision;
+  if (!d) return "";
+  if (d.type === "route" && attempt && attempt.role === d.role) {
+    if (attempt.outcome === "throttled")
+      return `handoff held: ${limitWords(attempt.limit, attempt.role)} ${attempt.max}/${attempt.max} — still to do`;
+    if (attempt.outcome === "route") return `handed to ${d.role} — a run of ${d.role} took it`;
+  }
+  switch (d.type) {
+    case "route":
+      return `handed to ${d.role}` + (d.depth > 1 ? ` (handoff chain, ${d.depth} of ${MAX_DEPTH})` : "");
+    case "throttled":
+      return `handoff held: ${limitWords(d.limit, d.role)} ${d.max}/${d.max} — still to do`;
+    case "cycle":
+      return `handoff stopped: ${d.role} is already in this handoff chain — needs a person to split the work`;
+    case "depth":
+      return `handoff stopped: handoff chain reached ${d.depth} of ${d.max} — needs a person`;
+    case "human":
+      if (d.reason === "ambiguous") return `a person decides: more than one role owns this (${(d.receivers ?? d.owners).join(", ")})`;
+      if (d.reason === "no-receiver")
+        return `a person decides: ${d.owners.join(", ")} ${d.owners.length > 1 ? "own" : "owns"} this and ${d.owners.length > 1 ? "take" : "takes"} no handed work (handoff = false)`;
+      if (d.reason === "key") return "a person decides: a key is shared by a grant, never handed over";
+      if (d.reason === "read") return "a person decides: a read is not handed over";
+      return "a person decides: no role owns this";
+    case "resolved":
+      return `no handoff needed — the policy moved and ${d.role} has it now`;
+    default:
+      return `handoff: ${d.type}`;
+  }
+}
+
+/** 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";
+}