seisin 0.4.2 → 0.6.0

package/src/grants.js

@@ -14,11 +14,12 @@ import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { realpathSync, lstatSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { WILD } from "./paths.js";
 
 /**
  * What every agent needs to write no matter which role it is.
  *
- * Found by running a real cell config through the sandbox: territory alone
+ * Found by running a policy with 32 roles through the sandbox: territory alone
  * looks correct and is unusable. An agent writes its session state under its
  * own config directory and its tools write scratch files to the temp dir, so a
  * policy of "your folders and nothing else" stops the agent before it starts.
@@ -67,7 +68,7 @@ export function roleHomeRoot(config) {
    *
    * This was `base64url(root).slice(-16)` — the TAIL of the encoded path, which
    * is the tail of the path itself. Two checkouts that end the same way get the
-   * same id: `/Users/ana/dev/proyecto` and `/Users/bob/dev/proyecto` collide, and
+   * same id: `/Users/ana/dev/project` and `/Users/bob/dev/project` collide, and
    * so do `/home/a/work/api` and `/home/b/work/api`. A collision here is not a
    * cosmetic clash — both repos' role `dev` would share one HOME, which is the
    * session token of one handed to the other. Measured on three of four ordinary
@@ -127,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.
  *
@@ -145,10 +251,18 @@ export function isLink(p) {
   }
 }
 
-/** The path with symlinks followed, or the path itself if it is not on disk. */
+/**
+ * The path with symlinks followed, or the path itself if it is not on disk.
+ *
+ * `.native` is realpath(3): one call instead of an lstat per component, and on
+ * a case-insensitive disk (APFS) it answers with the case the disk has. The JS
+ * version keeps whatever case it was given, so `/users/x` and `/Users/x` —
+ * one directory — compared as two, and a path spelled the other way came out
+ * "outside the repo" while the kernel treated it as inside.
+ */
 export function realOrSelf(p) {
   try {
-    return realpathSync(p);
+    return realpathSync.native(p);
   } catch {
     return p;
   }
@@ -159,7 +273,7 @@ export function expand(p) {
   if (p === "$TMPDIR") out = tmpdir();
   else if (p === "~" || p.startsWith("~/")) out = join(homedir(), p.slice(2));
   try {
-    return realpathSync(out);
+    return realpathSync.native(out);
   } catch {
     return out; // not on disk yet; hand the literal through rather than drop it
   }
@@ -195,7 +309,6 @@ export function toWritePath(glob, key = "writes") {
  * prefixes, and "one level down" is not a prefix. Refusing is not a placeholder
  * here, it is the answer.
  */
-const WILD = /[*?[\]]/;                       // owners.js treats all four as wildcards
 const EXPRESSIBLE = (g) =>
   g === "**" ||                               // the whole repo
   !WILD.test(g) ||                            // a literal path
@@ -217,7 +330,7 @@ function unexpressible(glob, key = "writes") {
  * grants the whole repo, so `observe: true` answers for that case.
  *
  * `.seisin/` is deliberately NOT here. It used to be, because the hook runs
- * inside the box and has to record what it decided — which made the log and
+ * inside the sandbox and has to record what it decided — which made the log and
  * the queue writable by the process they are a record of. The hook now sends
  * its lines to the parent over a socket and the parent holds the file. See
  * spool.js.
@@ -226,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;
@@ -234,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";
+}