trantor 0.17.21 → 0.17.23

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.21"
+    "version": "0.17.23"
   },
   "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.21",
+      "version": "0.17.23",
       "author": {
         "name": "Sasha Bogojevic"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.21",
+  "version": "0.17.23",
   "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/baton-close.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// trantor baton-close — the second half of the baton pass. Runs DETACHED, armed by the handoff hook.
+// Waits until the FRESH session has consumed the handoff (consumed:true on the handoff file = it
+// started and loaded the context), THEN closes the ORIGINAL session's Terminal window — so you're never
+// left with two live sessions on one project, and never a gap where neither is alive. Defensive: aborts
+// if the fresh session never shows (timeout), and re-validates the window's tty before closing so it can
+// NEVER close the wrong window. Args: <handoffFile> <originalWindowId> <originalTty>
+import { readFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+const [, , handoffFile, windowId, originalTty] = process.argv;
+const POLL_MS = 1500, TIMEOUT_MS = 120_000;
+
+const consumed = () => { try { return JSON.parse(readFileSync(handoffFile, "utf8")).consumed === true; } catch { return false; } };
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+function ttyOfWindow(id) {
+  try {
+    return execSync(`osascript -e ${JSON.stringify(`tell application "Terminal" to get tty of selected tab of (first window whose id is ${id})`)}`,
+      { encoding: "utf8", timeout: 3000 }).trim();
+  } catch { return ""; }
+}
+function closeWindow(id, tty) {
+  // re-validate: only close if the window is STILL on the original tty (never close a re-used/wrong window)
+  const cur = ttyOfWindow(id);
+  if (!cur || (originalTty && cur !== originalTty)) {
+    process.stderr.write(`[trantor] baton-close: window ${id} tty changed (${cur} != ${originalTty}) — NOT closing\n`);
+    return false;
+  }
+  try {
+    // SIGKILL the processes on that tty first (claude traps SIGTERM; a live login makes close() pop a dialog)
+    const dev = (tty || cur).replace(/^\/dev\//, "");
+    for (const pid of execSync(`ps -t ${dev} -o pid= 2>/dev/null || true`, { encoding: "utf8" }).trim().split("\n").filter(Boolean)) {
+      try { execSync(`kill -9 ${pid.trim()} 2>/dev/null || true`); } catch {}
+    }
+  } catch {}
+  try { execSync(`osascript -e ${JSON.stringify(`tell application "Terminal" to close (first window whose id is ${id})`)}`, { timeout: 3000 }); return true; } catch { return false; }
+}
+
+(async () => {
+  if (!handoffFile || !windowId) process.exit(0);
+  const deadline = Date.now() + TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (consumed()) {
+      await sleep(2500); // let the fresh session settle (register, inject) before we pull the original
+      const ok = closeWindow(windowId, originalTty);
+      process.stderr.write(`[trantor] baton-close: fresh session took over → original window ${windowId} ${ok ? "closed" : "left (validation/close failed)"}\n`);
+      process.exit(0);
+    }
+    await sleep(POLL_MS);
+  }
+  process.stderr.write(`[trantor] baton-close: fresh session never confirmed within ${TIMEOUT_MS / 1000}s — leaving the original alive (safe)\n`);
+  process.exit(0);
+})();

package/bin/baton.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// `trantor handoff` — one-command manual baton (auto-summary variant). Discovers the current session's
+// transcript, writes a whole-session handoff (auto-summary + verbatim in-flight tail), opens a fresh
+// self-announcing session, and closes THIS window once it takes over. Run from inside the session you
+// want to hand off. (The richer MODEL-authored handoff is the /trantor:handoff skill.)
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveProject } from "../lib/project.mjs";
+import { writeHandoff, spawnBaton } from "../hooks/lib/handoff.mjs";
+
+const cwd = process.cwd();
+const project = resolveProject(cwd);
+
+// The active session's transcript = newest *.jsonl directly in this project's Claude dir
+// (~/.claude/projects/<cwd-with-slashes-as-dashes>/), excluding the subagents/ subtree.
+function findTranscript() {
+  const dashed = cwd.replace(/\//g, "-");
+  const base = join(homedir(), ".claude", "projects");
+  let best = "", bestM = 0;
+  let dirs = []; try { dirs = readdirSync(base).filter(d => d === dashed || d.endsWith(dashed)); } catch {}
+  for (const d of dirs) {
+    let ents = []; try { ents = readdirSync(join(base, d)); } catch {}
+    for (const f of ents) {
+      if (!f.endsWith(".jsonl")) continue;
+      try { const m = statSync(join(base, d, f)).mtimeMs; if (m > bestM) { best = join(base, d, f); bestM = m; } } catch {}
+    }
+  }
+  return best;
+}
+
+const transcript = findTranscript();
+const { file } = writeHandoff({ projectDir: cwd, sessionId: "", transcript, trigger: "manual-cli" });
+console.log(`📋 handoff saved for ${project}: ${file}`);
+const { spawned, armed, windowId } = spawnBaton({ projectDir: cwd, handoffFile: file });
+console.log(spawned
+  ? `🔄 baton: a fresh session is opening (it'll recap the handoff)${armed ? ` — this window (${windowId}) closes once it takes over` : " — couldn't detect this window; close it yourself once the new one is up"}`
+  : `handoff saved, but couldn't spawn a fresh session (non-macOS or spawn disabled) — open a new session here to take over`);

package/bin/cli.mjs

@@ -27,6 +27,7 @@ switch (cmd) {
   case "watch":   run("bin/relay-watch.mjs"); break;
   case "catchup": run("bin/catchup.mjs"); break;
   case "backfill": run("bin/git-backfill.mjs"); break;
+  case "handoff": run("bin/baton.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 {}
@@ -48,6 +49,7 @@ switch (cmd) {
   trantor ui          open the live dashboard (board + flow views)
   trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
   trantor backfill    card past GIT work onto the board (solo commits that were never carded) — [--since "14 days ago"] [--dry-run]
+  trantor handoff     finish this session NOW: write a handoff, open a fresh session that takes over, and close this one (manual baton)
   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/handoff-prompt.sh

@@ -7,15 +7,17 @@
 # Agent to spawn = $AGENT_CMD (default "claude") — same agent, fresh window.
 DIR="${1:-$HOME}"
 TIMEOUT="${2:-25}"
-AGENT_CMD="${AGENT_CMD:-claude}"
+# The fresh session SELF-ANNOUNCES: it opens already recapping the handoff it took over, so it's never
+# a confusing empty prompt. Single-quoted so it survives osascript->shell with no escaping (no apostrophes).
+AGENT_CMD="${AGENT_CMD:-claude 'Recap the handoff you just took over — what was the previous session doing, and where do we continue? Then wait for me.'}"
 HERE="$(cd "$(dirname "$0")" && pwd)"
 NAME="$(basename "$DIR")"
 
-MSG="trantor — this session's context window is full ($NAME). Open a FRESH session to take over with a full window? It loads a handoff of this session. (The current session keeps compacting either way.)"
+MSG="trantor — context is at ~90% on $NAME. Hand off to a FRESH full-window session now? It loads this session's handoff and continues; this window then closes (baton pass). Cancel to keep working here."
 
 # Best-effort timed dialog. On timeout, error, or no UI session -> empty -> we spawn (the default).
-CHOICE="$(osascript -e "button returned of (display dialog \"${MSG//\"/\\\"}\" buttons {\"Keep compacting\", \"Open fresh session\"} default button \"Open fresh session\" giving up after $TIMEOUT with title \"trantor\")" 2>/dev/null)"
+CHOICE="$(osascript -e "button returned of (display dialog \"${MSG//\"/\\\"}\" buttons {\"Keep working here\", \"Hand off\"} default button \"Hand off\" giving up after $TIMEOUT with title \"trantor\")" 2>/dev/null)"
 
-if [ "$CHOICE" != "Keep compacting" ]; then
+if [ "$CHOICE" != "Keep working here" ]; then
   "$HERE/open-session.sh" "$DIR" "$AGENT_CMD"
 fi

package/bin/write-handoff.mjs

@@ -1,17 +1,29 @@
 #!/usr/bin/env node
-import { writeFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+// Save a model-authored handoff (piped on stdin) for this project; the next session auto-loads it.
+// With --baton: ALSO open a fresh self-announcing session and close THIS window once it takes over
+// (the one-command manual baton behind /trantor:handoff). Without it: just write the file (legacy).
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execSync } from "node:child_process";
+import { spawnBaton } from "../hooks/lib/handoff.mjs";
+
+const baton = process.argv.includes("--baton");
 const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const name = basename(project);
 let summary = ""; process.stdin.setEncoding("utf8");
 for await (const c of process.stdin) summary += c;
 const dir = join(homedir(), ".agent-bus", "handoffs");
 if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-const stamp = (() => { try { return execSync("date +%s",{encoding:"utf8"}).trim(); } catch { return String(process.pid); } })();
-let git=""; try { git = execSync("git -C "+JSON.stringify(project)+" status --short 2>/dev/null | head -30",{encoding:"utf8"}).trim(); } catch {}
-const rec = { id:`${name}-${stamp}`, project, projectName:name, machine:hostname(), trigger:"manual-skill", stamp:Number(stamp)||0, summary:summary.trim()||"(empty)", gitStatus:git, consumed:false };
+const stamp = (() => { try { return execSync("date +%s", { encoding: "utf8" }).trim(); } catch { return String(process.pid); } })();
+let git = ""; try { git = execSync("git -C " + JSON.stringify(project) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
+const rec = { id: `${name}-${stamp}`, project, projectName: name, machine: hostname(), trigger: baton ? "manual-baton" : "manual-skill", stamp: Number(stamp) || 0, summary: summary.trim() || "(empty)", gitStatus: git, consumed: false };
 const file = join(dir, `${rec.id}.json`);
-writeFileSync(file, JSON.stringify(rec,null,2));
+writeFileSync(file, JSON.stringify(rec, null, 2));
 console.log(`handoff saved: ${file}`);
+
+if (baton) {
+  const { spawned, armed, windowId } = spawnBaton({ projectDir: project, handoffFile: file });
+  if (spawned) console.log(`baton: fresh session opening (self-recapping)${armed ? ` — this window (${windowId}) closes once it takes over` : " — original window left open (couldn't detect it)"}`);
+  else console.log(`baton: could not spawn a fresh session (non-macOS or spawn disabled) — handoff saved, open a new session manually`);
+}

package/hooks/handoff-now.mjs

@@ -1,20 +1,24 @@
 #!/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";
+// trantor — detached BATON-PASS worker. The PostToolUse heartbeat spawns this when a session crosses
+// its context warn threshold (~90% of a known window). It writes a whole-session handoff (narrative +
+// verbatim in-flight tail), spawns a FRESH session to take over, and arms the baton-close watcher which
+// — once the fresh session has consumed the handoff — closes THIS (original) session's Terminal window.
+// The heavy scrooge summary runs here, detached, so it never blocks a tool call. The original's window
+// id + tty are detected by the heartbeat (which has the controlling tty) and passed in as args.
+// Args: <projectDir> <sessionId> <transcriptPath> [trigger] [originalWindowId] [originalTty]
+import { readConfig, writeHandoff, pingBus, maybeSpawn, armBatonClose } from "./lib/handoff.mjs";
 import { basename } from "node:path";
 
-const [, , projectDir = process.cwd(), sessionId = "", transcript = "", trigger = "context-warn"] = process.argv;
+const [, , projectDir = process.cwd(), sessionId = "", transcript = "", trigger = "context-warn", windowId = "", tty = ""] = 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.
+  process.stderr.write(`[trantor] baton handoff written: ${file}\n`);
   await pingBus(basename(projectDir), record.id, conf);
+  if (maybeSpawn(projectDir, conf)) {                 // open the fresh session that takes over
+    const armed = windowId ? armBatonClose(file, windowId, tty, conf) : false;  // close the original once fresh confirms
+    process.stderr.write(`[trantor] fresh session spawned${armed ? ` · baton-close armed for window ${windowId}` : " · no original-window close (none detected / disabled)"}\n`);
+  }
 } catch (e) {
   process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);
 }

package/hooks/heartbeat.mjs

@@ -18,7 +18,7 @@ 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 { readConfig, contextUsage, warnFrac, alreadyHandedOff, controllingTty, terminalWindowForTty } from "./lib/handoff.mjs";
 import { resolveProject, hostId } from "../lib/project.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
@@ -56,8 +56,12 @@ async function maybeEarlyWarn(stdinRaw, session) {
     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"],
+    // 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();
+    const windowId = tty ? terminalWindowForTty(tty) : "";
+    process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% of ${usage.window} — baton pass (window ${windowId || "?"})\n`);
+    const child = spawn(process.execPath, [join(HERE, "handoff-now.mjs"), projectDir, sessionId, transcript, "context-warn", windowId, tty],
       { detached: true, stdio: "ignore" });
     child.unref();
   } catch {}

package/hooks/lib/handoff.mjs

@@ -75,8 +75,8 @@ export function resolveWindow(model = "", conf = readConfig()) {
 }
 
 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;
+  const f = Number(process.env.RELAY_CONTEXT_WARN_FRAC || conf.contextWarnFrac || 0.90);
+  return f > 0 && f < 1 ? f : 0.90;   // baton pass fires at 90% — runway to summarize + hand off before the wall
 }
 
 // ---- per-session guard (shared by both paths) -------------------------------
@@ -176,6 +176,13 @@ export function buildSummary(transcriptPath) {
   return `*(no summarizer available — representative transcript digest)*\n\n${convo.slice(-12000)}`;
 }
 
+// The exact recent exchange, VERBATIM (not summarized/sampled) — so a baton-pass handoff carries the
+// precise in-flight state (e.g. the live cs_live_… URL, the exact decision point) even if the scrooge
+// narrative times out on a huge transcript. This is what lets the fresh session truly continue, not guess.
+export function verbatimRecentTail(transcript, chars = 7000) {
+  try { return collectTurns(transcript).join("\n\n").slice(-chars); } catch { return ""; }
+}
+
 // ---- write + announce + spawn ----------------------------------------------
 export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary }) {
   const projectName = basename(projectDir);
@@ -183,12 +190,15 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
   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 narrative = summary ?? buildSummary(transcript);
+  const tail = verbatimRecentTail(transcript);
   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),
+    // 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, consumed: false,
   };
   const file = join(HANDOFF_DIR, `${record.id}.json`);
@@ -196,6 +206,47 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
   return { file, record };
 }
 
+// --- baton pass: the original session's Terminal window (macOS), so the fresh session can replace it ---
+// Walk the process tree to the controlling tty (the hook itself may show "??" but its parent claude
+// owns the Terminal's tty). Returns "/dev/ttysNNN" or "".
+export function controllingTty() {
+  for (const pid of [process.pid, process.ppid, getPpid(process.ppid)]) {
+    if (!pid) continue;
+    try { const t = execSync(`ps -o tty= -p ${pid}`, { encoding: "utf8" }).trim(); if (t && t !== "??" && t !== "?") return "/dev/" + t; } catch {}
+  }
+  return "";
+}
+function getPpid(pid) { if (!pid) return 0; try { return Number(execSync(`ps -o ppid= -p ${pid}`, { encoding: "utf8" }).trim()) || 0; } catch { return 0; } }
+
+// Find the Terminal.app window id whose selected tab is on `tty` — the window to close on takeover.
+export function terminalWindowForTty(tty) {
+  if (process.platform !== "darwin" || !tty) return "";
+  const osa = `tell application "Terminal"
+    repeat with w in windows
+      try
+        if (tty of selected tab of w) is "${tty}" then return (id of w) as string
+      end try
+    end repeat
+    return ""
+  end tell`;
+  try { return execSync(`osascript -e ${JSON.stringify(osa)}`, { encoding: "utf8", timeout: 3000 }).trim(); } catch { return ""; }
+}
+
+// Arm the baton-close watcher: a DETACHED process that waits until the fresh session consumes the
+// handoff (consumed:true), then closes the original Terminal window. Never closes blind: aborts on
+// timeout (fresh never showed) and re-validates the window's tty before closing.
+export function armBatonClose(handoffFile, originalWindowId, originalTty, conf = readConfig()) {
+  try {
+    if (process.platform !== "darwin" || !originalWindowId) return false;
+    if (process.env.TRANTOR_NO_BATON_CLOSE === "1" || conf.batonClose === false) return false;
+    const closer = join(HERE, "..", "..", "bin", "baton-close.mjs");
+    if (!existsSync(closer)) return false;
+    const child = spawn(process.execPath, [closer, handoffFile, String(originalWindowId), originalTty || ""], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch { return false; }
+}
+
 export async function pingBus(projectName, id, conf = readConfig()) {
   try {
     await fetch(`${relayUrl(conf)}/send`, {
@@ -223,3 +274,41 @@ export function maybeSpawn(projectDir, conf = readConfig()) {
     return true;
   } catch (e) { process.stderr.write(`[trantor] maybeSpawn error: ${e?.message}\n`); return false; }
 }
+
+// The self-announcing fresh session command (single-quoted so it survives osascript→shell un-escaped).
+export const RECAP_CMD = "claude 'Recap the handoff you just took over — what was the previous session doing, and where do we continue? Then wait for me.'";
+
+// Spawn a fresh self-announcing session WITHOUT the dialog (manual handoff — the user already decided).
+export function spawnFresh(projectDir) {
+  try {
+    if (process.platform !== "darwin" || process.env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
+    const script = join(HERE, "..", "..", "bin", "open-session.sh");
+    if (!existsSync(script)) return false;
+    const child = spawn("/bin/bash", [script, projectDir, RECAP_CMD], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch { return false; }
+}
+
+// Terminal.app's front window (id + tty) — the fallback when there's no controlling tty (a manual
+// handoff runs through the headless Bash tool). The session you're looking at when you invoke it.
+export function frontTerminalWindow() {
+  if (process.platform !== "darwin") return { id: "", tty: "" };
+  try {
+    const out = execSync(`osascript -e ${JSON.stringify(`tell application "Terminal" to return (id of front window as string) & "|" & (tty of selected tab of front window)`)}`,
+      { encoding: "utf8", timeout: 3000 }).trim();
+    const [id, tty] = out.split("|"); return { id: id || "", tty: tty || "" };
+  } catch { return { id: "", tty: "" }; }
+}
+
+// MANUAL one-command baton: spawn the fresh session (no dialog) + arm the close of THIS window once the
+// fresh one consumes the handoff. Window detection: controlling tty first (if invoked with one), else
+// Terminal's front window. Returns { spawned, armed }.
+export function spawnBaton({ projectDir, handoffFile, conf = readConfig() }) {
+  const spawned = spawnFresh(projectDir);
+  if (!spawned) return { spawned: false, armed: false };
+  let tty = controllingTty(), windowId = tty ? terminalWindowForTty(tty) : "";
+  if (!windowId) { const f = frontTerminalWindow(); windowId = f.id; tty = f.tty; }
+  const armed = windowId ? armBatonClose(handoffFile, windowId, tty, conf) : false;
+  return { spawned, armed, windowId };
+}

package/hooks/precompact.mjs

@@ -6,8 +6,8 @@
 // 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 { readConfig, writeHandoff, pingBus, maybeSpawn, armBatonClose,
+         contextUsage, alreadyHandedOff, markHandedOff, controllingTty, terminalWindowForTty } from "./lib/handoff.mjs";
 import { basename } from "node:path";
 
 function readStdin() {
@@ -37,7 +37,11 @@ try {
     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`);
+    // baton pass: arm the close of THIS window once the fresh session takes over (we have the tty here)
+    const tty = controllingTty();
+    const windowId = tty ? terminalWindowForTty(tty) : "";
+    const armed = windowId ? armBatonClose(file, windowId, tty, conf) : false;
+    process.stderr.write(`[trantor] fresh-session spawned (PreCompact)${armed ? ` · baton-close armed for window ${windowId}` : ""}\n`);
   }
 } catch (err) {
   process.stderr.write(`[trantor] precompact error: ${err?.message || err}\n`);

package/package.json

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

package/skills/handoff/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: handoff
 description: |
-  Write a rich handoff for the CURRENT session so a fresh Claude Code session can take over
-  with a full new context window (instead of compacting). Use proactively when context is
-  getting full, or before ending, to pass the baton cleanly. Trigger: /trantor:handoff
+  Finish the CURRENT session in one move: write a rich model-authored handoff, open a fresh
+  full-window session that takes over (it auto-recaps the handoff), and close this one once the
+  fresh session has it — a clean baton pass, one session at a time. Use when you want to wrap up
+  and continue fresh on demand (not just at the compaction threshold). Trigger: /trantor:handoff
 user-invocable: true
 ---
 
@@ -23,14 +24,17 @@ re-deriving context, and save it so the next session in this project auto-loads
    - **KEY FILES & LOCATIONS** — exact paths, commands, URLs, IDs the successor needs
    - **GOTCHAS** — anything that will bite if forgotten
 
-2. Save it by piping the markdown to the helper:
+2. Save it AND pass the baton in one shot — pipe the markdown to the helper with `--baton`:
    ```bash
-   cat << 'HANDOFF' | node "$(dirname "$(command -v claude)")/../<plugin>/bin/write-handoff.mjs"
+   cat << 'HANDOFF' | node "${CLAUDE_PLUGIN_ROOT}/bin/write-handoff.mjs" --baton
    <your handoff markdown>
    HANDOFF
    ```
-   (Or call the plugin's `bin/write-handoff.mjs` directly via its `${CLAUDE_PLUGIN_ROOT}`.)
+   `--baton` writes the handoff, opens a FRESH session that takes over (it auto-recaps the handoff
+   on open), and closes THIS Terminal window once the fresh session has consumed it — a true baton
+   pass, one session at a time. (Omit `--baton` to only write the handoff without spawning/closing.)
+   It's safe: the original window is closed ONLY after the fresh session confirms it took over, and
+   never if the fresh session fails to start.
 
-3. Tell the user: open a fresh terminal + `claude` in this same project directory — the
-   SessionStart hook will detect the handoff and the new session takes over with a full window.
-   (The PreCompact hook also writes one automatically at the compaction threshold.)
+3. Tell the user briefly: "Handoff written — a fresh session is opening and will recap it; this
+   window closes once it takes over." Then stop (the baton will close this session shortly).