trantor 0.17.13 → 0.17.15

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + context-handoff for independent AI coding agents (Claude, Codex, Gemini, …)",
-    "version": "0.17.13"
+    "version": "0.17.15"
   },
   "plugins": [
     {
       "name": "trantor",
       "source": "./",
       "description": "The hub-world for AI agent crews. Say \"fire up the crew\" and Claude becomes the architect: a plan-aware Advisor routes the work (solo / cheap inline calls / live crew of Codex, Gemini, Kimi & DeepSeek in their own terminal windows), a Kanban/flow command center with a testing gate tracks it, and an economics brain (Scrooge) keeps the receipts. Includes the relay MCP, a SessionStart auto-discovery hook, and a PreCompact context-handoff so a fresh session can take over a full window instead of compacting.",
-      "version": "0.17.13",
+      "version": "0.17.15",
       "author": {
         "name": "Sasha Bogojevic"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.13",
+  "version": "0.17.15",
   "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/catchup.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// trantor catchup — "where are we on this project?" on demand. Reads the continuous
+// board (the durable, cross-session project record), the recent git log, and — if
+// scrooge is on PATH — synthesizes a short narrative. The SessionStart hook already
+// injects the structured snapshot every start; this is the richer brief you ask for
+// when you want it. Run from inside a project: `trantor catchup`.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { resolveProject } from "../lib/project.mjs";
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const c = join(homedir(), ".agent-bus", "config.json"); if (existsSync(c)) { const u = JSON.parse(readFileSync(c, "utf8")).url; if (u) return u; } } catch {}
+  return "http://127.0.0.1:4477";
+}
+const haveScrooge = () => { try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; } };
+
+const dir = process.cwd();
+const project = resolveProject(dir);
+const url = relayUrl();
+
+let cu = null;
+try { cu = await (await fetch(`${url}/catchup?project=${encodeURIComponent(project)}`, { signal: AbortSignal.timeout(4000) })).json(); } catch (e) { console.error(`could not reach hub at ${url}: ${e.message}`); }
+let gitlog = "";
+try { gitlog = execSync(`git -C ${JSON.stringify(dir)} log --oneline -12 2>/dev/null`, { encoding: "utf8" }).trim(); } catch {}
+
+const line = (arr) => (arr || []).map(t => `  #${t.id} ${String(t.title).slice(0, 80)}${t.assignee ? ` @${t.assignee}` : ""}`).join("\n");
+console.log(`\n📋 trantor catchup — ${project}\n${"─".repeat(48)}`);
+if (cu && cu.total > 0) {
+  if (cu.brief) console.log(`Brief: ${cu.brief}\n`);
+  const c = cu.counts;
+  console.log(`Cards: ${cu.total} — ${c.done} done · ${c.doing} doing · ${c.testing} testing · ${c.todo} todo · ${c.failed} failed · ${c.blocked} blocked`);
+  if (cu.doing?.length)      console.log(`\nIn progress:\n${line(cu.doing)}`);
+  if (cu.testing?.length)    console.log(`\nIn testing:\n${line(cu.testing)}`);
+  if (cu.failed?.length)     console.log(`\nFailed (needs attention):\n${line(cu.failed)}`);
+  if (cu.blocked?.length)    console.log(`\nBlocked:\n${line(cu.blocked)}`);
+  if (cu.todo?.length)       console.log(`\nQueued:\n${line(cu.todo)}`);
+  if (cu.recentDone?.length) console.log(`\nRecently done:\n${line(cu.recentDone)}`);
+} else {
+  console.log(`No cards on the board for "${project}" yet.`);
+}
+if (gitlog) console.log(`\nRecent commits:\n${gitlog.split("\n").map(l => "  " + l).join("\n")}`);
+
+if (haveScrooge() && (cu?.total || gitlog)) {
+  const ctx = `PROJECT: ${project}\n\nBOARD:\n${JSON.stringify(cu, null, 2)}\n\nRECENT COMMITS:\n${gitlog}`;
+  const sys = "You are briefing someone resuming this project. From the board state + git log, write a SHORT 'where are we' narrative: what's built, what's in flight, what's next, and any risk (failed/blocked cards, or a stale card whose work looks already done elsewhere). 6-10 lines. No preamble.";
+  try {
+    console.log(`\n${"─".repeat(48)}\nWhere we are:\n`);
+    console.log(execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, { input: ctx, encoding: "utf8", timeout: 60000, maxBuffer: 4 * 1024 * 1024 }).trim());
+  } catch (e) { console.error(`(scrooge brief skipped: ${e.message})`); }
+} else if (!haveScrooge()) {
+  console.log(`\n(install scrooge for a synthesized narrative)`);
+}
+console.log("");

package/bin/cli.mjs

@@ -25,6 +25,7 @@ switch (cmd) {
   case "swap":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "swap", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
   case "hub":     run("hub.mjs"); break;
   case "watch":   run("bin/relay-watch.mjs"); break;
+  case "catchup": run("bin/catchup.mjs"); break;
   case "ui": {
     let url = "http://127.0.0.1:4477";
     try { url = JSON.parse(readFileSync(join(process.env.HOME || "", ".agent-bus", "config.json"), "utf8")).url || url; } catch {}
@@ -44,6 +45,7 @@ switch (cmd) {
   trantor up …        spawn a crew here:   trantor up codex gemini kimi deepseek:deepseek-v4-pro
   trantor down        tear the crew down (kills processes, closes windows, no dialogs)
   trantor ui          open the live dashboard (board + flow views)
+  trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
   trantor advise      ask the Advisor directly (JSON on stdin; --demo to see it)
   trantor hub         run the hub in the foreground (setup installs it as a service instead)
   trantor watch       live bus feed in the terminal

package/bin/crew-runner.mjs

@@ -12,10 +12,15 @@ import { execSync, spawnSync } from "node:child_process";
 import { readFileSync, existsSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
+import { resolveProject } from "../lib/project.mjs";
 
 const AGENT = process.argv[2];
 const DIR = process.argv[3] || process.cwd();
-const PROJ = basename(DIR);
+// Crew agents MUST share the orchestrator's project key (one repo = one lane).
+// RELAY_PROJECT is inherited from crew.sh (the host's resolved key); else fall
+// back to the git-repo-root basename — never a loose dir basename that could
+// fork the host's "builtbetter.ai" into a separate "builtbetter" lane.
+const PROJ = process.env.RELAY_PROJECT || resolveProject(DIR);
 const SESSION = `${AGENT}:${PROJ}`;
 if (!AGENT) { console.error("usage: crew-runner.mjs <agent> [project-dir]"); process.exit(1); }
 

package/bin/crew.sh

@@ -16,7 +16,10 @@
 set -u
 CMD="${1:-up}"; shift 2>/dev/null || true
 DIR="$(pwd)"
-PROJ="$(basename "$DIR")"
+# Canonical project key: the orchestrator's RELAY_PROJECT wins, else the GIT REPO ROOT
+# basename (stable across subdirs), else the cwd basename. The crew inherits this exact
+# key so one repo = one lane (no host "builtbetter.ai" vs crew "builtbetter" split).
+PROJ="${RELAY_PROJECT:-$(basename "$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null || echo "$DIR")")}"
 BUS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 STATE="$HOME/.agent-bus/crew-windows.txt"
 mkdir -p "$HOME/.agent-bus"
@@ -143,7 +146,7 @@ spawn_grid() {  # $@ = agents — (re)computes the grid for THIS batch and spawn
     local X1=$(( GX + C * CW )) Y1=$(( GY + R * CH )) WID=""
     WID="$(osascript \
       -e 'tell application "Terminal"' \
-      -e "  set w to do script \"cd $DIR && clear && CREW_MODEL=$MODEL node $BUS_DIR/bin/crew-runner.mjs $AGENT $DIR\"" \
+      -e "  set w to do script \"cd $DIR && clear && CREW_MODEL=$MODEL RELAY_PROJECT=$PROJ node $BUS_DIR/bin/crew-runner.mjs $AGENT $DIR\"" \
       -e "  set custom title of w to \"$(echo "$AGENT" | tr '[:lower:]' '[:upper:]') — trantor crew\"" \
       -e "  set theWin to first window whose tabs contains w" \
       -e "  set bounds of theWin to {$X1, $Y1, $(( X1 + CW )), $(( Y1 + CH ))}" \

package/hooks/handoff-now.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// trantor — detached EARLY-WARNING handoff worker. The PostToolUse heartbeat spawns this when a
+// session crosses its context warn threshold (~85% of a known window). Its job is to PREPARE a
+// safety-net handoff and NOTIFY — NOT to open a window. Spawning a fresh session while the original
+// is still perfectly usable created a surprise pop-up + an orphaned duplicate session; the actual
+// fresh-window spawn now happens only AT THE WALL (PreCompact). The (~60s) scrooge summary runs here,
+// detached, so it never blocks a tool call. Args: <projectDir> <sessionId> <transcriptPath> [trigger]
+import { readConfig, writeHandoff, pingBus, contextUsage } from "./lib/handoff.mjs";
+import { basename } from "node:path";
+
+const [, , projectDir = process.cwd(), sessionId = "", transcript = "", trigger = "context-warn"] = process.argv;
+try {
+  const conf = readConfig();
+  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
+  process.stderr.write(`[trantor] early handoff written (safety net, no spawn): ${file}\n`);
+  // notify the bus so a watcher knows a handoff is ready — but do NOT spawn a window here.
+  await pingBus(basename(projectDir), record.id, conf);
+} catch (e) {
+  process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);
+}
+process.exit(0);

package/hooks/heartbeat.mjs

@@ -14,11 +14,54 @@
 // We POST /register WITHOUT a status field so the session's meaningful status is preserved
 // (the hub only overwrites status when one is supplied).
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readConfig, contextUsage, warnFrac, alreadyHandedOff } from "./lib/handoff.mjs";
+import { resolveProject, hostId } from "../lib/project.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500);
+const INFLIGHT_MS = 5 * 60 * 1000;
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+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), 80); });
+}
+
+// Proactive early-warning: when the live context occupancy crosses the warn
+// fraction of a KNOWN window (env RELAY_CONTEXT_WINDOW / config.contextWindow —
+// the transcript can't reveal 200k vs 1M, so it must be declared), hand off
+// BEFORE the compaction wall. The heavy summary runs in a detached worker so we
+// never block this tool call. No-op when the window is unknown.
+async function maybeEarlyWarn(stdinRaw, session) {
+  try {
+    const conf = readConfig();
+    const input = JSON.parse(stdinRaw || "{}");
+    const transcript = input.transcript_path || "";
+    const sessionId = input.session_id || "";
+    if (!transcript) return;
+    const usage = contextUsage(transcript, conf);
+    if (!usage || !usage.window || usage.frac == null) return; // window unknown → only PreCompact guards
+    if (usage.frac < warnFrac(conf)) return;
+    if (alreadyHandedOff(sessionId, usage.tokens)) return;
+
+    // In-flight guard: the detached worker takes ~tens of seconds to summarize;
+    // don't launch a second one on the next heartbeat tick meanwhile.
+    const inflight = join(homedir(), ".agent-bus", `handoff-inflight-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);
+    try { if (existsSync(inflight) && Date.now() - (Number(readFileSync(inflight, "utf8")) || 0) < INFLIGHT_MS) return; } catch {}
+    try { writeFileSync(inflight, String(Date.now())); } catch {}
+
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% of ${usage.window} — launching early handoff\n`);
+    const child = spawn(process.execPath, [join(HERE, "handoff-now.mjs"), projectDir, sessionId, transcript, "context-warn"],
+      { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {}
+}
 
 function relayUrl() {
   if (process.env.RELAY_URL) return process.env.RELAY_URL;
@@ -29,7 +72,7 @@ function relayUrl() {
   return "http://127.0.0.1:4477";
 }
 
-async function main() {
+async function main(stdinRaw) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // Mirror sessionstart.mjs: home-directory sessions aren't project work — don't register
   // them (would spawn a phantom "<username>" board). Opt in with RELAY_SESSION/RELAY_PROJECT.
@@ -38,11 +81,11 @@ async function main() {
   // Mirror mcp.mjs identity resolution EXACTLY so we refresh the same peer the relay
   // registered (not a phantom): RELAY_PROJECT wins for project; RELAY_SESSION wins for
   // identity, else a RELAY_AGENT brand ("codex","kimi",…) per project, else hostname:project.
-  const project = process.env.RELAY_PROJECT || basename(projectDir);
+  const project = resolveProject(projectDir);
   const session = process.env.RELAY_SESSION
-    || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostname()}:${project}`);
+    || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
 
-  // Throttle: only ping if HEARTBEAT_MS has elapsed since the last ping for THIS session.
+  // Throttle: only act if HEARTBEAT_MS has elapsed since the last tick for THIS session.
   const stamp = join(homedir(), ".agent-bus", `hb-${session.replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);
   try {
     if (existsSync(stamp)) {
@@ -62,7 +105,11 @@ async function main() {
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
   } catch {}
+
+  // Same cadence as the presence ping: check context pressure and hand off early
+  // if we've crossed the warn threshold of a known window.
+  await maybeEarlyWarn(stdinRaw, session);
 }
 
 // Never block or break the tool flow: swallow everything, always exit clean.
-main().catch(() => {}).finally(() => process.exit(0));
+readStdin().then(main).catch(() => {}).finally(() => process.exit(0));

package/hooks/lib/handoff.mjs

@@ -0,0 +1,225 @@
+// trantor handoff core — shared by the PreCompact hook (at-the-wall) and the
+// PostToolUse heartbeat (proactive early-warning). One place that knows how to:
+//   • read a session's live context occupancy from its transcript usage,
+//   • build a WHOLE-SESSION summary (not just the tail),
+//   • write a handoff record, and
+//   • spawn a fresh same-agent session in a new terminal that takes it over.
+//
+// Why this exists: PreCompact fires only at the compaction wall and cannot stop
+// compaction, so the only way to continue with a full window is to open a NEW
+// session that loads the handoff. The heartbeat path lets us do that BEFORE the
+// wall when we know the window size. Both paths share a per-session guard so we
+// never write/spawn twice for the same context window.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir, hostname } from "node:os";
+import { execSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const HANDOFF_DIR = join(homedir(), ".agent-bus", "handoffs");
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function readConfig() {
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    return existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")) : {};
+  } catch { return {}; }
+}
+
+export function relayUrl(conf = readConfig()) {
+  return process.env.RELAY_URL || conf.url || "http://127.0.0.1:4477";
+}
+
+// ---- context occupancy ------------------------------------------------------
+// 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 = "";
+  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);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let r; try { r = JSON.parse(lines[i]); } 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 };
+    }
+  }
+  return null;
+}
+
+// The transcript logs the model WITHOUT the [1m] marker, so we cannot tell a
+// 200k window from a 1M one. There is therefore no safe universal default — the
+// window must be declared (env RELAY_CONTEXT_WINDOW or config.contextWindow) for
+// the proactive early-warning to activate. Returns 0 when unknown (→ no warning).
+export function resolveWindow(model = "", conf = readConfig()) {
+  const explicit = Number(process.env.RELAY_CONTEXT_WINDOW || conf.contextWindow || 0);
+  if (explicit > 0) return explicit;
+  if (/\[1m\]|-1m\b|:1m\b/i.test(model)) return 1_000_000; // honored if ever present
+  return 0;
+}
+
+export function warnFrac(conf = readConfig()) {
+  const f = Number(process.env.RELAY_CONTEXT_WARN_FRAC || conf.contextWarnFrac || 0.85);
+  return f > 0 && f < 1 ? f : 0.85;
+}
+
+// ---- per-session guard (shared by both paths) -------------------------------
+// One handoff+spawn per context window. Re-arms after a compaction resets the
+// context (tokens drop well below where we fired).
+function guardPath(sessionId) {
+  const safe = String(sessionId || "nosession").replace(/[^A-Za-z0-9_.-]/g, "_");
+  return join(homedir(), ".agent-bus", `handoff-fired-${safe}.json`);
+}
+export function alreadyHandedOff(sessionId, curTokens = 0) {
+  try {
+    const p = guardPath(sessionId);
+    if (!existsSync(p)) return false;
+    const g = JSON.parse(readFileSync(p, "utf8"));
+    // Re-arm if context clearly reset (e.g. after a compaction) — well below the fire point.
+    if (curTokens && g.atTokens && curTokens < g.atTokens * 0.7) return false;
+    return true;
+  } catch { return false; }
+}
+export function markHandedOff(sessionId, curTokens = 0) {
+  try {
+    if (!existsSync(dirname(guardPath(sessionId)))) mkdirSync(dirname(guardPath(sessionId)), { recursive: true });
+    writeFileSync(guardPath(sessionId), JSON.stringify({ at: nowSec(), atTokens: curTokens || 0 }));
+  } catch {}
+}
+
+function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8" }).trim()) || 0; } catch { return 0; } }
+
+// ---- whole-session summary --------------------------------------------------
+function collectTurns(transcriptPath) {
+  const rows = readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean)
+    .map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  const turns = [];
+  for (const r of rows) {
+    if (!(r.type === "user" || r.type === "assistant") || !r.message) continue;
+    const c = r.message.content;
+    let text = "";
+    if (typeof c === "string") text = c;
+    else if (Array.isArray(c)) text = c.filter(b => b?.type === "text").map(b => b.text).join("\n");
+    text = (text || "").trim();
+    if (!text || text.startsWith("<task-notification") || text.startsWith("<command")) continue;
+    turns.push(`### ${r.type.toUpperCase()}\n${text.slice(0, 2400)}`);
+  }
+  return turns;
+}
+
+// Build a digest that spans the WHOLE session: the opening turns (the task &
+// goal framing), an even sample of the middle (the arc of the work), and a
+// fuller recent tail (current state). The old hook kept only the last 16KB —
+// on a multi-hour session that captured only the final moments.
+function digest(turns, budget = 56_000) {
+  const joined = turns.join("\n\n");
+  if (joined.length <= budget) return joined;
+
+  const headN = Math.min(6, turns.length);
+  const tailN = Math.min(24, Math.max(0, turns.length - headN));
+  const head = turns.slice(0, headN);
+  const tail = turns.slice(turns.length - tailN);
+  const midPool = turns.slice(headN, turns.length - tailN);
+
+  // Evenly sample the middle so the summarizer sees the whole trajectory.
+  const midKeep = 18;
+  const mid = [];
+  if (midPool.length > 0) {
+    const step = Math.max(1, Math.floor(midPool.length / midKeep));
+    for (let i = 0; i < midPool.length && mid.length < midKeep; i += step) mid.push(midPool[i]);
+  }
+  let out = [
+    ...head,
+    midPool.length ? "### … (mid-session, evenly sampled) …" : "",
+    ...mid,
+    tail.length ? "### … (recent) …" : "",
+    ...tail,
+  ].filter(Boolean).join("\n\n");
+  if (out.length > budget) out = out.slice(out.length - budget); // never blow the budget
+  return out;
+}
+
+function haveScrooge() {
+  if (process.env.TRANTOR_NO_SCROOGE === "1") return false; // opt out (tests / no-LLM summary)
+  try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; }
+}
+
+export function buildSummary(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return "*(no transcript available to summarize)*";
+  let convo = "";
+  try { convo = digest(collectTurns(transcriptPath)); } catch { convo = ""; }
+  if (!convo) return "*(transcript unreadable)*";
+  const sys = "You are writing a SESSION HANDOFF so a fresh Claude Code session can take over without losing context. The text spans an entire (possibly multi-hour) session: opening turns, an even sample of the middle, and the recent tail. Produce a concise but COMPLETE markdown handoff with these sections: TASK (what we're doing + the goal), STATE (done / in-progress), KEY DECISIONS, OPEN THREADS & NEXT STEPS (concrete actions), KEY FILES & locations (exact paths). Be specific. Cover the whole arc, not just the end. Do not pad.";
+  if (haveScrooge()) {
+    try {
+      return execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, {
+        input: convo, encoding: "utf8", timeout: 60_000, maxBuffer: 8 * 1024 * 1024,
+      }).trim() || `*(empty summary — raw recent tail)*\n\n${convo.slice(-8000)}`;
+    } catch (e) { process.stderr.write(`[trantor] scrooge summarize failed: ${e?.message}\n`); }
+  }
+  return `*(no summarizer available — representative transcript digest)*\n\n${convo.slice(-12000)}`;
+}
+
+// ---- write + announce + spawn ----------------------------------------------
+export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary }) {
+  const projectName = basename(projectDir);
+  if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
+  const stamp = nowSec() || Date.now();
+  let gitStatus = "";
+  try { gitStatus = execSync("git -C " + JSON.stringify(projectDir) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
+  const record = {
+    id: `${projectName}-${stamp}`,
+    project: projectDir, projectName, machine: hostname(),
+    session_id: sessionId || "", trigger: trigger || "auto",
+    transcript_path: transcript || "", stamp: Number(stamp) || 0,
+    summary: summary ?? buildSummary(transcript),
+    gitStatus, consumed: false,
+  };
+  const file = join(HANDOFF_DIR, `${record.id}.json`);
+  writeFileSync(file, JSON.stringify(record, null, 2));
+  return { file, record };
+}
+
+export async function pingBus(projectName, id, conf = readConfig()) {
+  try {
+    await fetch(`${relayUrl(conf)}/send`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ from: `${hostname()}:${projectName}`, to: "all",
+        text: `📋 Handoff ready for ${projectName} — open a fresh session here to take over (id ${id}).` }),
+      signal: AbortSignal.timeout(2000),
+    }).catch(() => {});
+  } catch {}
+}
+
+// Spawn a fresh same-agent session (macOS) that takes over via the handoff.
+// Default = ON (prompt with a timeout, default button "Open fresh session").
+// Disable with config.autoHandoffPrompt:false or env TRANTOR_NO_HANDOFF_SPAWN=1.
+export function maybeSpawn(projectDir, conf = readConfig()) {
+  try {
+    if (process.platform !== "darwin") return false;
+    if (process.env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
+    if (conf.autoHandoffPrompt === false) return false;
+    const script = join(HERE, "..", "..", "bin", "handoff-prompt.sh");
+    if (!existsSync(script)) { process.stderr.write(`[trantor] handoff-prompt.sh missing\n`); return false; }
+    const timeout = String(conf.handoffPromptTimeout || 25);
+    const child = spawn("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch (e) { process.stderr.write(`[trantor] maybeSpawn error: ${e?.message}\n`); return false; }
+}

package/hooks/precompact.mjs

@@ -1,18 +1,14 @@
 #!/usr/bin/env node
-// trantor PreCompact hook — fires right before Claude Code compacts a full
-// context window. Instead of (just) compacting, it writes a rich HANDOFF so you can
-// open a FRESH session that takes over with a new full window. The SessionStart hook
-// detects the pending handoff and loads it.
-//
-// Handoff generation: if `scrooge` is on PATH, it summarizes the recent transcript
-// into a structured handoff cheaply; otherwise it falls back to a raw transcript tail.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { join, basename, dirname } from "node:path";
-import { homedir, hostname } from "node:os";
-import { execSync, spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
-const HANDOFF_DIR = join(homedir(), ".agent-bus", "handoffs");
+// trantor PreCompact hook — fires right before Claude Code compacts a full context
+// window. A PreCompact hook CANNOT stop compaction; the current window is always
+// compacted. So its job is to write a rich WHOLE-SESSION handoff and (on macOS, by
+// default) prompt to open a FRESH session in a new terminal that takes over with a
+// full window. The new session's SessionStart hook loads the handoff. This is the
+// at-the-wall backstop; the heartbeat hook can also fire this earlier when the
+// context window size is known (see hooks/lib/handoff.mjs).
+import { readConfig, writeHandoff, pingBus, maybeSpawn,
+         contextUsage, alreadyHandedOff, markHandedOff } from "./lib/handoff.mjs";
+import { basename } from "node:path";
 
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
@@ -20,97 +16,29 @@ function readStdin() {
     setTimeout(() => res(d), 100); });
 }
 
-// Pull readable recent conversation text from a Claude Code transcript JSONL.
-function recentTranscript(path, maxChars = 16000) {
-  try {
-    const rows = readFileSync(path, "utf8").split("\n").filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-    const turns = [];
-    for (const r of rows) {
-      if (!(r.type === "user" || r.type === "assistant") || !r.message) continue;
-      const c = r.message.content;
-      let text = "";
-      if (typeof c === "string") text = c;
-      else if (Array.isArray(c)) text = c.filter(b => b?.type === "text").map(b => b.text).join("\n");
-      if (text.trim() && !text.startsWith("<task-notification") && !text.startsWith("<command")) {
-        turns.push(`### ${r.type.toUpperCase()}\n${text.slice(0, 2000)}`);
-      }
-    }
-    let out = turns.join("\n\n");
-    if (out.length > maxChars) out = out.slice(out.length - maxChars); // keep the most recent
-    return out;
-  } catch { return ""; }
-}
-
-function haveScrooge() { try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; } }
-
-function summarize(convo) {
-  const sys = "You are writing a SESSION HANDOFF so a fresh Claude Code session can take over without losing context. From the conversation, produce a concise but complete markdown handoff with these sections: TASK (what we're doing + the goal), STATE (done / in-progress), KEY DECISIONS, OPEN THREADS & NEXT STEPS (concrete actions), KEY FILES & locations (exact paths). Be specific. Do not pad.";
-  if (haveScrooge()) {
-    try {
-      return execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, {
-        input: convo, encoding: "utf8", timeout: 45000, maxBuffer: 4 * 1024 * 1024,
-      }).trim();
-    } catch (e) { process.stderr.write(`[trantor] scrooge summarize failed: ${e?.message}\n`); }
-  }
-  // fallback: raw recent tail
-  return `*(no summarizer available — raw recent transcript tail)*\n\n${convo.slice(-6000)}`;
-}
-
 try {
   const input = JSON.parse((await readStdin()) || "{}");
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const projectName = basename(projectDir);
   const transcript = input.transcript_path || "";
   const trigger = input.trigger || "auto";
+  const sessionId = input.session_id || "";
+  const conf = readConfig();
 
-  const convo = transcript && existsSync(transcript) ? recentTranscript(transcript) : "";
-  const summary = convo ? summarize(convo) : "*(no transcript available to summarize)*";
-
-  let gitStatus = "";
-  try { gitStatus = execSync("git -C " + JSON.stringify(projectDir) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
-
-  if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
-  const stamp = (() => { try { return execSync("date +%s", { encoding: "utf8" }).trim(); } catch { return String(process.pid); } })();
-
-  const record = {
-    id: `${projectName}-${stamp}`,
-    project: projectDir, projectName,
-    machine: hostname(),
-    session_id: input.session_id || "",
-    trigger, transcript_path: transcript,
-    stamp: Number(stamp) || 0,
-    summary,
-    gitStatus,
-    consumed: false,
-  };
-  const file = join(HANDOFF_DIR, `${record.id}.json`);
-  writeFileSync(file, JSON.stringify(record, null, 2));
+  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
   process.stderr.write(`[trantor] handoff written: ${file} (trigger=${trigger})\n`);
 
-  // best-effort: ping the relay hub so other sessions/machines know a handoff is ready
-  try {
-    const cfg = join(homedir(), ".agent-bus", "config.json");
-    const url = process.env.RELAY_URL || (existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")).url : "") || "http://127.0.0.1:4477";
-    await fetch(`${url}/send`, { method: "POST", headers: { "content-type": "application/json" },
-      body: JSON.stringify({ from: `${hostname()}:${projectName}`, to: "all", text: `📋 Handoff ready for ${projectName} — open a fresh session here to take over (id ${record.id}).` }),
-      signal: AbortSignal.timeout(2000) }).catch(() => {});
-  } catch {}
+  await pingBus(projectName, record.id, conf);
 
-  // OPT-IN: on macOS, if config.autoHandoffPrompt is true, ask the user (with a timeout,
-  // default = yes) whether to spawn a FRESH same-agent session that takes over via the
-  // handoff. Detached so it never blocks compaction. Off by default.
-  try {
-    const cfg = join(homedir(), ".agent-bus", "config.json");
-    const conf = existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")) : {};
-    if (conf.autoHandoffPrompt && process.platform === "darwin") {
-      const script = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "handoff-prompt.sh");
-      if (existsSync(script)) {
-        const child = spawn("/bin/bash", [script, projectDir, String(conf.handoffPromptTimeout || 25)], { detached: true, stdio: "ignore" });
-        child.unref();
-        process.stderr.write(`[trantor] handoff prompt launched (opt-in)\n`);
-      }
-    }
-  } catch {}
+  // 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)) {
+    process.stderr.write(`[trantor] fresh session already spawned for this window — handoff refreshed only\n`);
+  } else if (maybeSpawn(projectDir, conf)) {
+    markHandedOff(sessionId, cur);
+    process.stderr.write(`[trantor] fresh-session prompt launched (PreCompact)\n`);
+  }
 } catch (err) {
   process.stderr.write(`[trantor] precompact error: ${err?.message || err}\n`);
 }