trantor 0.18.17 → 0.18.18

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.17",
+  "version": "0.18.18",
   "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/README.md

@@ -348,6 +348,14 @@ same project **takes over with a brand-new full context window**. Works manually
 agent via `relay_handoff`. Optional macOS auto-prompt (`autoHandoffPrompt` in
 `~/.agent-bus/config.json`) offers to open the fresh session for you, with a timeout.
 
+Since 0.18.18 the succession is a machine, not a ritual: at 90% context the running agent is
+told to finish or checkpoint and author the boundary handoff itself; the app's banner counts
+down ("handing off in 10s") when the dial allows; an automatic digest defers to a fresh
+model-authored handoff instead of superseding it; the successor is injected a capped ≤4KB recap
+(the verbatim tail stays on disk, one path away) and gets a kickoff prompt so it recaps without
+being spoken to; and a session hosted in a Workspace pane is replaced in place by a detached
+driver — the same chain the app's [Hand off now] button runs.
+
 Why crews never exhaust the orchestrator: bus messages are **by reference** (~70 tokens),
 work products stay in each agent's own context — the orchestrator burns at coordination
 rate, not work rate.

package/bin/baton-pane.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// The --baton pane leg (#5643). When the dying session lives in a hosted pane, the Terminal
+// spawn is exactly wrong (the fresh window lands on the surface the operator is leaving), so
+// spawnFresh refuses — and until now the chain dead-ended at "open a new session manually".
+// A session cannot replace itself (SYSTEM-CONTRACT §5): this helper is the outside hand, run
+// DETACHED from the dying session so it survives it. The chain mirrors the app's proven
+// handoff_now (lib.rs): idle-gate → graceful end → reopen → kickoff prompt over the socket.
+//
+//   node bin/baton-pane.mjs --project <dir> --handoff <file> [--pane <id>]
+//
+// Env seams (the drill's off switches, same doctrine as TRANTOR_NO_HANDOFF_SPAWN):
+//   TRANTOR_BATON_IDLE_DEADLINE_S  give up waiting for idle after this many seconds (default 600)
+//   TRANTOR_BATON_REOPEN           command to reopen the pane, instead of `trantor open`
+//                                  (the drill points this at its own herdr world)
+// Detached means nobody reads stdout: everything lands in <bus>/logs/baton-pane-<project>.log.
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync, execSync } from "node:child_process";
+import { createConnection } from "node:net";
+
+const arg = (name) => { const i = process.argv.indexOf(name); return i > 0 ? process.argv[i + 1] : ""; };
+const projectDir = arg("--project") || process.cwd();
+const handoffFile = arg("--handoff");
+const projectName = basename(projectDir);
+const busDir = process.env.AGENT_BUS_DIR || process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus");
+
+const logDir = join(busDir, "logs");
+try { mkdirSync(logDir, { recursive: true }); } catch {}
+const logFile = join(logDir, `baton-pane-${projectName}.log`);
+const log = (s) => { try { appendFileSync(logFile, `${new Date().toISOString()} ${s}\n`); } catch {} };
+
+// Same text as the app's kickoff (lib.rs KICKOFF_PROMPT) — one boot prompt so the successor
+// recaps unprompted instead of sitting idle until a human types (the 15-minute silence, #5649).
+const KICKOFF_PROMPT = "You have just taken over via handoff. Recap now per your instructions.";
+
+// The pane, resolved exactly like the app does (orch_pane_from_rows): last orch row wins.
+export function orchPane(rows, project) {
+  let pane = null;
+  for (const l of String(rows).split("\n")) {
+    const f = l.split("\t");
+    if (f[0] === project && f[1] === "orch" && f[3] && f[3].trim()) pane = f[3].trim();
+  }
+  return pane;
+}
+
+function herdrJson(args) {
+  try { return JSON.parse(execFileSync("herdr", args, { encoding: "utf8", timeout: 15000 })); } catch { return null; }
+}
+
+/** One request over herdr's socket — byte-identical to the app's transport (herdr.rs). */
+function socketRequest(req, timeoutMs = 30_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); });
+  });
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+const agentStatus = (pane) => herdrJson(["agent", "get", pane])?.result?.agent?.agent_status || null;
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+async function main() {
+  if (!handoffFile || !existsSync(handoffFile)) { log(`no handoff file (${handoffFile}) — abort`); process.exit(1); }
+  const pane = arg("--pane") || orchPane((() => { try { return readFileSync(join(busDir, "crew-windows.txt"), "utf8"); } catch { return ""; } })(), projectName);
+  if (!pane) { log(`no orch pane row for ${projectName} — abort (the window path should have run instead)`); process.exit(1); }
+  log(`armed: pane=${pane} handoff=${basename(handoffFile)}`);
+
+  // 1. Idle gate. The dying session invoked us MID-TURN (the skill's Bash call); ending it now
+  //    would kill in-flight work — the exact failure #5645 exists to prevent. Wait for the turn
+  //    boundary, with a deadline so a hung session doesn't pin this process forever.
+  const deadline = Date.now() + (Number(process.env.TRANTOR_BATON_IDLE_DEADLINE_S) || 600) * 1000;
+  let st;
+  while ((st = agentStatus(pane)) === "working") {
+    if (Date.now() > deadline) { log(`idle deadline passed (still ${st}) — giving up, handoff waits on disk`); process.exit(1); }
+    await sleep(3000);
+  }
+  log(`idle gate passed (status=${st ?? "no agent"})`);
+
+  // 2. Graceful end, mirroring end_process_gracefully: TERM, short wait, KILL.
+  const info = herdrJson(["pane", "process-info", "--pane", pane])?.result?.process_info;
+  const pid = Number(info?.foreground_process_group_id) || Number(info?.foreground_processes?.[0]?.pid) || 0;
+  if (pid > 0 && alive(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch {}
+    const killAt = Date.now() + 10_000;
+    while (alive(pid) && Date.now() < killAt) await sleep(200);
+    if (alive(pid)) { try { process.kill(pid, "SIGKILL"); } catch {} }
+    log(`ended pid ${pid}`);
+  } else {
+    log("no foreground process to end (already gone)");
+  }
+
+  // 3. Reopen. `trantor open` rebinds orch-sessions.txt and restarts the pane's session — the
+  //    bookkeeping the classic seam regression comes from skipping. The drill overrides this to
+  //    stay inside its own herdr world.
+  const reopen = process.env.TRANTOR_BATON_REOPEN || "trantor open";
+  try {
+    execSync(reopen, { cwd: projectDir, encoding: "utf8", timeout: 120_000, stdio: "pipe" });
+    log(`reopened via: ${reopen}`);
+  } catch (e) {
+    log(`reopen FAILED (${String(e?.message).slice(0, 200)}) — handoff waits on disk`);
+    process.exit(1);
+  }
+
+  // 4. Kickoff — retry while the successor boots; a NotReady prompt would land on nobody.
+  for (let i = 0; i < 20; i++) {
+    if (agentStatus(pane) === "idle") break;
+    await sleep(3000);
+  }
+  try {
+    const raw = await socketRequest({ id: "trantor:agent.prompt", method: "agent.prompt", params: { target: pane, text: KICKOFF_PROMPT } });
+    log(`kickoff: ${String(JSON.parse(raw).result?.type)}`);
+  } catch (e) {
+    log(`kickoff FAILED (${String(e?.message).slice(0, 120)}) — successor may sit idle until spoken to`);
+  }
+}
+
+// Import-safe (the drill imports orchPane): only run as a script.
+if (process.argv[1] && basename(process.argv[1]) === "baton-pane.mjs") {
+  main().catch(e => { log(`crash: ${String(e?.stack || e).slice(0, 400)}`); process.exit(1); });
+}

package/bin/drill-surface.mjs

@@ -16,7 +16,7 @@
 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 { execFileSync, execSync, spawn } from "node:child_process";
 import { createConnection } from "node:net";
 
 const KEEP = process.argv.includes("--keep");
@@ -297,6 +297,72 @@ 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.`);
 }
 
+// ---------- S4b · the --baton pane leg (#5643) ----------
+// The CLI-side replacement chain: a MANUAL handoff on disk, then bin/baton-pane.mjs (the detached
+// driver spawnBaton arms for hosted panes) replaces the pane's session in place — idle gate,
+// graceful end, reopen, kickoff — and the successor claims AND recaps with no human prompt.
+// The reopen is overridden to stay inside this drill's herdr world; the chain is otherwise the
+// production one. The routing itself (spawnBaton → driver, never a window) is drilled hermetically
+// in test-handoff.mjs.
+step("S4b · --baton pane leg: the driver replaces the session in place, kickoff recaps it");
+{
+  let st0 = null;
+  try { st0 = herdr(["agent", "get", pane]).result?.agent?.agent_status || null; } catch {}
+  if (!st0) {
+    SKIP("--baton pane leg", "no live agent in the pane (S4 did not leave a successor)");
+  } else {
+    let hf = null;
+    try {
+      const wh = execFileSync(process.execPath, [join(import.meta.dirname, "write-handoff.mjs")], {
+        input: "# handoff\nS4b: the pane leg drill — recap me.", encoding: "utf8", timeout: 30_000,
+        env: { ...process.env, CLAUDE_PROJECT_DIR: proj, AGENT_BUS_DIR: bus, TRANTOR_NO_HANDOFF_SPAWN: "1", TRANTOR_NO_BATON_SPAWN: "1" },
+      });
+      hf = /handoff saved: (\S+\.json)/.exec(wh)?.[1] || null;
+    } catch (e) { FAIL("S4b manual handoff written", String(e.message || e).slice(0, 120)); }
+    if (hf) {
+      PASS("manual handoff written for the pane to carry", basename(hf));
+      const child = spawn(process.execPath, [join(import.meta.dirname, "baton-pane.mjs"),
+        "--project", proj, "--handoff", hf, "--pane", pane], {
+        env: { ...process.env, AGENT_BUS_DIR: bus, TRANTOR_BATON_IDLE_DEADLINE_S: "90",
+          TRANTOR_BATON_REOPEN: `herdr agent start drill3 --kind claude --pane ${pane}` },
+        stdio: "ignore",
+      });
+      const exited = new Promise(res => child.on("exit", c => res(c)));
+      // Environment noise, not the leg: a fresh session may block on the trust dialog; answer it
+      // the way startClaude does so the kickoff has someone to land on.
+      const watcher = (async () => {
+        for (let i = 0; i < 40; i++) {
+          await sleep(3000);
+          try {
+            const g = herdr(["agent", "get", "drill3"]);
+            const st = g.result?.agent?.agent_status;
+            if (st === "blocked") herdr(["agent", "send-keys", "drill3", "enter"]);
+            if (st === "idle") break;
+          } catch {}
+        }
+      })();
+      const code = await Promise.race([exited, sleep(180_000).then(() => "timeout")]);
+      await watcher;
+      if (code === 0) PASS("driver ran the whole chain (idle gate → graceful end → reopen → kickoff)");
+      else FAIL("driver ran the whole chain", `exit ${code} — see ${join(bus, "logs")}/baton-pane-*.log`);
+      const rec = await waitFor("S4b claimed+recapped", () => {
+        try {
+          const r = JSON.parse(readFileSync(hf, "utf8"));
+          const s = (r.states || []).map(x => x.state);
+          return s.includes("claimed") && s.includes("recapped") ? r : null;
+        } catch { return null; }
+      }, { timeoutMs: 120_000, everyMs: 2_000 });
+      if (rec) PASS("successor claimed AND recapped — kicked off by the driver, no human prompt",
+        rec.states.map(s => s.state).join("→"));
+      else {
+        let states = "unreadable";
+        try { states = JSON.parse(readFileSync(hf, "utf8")).states?.map(s => s.state).join(",") || "none"; } catch {}
+        FAIL("successor claimed AND recapped without a human prompt", states);
+      }
+    }
+  }
+}
+
 // ---------- 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");

package/bin/write-handoff.mjs

@@ -6,7 +6,7 @@ import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from
 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";
+import { spawnBaton, handoffMode } from "../hooks/lib/handoff.mjs";
 import { handoffDir } from "../lib/project.mjs";
 
 const baton = process.argv.includes("--baton");
@@ -46,19 +46,24 @@ if (latest) {
     .find(p => { try { return JSON.parse(readFileSync(p, "utf8")).consumed === false; } catch { return false; } });
   if (!found) { console.error(`no unconsumed handoff for "${name}" in ${dir} — write one first (pipe it in), then baton it`); process.exit(1); }
   console.log(`baton on the existing handoff: ${found}`);
-  const { spawned, armed, windowId } = spawnBaton({ projectDir: project, handoffFile: found });
-  if (spawned) console.log(`baton: fresh session opening (self-recapping)${armed ? ` — this window (${windowId}) closes once it takes over` : ""}`);
+  const r = spawnBaton({ projectDir: project, handoffFile: found });
+  if (r.pane && r.spawned) console.log("baton: pane replacement armed (#5643) — this session ends at the turn boundary and the pane reopens fresh, self-recapping");
+  else if (r.spawned) console.log(`baton: fresh session opening (self-recapping)${r.armed ? ` — this window (${r.windowId}) closes once it takes over` : ""}`);
   else console.log("baton: could not spawn a fresh session (non-macOS or spawn disabled) — handoff is saved, open a new session manually");
   process.exit(0);
 }
 
-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 };
+// The manual skill path opens the §5 ledger with WRITTEN like every other writer (#5642), and
+// carries the same interface the hooks-side records have: transcript_path ("" — the summary IS
+// the model's own words), mode (attended|unattended, #5648).
+const rec = { id: `${name}-${stamp}`, project, projectName: name, machine: hostname(), trigger: baton ? "manual-baton" : "manual-skill", stamp: Number(stamp) || 0, summary: summary.trim() || "(empty)", transcript_path: "", mode: handoffMode(name), gitStatus: git, consumed: false, states: [{ state: "written", ts: Number(stamp) || 0, by: baton ? "manual-baton" : "manual-skill" }] };
 const file = join(dir, `${rec.id}.json`);
 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)"}`);
+  const r = spawnBaton({ projectDir: project, handoffFile: file });
+  if (r.pane && r.spawned) console.log("baton: pane replacement armed (#5643) — this session ends at the turn boundary and the pane reopens fresh, self-recapping");
+  else if (r.spawned) console.log(`baton: fresh session opening (self-recapping)${r.armed ? ` — this window (${r.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/heartbeat.mjs

@@ -29,6 +29,16 @@ const ARM_MAX_MS = Number(process.env.TRANTOR_BATON_ARM_MAX_MS || 15 * 60 * 1000
 const INFLIGHT_MS = 5 * 60 * 1000;
 const HERE = dirname(fileURLToPath(import.meta.url));
 
+// #5645 agent-aware succession: the moment the baton ARMS (warn frac, auto dial), the running agent
+// is TOLD — via this hook's PostToolUse additionalContext, the one sanctioned channel that reaches a
+// session mid-flow without driving its terminal. The agent then participates in its own succession:
+// it reaches a real task boundary and authors the model-written handoff from the FRESHEST state,
+// instead of the digest describing work 36 seconds stale (2026-08-24) or missing everything done
+// after an early handoff write. Injected ONCE per arming (the fresh-arm path only) — a per-tool-call
+// reminder would be context spam. Guards stay upstream: no arm mid-sub-agent build, no arm in 'ask'
+// dial mode, so neither produces the notice.
+let ARM_CTX = "";
+
 // The model this session is ACTUALLY running, read from the transcript tail — the harness does not
 // hand hooks a model field, but every assistant entry records one. Tail-read only (transcripts grow
 // to MBs); any failure returns "" and the peer simply keeps its last known model.
@@ -143,6 +153,11 @@ async function maybeEarlyWarn(stdinRaw, session) {
     // forever. It is marked where the baton actually fires: here on the backstop path, and in the
     // Stop hook on the normal path. Re-arming every tick is prevented by the age check above.
     armBaton(sessionId, { projectDir, transcript, reason: "context-warn", windowId, tty, tokens: usage.tokens });
+    // Tell the RUNNING agent (once, at arm time): wrap up and author the boundary handoff yourself.
+    ARM_CTX = `<system-reminder>TRANTOR SUCCESSION ARMED — this session is at ${Math.round(usage.frac * 100)}% of its context window, and the baton is armed: your NEXT STOP fires the handoff. You are now responsible for your own succession:\n`
+      + `1. Reach a real task boundary — finish, pause, or checkpoint your in-flight work NOW; do not start new work.\n`
+      + `2. Author (or refresh) the rich handoff from your CURRENT state — via the handoff skill or the relay_handoff MCP tool — so the successor gets the freshest picture, not a digest of a session 36 seconds stale. A fresh model-authored handoff supersedes the auto-digest.\n`
+      + `3. Then end your turn. The Stop hook fires the baton at that boundary.</system-reminder>`;
   } catch {}
 }
 
@@ -216,4 +231,14 @@ async function main(stdinRaw) {
 }
 
 // Never block or break the tool flow: swallow everything, always exit clean.
-readStdin().then(main).catch(() => {}).finally(() => process.exit(0));
+// stdout carries the arm-time succession notice (above) when — and only when — this tick armed
+// the baton; every other tick emits "{}", exactly as inbox-deliver.mjs does on a quiet poll.
+function emitAndExit() {
+  try {
+    process.stdout.write(ARM_CTX
+      ? JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: ARM_CTX } })
+      : "{}");
+  } catch {}
+  process.exit(0);
+}
+readStdin().then(main).catch(() => {}).finally(emitAndExit);

package/hooks/lib/handoff.mjs

@@ -17,6 +17,7 @@ import { execSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { deriveSubagentManifest } from "../../lib/subagent-manifest.mjs";
 import { signedPost } from "./api.mjs";
+import { loadAutonomy, resolveAutonomy } from "../../lib/autonomy.mjs";
 
 // Writer and reader MUST resolve the same directory — see lib/project.mjs busDir(). This used to
 // honour only RELAY_DATA_DIR while the reader honoured neither override.
@@ -307,6 +308,68 @@ export function verbatimRecentTail(transcript, chars = 7000) {
   try { return collectTurns(transcript).join("\n\n").slice(-chars); } catch { return ""; }
 }
 
+// ---- #5648: handoff writer discipline --------------------------------------
+// The inline summary is the RECAP, not the record: the successor reads it as a hook injection,
+// and an oversized injection gets persisted to a file the successor re-reads — paying twice for
+// the same context. Cap the composed digest at ~4KB. When it must cut, keep BOTH ends a successor
+// needs — the opening (task & goal framing) and the tail (current state) — cutting each on a
+// paragraph boundary, with an explicit elision marker so nobody mistakes the middle for missing.
+export function capSummary(text, cap = 4096) {
+  const s = String(text || "");
+  if (s.length <= cap) return s;
+  const elide = "\n\n[…]\n\n";
+  const headRaw = s.slice(0, Math.max(0, cap - elide.length - 2048));
+  const hCut = headRaw.lastIndexOf("\n\n");
+  const head = hCut > 200 ? headRaw.slice(0, hCut) : headRaw;
+  let tail = s.slice(s.length - (cap - head.length - elide.length));
+  const tCut = tail.indexOf("\n\n");
+  if (tCut > 0 && tCut < 2000) tail = tail.slice(tCut + 2);   // drop the partial opening line
+  return head + elide + tail;
+}
+
+// How fresh a model-authored handoff must be before an automatic digest DEFERS to it: 15 minutes.
+// Older than that, the state it describes has likely moved on — compose fresh.
+const FRESH_HANDOFF_SEC = 15 * 60;
+const MANUAL_TRIGGERS = ["manual-skill", "manual-baton"];
+
+// The newest unconsumed MODEL-authored handoff (the /trantor:handoff skill / manual baton path)
+// for this project, if it is still fresh. Incident (#5648): minutes after the operator hand-wrote
+// trantor-1788141357, an automatic digest recomposed and SUPERSEDED it — the successor then
+// loaded the machine's lossy summary instead of the author's exact words. The digest is the
+// fallback, never the replacement.
+export function freshAuthoredHandoff(projectName, nowS = nowSec() || Math.floor(Date.now() / 1000)) {
+  try {
+    if (!existsSync(HANDOFF_DIR)) return null;
+    const re = new RegExp("^" + String(projectName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "-(\\d+)\\.json$");
+    const cands = readdirSync(HANDOFF_DIR)
+      .map(f => { const m = re.exec(f); return m ? { f, stamp: Number(m[1]) } : null; })
+      .filter(Boolean)
+      .sort((a, b) => b.stamp - a.stamp)
+      .map(x => join(HANDOFF_DIR, x.f));
+    for (const p of cands) {
+      try {
+        const r = JSON.parse(readFileSync(p, "utf8"));
+        if (r.consumed !== false) continue;
+        if (!MANUAL_TRIGGERS.includes(r.trigger)) continue;
+        if (nowS - (Number(r.stamp) || 0) > FRESH_HANDOFF_SEC) continue;
+        return r;
+      } catch {}
+    }
+  } catch {}
+  return null;
+}
+
+// mode:"attended"|"unattended" on every handoff record (#5648) — WHO pulls the baton trigger.
+// Read from the resolved autonomy dials (the same JSON `trantor autonomy json` prints):
+// baton:"auto" means the arm-at-warn → fire-at-turn-boundary chain runs itself (unattended);
+// the default "ask" keeps the operator in the loop (attended). Fail closed to "attended".
+export function handoffMode(projectName) {
+  try {
+    const a = resolveAutonomy(projectName, loadAutonomy());
+    return a.baton === "auto" ? "unattended" : "attended";
+  } catch { return "attended"; }
+}
+
 // ---- 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
@@ -338,11 +401,18 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     } catch {}
   }
   if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
+  // #5648: an automatic digest must never recompose+supersede a FRESH model-authored handoff.
+  // If one exists (<15min, unconsumed), point the baton at THAT and write nothing — the caller's
+  // spawn path proceeds on the authored handoff exactly as if it had just written it.
+  const fresh = freshAuthoredHandoff(projectName);
+  if (fresh) return { deferred: true, file: join(HANDOFF_DIR, `${fresh.id}.json`), record: fresh };
   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);
+  // Cap the composed narrative to the injection budget (~4KB). The verbatim tail is deliberately
+  // NOT embedded anymore: the record's transcript_path points at the full exchange, and embedding
+  // it here doubled the successor's read for state that was already one path away (#5648).
+  const narrative = capSummary(summary ?? buildSummary(transcript));
   // Sub-agent manifest SNAPSHOT (fallback). The successor should re-derive it LIVE via
   // `trantor agents <sid>` (catches files an agent finished that were clobbered AFTER this
   // snapshot — the kill that motivated this corrupted a completed 30KB lib post-handoff). This
@@ -363,8 +433,10 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     project: projectDir, projectName, machine: hostname(),
     session_id: sessionId || "", trigger: trigger || "auto",
     transcript_path: transcript || "", stamp: Number(stamp) || 0,
-    // 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}` : ""),
+    // recap-sufficient inline summary, capped ~4KB — the full story lives at transcript_path
+    summary: narrative,
+    // attended|unattended — who pulls the baton trigger (resolved autonomy `baton` dial)
+    mode: handoffMode(projectName),
     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 || "" }],
@@ -543,14 +615,31 @@ export function resolveOriginalWindow() {
   return { windowId, tty };
 }
 
+// The pane leg of the baton (#5643): hand the replacement to a DETACHED driver (bin/baton-pane.mjs)
+// that survives this session's death — idle-gate → graceful end → trantor open → kickoff. The
+// window machinery (resolve/arm-close) is deliberately absent here: there is no window to close,
+// and the old path's answer ("spawn disabled — open manually") left the operator doing the
+// machine's job by hand.
+export function spawnPaneBaton(projectDir, handoffFile) {
+  try {
+    const script = join(HERE, "..", "..", "bin", "baton-pane.mjs");
+    if (!existsSync(script)) return false;
+    const child = spawn(process.execPath, [script, "--project", projectDir, "--handoff", handoffFile], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch { return false; }
+}
+
 // MANUAL one-command baton: spawn the fresh session (no dialog) + arm the close of THIS window once the
 // fresh one consumes the handoff. Returns { spawned, armed, windowId }.
 // ORDER IS LOAD-BEARING: resolve the original window BEFORE spawning. Reversing it is the
 // "successor closes ITSELF" bug — the just-opened window is frontmost, the front-window fallback
 // captures it, and baton-close then kills the FRESH session the moment it takes over. The seams
-// (_resolveWindow/_spawnFresh/_armClose) exist so the ordering can be regression-tested headlessly.
+// (_resolveWindow/_spawnFresh/_armClose/_hasPane/_spawnPane) exist so the ordering can be
+// regression-tested headlessly.
 export function spawnBaton({ projectDir, handoffFile, conf = readConfig(),
-  _resolveWindow = resolveOriginalWindow, _spawnFresh = spawnFresh, _armClose = armBatonClose }) {
+  _resolveWindow = resolveOriginalWindow, _spawnFresh = spawnFresh, _armClose = armBatonClose,
+  _hasPane = hasOrchPane, _spawnPane = spawnPaneBaton }) {
   // A DRILL MUST BE ABLE TO SAY NO. There was no such switch, so exercising the baton path in a
   // test opened real Terminal windows running real `claude` sessions in temp directories the test
   // then deleted, each parked on a "do you trust this folder?" prompt. Five of them were found by
@@ -559,6 +648,12 @@ export function spawnBaton({ projectDir, handoffFile, conf = readConfig(),
   if (spawnSuppressed() || conf.batonSpawn === false) {
     return { spawned: false, armed: false, windowId: "", suppressed: true };
   }
+  // Hosted pane (#5643): the pane IS the successor surface — no window is resolved, spawned, or
+  // armed for closing. The detached driver replaces the session at the turn boundary.
+  if (_hasPane(basename(projectDir))) {
+    const spawned = _spawnPane(projectDir, handoffFile);
+    return { spawned, armed: false, windowId: "", pane: true };
+  }
   const { windowId, tty } = _resolveWindow();   // original window FIRST, while it's still frontmost
   const spawned = _spawnFresh(projectDir);
   if (!spawned) return { spawned: false, armed: false, windowId: "" };

package/hooks/prompt-focus.mjs

@@ -43,7 +43,12 @@ function loadRecapCtx(sessionId) {
     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>`;
+    // #5645 mandate pinning: the stamp carries rec.mode — the reminder enforces the SAME succession
+    // mandate the sessionstart injection announced, right up to the first Stop that records RECAPPED.
+    const mandate = rec.mode === "unattended"
+      ? " Then RESUME the handoff's OPEN THREADS immediately — they are your work order; this succession is unattended, do NOT wait for the user."
+      : " Then WAIT for the user.";
+    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.${mandate}</system-reminder>`;
   } catch { return ""; }
 }
 function emitAndExit() {

package/hooks/sessionstart.mjs

@@ -67,8 +67,10 @@ function loadPendingHandoff(projectName, { claim = true, freshSession = null } =
           writeFileSync(p, JSON.stringify(rec, null, 2));
           if (freshSession?.session_id) {
             try {
+              // #5645: the mandate rides the stamp too, so prompt-focus's recap reminder pins
+              // the SAME rec.mode the injection below announces (attended=WAIT / unattended=RESUME).
               writeFileSync(join(dir, `recap-pending-${String(freshSession.session_id).replace(/[^A-Za-z0-9_.-]/g, "_")}.json`),
-                JSON.stringify({ handoffId: rec.id, ts: nowSec() }));
+                JSON.stringify({ handoffId: rec.id, ts: nowSec(), mode: rec.mode === "unattended" ? "unattended" : "attended" }));
             } catch {}
           }
         }
@@ -109,6 +111,26 @@ function sanitize(s) {
   return out;
 }
 
+// #5645 injection cap: the handoff injection is a POINTER, not a payload. The 2026-08-30 failure:
+// a 22KB record (narrative + embedded verbatim tail) was injected and then re-read, costing ~9% of
+// the fresh window at boot. The writer contract (#5648, hooks/lib) caps rec.summary at ~4KB and
+// keeps the verbatim tail OUT of it; this reader enforces the same bound against older/oversized
+// records — strip any embedded verbatim block, hard-cap on a line boundary, point at the record
+// file + transcript for the rest.
+const HANDOFF_INJECT_CAP = 4096;
+function capHandoffSummary(handoff) {
+  let s = String(handoff?.summary || "");
+  const marker = s.indexOf("\n---\n## Verbatim recent exchange");
+  if (marker > 0) s = s.slice(0, marker);
+  if (s.length <= HANDOFF_INJECT_CAP) return s;
+  const cut = s.slice(0, HANDOFF_INJECT_CAP);
+  const nl = cut.lastIndexOf("\n");
+  s = (nl > HANDOFF_INJECT_CAP * 0.6 ? cut.slice(0, nl) : cut).trimEnd();
+  let ptr = `\n\n…(summary capped at ${HANDOFF_INJECT_CAP} chars — full record: ${join(handoffDir(), `${handoff.id}.json`)}`;
+  if (handoff.transcript_path) ptr += ` · full transcript: ${handoff.transcript_path}`;
+  return s + ptr + ")";
+}
+
 // Fail-silent wrapper for the optional #4214 resources detection lib (hooks/lib/resources.mjs).
 // A throwing detector — or a half-landed lib whose export isn't a function yet — must never break
 // session start; this returns dft on any error. The lib is itself fail-silent, this is defense-in-depth.
@@ -454,8 +476,15 @@ try {
     if (claimed && stdinObj.session_id) {
       await jpost(`${url}/instance/supersede`, { name: session, exceptInstanceId: String(stdinObj.session_id) }, session).catch(() => {});
     }
-    additionalContext += `<trantor-handoff id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}" trigger="${sanitize(handoff.trigger)}">\n`;
-    additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch. Recap the task, state, and next step in at most 3 sentences, then wait. Keep replies short: no status tables, no headers, no walls of text unless the user explicitly asks for detail.\n\n`;
+    additionalContext += `<trantor-handoff id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}" trigger="${sanitize(handoff.trigger)}" mode="${sanitize(handoff.mode === "unattended" ? "unattended" : "attended")}">\n`;
+    // #5645 mandate pinning: the successor's orders ride rec.mode (#5644's long-run switch flips it).
+    // attended (default) = recap-then-WAIT; unattended = recap-then-RESUME — the handoff's OPEN
+    // THREADS are the work order ("handoffs must never be a break").
+    if (handoff.mode === "unattended") {
+      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit, in UNATTENDED (long-run) mode.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch. Recap the task, state, and next step in at most 3 sentences, then RESUME the open threads immediately — they are your work order. Do NOT wait for the user; keep building. Keep replies short: no status tables, no headers, no walls of text.\n\n`;
+    } else {
+      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch. Recap the task, state, and next step in at most 3 sentences, then wait. Keep replies short: no status tables, no headers, no walls of text unless the user explicitly asks for detail.\n\n`;
+    }
     // Verification gates FIRST — these are structured "must verify before shipping" claims the prior
     // session couldn't independently prove. They go above the summary on purpose: a safety-critical
     // check must not be skimmed past (the lesson of the lost "verify Gail coefficients" intent).
@@ -469,7 +498,7 @@ try {
       }
       additionalContext += `\n`;
     }
-    additionalContext += `## Handoff summary\n${sanitize(handoff.summary)}\n`;
+    additionalContext += `## Handoff summary\n${sanitize(capHandoffSummary(handoff))}\n`;
     if (handoff.gitStatus) additionalContext += `\n## Git working-tree at handoff\n\`\`\`\n${sanitize(handoff.gitStatus)}\n\`\`\`\n`;
     // Sub-agent manifest: LIVE-primary, snapshot-as-fallback. The prior session may have had
     // sub-agents (Agent/Task, Workflow) building things you can't see in its narrative — and a

package/package.json

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

package/skills/handoff/SKILL.md

@@ -13,6 +13,11 @@ user-invocable: true
 Write a complete handoff capturing everything a NEW session needs to continue this work without
 re-deriving context, and save it so the next session in this project auto-loads it on start.
 
+Hosted in a Workspace pane? Since 0.18.18 `--baton` detects the pane and drives the in-place
+replacement itself (idle gate, graceful end, reopen, kickoff prompt) — no Terminal window opens,
+and the successor recaps unprompted. Nothing extra to do; the notes below about windows apply
+only to plain Terminal sessions.
+
 ## Instructions
 
 0. **Already written one this session?** Then do NOT write it again — pass the baton on it: