trantor 0.18.15 → 0.18.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.15",
+  "version": "0.18.17",
   "description": "Trantor \u2014 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/adopt.mjs

@@ -15,7 +15,7 @@ import { readdirSync, statSync, existsSync, readFileSync, writeFileSync, mkdirSy
 import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-import { resolveProject } from "../lib/project.mjs";
+import { resolveProject, writeOrchSession } from "../lib/project.mjs";
 
 const D = "\x1b[2m", B = "\x1b[1m", Y = "\x1b[33m", G = "\x1b[32m", R = "\x1b[0m";
 const args = process.argv.slice(2);
@@ -74,14 +74,10 @@ if (candidates.length > 1) {
   console.log(`${D}the newest is assumed to be yours; pick another with --session <id>${R}`);
 }
 
-// Record it where `trantor open` looks. Same file, same format the orchestrator pane already uses,
-// so adopting and opening fresh converge on one mechanism rather than two.
-const busDir = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
-const store = join(busDir, "orch-sessions.txt");
-mkdirSync(dirname(store), { recursive: true });
-const rows = existsSync(store) ? readFileSync(store, "utf8").split("\n").filter(Boolean) : [];
-const kept = rows.filter(r => r.split("\t")[0] !== project);
-writeFileSync(store, [...kept, `${project}\t${chosen}`].join("\n") + "\n");
+// Record it where `trantor open` looks. One choke point for the map (writeOrchSession) so every
+// rewrite is attributable in orch-sessions.log — adopt is one of the map's three writers
+// (SYSTEM-CONTRACT §4), and until 2026-08-30 it wrote the file by hand, invisibly.
+writeOrchSession(project, chosen, "adopt");
 console.log(`\n${G}recorded${R} ${chosen} as ${project}'s orchestrator session`);
 
 // Two live claudes on one transcript is the one thing that must not happen: they would interleave

package/bin/autonomy.mjs

@@ -18,7 +18,7 @@ function projectFlag() {
 }
 
 const BOOLS = ["commit", "push", "deploy", "swapDeadSeat", "retryFailedTurn"];
-const ENUMS = { harness: ["prompt", "bypass"] };
+const ENUMS = { harness: ["prompt", "bypass"], baton: ["ask", "auto"] };
 
 if (cmd === "get") {
   // Machine-readable, one value, no decoration — crew.sh reads this.

package/bin/cli.mjs

@@ -74,6 +74,7 @@ switch (cmd) {
   case "handoff": run("bin/baton.mjs"); break;
   case "adopt": run("bin/adopt.mjs"); break;
   case "takeover": run("bin/takeover.mjs"); break;
+  case "drill": run("bin/drill-surface.mjs"); break;
   case "summarize": run("bin/summarize.mjs"); break;
   case "policy": run("bin/policy.mjs"); break;
   case "proposals": case "proposal": run("bin/proposals.mjs"); break;

package/bin/drill-surface.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// `trantor drill` — the §7 end-to-end SEAM drill (SYSTEM-CONTRACT.md; Phase 5 of the reassembly).
+//
+// Unit suites passing while the seams fail is this project's most-repeated lesson. This drill
+// runs the REAL components against each other on a throwaway project: a real herdr workspace,
+// a real Claude session, the real socket transport the app uses, the real hooks, the real
+// handoff machine — and asserts on evidence (transcript rows, herdr state, ledger files),
+// never on exit codes alone.
+//
+// It is the ship gate for desktop/chat/handoff/crew changes: run it before every such release;
+// a red drill does not ship. (There is no scripted release path to wire it into — the release
+// dance is manual — so the gate is this command plus the contract that mandates it.)
+//
+// Flags: --keep  leave the scratch world in place for inspection (prints paths).
+
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { execFileSync, execSync } from "node:child_process";
+import { createConnection } from "node:net";
+
+const KEEP = process.argv.includes("--keep");
+const G = "\x1b[32m", Rd = "\x1b[31m", Y = "\x1b[33m", D = "\x1b[2m", R = "\x1b[0m";
+let pass = 0, fail = 0, skip = 0;
+const PASS = (s, ev = "") => { pass++; console.log(`  ${G}PASS${R}  ${s}${ev ? `  ${D}${ev}${R}` : ""}`); };
+const FAIL = (s, ev = "") => { fail++; console.log(`  ${Rd}FAIL${R}  ${s}${ev ? `  ${D}${ev}${R}` : ""}`); };
+const SKIP = (s, why) => { skip++; console.log(`  ${Y}SKIP${R}  ${s}  ${D}${why}${R}`); };
+const step = (n) => console.log(`\n${n}`);
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+function herdr(args, { json = true } = {}) {
+  const out = execFileSync("herdr", args, { encoding: "utf8", timeout: 90_000 });
+  return json ? JSON.parse(out) : out;
+}
+
+/** One request over herdr's socket — byte-identical to the app's transport (herdr.rs). */
+function socketRequest(req, timeoutMs = 90_000) {
+  const sockPath = join(homedir(), ".config", "herdr", "herdr.sock");
+  return new Promise((resolve, reject) => {
+    const s = createConnection(sockPath);
+    const t = setTimeout(() => { s.destroy(); reject(new Error("socket timeout")); }, timeoutMs);
+    let buf = "";
+    s.on("connect", () => s.write(JSON.stringify(req) + "\n"));
+    s.on("data", (d) => {
+      buf += d.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl >= 0) { clearTimeout(t); s.destroy(); resolve(buf.slice(0, nl)); }
+    });
+    s.on("error", (e) => { clearTimeout(t); reject(e); });
+  });
+}
+
+async function waitFor(desc, fn, { timeoutMs = 60_000, everyMs = 1_000 } = {}) {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    const v = await fn();
+    if (v) return v;
+    await sleep(everyMs);
+  }
+  return null;
+}
+
+function transcriptDirFor(projDir) {
+  return join(homedir(), ".claude", "projects", String(projDir).replace(/[/.]/g, "-"));
+}
+function newestJsonl(dir) {
+  try {
+    return readdirSync(dir).filter(f => f.endsWith(".jsonl"))
+      .map(f => ({ f: join(dir, f), m: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.m - a.m)[0]?.f || null;
+  } catch { return null; }
+}
+function userTurnsContaining(file, needle) {
+  const hits = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line) continue;
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    if (r?.type !== "user") continue;
+    const c = r.message?.content;
+    const t = typeof c === "string" ? c
+      : Array.isArray(c) ? c.map(b => (b && typeof b === "object" && b.type === "text") ? b.text : "").join(" ") : "";
+    if (t.includes(needle)) hits.push(t);
+  }
+  return hits;
+}
+function assistantSaid(file, needle) {
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line) continue;
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    if (r?.type !== "assistant") continue;
+    for (const b of r.message?.content || []) {
+      if (b && b.type === "text" && String(b.text).includes(needle)) return true;
+    }
+  }
+  return false;
+}
+
+
+/** Start a Claude agent in a pane, answering the folder-trust dialog if it blocks startup
+ *  (the P0b recovery: agent_not_ready keeps the name live; one enter accepts the fresh dir). */
+async function startClaude(name, paneId) {
+  let blocked = false;
+  try {
+    const r = herdr(["agent", "start", name, "--kind", "claude", "--pane", paneId]);
+    if (r.result?.agent?.agent_status === "idle") return "idle";
+    blocked = true;
+  } catch { blocked = true; }
+  if (blocked) {
+    await sleep(1500);
+    try { herdr(["agent", "send-keys", name, "enter"]); } catch {}
+    const settled = await waitFor("startup dialog answered", () => {
+      try {
+        const g = herdr(["agent", "get", name]);
+        const st = g.result?.agent?.agent_status;
+        return st === "idle" ? st : null;
+      } catch { return null; }
+    }, { timeoutMs: 45_000, everyMs: 2_000 });
+    return settled || "not-ready";
+  }
+  return "not-ready";
+}
+
+// ---------- S0 · version skew ----------
+step("S0 · version skew (hooks vs CLI vs app)");
+{
+  const cli = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")).version;
+  let plugin = "?";
+  try {
+    // The plugin cache keeps one directory per version; the newest is what sessions load.
+    const cache = join(homedir(), ".claude", "plugins", "cache", "trantor", "trantor");
+    plugin = readdirSync(cache).filter(v => /^\d+\.\d+\.\d+$/.test(v))
+      .sort((a, b) => { const A = a.split(".").map(Number), B = b.split(".").map(Number); return (A[0]-B[0]) || (A[1]-B[1]) || (A[2]-B[2]); })
+      .pop() || "?";
+  } catch {}
+  let app = "?";
+  try { app = execSync('plutil -extract CFBundleShortVersionString raw "/Applications/Trantor.app/Contents/Info.plist"', { encoding: "utf8" }).trim(); } catch {}
+  console.log(`  ${D}cli ${cli} · plugin ${plugin} · app ${app}${R}`);
+  if (plugin === "?") {
+    console.log(`  ${Y}WARN${R}  plugin hook version unreadable — cannot rule out skew`);
+  } else if (plugin !== cli) {
+    console.log(`  ${Y}WARN${R}  installed plugin hooks (${plugin}) differ from this tree (${cli}) — running sessions use the PLUGIN's hooks`);
+  } else {
+    PASS("no hook/CLI version skew", `${cli}`);
+  }
+  globalThis.__skew = plugin !== "?" && plugin !== cli;
+}
+
+// ---------- world ----------
+// NOT tmpdir(): macOS tmp is a /var symlink and Claude records the /private/var realpath,
+// so the transcript-slug lookup would miss. A dot-dir under $HOME has no such alias.
+const world = join(homedir(), `.tt-drill-${process.pid}`);
+const proj = join(world, "drill-proj");
+const bus = join(world, "bus");
+mkdirSync(proj, { recursive: true });
+mkdirSync(join(bus, "handoffs"), { recursive: true });
+execFileSync("git", ["init", "-q"], { cwd: proj });
+// The drill's handoff phase exercises the AUTO chain deliberately; the shipped default is ask.
+writeFileSync(join(bus, "autonomy.json"), JSON.stringify({ version: 1, defaults: { baton: "auto" }, projects: {} }));
+const projectName = basename(proj);
+const tDir = transcriptDirFor(proj);
+
+let ws = null, pane = null;
+const cleanup = () => {
+  if (KEEP) { console.log(`\n${D}--keep: world at ${world} · workspace ${ws?.workspace_id || "?"} left open${R}`); return; }
+  try { if (pane) herdr(["agent", "prompt", pane, "/exit"], { json: true }); } catch {}
+  try { if (ws) herdr(["workspace", "close", ws.workspace_id], { json: true }); } catch {}
+  try { rmSync(world, { recursive: true, force: true }); } catch {}
+};
+process.on("exit", cleanup);
+
+// ---------- S1 · cold start ----------
+step("S1 · cold start: workspace, clean env, agent, transcript EXISTS");
+try {
+  const created = herdr(["workspace", "create", "--cwd", proj, "--label", "tt-drill"]);
+  ws = { workspace_id: created.result.workspace.workspace_id };
+  pane = created.result.root_pane.pane_id;
+  PASS("throwaway herdr workspace", `${ws.workspace_id} pane ${pane}`);
+  // The P0b trap, prevented at the source: a pane inheriting CLAUDE_CODE_CHILD_SESSION runs
+  // Claude with transcript saving OFF — an invisible session. Every spawn path must clear it.
+  herdr(["pane", "run", pane,
+    `unset CLAUDE_CODE_CHILD_SESSION; export AGENT_BUS_DIR=${bus} RELAY_URL=http://127.0.0.1:1 ` +
+    `TRANTOR_NO_SCROOGE=1 TRANTOR_NO_HANDOFF_SPAWN=1 TRANTOR_NO_BALANCE_CHECK=1 ` +
+    `RELAY_CONTEXT_WARN_FRAC=0.000001 RELAY_STOP_TIMEOUT_MS=300 RELAY_CONTEXT_WINDOW=1000000; echo ENV-READY`], { json: false });
+  await sleep(1500);
+  const st = await startClaude("drill", pane);
+  if (st === "idle") PASS("claude starts and settles idle (trust dialog auto-answered if shown)");
+  else FAIL("claude starts and settles idle", String(st));
+} catch (e) {
+  FAIL("S1 world setup", String(e.message || e).slice(0, 160));
+  console.log(`\n${Rd}cannot continue without S1${R}`);
+  process.exit(1);
+}
+
+// ---------- S2 · transport ----------
+step("S2 · transport: whole multiline message through the app's exact socket call");
+const MARK = `drill-${Date.now() % 100000}`;
+{
+  const text = `-leading dash line for ${MARK}.\nSecond line with /tmp/fake.png mid-sentence.\nReply with exactly ${MARK}-OK and nothing else.`;
+  const raw = await socketRequest({ id: "trantor:agent.prompt", method: "agent.prompt", params: { target: pane, text } });
+  const resp = JSON.parse(raw);
+  if (resp.result?.type === "agent_prompted") PASS("agent.prompt accepted (no keystrokes involved)");
+  else FAIL("agent.prompt accepted", raw.slice(0, 120));
+
+  const tfile = await waitFor("transcript exists", () => newestJsonl(tDir), { timeoutMs: 10_000, everyMs: 500 });
+  if (tfile) PASS("transcript EXISTS within seconds (CLAUDE_CODE_CHILD_SESSION trap absent)", basename(tfile));
+  else FAIL("transcript EXISTS within seconds — invisible-session trap?");
+
+  if (tfile) {
+    const replied = await waitFor("reply", () => assistantSaid(tfile, `${MARK}-OK`) || null, { timeoutMs: 120_000, everyMs: 2_000 });
+    const turns = userTurnsContaining(tfile, MARK);
+    if (turns.length === 1 && turns[0].includes("\n") && turns[0].startsWith("-leading"))
+      PASS("ONE user turn, newlines intact, dash-leading text unmangled");
+    else FAIL("ONE whole user turn", `turns=${turns.length}`);
+    if (replied) PASS("the reply came back");
+    else FAIL("the reply came back");
+  }
+}
+
+// ---------- S3 · identity ----------
+step("S3 · identity: the pane itself names the session (Phase 2)");
+let predecessorSid = null;
+{
+  const got = herdr(["agent", "get", "drill"]);
+  const as = got.result?.agent?.agent_session;
+  const tfile = newestJsonl(tDir);
+  predecessorSid = as?.kind === "id" ? as.value : null;
+  if (predecessorSid && tfile && basename(tfile) === `${predecessorSid}.jsonl`)
+    PASS("pane report matches the live transcript", predecessorSid.slice(0, 8));
+  else if (!as) FAIL("pane reports its session — is the herdr claude integration installed?");
+  else FAIL("pane report matches the live transcript", `${as?.value?.slice(0, 8)} vs ${tfile && basename(tfile).slice(0, 8)}`);
+}
+
+// ---------- S4 · the handoff machine ----------
+step("S4 · handoff machine: warn → arm → fire → WRITTEN → successor claims → RECAPPED");
+{
+  // A turn that uses a tool: the heartbeat is PostToolUse, so only tool use can arm the baton.
+  // The heartbeat is PostToolUse: only a REAL tool call can arm the baton. Models sometimes
+  // answer without the tool (observed: run 2 of 3 on 2026-08-30 — 1-in-3 prompt fragility,
+  // not a seam), so ask, verify tool use in the transcript, and re-ask up to twice.
+  const findHandoff = () => {
+    try {
+      const f = readdirSync(join(bus, "handoffs")).find(x => x.startsWith(`${projectName}-`) && x.endsWith(".json"));
+      return f ? join(bus, "handoffs", f) : null;
+    } catch { return null; }
+  };
+  let handoffFile = null;
+  for (let attempt = 1; attempt <= 3 && !handoffFile; attempt++) {
+    const raw = await socketRequest({ id: "trantor:agent.prompt", method: "agent.prompt", params: {
+      target: pane, text: `You MUST call the Bash tool now and run exactly: pwd — do not answer without calling it. Then reply with just DONE-S4-${attempt}.` } });
+    if (JSON.parse(raw).result?.type !== "agent_prompted") { FAIL("S4 prompt accepted", raw.slice(0, 100)); break; }
+    handoffFile = await waitFor("handoff written", findHandoff, { timeoutMs: 120_000, everyMs: 2_000 });
+    if (!handoffFile) console.log(`  ${D}attempt ${attempt}: no handoff yet — re-asking with the tool requirement${R}`);
+  }
+  if (!handoffFile) {
+    FAIL("the armed baton fired and WROTE a handoff at the turn boundary");
+  } else {
+    const rec = JSON.parse(readFileSync(handoffFile, "utf8"));
+    const states = (rec.states || []).map(s => s.state);
+    if (states[0] === "written") PASS("§5 ledger opens with WRITTEN", `${basename(handoffFile)}`);
+    else FAIL("§5 ledger opens with WRITTEN", states.join(","));
+
+    // Successor: end the predecessor, start fresh in the SAME pane — the claim is sessionstart's.
+    try { herdr(["agent", "prompt", "drill", "/exit"]); } catch {}
+    await sleep(4000);
+    const st2 = await startClaude("drill2", pane);
+    if (st2 !== "idle") FAIL("successor claude starts", String(st2));
+    const claimed = await waitFor("claimed on ledger", () => {
+      try {
+        const r = JSON.parse(readFileSync(handoffFile, "utf8"));
+        return (r.states || []).some(s => s.state === "claimed") ? r : null;
+      } catch { return null; }
+    }, { timeoutMs: 60_000, everyMs: 2_000 });
+    if (claimed) PASS("successor CLAIMED it (sessionstart, on the ledger)", `by ${claimed.states.find(s => s.state === "claimed")?.by?.slice(0, 8)}`);
+    else FAIL("successor CLAIMED it");
+
+    const stamp = () => {
+      try { return readdirSync(join(bus, "handoffs")).find(f => f.startsWith("recap-pending-")); } catch { return null; }
+    };
+    if (stamp()) PASS("recap net armed (pending stamp exists)");
+    else FAIL("recap net armed (pending stamp exists)");
+
+    const raw2 = await socketRequest({ id: "trantor:agent.prompt", method: "agent.prompt", params: {
+      target: pane, text: "Say only: ACK-S4" } });
+    if (JSON.parse(raw2).result?.type !== "agent_prompted") FAIL("successor prompt accepted", raw2.slice(0, 100));
+    const recapped = await waitFor("recapped", () => {
+      try {
+        const r = JSON.parse(readFileSync(handoffFile, "utf8"));
+        return (r.states || []).some(s => s.state === "recapped") && !stamp() ? r : null;
+      } catch { return null; }
+    }, { timeoutMs: 120_000, everyMs: 2_000 });
+    if (recapped) PASS("first Stop recorded RECAPPED and cleared the net", recapped.states.map(s => s.state).join("→"));
+    else FAIL("first Stop recorded RECAPPED and cleared the net", stamp() ? "stamp still present" : "no recapped state");
+  }
+}
+
+if (globalThis.__skew && fail > 0) {
+  console.log(`  ${Y}NOTE${R}  S4 runs the INSTALLED plugin's hooks — with the skew above, ledger/recap failures are expected until the newer CLI is published and \`claude plugin update trantor@trantor\` runs.`);
+}
+
+// ---------- S5 · takeover ----------
+step("S5 · takeover from a Terminal session");
+SKIP("takeover chain", "needs an interactive Terminal-window session; proven live 2026-08-28 (0.18.13 drill) — automate in drill v2");
+
+// ---------- verdict ----------
+console.log(`\n${fail === 0 ? G + "DRILL GREEN" : Rd + "DRILL RED"}${R} — ${pass} passed, ${fail} failed, ${skip} skipped`);
+process.exit(fail === 0 ? 0 : 1);

package/hooks/heartbeat.mjs

@@ -96,6 +96,15 @@ async function maybeEarlyWarn(stdinRaw, session) {
     };
 
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    // The baton dial (#5509 W2, SYSTEM-CONTRACT §5): "ask" (default) means the OPERATOR fires
+    // handoffs — the app's banner asks at this same threshold, and this hook neither arms nor
+    // auto-fires. "auto" restores the arm-here → fire-at-Stop chain below. PreCompact remains
+    // the at-the-wall backstop in both modes.
+    const { resolveAutonomy } = await import("../lib/autonomy.mjs");
+    if (resolveAutonomy(resolveProject(projectDir)).baton !== "auto") {
+      process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% — baton dial is 'ask': the banner offers, nothing auto-fires\n`);
+      return;
+    }
     // Detect THIS session's Terminal window NOW (the hook has the controlling tty; the detached worker
     // won't) so the baton-close can replace this exact window once the fresh session takes over.
     const tty = controllingTty();

package/hooks/lib/handoff.mjs

@@ -53,18 +53,45 @@ export function contextUsage(transcriptPath, conf = readConfig()) {
   } catch { return null; }
 
   const lines = buf.split("\n").filter(Boolean);
-  for (let i = lines.length - 1; i >= 0; i--) {
-    let r; try { r = JSON.parse(lines[i]); } catch { continue; }
+  const rows = [];
+  let model = "";
+  for (const line of lines) {
+    let r; try { r = JSON.parse(line); } catch { continue; }
     const u = r?.message?.usage;
-    if (r?.type === "assistant" && u) {
-      const tokens = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
-      if (tokens <= 0) continue;
-      const model = r.message.model || "";
-      const window = resolveWindow(model, conf);
-      return { tokens, window, frac: window ? tokens / window : null, model };
-    }
+    if (r?.type !== "assistant" || !u) continue;
+    const tokens = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+    if (tokens <= 0) continue;
+    rows.push(tokens);
+    model = r.message.model || model;
   }
-  return null;
+  const tokens = guardContextTokens(rows);
+  if (tokens == null) return null;
+  const window = resolveWindow(model, conf);
+  return { tokens, window, frac: window ? tokens / window : null, model };
+}
+
+// The #5572 poison guard — the SAME rule, from the SAME fixture manifest
+// (test/fixtures/context/manifest.json), as the desktop gauge's ContextGuard: the baton must
+// read what the gauge reads, or the banner and the heartbeat disagree. Report the last row
+// unless it falls below 40% of the session max; then report the recent maximum (a lone
+// collapsed row is an artifact — across 1,839 usage rows in the two incident-era transcripts,
+// zero real drops below that floor were observed) unless the last FIVE rows all sit below the
+// floor: a sustained new level is reality, accept it.
+export function guardContextTokens(rows) {
+  let max = 0;
+  const recent = [];
+  for (const t of rows) {
+    if (!t || t <= 0) continue;
+    recent.push(t);
+    if (recent.length > 5) recent.shift();
+    if (t > max) max = t;
+  }
+  if (!recent.length) return null;
+  const last = recent[recent.length - 1];
+  const floor = max * 0.4;
+  if (last >= floor) return last;
+  if (recent.length === 5 && recent.every(r => r < floor)) return last;
+  return Math.max(...recent);
 }
 
 // The transcript logs the model WITHOUT the [1m] marker, so we cannot tell a
@@ -281,6 +308,20 @@ export function verbatimRecentTail(transcript, chars = 7000) {
 }
 
 // ---- write + announce + spawn ----------------------------------------------
+/** Append one §5 state transition to a handoff's own file — the machine's ledger rides the
+ *  record it describes (SYSTEM-CONTRACT §5): every owner of a transition already holds this
+ *  file, it survives both sessions it connects, and no network is involved. Best-effort. */
+export function appendHandoffState(id, state, by = "") {
+  try {
+    const p = join(HANDOFF_DIR, `${id}.json`);
+    const rec = JSON.parse(readFileSync(p, "utf8"));
+    if (!Array.isArray(rec.states)) rec.states = [];
+    rec.states.push({ state, ts: nowSec() || Math.floor(Date.now() / 1000), by });
+    writeFileSync(p, JSON.stringify(rec, null, 2));
+    return true;
+  } catch { return false; }
+}
+
 export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary, force = false }) {
   const projectName = basename(projectDir);
   // Server-side storm guard: a session running OLD hooks (before the local markHandedOff guard) re-fires
@@ -325,6 +366,8 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     // narrative + a verbatim recent-exchange block so exact in-flight state always survives
     summary: narrative + (tail ? `\n\n---\n## Verbatim recent exchange (exact in-flight state — continue from here)\n${tail}` : ""),
     gitStatus, subagents, verifyGates, consumed: false,
+    // The §5 machine's ledger: every transition appends here via appendHandoffState.
+    states: [{ state: "written", ts: Number(stamp) || 0, by: sessionId || "" }],
   };
   const file = join(HANDOFF_DIR, `${record.id}.json`);
   writeFileSync(file, JSON.stringify(record, null, 2));

package/hooks/prompt-focus.mjs

@@ -29,21 +29,46 @@ function titleFrom(prompt) {
   return s.slice(0, 120);
 }
 
+
+// §5 recap net (SYSTEM-CONTRACT): while this session carries a claimed-but-unrecapped handoff
+// (the recap-pending stamp sessionstart wrote), EVERY prompt before its first Stop carries the
+// reminder — including the stale queued message that ate the 2026-08-30 takeover. The stamp is
+// cleared (and RECAPPED recorded) by stop-inbox at the first turn boundary.
+import { handoffDir } from "../lib/project.mjs";
+import { existsSync as _ex, readFileSync as _rf } from "node:fs";
+let RECAP_CTX = "";
+function loadRecapCtx(sessionId) {
+  try {
+    if (!sessionId) return "";
+    const p = join(handoffDir(), `recap-pending-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "_")}.json`);
+    if (!_ex(p)) return "";
+    const rec = JSON.parse(_rf(p, "utf8"));
+    return `<system-reminder>You took over via handoff ${rec.handoffId}. If you have not yet recapped it, your reply MUST begin with the ≤3-sentence recap (task, state, next step) before anything else — including before answering this message.</system-reminder>`;
+  } catch { return ""; }
+}
+function emitAndExit() {
+  process.stdout.write(RECAP_CTX
+    ? JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: RECAP_CTX } })
+    : "{}");
+  process.exit(0);
+}
+
 try {
-  if (process.env.TRANTOR_NO_FOCUS === "1") { process.stdout.write("{}"); process.exit(0); }   // opt-out
+  if (process.env.TRANTOR_NO_FOCUS === "1") { emitAndExit(); }   // opt-out
   const input = JSON.parse((await readStdin()) || "{}");
+  RECAP_CTX = loadRecapCtx(String(input.session_id || ""));
   const prompt = String(input.prompt || "");
   const cwd = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // don't card home-dir sessions (matches sessionstart's phantom-project guard)
-  if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && cwd === homedir()) { process.stdout.write("{}"); process.exit(0); }
+  if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && cwd === homedir()) { emitAndExit(); }
   const trimmed = prompt.replace(/\s+/g, " ").trim();
   // skip empties, tiny continuations, and pure acks — they're not a new focus
-  if (!trimmed || trimmed.length < 12 || ACK.test(trimmed)) { process.stdout.write("{}"); process.exit(0); }
+  if (!trimmed || trimmed.length < 12 || ACK.test(trimmed)) { emitAndExit(); }
   // HARNESS-INJECTED prompts are not a human's focus. Task notifications, hook system-reminders and
   // protocol frames arrive through the same UserPromptSubmit channel, and carding one titled a board
   // card "<task-notification> <task-id>bavlqfmzq</task-id>…" — pure noise a human cannot read.
   if (/^\s*[<{[]/.test(trimmed) || /<task-notification>|<system-reminder>|<teammate-message/i.test(trimmed)) {
-    process.stdout.write("{}"); process.exit(0);
+    emitAndExit();
   }
   const project = resolveProject(cwd);
   const session = process.env.RELAY_SESSION
@@ -74,5 +99,4 @@ try {
 } catch (e) {
   process.stderr.write(`[trantor] prompt-focus error: ${e?.message || e}\n`);
 }
-process.stdout.write("{}");
-process.exit(0);
+emitAndExit();

package/hooks/sessionstart.mjs

@@ -57,7 +57,20 @@ function loadPendingHandoff(projectName, { claim = true, freshSession = null } =
               transcript_path: freshSession.transcript_path || "",
             };
           }
+          // §5 CLAIMED, on the machine's ledger (SYSTEM-CONTRACT), and the recap net armed:
+          // a recap-pending stamp names this successor. Every prompt before its first Stop
+          // carries a recap reminder (prompt-focus), and the first Stop marks RECAPPED —
+          // the 2026-08-30 failure (successor answered a stale queued message, never
+          // recapped) becomes mechanically impossible instead of hopefully avoided.
+          if (!Array.isArray(rec.states)) rec.states = [];
+          rec.states.push({ state: "claimed", ts: nowSec(), by: freshSession?.session_id || "" });
           writeFileSync(p, JSON.stringify(rec, null, 2));
+          if (freshSession?.session_id) {
+            try {
+              writeFileSync(join(dir, `recap-pending-${String(freshSession.session_id).replace(/[^A-Za-z0-9_.-]/g, "_")}.json`),
+                JSON.stringify({ handoffId: rec.id, ts: nowSec() }));
+            } catch {}
+          }
         }
         return rec;
       }
@@ -425,8 +438,8 @@ try {
   // thread, so the map `trantor open` resumes and the app's chat reads moves with it. The pane
   // also records itself on every fresh start — that keeps the map honest even if a future
   // claude forks the session id on resume.
-  if (claimed && orchOrigin && stdinObj.session_id) writeOrchSession(project, String(stdinObj.session_id));
-  if (isOrchPane && !isCompact && stdinObj.session_id) writeOrchSession(project, String(stdinObj.session_id));
+  if (claimed && orchOrigin && stdinObj.session_id) writeOrchSession(project, String(stdinObj.session_id), "sessionstart-claim");
+  if (isOrchPane && !isCompact && stdinObj.session_id) writeOrchSession(project, String(stdinObj.session_id), "orch-pane-start");
   if (handoff && held) {
     process.stderr.write(`[trantor] pending handoff ${handoff.id} HELD for the orch pane (${Math.round(ageMs / 60000)}m old)\n`);
     const mins = Math.max(1, Math.round((holdMs - ageMs) / 60000));

package/hooks/stop-inbox.mjs

@@ -21,15 +21,15 @@
 //   * Only claim delivery once we have actually decided to surface it (peek first). Marking a message
 //     delivered and then letting the stop through would hide it from the waker too — a silent hole.
 //   * Any error, or a hub that is down -> allow the stop. Never trap a session because of us.
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
-import { resolveProject, hostId } from "../lib/project.mjs";
+import { resolveProject, hostId, handoffDir } from "../lib/project.mjs";
 import { signedGet } from "./lib/api.mjs";   // signed: enforce hubs 401 unsigned reads — unsigned, T2 delivery is silently dead
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
-import { readArm, clearArm, markHandedOff } from "./lib/handoff.mjs";
+import { readArm, clearArm, markHandedOff, appendHandoffState } from "./lib/handoff.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -147,6 +147,23 @@ async function main() {
       process.stderr.write("[trantor] turn boundary reached — firing the armed baton\n");
     }
   } catch {}
+  // §5 RECAPPED (SYSTEM-CONTRACT): this session's FIRST turn boundary after claiming a handoff.
+  // By Stop time an assistant reply exists, and every prompt of that first turn carried the
+  // recap reminder (prompt-focus) — so the reply had the instruction in front of it. Record the
+  // transition on the handoff's own ledger and disarm the net.
+  try {
+    const sid = String(input.session_id || "");
+    if (sid) {
+      const stampPath = join(handoffDir(), `recap-pending-${sid.replace(/[^A-Za-z0-9_.-]/g, "_")}.json`);
+      if (existsSync(stampPath)) {
+        try {
+          const stamp = JSON.parse(readFileSync(stampPath, "utf8"));
+          appendHandoffState(stamp.handoffId, "recapped", sid);
+        } catch {}
+        try { unlinkSync(stampPath); } catch {}
+      }
+    }
+  } catch {}
   // Mirror the other hooks: a home-directory session isn't project work and isn't on the bus.
   if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && projectDir === homedir()) return allow();
 

package/lib/autonomy.mjs

@@ -32,9 +32,16 @@ export const DEFAULTS = Object.freeze({
   deploy: false,
   swapDeadSeat: true,   // replacing an exhausted seat costs nothing and loses nothing
   retryFailedTurn: true,
+  // Who pulls the handoff trigger at the context warn line (#5509 W2, SYSTEM-CONTRACT §5).
+  // "ask" (default): the app's banner asks; the heartbeat neither arms nor auto-fires — the
+  // 2026-08-28 silent handoff is the incident this default answers. "auto": the proven
+  // arm-at-warn → fire-at-turn-boundary chain. PreCompact remains the at-the-wall backstop
+  // in BOTH modes: dying mid-compaction is strictly worse than an unasked handoff.
+  baton: "ask",         // ask | auto
 });
 
 const HARNESS = ["prompt", "bypass"];
+const BATON = ["ask", "auto"];
 
 export function loadAutonomy() {
   const p = AUTONOMY_PATH();
@@ -68,6 +75,7 @@ export function resolveAutonomy(project, cfg = loadAutonomy()) {
     deploy: !!merged.deploy,
     swapDeadSeat: merged.swapDeadSeat !== false,
     retryFailedTurn: merged.retryFailedTurn !== false,
+    baton: BATON.includes(merged.baton) ? merged.baton : DEFAULTS.baton,
   };
   if (!out.commit) out.push = false;
   if (!out.push) out.deploy = false;

package/lib/balances.mjs

@@ -51,7 +51,15 @@ export const ADAPTERS = [
       const win = (w, name) => (w && w.utilization != null)
         ? { name, usedPct: Math.round(w.utilization), resetsAt: w.resets_at || null, locked: w.locked_reason || null }
         : null;
-      return { windows: [win(d.five_hour, "5h"), win(d.seven_day, "7d")].filter(Boolean) };
+      // Model-scoped weekly limits ride limits[] (kind "weekly_scoped", scope.model.display_name
+      // e.g. "Fable") — Orca shows these as their own segment ("36% used Fable") and so do we.
+      // Captured live 2026-08-30: session/weekly_all in limits[] duplicate five_hour/seven_day,
+      // so only the scoped entries add information.
+      const scoped = (Array.isArray(d.limits) ? d.limits : [])
+        .filter((l) => l && l.kind === "weekly_scoped" && l.percent != null && l.scope?.model?.display_name)
+        .map((l) => ({ name: String(l.scope.model.display_name), usedPct: Math.round(l.percent),
+                       resetsAt: l.resets_at || null, locked: null, scoped: true }));
+      return { windows: [win(d.five_hour, "5h"), win(d.seven_day, "7d"), ...scoped].filter(Boolean) };
     },
   },
 
@@ -168,17 +176,51 @@ export async function fetchBalances(env = process.env, opts = {}) {
     catch (e) { return { ...base, ok: false, error: String(e?.message || e) }; }
   });
   const rows = (await Promise.all(jobs)).filter(Boolean);
-  // Codex has no balance API to query — it authenticates by `codex login` and bills a
-  // subscription. The fleet list must still show it, honestly, or the header reads as if the
-  // seat does not exist. Evidence of configuration is the login artifact, not an env key.
-  if (!only || only.has("codex") || only.has("openai")) {
+  // Codex: OpenAI publishes no public balance API, but the Codex CLI's OWN token can read the
+  // ChatGPT backend's usage windows — the same source Orca's footer reads (#5570; verified live
+  // 2026-08-30: plan_type + primary/secondary_window {used_percent, reset_at}). Evidence of
+  // configuration is the login artifact (~/.codex/auth.json), not an env key. The token never
+  // leaves the process; only percentages are reported. If the endpoint is unreachable, fall
+  // back to the honest subscription row this used to be — never an error row for a seat that
+  // bills flat.
+  // Same profile gate as every adapter (latent bug from the v6 static row, surfaced 2026-08-30:
+  // `!only ||` made a codex row appear with NO profile at all — "better empty than wrong").
+  if (only && (only.has("codex") || only.has("openai"))) {
     try {
-      const { existsSync } = await import("node:fs");
+      const { existsSync, readFileSync } = await import("node:fs");
       const { join } = await import("node:path");
       const { homedir } = await import("node:os");
-      if (existsSync(join(homedir(), ".codex", "auth.json"))) {
-        rows.push({ provider: "codex", label: "Codex", kind: "subscription", via: "codex login",
-          ok: true, plan: "OpenAI subscription", note: "no balance API — flat subscription" });
+      const authPath = join(homedir(), ".codex", "auth.json");
+      if (existsSync(authPath)) {
+        const base = { provider: "codex", label: "Codex", via: "codex login", ok: true };
+        try {
+          const tok = JSON.parse(readFileSync(authPath, "utf8"))?.tokens || {};
+          if (!tok.access_token) throw new Error("no codex token");
+          const r = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+            headers: {
+              authorization: `Bearer ${tok.access_token}`,
+              "ChatGPT-Account-Id": tok.account_id || "",
+              "User-Agent": "codex-cli", "OpenAI-Beta": "codex-1", originator: "Codex Desktop",
+            },
+            signal: AbortSignal.timeout(8000),
+          });
+          if (!r.ok) throw new Error(`wham/usage ${r.status}`);
+          const d = await r.json();
+          const win = (w, fallbackName) => {
+            if (!w || w.used_percent == null) return null;
+            const secs = Number(w.limit_window_seconds) || 0;
+            const name = secs === 604800 ? "7d" : secs > 0 && secs <= 21600 ? "5h"
+              : secs > 0 ? `${Math.round(secs / 3600)}h` : fallbackName;
+            return { name, usedPct: Math.round(w.used_percent),
+                     resetsAt: w.reset_at ? Number(w.reset_at) * 1000 : null, locked: null };
+          };
+          const windows = [win(d.rate_limit?.primary_window, "5h"), win(d.rate_limit?.secondary_window, "7d")].filter(Boolean);
+          if (!windows.length) throw new Error("no usage windows in response");
+          rows.push({ ...base, kind: "windows", plan: d.plan_type ? `ChatGPT ${d.plan_type}` : "OpenAI subscription", windows });
+        } catch {
+          rows.push({ ...base, kind: "subscription",
+            plan: "OpenAI subscription", note: "usage endpoint unreachable — flat subscription" });
+        }
       }
     } catch { /* no fs access → no row, never an error */ }
   }

package/lib/project.mjs

@@ -6,7 +6,7 @@
 // RELAY_PROJECT always wins (deliberate override / crew inheritance). The hub
 // applies an alias map on top of this to fold any historical divergence.
 import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { basename, join, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
 
@@ -93,14 +93,25 @@ export function orchWriterSid(projectDir, project, { withinMs = 90_000, env = pr
   } catch {}
   return "";
 }
-export function writeOrchSession(project, sid) {
+export function writeOrchSession(project, sid, by = "unknown") {
   try {
     if (!project || !sid) return false;
     const p = orchSessionsPath();
     mkdirSync(dirname(p), { recursive: true });
     const rows = existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean) : [];
+    const prev = rows.find(r => r.split("\t")[0] === project)?.split("\t")[1] || "";
     const kept = rows.filter(r => r.split("\t")[0] !== project);
     writeFileSync(p, [...kept, `${project}\t${sid}`].join("\n") + "\n");
+    // Every rewrite leaves a row in the sibling log (SYSTEM-CONTRACT §4: the map has exactly
+    // three writers, and a rewrite must be attributable after the fact). Local and append-only
+    // on purpose: this runs inside hooks with no time for network, and the interesting rewrite
+    // — a handoff claim — additionally becomes a bus event when the Phase 4 state machine lands.
+    if (prev !== sid) {
+      try {
+        appendFileSync(join(busDir(), "orch-sessions.log"),
+          `${new Date().toISOString()}\t${project}\t${prev || "-"}\t${sid}\t${by}\n`);
+      } catch {}
+    }
     return true;
   } catch { return false; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.15",
+  "version": "0.18.17",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"