trantor 0.18.108 → 0.18.109

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.108",
+  "version": "0.18.109",
   "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/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/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);

package/hooks/model-switch.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// trantor PostModelSwitch hook — Claude Code reports the session's new model (to_model). The
+// heartbeat only learns it from the transcript tail, a minute and a turn late, so this tells the
+// hub right away and the peer row (and anything pricing off it) carries the model that is running.
+// Prints nothing: plain stdout on this event becomes model context. Fail-silent, exits 0.
+import { homedir } from "node:os";
+import { sessionContext, signedPost } from "./lib/api.mjs";
+import { modelSwitchRegister } from "./lib/cc-signals.mjs";
+
+setTimeout(() => process.exit(0), 4000).unref();   // watchdog: never hold up the switch
+
+function readStdin() {
+  return new Promise(res => {
+    let d = ""; process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => { d += c; });
+    process.stdin.on("end", () => res(d));
+    setTimeout(() => res(d), 300);
+  });
+}
+
+try {
+  const input = JSON.parse((await readStdin()) || "{}");
+  const cwd = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // Same rule as heartbeat.mjs: a bare home-directory session is not project work.
+  if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && cwd === homedir()) process.exit(0);
+  const { session, project } = sessionContext(cwd);
+  const llm = process.env.RELAY_LLM || (process.env.RELAY_AGENT ? process.env.RELAY_AGENT.replace(/-orch$/, "") : "claude");
+  const body = modelSwitchRegister(input, { session, project, llm });
+  if (body) {
+    await signedPost("/register", body, { session, timeoutMs: 2500 });
+    process.stderr.write(`[trantor] model switch ${input.from_model || "?"} -> ${body.model} (${input.source || "?"})\n`);
+  }
+} catch (e) {
+  process.stderr.write(`[trantor] model-switch error: ${e?.message || e}\n`);
+}
+process.exit(0);

package/hooks/precompact.mjs

@@ -31,7 +31,13 @@ try {
   // Spawn a fresh session UNLESS the heartbeat early-warning already did so for this
   // window (shared guard). The handoff file is always refreshed above regardless.
   const cur = contextUsage(transcript, conf)?.tokens || 0;
-  if (alreadyHandedOff(sessionId, cur)) {
+  // CC 2.1.299 compacts an idle 200K+ session on its own before the prompt cache expires. The
+  // changelog does not say whether PreCompact fires for it or what `trigger` it carries. Nobody is
+  // at the keyboard then, so only the two known triggers may open a fresh session or a prompt; any
+  // other value keeps the handoff file fresh and stops there.
+  if (trigger !== "auto" && trigger !== "manual") {
+    process.stderr.write(`[trantor] compaction trigger "${trigger}" is not auto/manual (idle compaction?) — handoff refreshed only, no fresh session\n`);
+  } else if (alreadyHandedOff(sessionId, cur)) {
     process.stderr.write(`[trantor] fresh session already spawned for this window — handoff refreshed only\n`);
   } else if (maybeSpawn(projectDir, conf)) {
     markHandedOff(sessionId, cur);

package/hooks/prompt-focus.mjs

@@ -37,6 +37,14 @@ const HARNESS_MARKERS = [
   "<command-name", "<environment_context", "[SYSTEM NOTIFICATION",
 ];
 const isHarnessInjection = (t) => HARNESS_MARKERS.some(m => t.startsWith(m));
+// CC 2.1.299 runs this hook BEFORE a slash command expands, so it sees the raw `/foo args`.
+// A bare command is never a focus; with arguments the focus is the arguments. Anchored on
+// `/name` then whitespace or end, so an absolute path ("/Users/x/y") is not a command.
+const SLASH_COMMAND = /^\/[A-Za-z][\w:.-]*(?:\s+([\s\S]*))?$/;
+function stripSlashCommand(text) {
+  const m = SLASH_COMMAND.exec(text);
+  return m ? (m[1] || "").trim() : text;
+}
 function titleFrom(prompt) {
   let s = String(prompt || "").replace(/\s+/g, " ").trim();
   // strip a leading politeness/imperative wrapper so the card reads as the WORK, not "can you please…"
@@ -80,7 +88,7 @@ try {
   // don't card home-dir sessions (matches sessionstart's phantom-project guard)
   if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && cwd === homedir()) { emitAndExit(); }
   const trimmed = prompt.replace(/\s+/g, " ").trim();
-  const text = unwrapPasted(trimmed);   // a paste's wrapper is transport; judge the words inside
+  const text = stripSlashCommand(unwrapPasted(trimmed));   // a paste's wrapper is transport; a raw /command is not the work
   // skip empties, tiny continuations, and pure acks — they're not a new focus
   if (!text || text.length < 12 || ACK.test(text)) { emitAndExit(); }
   // The Accounts ask drill launches a real Claude session, so its scripted prompt traverses this

package/hooks/sessionstart.mjs

@@ -17,6 +17,7 @@ import { getJSON, signedGet, signedPost, loadIdentity } from "./lib/api.mjs";
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
 import { ensureEnrolled } from "../lib/enroll.mjs";
 import { memoryStartLine } from "./lib/memory-start.mjs";
+import { staleResumeLine } from "./lib/cc-signals.mjs";
 
 // The build doctrine (docs/BUILD-DOCTRINE.md) in short form, one line per rule, injected for every
 // project's ORCHESTRATOR at boot (#6452): orchestrators that never opened the doc missed the ruling.
@@ -294,6 +295,14 @@ try {
     } catch {}
   }
 
+  // Claude Code hands a resume its staleness and re-cache estimate: one line so the model and the
+  // operator can pick resume vs fresh. Nothing when the fields are absent.
+  const staleLine = staleResumeLine(stdinObj);
+  if (staleLine) {
+    additionalContext += `<trantor-resume-staleness>${sanitize(staleLine)}</trantor-resume-staleness>\n`;
+    process.stderr.write(`[trantor] ${staleLine}\n`);
+  }
+
   // CATCH-UP: a project is a DURABLE, continuous lane — not a session. Before doing
   // anything, this session reconciles with the living board: what's been built, what's
   // in flight, what's queued, plus the latest commits. So a fresh window resumes the

package/hooks/statusline.mjs

@@ -6,6 +6,7 @@
 import { readFileSync, writeFileSync, statSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { promptCacheOf } from "./lib/cc-signals.mjs";
 
 const FLOOR_MS = 15_000;
 
@@ -14,11 +15,12 @@ async function main() {
   for await (const c of process.stdin) raw += c;
   const j = JSON.parse(raw);
   const rl = j.rate_limits;
+  const promptCache = promptCacheOf(j);
   // SAFETY: rate_limits is the Claude statusline envelope decoded by JSON.parse above; the check
   // separates "tick carries a rate_limits envelope" (any object, even field-less — it refreshes
   // the stamp below) from "no envelope" (primitives/null — a free exit).
   // oxlint-disable-next-line anti-slop/no-runtime-typeof
-  if (!rl || typeof rl !== "object") return;               // most ticks carry none — free exit
+  if ((!rl || typeof rl !== "object") && !promptCache) return;   // most ticks carry neither — free exit
   const sid = String(j.session_id || j.sessionId || "nosession").replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 80);
   const dir = join(homedir(), ".agent-bus");
   const stamp = join(dir, `usage-claude-${sid}.stamp`);
@@ -27,17 +29,19 @@ async function main() {
 
   const payload = {
     configDir: process.env.CLAUDE_CONFIG_DIR || null,
-    fiveHour: rl.five_hour ?? rl.fiveHour ?? null,
-    sevenDay: rl.seven_day ?? rl.sevenDay ?? null,
+    fiveHour: rl?.five_hour ?? rl?.fiveHour ?? null,
+    sevenDay: rl?.seven_day ?? rl?.sevenDay ?? null,
     // The fable/model-scoped window normally arrives via the OAuth poller, but accept the
     // statusline-shaped variants too — schema drift degrades instead of going dark.
-    fable: rl.fable_weekly ?? rl.fable ?? null,
+    fable: rl?.fable_weekly ?? rl?.fable ?? null,
   };
-  if (!payload.fiveHour && !payload.sevenDay && !payload.fable) return;
+  const hasWindows = !!(payload.fiveHour || payload.sevenDay || payload.fable);
+  if (!hasWindows && !promptCache) return;
+  if (promptCache) payload.promptCache = promptCache;
   // PRIMARY: the local live cache — lib/balances.mjs merges it and skips the OAuth poll while
   // it is fresh (Orca's isLiveClaudeUsageFresh, docs/RESEARCH-orca-usage.md §2). This is the
   // path the app's footer actually reads (it shells the local CLI, not the hub).
-  try { writeFileSync(join(dir, "usage-claude-live.json"), JSON.stringify({ ts: Date.now(), ...payload })); } catch {}
+  if (hasWindows) try { writeFileSync(join(dir, "usage-claude-live.json"), JSON.stringify({ ts: Date.now(), ...payload })); } catch {}
   // SECONDARY, best-effort: the hub copy, for dashboard surfaces that read hub state.
   const { signedPost } = await import("./lib/api.mjs");
   const { hostId } = await import("../lib/project.mjs");

package/hooks/subagent-start.mjs

@@ -5,6 +5,11 @@
 // keyed by agent_id if none exists). Registering both never double-posts. Fail-silent throughout.
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { signedPost } from "./lib/api.mjs";
+import { failOpenAfter } from "./lib/fail-open.mjs";
+
+// PreToolUse (Task|Agent) gates the dispatch: CC 2.1.299 refuses it if this hook cannot answer in time.
+failOpenAfter(Number(process.env.RELAY_SUBAGENT_WATCHDOG_MS || 5000));
+const HUB_TIMEOUT_MS = 3000;
 
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
@@ -29,7 +34,7 @@ try {
         project, enrich: true, agentType, agentId, parent,
         by: `${hostId()}:${project}`,
         source: "cc-subagent", costKind: "subagent-notional", phase: "sub-agents",
-      });
+      }, { timeoutMs: HUB_TIMEOUT_MS });
     }
   } else {
     // CREATE path (PreToolUse Task|Agent) — dispatch time, has the prompt → good title.
@@ -46,7 +51,7 @@ try {
       parent: String(input.session_id || "").slice(0, 120),
       assignee: `${agentType}:${project}`, by: `${hostId()}:${project}`,
       source: "cc-subagent", costKind: "subagent-notional", phase: "sub-agents",
-    });
+    }, { timeoutMs: HUB_TIMEOUT_MS });
   }
 } catch (e) {
   process.stderr.write(`[trantor] subagent-start error: ${e?.message || e}\n`);

package/hub/routes/admin.mjs

@@ -414,7 +414,15 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
         ? { name, usedPct: Math.round(Number(w.used_percentage ?? w.utilization)), resetsAt: w.resets_at ?? null } : null;
       const wins = [["fiveHour", "5h"], ["sevenDay", "7d"], ["fable", "Fable"]]
         .map(([k, n]) => win(b[k], n)).filter(Boolean);
-      if (!wins.length) return json(res, 400, { error: "no usable windows" });
+      // The statusline's prompt_cache stats ride along (or alone) and land on the same Claude entry.
+      const pcIn = b.promptCache;
+      const pcNum = (v) => (Number.isFinite(v) ? v : null);
+      const pc = (pcIn && pcIn instanceof Object && !Array.isArray(pcIn)) ? {
+        warm: pcIn.warm === true, hitRatio: pcNum(pcIn.hitRatio), requests: pcNum(pcIn.requests), misses: pcNum(pcIn.misses),
+        ttl: pcIn.ttl === "1h" || pcIn.ttl === "5m" ? pcIn.ttl : null, recacheTokensIfCold: pcNum(pcIn.recacheTokensIfCold),
+        lastMissCause: pcIn.lastMissCause ? String(pcIn.lastMissCause).slice(0, 40) : null,
+      } : null;
+      if (!wins.length && !pc) return json(res, 400, { error: "no usable windows" });
       const patchSnaps = [(state.balances ||= { ts: 0, by: "", entries: [] })];
       const machine = String(b.machine || "").trim().slice(0, 60);
       if (machine) patchSnaps.push(((state.balancesByMachine ||= {})[machine] ||= { ts: now(), by: "", entries: [], profile: {} }));
@@ -425,12 +433,14 @@ export async function routeAdmin({ req, res, q, P, auth, ctx }) {
       };
       const e = claudeEntry(patchSnaps[patchSnaps.length - 1]);   // dedupe against the most specific copy
       // Same-value posts inside 30s are dropped (the statusline ticks ~3x/sec while streaming).
-      const sig = JSON.stringify(wins);
-      if (e._liveSig === sig && now() - (e.liveTs || 0) < 30_000) return json(res, 200, { ok: true, deduped: true });
+      const sig = JSON.stringify([wins, pc]);
+      if (wins.length && e._liveSig === sig && now() - (e.liveTs || 0) < 30_000) return json(res, 200, { ok: true, deduped: true });
       for (const snap of patchSnaps) {
         const t = claudeEntry(snap);
         for (const w of wins) { const cur = (t.windows ||= []).find(x => x.name === w.name); if (cur) Object.assign(cur, w); else t.windows.push({ ...w }); }
-        t.ok = true; t.liveTs = now(); t._liveSig = sig; t.liveSource = "statusline";
+        // Only live windows stamp liveTs: a cache-only post must not make the OAuth poller skip Claude.
+        if (wins.length) { t.ok = true; t.liveTs = now(); t._liveSig = sig; t.liveSource = "statusline"; }
+        if (pc) t.promptCache = { ...pc, ts: now() };
       }
       markDirty();
       return json(res, 200, { ok: true, windows: wins.length });

package/mods/trantor-band/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "trantor-band",
+  "version": "0.1.0",
+  "description": "Pilot: a line above the Claude Code prompt with live context fill and the project's handoff state, read from Trantor's files. Off unless TRANTOR_MOD=1."
+}

package/mods/trantor-band/hooks/band-lib.mjs

@@ -0,0 +1,72 @@
+// Pure helpers for the trantor-band pilot mod (#12091). No I/O and no Node imports on purpose:
+// the mod runs in Claude Code's sandboxed module environment, and the tests import this file directly.
+
+// The session id comes from Claude Code, but it names a file, so keep it to a safe alphabet.
+export function safeId(id) {
+  return String(id ?? "").replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 120);
+}
+
+// Context fill as a fraction, from $.session.usage().context. Null until the first API response.
+export function contextFraction(context) {
+  const tokens = Number(context?.tokens);
+  const window = Number(context?.window);
+  if (context?.tokens == null || !Number.isFinite(tokens) || !Number.isFinite(window) || window <= 0 || tokens < 0) return null;
+  return Math.min(1, tokens / window);
+}
+
+export function contextPercent(context) {
+  const frac = contextFraction(context);
+  return frac === null ? null : Math.round(frac * 100);
+}
+
+// The file the pilot leaves for Trantor's own code to read later.
+export function contextRecord(context, ts) {
+  const frac = contextFraction(context);
+  if (frac === null) return null;
+  return { ts, tokens: Number(context.tokens), window: Number(context.window), frac: Math.round(frac * 10000) / 10000 };
+}
+
+// The project id a checkout records in .trantor/project.json, mirroring lib/project.mjs readProjectId.
+export function projectFromMarker(text) {
+  try {
+    const id = JSON.parse(text)?.id;
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/.test(String(id ?? "")) && !String(id).includes("..") ? String(id) : "";
+  } catch { return ""; }
+}
+
+export function basename(path) {
+  return String(path ?? "").replace(/\/+$/, "").split("/").pop() || "";
+}
+
+// The newest <project>-<unix seconds>.json among a directory listing, or "" (the name handoff.mjs writes).
+export function newestHandoffName(names, project) {
+  if (!project) return "";
+  const prefix = `${project}-`;
+  let best = "";
+  let bestTs = -1;
+  for (const name of names || []) {
+    if (!name.startsWith(prefix)) continue;
+    const rest = name.slice(prefix.length);
+    if (!/^\d+\.json$/.test(rest)) continue;
+    const ts = Number(rest.slice(0, -5));
+    if (ts > bestTs) { bestTs = ts; best = name; }
+  }
+  return best;
+}
+
+// "pending" (written, nobody has it), "claimed" (a fresh session holds an unexpired claim), or ""
+// when it is consumed or unreadable. Mirrors hooks/lib/handoff-claims.mjs: consumed, claim.expiresAt.
+export function handoffState(text, nowSeconds) {
+  let record;
+  try { record = JSON.parse(text); } catch { return ""; }
+  if (!record || record.consumed) return "";
+  return Number(record.claim?.expiresAt) > nowSeconds ? "claimed" : "pending";
+}
+
+// The band's one line. Parts that are unknown are left out; an empty result means draw nothing.
+export function bandText({ percent, handoff }) {
+  const parts = [];
+  if (Number.isFinite(percent)) parts.push(`ctx ${percent}%`);
+  if (handoff) parts.push(`handoff ${handoff}`);
+  return parts.join(" · ");
+}

package/mods/trantor-band/hooks/hooks.json

@@ -0,0 +1,5 @@
+{
+  "modules": [
+    "./trantor-band.tsx"
+  ]
+}

package/mods/trantor-band/hooks/trantor-band.tsx

@@ -0,0 +1,83 @@
+// Read-only pilot band (#12091): "ctx 34% · handoff pending" above the prompt, OFF unless TRANTOR_MOD=1.
+// It never calls the hub (no auth surface) and any error draws nothing.
+// The one write is ~/.agent-bus/mod-context/<session>.json.
+import type { EngineInterface, Register } from 'claude-code'
+
+import {
+  bandText, basename, contextPercent, contextRecord, handoffState, newestHandoffName, projectFromMarker, safeId,
+} from './band-lib.mjs'
+
+type Snapshot = { percent: number | null; handoff: string; at: number }
+
+const REFRESH_MS = 15_000
+
+// A reload starts these over; they are only a cache of what the files and the engine can say again.
+let snap: Snapshot = { percent: null, handoff: '', at: 0 }
+
+// AGENT_BUS_DIR mirrors hooks/lib/handoff.mjs; HOME is the fallback.
+async function busDir($: EngineInterface): Promise<string> {
+  const override = await $.env.get('AGENT_BUS_DIR')
+  if (override) return override
+  const home = await $.env.get('HOME')
+  return home ? `${home}/.agent-bus` : ''
+}
+
+async function readHandoff($: EngineInterface, bus: string): Promise<string> {
+  const root = await $.session.root()
+  let project = ''
+  try { project = projectFromMarker(await $.fs.read(`${root}/.trantor/project.json`)) } catch {}
+  if (!project) project = basename(root)
+  const dir = `${bus}/handoffs`
+  const entries = await $.fs.list(dir)
+  const name = newestHandoffName(entries.map(entry => entry.name), project)
+  if (!name) return ''
+  return handoffState(await $.fs.read(`${dir}/${name}`), Math.floor((await $.clock.now()) / 1000))
+}
+
+// One refresh: the live context from the native API, the handoff file, and the context JSON.
+async function refresh($: EngineInterface, writeContext: boolean): Promise<void> {
+  try {
+    if ((await $.env.get('TRANTOR_MOD')) !== '1') return
+    const bus = await busDir($)
+    const usage = await $.session.usage()
+    const now = await $.clock.now()
+    let handoff = ''
+    try { if (bus) handoff = await readHandoff($, bus) } catch {}
+    snap = { percent: contextPercent(usage.context), handoff, at: now }
+    if (writeContext && bus) {
+      const record = contextRecord(usage.context, now)
+      const id = safeId(await $.session.id())
+      if (record && id) await $.fs.write(`${bus}/mod-context/${id}.json`, JSON.stringify(record))
+    }
+  } catch {}
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await refresh($, false)
+    return next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    await refresh($, true)
+    try { $.ui.invalidate('ui.render') } catch {}
+    return next(e)
+  })
+
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    try {
+      if ((await $.env.get('TRANTOR_MOD')) !== '1' || e.props.hasSurvey) return next(e)
+      if ((await $.clock.now()) - snap.at > REFRESH_MS) await refresh($, false)
+      const text = bandText(snap)
+      if (!text) return next(e)
+      const { Box, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text dimColor>{text}</Text>
+        </Box>
+      )
+    } catch {
+      return next(e)
+    }
+  })
+}

package/mods/trantor-band/trantor-band.test.ts

@@ -0,0 +1,70 @@
+// The engine's own headless harness for mods: `claude plugin test mods/trantor-band`.
+import { expect, mock, test } from 'claude-code/testing'
+
+// The stand-ins below only need the fields the mod reads; the full engine types are not the point.
+const PROPS: any = {
+  hasSurvey: false,
+  isWorking: false,
+  maxRows: 10,
+  bodyColumns: 80,
+  scroll: { offset: 0, bodyRows: 10 },
+  view: {},
+}
+
+const USAGE: any = {
+  startedAt: 0,
+  context: { tokens: 34_000, window: 100_000, percent: 34 },
+  rateLimits: [],
+}
+
+const FILES: any = [
+  { name: 'demo-100.json', kind: 'file', size: 1, mtimeMs: 0, isLink: false },
+  { name: 'demo-200.json', kind: 'file', size: 1, mtimeMs: 0, isLink: false },
+]
+
+// What the engine would draw there when the mod passes: a plain Text.
+const engineBand = ($: any, e: any): any => {
+  const { Text } = $.ui.resolve(e)
+  return h(Text, null, 'engine band')
+}
+
+const mountBand = ($: any): Promise<any> =>
+  $.ui.mount({ plugin: 'trantor', surface: 'terminal', component: 'AbovePrompt', props: PROPS })
+
+test('the band passes through to the engine band while TRANTOR_MOD is unset', async ($, on) => {
+  mock.env(on, {})
+  on('session.usage', () => ({ value: USAGE }))
+  on('ui.render', engineBand)
+  const ui = await mountBand($)
+  expect((await ui.find({ type: 'Text' }))?.text).toBe('engine band')
+  await ui.unmount()
+})
+
+test('the band shows the live context fill when TRANTOR_MOD=1', async ($, on) => {
+  mock.env(on, { TRANTOR_MOD: '1', HOME: '/h' })
+  mock.clock(on, { now: 1_000_000 })
+  on('session.usage', () => ({ value: USAGE }))
+  on('session.root', () => ({ value: '/work/demo' }))
+  on('fs.read', () => ({ deny: 'ENOENT' }))
+  on('fs.list', () => ({ deny: 'ENOENT' }))
+  on('ui.render', engineBand)
+  const ui = await mountBand($)
+  expect((await ui.find({ type: 'Text', text: /ctx 34%/ }))?.text).toContain('ctx 34%')
+  await ui.unmount()
+})
+
+test('the band names the newest unconsumed handoff of the project', async ($, on) => {
+  mock.env(on, { TRANTOR_MOD: '1', HOME: '/h' })
+  mock.clock(on, { now: 1_000_000 })
+  on('session.usage', () => ({ value: USAGE }))
+  on('session.root', () => ({ value: '/work/demo' }))
+  on('fs.list', () => ({ value: FILES }))
+  on('fs.read', (_$: any, e: any) => {
+    if (e.path.endsWith('project.json')) return { deny: 'ENOENT' }
+    return { value: e.path.endsWith('demo-200.json') ? '{"consumed":false}' : '{"consumed":true}' }
+  })
+  on('ui.render', engineBand)
+  const ui = await mountBand($)
+  expect((await ui.find({ type: 'Text', text: /handoff/ }))?.text).toContain('ctx 34% · handoff pending')
+  await ui.unmount()
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.108",
+  "version": "0.18.109",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -22,6 +22,7 @@
     "ui.html",
     "bin/",
     "hooks/",
+    "mods/",
     "lib/",
     "skills/",
     "deploy/",