trantor 0.18.108 → 0.18.110

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.108",
+  "version": "0.18.110",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/README.md

@@ -417,9 +417,16 @@ rate, not work rate.
 ```
 trantor setup | doctor | connect | profile | provider | models
         | new <name> | up <agents…> | swap <old> <new> | down | seat-why <agent> | ui | advise | hub | watch
-        | adopt <project> | reconcile | duty | orchestrate | patrol | app | backfill | init-hooks
+        | adopt <project> | reconcile | duty | orchestrate | patrol | app | backfill | init-hooks | pair
 ```
 
+- **`trantor pair`** pairs the iPhone and iPad companion app (`ios/`, an operator console for
+  fleet decisions). It mints a single-use, ten-minute invite with the `approver` role (decides
+  holds, proposals and gates; never deletes projects or mints invites) and prints a
+  `trantor://enroll` link. `--sim` opens it in the booted simulator, `--json` prints it for
+  scripts, and `--role owner` widens the scope. The desktop app's Settings shows the same invite
+  as a QR code. It signs as the operator's owner identity (`TRANTOR_IDENTITY`, default `sasha@mac`).
+
 - **`trantor new <name>`** — project genesis in one command: makes the dir under your dev root
   (`TRANTOR_DEV_ROOT` or `~/development`), git on main (or `--from <git-url>`, or `--adopt` an
   existing folder), installs the auto-card hook, posts the brief to the hub, and opens the first

package/bin/cli.mjs

@@ -187,6 +187,7 @@ switch (cmd) {
     else console.error(`Invite failed: ${j.error || r.statusText}`);
     break;
   }
+  case "pair":    run("bin/pair.mjs"); break;
   case "enroll": {
     const token = args[0];
     if (!token) { console.error("usage: trantor enroll <token>"); process.exit(1); }
@@ -256,6 +257,7 @@ switch (cmd) {
   trantor down        tear the crew down (kills processes, closes windows, no dialogs)
   trantor prune       drop dead crew-window tracking rows (ghost workspaces/panes) without spawning anything
   trantor ui          open the live dashboard (board + flow views)
+  trantor pair        pair a phone: mint a trantor://enroll link for the companion app — [--role owner] [--sim] [--json]
   trantor app         the DESKTOP app: status | install | update — pulls the latest DMG from GitHub Releases
   trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
   trantor agents      what this session's sub-agents did (task · returned? · files written · survived on disk) — [<sessionId>] [--json]

package/bin/crew-runner.mjs

@@ -265,11 +265,11 @@ const CLI = {
   // the token-scrooge .env so an existing OPENROUTER_API_KEY authenticates with no extra wiring.
   openrouter: { first: `opencode run --dir {DIR}{M} "$(cat {P})"`,
               next:  `opencode run --dir {DIR} -s {SID}{M} "$(cat {P})"`, mflag: " -m ", pinned: true, env: join(homedir(), ".token-scrooge", ".env") },
-  claude:   { first: `claude{M} -p "$(cat {P})" --dangerously-skip-permissions`,
-              next:  `claude -c{M} -p "$(cat {P})" --dangerously-skip-permissions`,
+  claude:   { first: `claude{M} -p "$(cat {P})" --permission-mode bypassPermissions --dangerously-skip-permissions`,
+              next:  `claude -c{M} -p "$(cat {P})" --permission-mode bypassPermissions --dangerously-skip-permissions`,
               // TDD §4.6: a state step is a fresh `claude -p` (no `-c`) carrying the assembled prefix, held
               // to the TurnResult grammar by --json-schema; test/state/test-runner-state.mjs pins the strings.
-              stateNext: `claude{M} -p "$(cat {P})" --dangerously-skip-permissions --output-format json --json-schema "$(cat {S})"`,
+              stateNext: `claude{M} -p "$(cat {P})" --permission-mode bypassPermissions --dangerously-skip-permissions --output-format json --json-schema "$(cat {S})"`,
               mflag: " --model " },
   // DeepSeek Harness: every turn is a fresh session (headless has no resume), so the seat leans on
   // the wake prompt and the board. `trantor connect` builds ~/.dsh/profiles/trantor; no model flag.

package/bin/pair.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// trantor pair — mint a phone-pairing invite and print it as a trantor://enroll link.
+// Same owner signing as `trantor invite`, but scoped for the companion app: every project,
+// the approver role, single use, ten minutes. The phone scans the QR (desktop Settings) or
+// opens the link (this command, --sim) and enrolls itself.
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+const asJson = args.includes("--json");
+const openSim = args.includes("--sim");
+const roleIdx = args.indexOf("--role");
+const role = roleIdx >= 0 ? (args[roleIdx + 1] || "") : "approver";
+if (!role || role.startsWith("--")) {
+  console.error("usage: trantor pair [--role owner] [--sim] [--json]");
+  process.exit(1);
+}
+
+const { load, signRequest } = await import(join(ROOT, "lib/identity.mjs"));
+const { resolveHubInfo } = await import(join(ROOT, "lib/project.mjs"));
+
+const hub = resolveHubInfo().url.replace(/\/+$/, "");
+// The operator's owner key, the same one the desktop app signs with (hub.rs owner_identity).
+// Loaded, never minted: a fresh key is unknown to the hub and every invite would 401.
+const owner = process.env.TRANTOR_IDENTITY || "sasha@mac";
+const id = load(owner);
+if (!id) { console.error(`error: no key for the owner identity "${owner}". Set TRANTOR_IDENTITY, or run \`trantor keys status\``); process.exit(1); }
+
+const payload = { scopes: [{ project: "*", role }], ttlSec: 600, kind: "human" };
+const body = JSON.stringify(payload);
+const sig = signRequest(id, { method: "POST", path: "/invite", body });
+let r;
+try {
+  r = await fetch(`${hub}/invite`, { method: "POST", headers: { "content-type": "application/json", ...sig }, body });
+} catch (e) {
+  console.error(`error: hub unreachable at ${hub} — ${e.message}`);
+  process.exit(1);
+}
+const j = await r.json().catch(() => ({}));
+
+// The hub may predate the approver role (#12113): an explicit 400 names it, an older hub is
+// quieter — cleanScope folds unknown roles down to read and echoes the folded scope. Either
+// way a link minted here would pair the phone into near-nothing, so refuse it instead.
+const echoed = Array.isArray(j.scopes) ? j.scopes[0]?.role : undefined;
+const roleRefused = !r.ok
+  ? /role|approver/i.test(String(j.error || "")) || r.status === 400
+  : echoed !== role;
+if (roleRefused) {
+  const why = r.ok
+    ? `this hub does not know the "${role}" role yet — it answered with "${echoed}", which would pair the phone near-read-only`
+    : `hub refused the invite: ${j.error || r.statusText}`;
+  if (asJson) console.log(JSON.stringify({ error: why, hint: "retry with --role owner" }));
+  else console.error(`Pairing refused: ${why}\nRetry with --role owner.`);
+  process.exit(1);
+}
+if (!r.ok) {
+  if (asJson) console.log(JSON.stringify({ error: j.error || r.statusText }));
+  else console.error(`Pairing failed: ${j.error || r.statusText}`);
+  process.exit(1);
+}
+
+const link = `trantor://enroll?hub=${encodeURIComponent(hub)}&token=${j.token}`;
+const expiresAt = Number(j.expiresAt) || Date.now() + 600000;
+const mins = Math.max(0, Math.round((expiresAt - Date.now()) / 60000));
+
+if (asJson) {
+  console.log(JSON.stringify({ link, token: j.token, hub, expiresAt }));
+} else {
+  console.log(`Pair link (single use):\n${link}\nExpires in ${mins} minute${mins === 1 ? "" : "s"}.`);
+}
+
+if (openSim) {
+  if (process.platform !== "darwin") {
+    console.error("--sim needs macOS (xcrun simctl)");
+    process.exit(1);
+  }
+  const sim = spawnSync("xcrun", ["simctl", "openurl", "booted", link], { stdio: "pipe" });
+  if (sim.status !== 0) {
+    console.error(`simctl could not open the link: ${String(sim.stderr).trim() || "no booted simulator?"}`);
+    process.exit(1);
+  }
+  if (!asJson) console.log("Opened in the booted simulator.");
+}

package/bin/wake-nudge.mjs

@@ -60,18 +60,41 @@ export function tokenFromEnvironment(text, socketPath) {
   return /(?:^|\s)CLAUDE_CODE_MESSAGING_TOKEN=(\S+)/.exec(text)?.[1] || "";
 }
 
-export function resolveRecipient(recipient, { bus = busDir(), localHost = hostId(), command = run, socketDir = "/tmp/cc-socks" } = {}) {
-  if (!recipient.startsWith(`${localHost}:`)) return null;
+// #12092: CC 2.1.248 may bind under a private per-user directory instead of the default one, so the
+// socket path comes from the target's own CLAUDE_CODE_MESSAGING_SOCKET. This is the same text read as above.
+export function messagingFromEnvironment(text) {
+  const socket = /(?:^|\s)CLAUDE_CODE_MESSAGING_SOCKET=(\S+)/.exec(text)?.[1] || "";
+  const token = /(?:^|\s)CLAUDE_CODE_MESSAGING_TOKEN=(\S+)/.exec(text)?.[1] || "";
+  return { socket: socket.startsWith("/") && !socket.split("/").includes("..") ? socket : "", token };
+}
+
+// #12092: where CC binds when the env var cannot be trusted (read from the CC 2.1.304 binary): the
+// default <XDG_RUNTIME_DIR or tmp>/cc-socks, and the per-uid fallback <tmp>/cc-socks-<uid> used when
+// the default is refused or the path is over 103 bytes. macOS /tmp is /private/tmp, so both spellings.
+export function fallbackSocketDirs({ env = process.env, uid = process.getuid?.() ?? 0 } = {}) {
+  const dirs = [];
+  if (env.XDG_RUNTIME_DIR) dirs.push(join(env.XDG_RUNTIME_DIR, "cc-socks"));
+  for (const base of ["/tmp", "/private/tmp"]) dirs.push(join(base, "cc-socks"), join(base, `cc-socks-${uid}`));
+  return [...new Set(dirs)];
+}
+
+// #12092: a structured verdict so an unreachable session carries a reason; resolveRecipient keeps
+// the old null-or-target contract. `quiet` marks ordinary skips (remote, busy, ambiguous) from
+// reportable ones (the session is local and idle but has no usable socket).
+export function resolveRecipientDetailed(recipient, { bus = busDir(), localHost = hostId(), command = run, socketDir } = {}) {
+  const skip = reason => ({ ok: false, quiet: true, reason });
+  const unreachable = reason => ({ ok: false, quiet: false, reason });
+  if (!recipient.startsWith(`${localHost}:`)) return skip("not a local recipient");
   const project = recipient.slice(localHost.length + 1);
   const mapped = read(join(bus, "orch-sessions.txt")).split("\n").find(line => line.split("\t")[0] === project)?.split("\t")[1]?.trim();
   let agents = [];
   try { agents = JSON.parse(command("herdr", ["agent", "list"])).result.agents; } catch { /* #7429: map remains available without herdr. */ }
   const panes = recipientPanes(project, mapped, agents);
-  if (panes.length > 1) return null;
+  if (panes.length > 1) return skip("more than one candidate pane");
   const pane = panes[0];
-  if (["working", "busy"].includes(pane?.agent_status)) return null;
+  if (["working", "busy"].includes(pane?.agent_status)) return skip("busy");
   const sid = pane?.agent_session?.value || mapped;
-  if (!sid || !/^[\w-]+$/.test(sid)) return null;
+  if (!sid || !/^[\w-]+$/.test(sid)) return skip("no session id");
   const rows = processRows(command("ps", ["-axo", "pid=,ppid=,command="]));
   let matches = rows.filter(row => claudeProcess(row.command) && new RegExp(`(?:--session-id|--resume|-r)\\s+${sid}(?:\\s|$)`).test(row.command));
   if (!matches.length && pane) {
@@ -79,36 +102,56 @@ export function resolveRecipient(recipient, { bus = busDir(), localHost = hostId
       const info = JSON.parse(command("herdr", ["pane", "process-info", "--pane", pane.pane_id])).result.process_info;
       const pids = new Set(info.foreground_processes.filter(p => /^(claude|claude.exe)$/.test(p.name)).map(p => p.pid));
       matches = rows.filter(row => pids.has(row.pid) && claudeProcess(row.command));
-    } catch { return null; }
+    } catch { return skip("claude process not found via herdr"); }
   }
-  if (matches.length !== 1) return null;
+  if (matches.length !== 1) return skip(matches.length ? "more than one claude process" : "claude process not found");
   const pid = matches[0].pid;
-  const socketPath = join(socketDir, `${pid}.sock`);
-  if (!existsSync(socketPath)) return null;
-  // #7429: preserve ps's default columns for env; descendants must name this exact socket.
+  // #7429: preserve ps's default columns for env. Only the target's own process tree is read.
+  let socket = ""; let token = "";
   for (const envPid of descendants(pid, rows)) {
-    let token = "";
-    try { token = tokenFromEnvironment(command("ps", ["eww", "-p", String(envPid)]), socketPath); } catch { continue; }
-    if (token) return { pid, sid, token, socketPath, pollStamp: ledgerPaths(recipient, sid, bus).pollStamp };
+    let found;
+    try { found = messagingFromEnvironment(command("ps", ["eww", "-p", String(envPid)])); } catch { continue; }
+    if (found.token && (found.socket || !socket)) { ({ socket, token } = found); if (socket) break; }
   }
-  return null;
+  // #12092: CC 2.1.290 --restricted sessions (and any session with messaging off) never open a socket.
+  if (!token) return unreachable(`no CLAUDE_CODE_MESSAGING_TOKEN in claude pid ${pid}'s environment (--restricted or cross-session messaging off); no socket to nudge`);
+  const dirs = socketDir ? [].concat(socketDir) : fallbackSocketDirs();
+  const tried = [socket, ...dirs.map(dir => join(dir, `${pid}.sock`))].filter(Boolean);
+  const socketPath = tried.find(path => existsSync(path));
+  if (!socketPath) return unreachable(`claude pid ${pid} has a messaging token but no socket exists at ${tried.join(" or ")}`);
+  return { ok: true, target: { pid, sid, token, socketPath, pollStamp: ledgerPaths(recipient, sid, bus).pollStamp } };
 }
 
-export function postNudge({ socketPath, token, sid }, ids, timeoutMs = 1500) {
+export function resolveRecipient(recipient, options = {}) {
+  const verdict = resolveRecipientDetailed(recipient, options);
+  return verdict.ok ? verdict.target : null;
+}
+
+// #12092: the inbox drops a silent connection after 30s, so write both newline-ended lines at once,
+// half-close and time out fast. It never replies here (held/refused go to the sender's own inbox).
+export function postNudgeDetailed({ socketPath, token, sid }, ids, timeoutMs = 1500) {
   const content = `<cross-session-message from="trantor:wake">\nYour Trantor bus inbox has unread message ids ${ids.map(id => `#${id}`).join(", ")}. Read them with relay_inbox and reply over the bus with relay_send. This nudge carries no message content; the signed bus messages are the source of truth.\n</cross-session-message>`;
   const lines = [{ type: "auth", token }, { type: "user", session_id: sid, message: { role: "user", content } }];
   return new Promise(resolve => {
     const socket = createConnection(socketPath);
-    let sent = false;
-    const finish = ok => { socket.destroy(); resolve(ok); };
-    socket.setTimeout(timeoutMs, () => finish(false));
-    socket.on("error", () => finish(false));
+    let sent = false; let settled = false; let failure = "";
+    const finish = (ok, reason) => {
+      if (settled) return;
+      settled = true; clearTimeout(hard); socket.destroy(); resolve({ ok, reason });
+    };
+    const hard = setTimeout(() => finish(false, sent ? "no close from the inbox after the write" : "connect or write timed out"), timeoutMs);
+    hard.unref();
+    socket.on("error", error => { failure = error.code || error.message; finish(false, `socket error ${failure}`); });
     socket.on("connect", () => socket.end(lines.map(line => JSON.stringify(line)).join("\n") + "\n", () => { sent = true; }));
-    socket.on("close", hadError => finish(sent && !hadError));
+    socket.on("close", hadError => finish(sent && !hadError, sent ? "" : "closed before the write finished"));
   });
 }
 
-export async function wakeOnce({ api, bus = busDir(), resolver = recipient => resolveRecipient(recipient, { bus }), verifyMs = 10000, now = Date.now(), attempted = new Set(), cursor = { id: 0, ts: 0 }, log = m => console.error(m) }) {
+export async function postNudge(target, ids, timeoutMs) {
+  return (await postNudgeDetailed(target, ids, timeoutMs)).ok;
+}
+
+export async function wakeOnce({ api, bus = busDir(), resolver = recipient => { const verdict = resolveRecipientDetailed(recipient, { bus }); return verdict.ok ? verdict.target : verdict.quiet ? null : { unreachable: verdict.reason }; }, verifyMs = 10000, now = Date.now(), attempted = new Set(), cursor = { id: 0, ts: 0 }, log = m => console.error(m) }) {
   const feed = await api(`/events?type=message&by=hub%3Aduty&since=${cursor.id}${cursor.id ? "" : "&limit=2000"}`);
   if (Number.isFinite(feed.latest) && feed.latest < cursor.id) {
     cursor.id = 0; cursor.ts = 0;
@@ -121,7 +164,12 @@ export async function wakeOnce({ api, bus = busDir(), resolver = recipient => re
     .map(event => ({ from: event.by, text: event.text, ts: event.ts }));
   const resolved = new Map();
   for (const { recipient } of dutyEscalations(messages)) {
-    if (!resolved.has(recipient)) resolved.set(recipient, resolver(recipient));
+    if (resolved.has(recipient)) continue;
+    const target = resolver(recipient);
+    // #12092: a local idle session with no usable socket is reported, never dropped silently; the
+    // cursor has moved past this alert so it is not retried, and duty's own triage path stays open.
+    if (target?.unreachable) log(`wake-nudge: ${recipient} unreachable: ${target.unreachable}; leaving it to the duty seat`);
+    resolved.set(recipient, target?.unreachable ? null : target);
   }
   const reachable = messages.filter(message => {
     const item = dutyEscalations([message])[0];
@@ -153,7 +201,8 @@ export async function wakeOnce({ api, bus = busDir(), resolver = recipient => re
       const local = resolved.get(target.recipient);
       const before = Number(read(local.pollStamp));
       const postedAt = Date.now();
-      if (!await postNudge(local, target.ids)) return;
+      const post = await postNudgeDetailed(local, target.ids);
+      if (!post.ok) { log(`wake-nudge: ${target.recipient} socket post failed: ${post.reason}`); return; }
       while (Date.now() - postedAt < verifyMs) {
         const stamp = Number(read(local.pollStamp));
         if (stamp > before && stamp >= postedAt) {
@@ -162,6 +211,9 @@ export async function wakeOnce({ api, bus = busDir(), resolver = recipient => re
         }
         await sleep(100);
       }
+      // #12092: written and closed, but the session never polled. The inbox gives no verdict on this
+      // connection, so held (bypassPermissions receiver, crossSessionInbound hold), refused and dropped look alike.
+      log(`wake-nudge: ${target.recipient} posted but not polled within ${verifyMs}ms: held, refused or dropped by the session (no verdict on this socket); duty keeps the triage path`);
     }));
     // #11355: a tick that ends with unverified sends releases their stamps — the ledger must
     // mirror the claim release below, or a failed send would silence the duty path for the TTL.

package/hooks/file-claim.mjs

@@ -9,11 +9,15 @@ import { join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { relayUrl, sessionContext, signedPost } from "./lib/api.mjs";
 import { writeOverseerLevel } from "./lib/overseer-level-cache.mjs";
+import { failOpenAfter } from "./lib/fail-open.mjs";
 import { overlapsFor } from "../lib/remote-overlap.mjs";
 
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_CLAIM_TIMEOUT_MS || 900);
 const RECLAIM_MS = Number(process.env.RELAY_RECLAIM_MS || 60 * 1000);
 
+// 2.1.299: a gating hook that cannot answer in time is refused, which would block the edit.
+failOpenAfter(Number(process.env.RELAY_CLAIM_WATCHDOG_MS || 6000));
+
 const allow = () => { process.stdout.write("{}"); process.exit(0); };
 
 function readStdin() {

package/hooks/file-hold.mjs

@@ -2,6 +2,7 @@
 import { gitCheckoutRoot } from "./lib/git-checkout.mjs";
 import { relative, resolve } from "node:path";
 import { relayUrl, sessionContext, signedPost } from "./lib/api.mjs";
+import { failOpenAfter, readStdinWithin } from "./lib/fail-open.mjs";
 import { readOverseerLevel, writeOverseerLevel } from "./lib/overseer-level-cache.mjs";
 
 function deny(reason) {
@@ -15,9 +16,12 @@ function unavailable() {
   process.stdout.write("{}");
 }
 
+// 2.1.299: a gating hook that cannot answer in time is refused, which would block the edit. The hub
+// call below is capped at 2.5s; this backstop answers "no decision" if anything else hangs.
+failOpenAfter(Number(process.env.RELAY_HOLD_WATCHDOG_MS || 5000));
+
 try {
-  let raw = "";
-  for await (const chunk of process.stdin) raw += chunk;
+  const raw = await readStdinWithin(1000);
   const input = JSON.parse(raw || "{}");
   const path = input.tool_name === "NotebookEdit" ? input.tool_input?.notebook_path : input.tool_input?.file_path;
   const ctx = sessionContext(input.cwd);
@@ -47,3 +51,5 @@ try {
 } catch {
   unavailable();
 }
+// The hook has answered. A host that left stdin open must not keep the process (and a second watchdog answer) alive.
+process.exit(0);

package/hooks/hooks.json

@@ -51,7 +51,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.mjs",
+            "timeout": 10
           }
         ]
       },
@@ -60,7 +61,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/file-claim.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/file-claim.mjs",
+            "timeout": 15
           }
         ]
       },
@@ -69,7 +71,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs",
+            "timeout": 10
           }
         ]
       },
@@ -78,7 +81,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs",
+            "timeout": 10
           }
         ]
       },
@@ -87,7 +91,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/file-hold.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/file-hold.mjs",
+            "timeout": 10
           }
         ]
       }
@@ -98,7 +103,20 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostModelSwitch": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/model-switch.mjs",
+            "timeout": 10
           }
         ]
       }

package/hooks/lib/await-operator.mjs

@@ -6,6 +6,7 @@ import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
 // Transcripts grow to MBs; the final assistant message is at the END at Stop time, so a tail window
 // is enough. 128 KiB covers a long closing reply; anything older is not the turn that just ended.
 const TAIL_BYTES = 128 * 1024;
+const WIDE_TAIL_BYTES = 2 * 1024 * 1024;
 
 /** The verdict zone is the LAST paragraph. A "?" buried mid-reply — a regex like `a?b`, a
  *  rhetorical aside, a question the turn itself went on to answer — is not the session waiting on
@@ -25,25 +26,35 @@ export function lastAssistantText(transcriptPath) {
     if (!transcriptPath || !existsSync(transcriptPath)) return "";
     const size = statSync(transcriptPath).size;
     if (!size) return "";
-    const want = Math.min(size, TAIL_BYTES);
-    const f = openSync(transcriptPath, "r");
-    let tail;
-    try {
-      const buf = Buffer.alloc(want);
-      readSync(f, buf, 0, want, size - want);
-      tail = buf.toString("utf8");
-    } finally { closeSync(f); }
-    const lines = tail.split("\n");
-    if (want < size) lines.shift();   // the window can open mid-line; drop the partial
-    let text = "";
-    for (const line of lines) {
-      let entry;
-      try { entry = JSON.parse(line); } catch { continue; }
-      if (entry?.type !== "assistant") continue;
-      const parts = Array.isArray(entry.message?.content) ? entry.message.content : [];
-      const joined = parts.filter(p => p?.type === "text").map(p => String(p.text ?? "")).join("\n").trim();
-      if (joined) text = joined;
+    // CC 2.1.300 writes each API request's system prompt and tools into the transcript: one such row
+    // can fill the whole 128 KiB window. Only a window that held NO assistant row at all widens (once);
+    // a tool-only final turn still reads as "", never as an older turn's prose.
+    for (const limit of [TAIL_BYTES, WIDE_TAIL_BYTES]) {
+      const want = Math.min(size, limit);
+      const f = openSync(transcriptPath, "r");
+      let tail;
+      try {
+        const buf = Buffer.alloc(want);
+        readSync(f, buf, 0, want, size - want);
+        tail = buf.toString("utf8");
+      } finally { closeSync(f); }
+      const lines = tail.split("\n");
+      if (want < size) lines.shift();   // the window can open mid-line; drop the partial
+      let text = "";
+      let sawAssistant = false;
+      for (const line of lines) {
+        // Only a line naming "assistant" is worth a parse; request rows are huge and never one.
+        if (!line.includes('"assistant"')) continue;
+        let entry;
+        try { entry = JSON.parse(line); } catch { continue; }
+        if (entry?.type !== "assistant") continue;
+        sawAssistant = true;
+        const parts = Array.isArray(entry.message?.content) ? entry.message.content : [];
+        const joined = parts.filter(p => p?.type === "text").map(p => String(p.text ?? "")).join("\n").trim();
+        if (joined) text = joined;
+      }
+      if (sawAssistant || want >= size) return text;
     }
-    return text;
+    return "";
   } catch { return ""; }
 }

package/hooks/lib/cc-signals.mjs

@@ -0,0 +1,42 @@
+// Pure decoders for the cheap signals Claude Code puts in hook and status line JSON, so the hooks
+// stay thin and the field names live in one place (docs/SYSTEM-CONTRACT.md section 9).
+
+const num = (v) => (v !== null && v !== "" && Number.isFinite(Number(v)) ? Number(v) : null);
+
+// Status line `prompt_cache` object (CC 2.1.251+) reduced to what the board shows; null when absent.
+export function promptCacheOf(j) {
+  const p = j?.prompt_cache;
+  if (!p || Array.isArray(p) || !(p instanceof Object)) return null;
+  const cause = p.last_miss_cause?.causes;
+  return {
+    warm: p.warm === true,
+    hitRatio: num(p.hit_ratio),
+    requests: num(p.requests),
+    misses: num(p.misses),
+    ttl: p.ttl === "1h" || p.ttl === "5m" ? p.ttl : null,
+    recacheTokensIfCold: num(p.recache_tokens_if_cold),
+    lastMissCause: Array.isArray(cause) && cause.length ? String(cause[0]).slice(0, 40) : null,
+  };
+}
+
+// One line for a resumed SessionStart (CC 2.1.251+): how stale the session is and what re-caching
+// it costs. Empty string unless this is a resume/fork and the staleness fields are present.
+export function staleResumeLine(input) {
+  if (input?.source !== "resume" && input?.source !== "fork") return "";
+  const secs = num(input.seconds_since_last_response);
+  if (secs === null) return "";
+  const age = secs >= 3600 ? `${(secs / 3600).toFixed(1)}h` : secs >= 60 ? `${Math.round(secs / 60)}m` : `${Math.round(secs)}s`;
+  const usd = num(input.estimated_cache_write_usd);
+  const toks = num(input.context_tokens);
+  const cold = input.prompt_cache_likely_expired === true;
+  const cost = usd !== null ? `, re-caching ${toks !== null ? `${Math.round(toks / 1000)}k tokens ` : ""}costs about $${usd.toFixed(2)}` : "";
+  return `Resumed session is ${age} stale, prompt cache ${cold ? "likely expired" : "probably still warm"}${cost}; a fresh session may be cheaper.`;
+}
+
+// PostModelSwitch input (CC 2.1.251+) to the /register body that tells the hub the session's model
+// right now, instead of waiting for the next heartbeat to read it off the transcript. Null if no model.
+export function modelSwitchRegister(input, { session, project, llm = "claude" }) {
+  const model = String(input?.to_model || "").trim();
+  if (!model) return null;
+  return { session, project, llm, model: model.slice(0, 60) };
+}

package/hooks/lib/fail-open.mjs

@@ -0,0 +1,22 @@
+// CC 2.1.299 refuses an action when its gating hook cannot answer in time, so ours must always
+// answer inside the hooks.json timeout. This backstop prints "no decision" if something hangs past
+// `ms`; the timer is unref'd, so a hook that finishes normally never reaches it.
+export function failOpenAfter(ms, answer = "{}") {
+  const t = setTimeout(() => {
+    try { process.stdout.write(answer); } catch {}
+    process.exit(0);
+  }, ms);
+  t.unref();
+  return t;
+}
+
+// stdin that gives up: a host that never closes the pipe must not hold the hook past its budget.
+export function readStdinWithin(ms) {
+  return new Promise(res => {
+    let d = ""; process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => { d += c; });
+    process.stdin.on("end", () => res(d));
+    process.stdin.on("error", () => res(d));
+    setTimeout(() => res(d), ms).unref();
+  });
+}

package/hooks/lib/handoff.mjs

@@ -41,24 +41,30 @@ export function relayUrl(conf = readConfig()) {
 // Read only the tail of the (potentially huge, append-only) transcript and find
 // the most recent assistant turn's usage. Current context tokens ≈ input +
 // cache_read + cache_creation (the cached prompt IS part of the window).
-export function contextUsage(transcriptPath, conf = readConfig()) {
-  if (!transcriptPath || !existsSync(transcriptPath)) return null;
-  let buf = "";
+
+// CC 2.1.300 also writes each API request's system prompt and tools into the transcript: huge rows
+// with no usage. A long row is parsed only if it names "usage" or the compaction marker.
+const BIG_ROW_BYTES = 64 * 1024;
+const TAIL_BYTES_STEPS = [1_500_000, 6_000_000];   // a tail full of request rows widens once
+
+function tailText(transcriptPath, want) {
+  let fd;
   try {
-    const fd = openSync(transcriptPath, "r");
-    try {
-      const size = fstatSync(fd).size;
-      const tail = Math.min(size, 1_500_000); // last ~1.5MB is plenty for recent turns
-      const b = Buffer.alloc(tail);
-      readSync(fd, b, 0, tail, size - tail);
-      buf = b.toString("utf8");
-    } finally { closeSync(fd); }
-  } catch { return null; }
-
-  const lines = buf.split("\n").filter(Boolean);
+    fd = openSync(transcriptPath, "r");
+    const size = fstatSync(fd).size;
+    const tail = Math.min(size, want);
+    const b = Buffer.alloc(tail);
+    readSync(fd, b, 0, tail, size - tail);
+    return { text: b.toString("utf8"), whole: tail >= size };
+  } catch { return null; } finally { if (fd !== undefined) { try { closeSync(fd); } catch {} } }
+}
+
+function usageRows(text) {
   const rows = [];
   let model = "";
-  for (const line of lines) {
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    if (line.length > BIG_ROW_BYTES && !line.includes("\"usage\"") && !line.includes("compact_boundary")) continue;
     let r; try { r = JSON.parse(line); } catch { continue; }
     if (r?.type === "system" && r?.subtype === "compact_boundary") { rows.push("compact"); continue; }
     const u = r?.message?.usage;
@@ -68,6 +74,19 @@ export function contextUsage(transcriptPath, conf = readConfig()) {
     rows.push(tokens);
     model = r.message.model || model;
   }
+  return { rows, model };
+}
+
+export function contextUsage(transcriptPath, conf = readConfig()) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+  let found = { rows: [], model: "" };
+  for (const want of TAIL_BYTES_STEPS) {
+    const t = tailText(transcriptPath, want);
+    if (!t) return null;
+    found = usageRows(t.text);
+    if (found.rows.length || t.whole) break;
+  }
+  const { rows, model } = found;
   const tokens = guardContextTokens(rows);
   if (tokens == null) return null;
   const window = resolveWindow(model, conf);