trantor 0.17.24 → 0.17.26

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

package/.claude-plugin/plugin.json

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

@@ -42,6 +42,41 @@ claude plugin install trantor
 That's it. (Prefer source? `git clone https://github.com/sashabogi/trantor && cd trantor &&
 npm install && bash deploy/setup.sh` — identical result.)
 
+## What gets installed — footprint & safety
+
+Trantor is a **local-first multi-agent orchestrator with a built-in cost router** — not a cloud
+service, and not an agent that runs off on its own. Here is *exactly* what the two steps above put
+on your machine, so you (or an agent installing it for you) can see the whole footprint up front:
+
+**`npm install -g trantor` + `trantor setup`**
+- The `trantor` CLI — one global npm package.
+- `~/.agent-bus/` — a single local directory holding **all** state: `config.json`, the board data
+  (`bus.json`), and `.env` for any **provider API keys you choose to add** (e.g. `DEEPSEEK_API_KEY`).
+  Nothing in here ever leaves your machine.
+- A local **hub** at `http://127.0.0.1:4477` — **loopback only**, not reachable from the network. On
+  macOS it's a launchd agent (`com.trantor.hub`) so it restarts at login; on Linux you run it yourself.
+- The economics engine (Scrooge) into `~/.local/bin` — the cost ledger and cheap-model router.
+
+**`claude plugin install trantor`** adds, inside Claude Code only:
+- An MCP server (`relay`) exposing the `relay_*` tools, plus the `/trantor:*` skills.
+- Hooks on four events — local Node scripts that only POST to the loopback hub: **SessionStart**
+  (register the session + show the live roster), **PostToolUse** (presence heartbeat + mirror your
+  TodoWrite list onto the board), **PreCompact** (write a handoff before the context window compacts),
+  **SubagentStop** (record each sub-agent's notional cost on the board).
+
+**What it does *not* do:** no cloud, no accounts, no telemetry, nothing phones home; it never uploads
+your code or keys; it doesn't touch other CLIs' credentials — Codex, Gemini, Kimi and DeepSeek are
+ones *you* already installed and signed into, and Trantor just coordinates them locally. The optional
+API keys in `~/.agent-bus/.env` are used only to call the cheap models *you* opted into for routing.
+
+**Remove everything, anytime:**
+```bash
+claude plugin uninstall trantor                  # drop the MCP tools, skills, and hooks
+launchctl bootout gui/$(id -u)/com.trantor.hub   # stop the hub service (macOS)
+rm -f ~/Library/LaunchAgents/com.trantor.hub.plist
+rm -rf ~/.agent-bus                              # delete all local state + keys
+```
+
 ## What to expect on first run
 
 `trantor setup` ends with the **doctor** — an honest map of where you stand:

package/bin/advise.mjs

@@ -14,6 +14,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
 
 const H = homedir();
 const read = (p, fb) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fb; } };
@@ -134,7 +135,9 @@ export function advise(input, world = loadWorld()) {
 }
 
 // ---- CLI ----
-if (import.meta.url === `file://${process.argv[1]}`) {
+// is-main guard via PROPERLY ENCODED file URL — a hand-built `file://${argv[1]}` silently no-ops when the
+// install path contains a URL-reserved char (e.g. a SPACE in ".../Application Support/..."). See profile.mjs.
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
   let input;
   if (process.argv.includes("--demo")) {
     input = { task: "neon asteroids game", packages: [

package/bin/baton-close.mjs

@@ -7,13 +7,55 @@
 // NEVER close the wrong window. Args: <handoffFile> <originalWindowId> <originalTty>
 import { readFileSync, existsSync } from "node:fs";
 import { execSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
 
 const [, , handoffFile, windowId, originalTty] = process.argv;
-const POLL_MS = 1500, TIMEOUT_MS = 120_000;
+const POLL_MS = 1500, TIMEOUT_MS = 180_000;
+// Once the handoff is consumed (= injected into the fresh session's context), wait up to this long for
+// the fresh session to actually PRODUCE its first assistant turn (it boots with `claude 'Recap…'`, so it
+// genuinely reads the handoff and replies) before we close the original. If the fresh session never
+// emits a turn (e.g. it crashed, or a non-recap spawn), we close anyway after this grace so we don't
+// leave two windows forever — the handoff is already in its context, so there's no data loss.
+const ENGAGE_GRACE_MS = 45_000;
 
-const consumed = () => { try { return JSON.parse(readFileSync(handoffFile, "utf8")).consumed === true; } catch { return false; } };
+const handoff = () => { try { return JSON.parse(readFileSync(handoffFile, "utf8")); } catch { return null; } };
+const consumed = () => handoff()?.consumed === true;
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
+// True once the fresh session's transcript shows an assistant turn at/after the handoff was consumed —
+// i.e. the new model has actually read the handoff and started driving (its recap reply). A brand-new
+// session's transcript has no prior assistant turns, so the first one to appear IS the takeover.
+export function freshEngaged(rec) {
+  try {
+    const tp = rec?.consumedBy?.transcript_path;
+    if (!tp || !existsSync(tp)) return false;
+    const consumedAt = Number(rec.consumedAt) || 0;
+    const lines = readFileSync(tp, "utf8").split("\n");
+    for (const ln of lines) {
+      if (!ln) continue;
+      let r; try { r = JSON.parse(ln); } catch { continue; }
+      if (r?.type !== "assistant") continue;
+      const ts = r.timestamp ? Math.floor(Date.parse(r.timestamp) / 1000) : 0;
+      if (!consumedAt || !ts || ts >= consumedAt - 5) return true;
+    }
+    return false;
+  } catch { return false; }
+}
+
+// Wait for genuine takeover (fresh assistant turn) with a bounded grace. Returns when engaged or grace
+// elapsed. If the handoff carries no consumedBy transcript (older record), there's nothing to watch — a
+// short settle and proceed, preserving prior behavior.
+async function waitForTakeover() {
+  const rec = handoff();
+  if (!rec?.consumedBy?.transcript_path) { await sleep(2500); return; }
+  const until = Date.now() + ENGAGE_GRACE_MS;
+  while (Date.now() < until) {
+    if (freshEngaged(handoff())) { await sleep(800); return; }  // small settle after the turn lands
+    await sleep(POLL_MS);
+  }
+  process.stderr.write(`[trantor] baton-close: fresh session consumed but produced no turn within ${ENGAGE_GRACE_MS / 1000}s — closing anyway (handoff already injected)\n`);
+}
+
 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})`)}`,
@@ -37,12 +79,15 @@ function closeWindow(id, tty) {
   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 () => {
+// Only run the close watcher when executed directly — importing this file (tests) must not block.
+const isMain = (() => { try { return import.meta.url === pathToFileURL(process.argv[1]).href; } catch { return false; } })();
+
+if (isMain) (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
+      await waitForTakeover(); // don't close until the fresh session has actually produced its recap turn
       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);

package/bin/doctor.mjs

@@ -54,9 +54,13 @@ else {
 console.log("\ncrew CLIs (install any subset — seats follow the work)");
 const CLIS = [
   { name: "codex",  bin: "codex",    wired: () => (readFileSync(join(H, ".codex", "config.toml"), "utf8")).includes("[mcp_servers.relay]"), auth: () => existsSync(join(H, ".codex", "auth.json")), login: "codex   (sign in with your ChatGPT account on first run)" },
-  { name: "gemini", bin: "gemini",   wired: () => !!read(join(H, ".gemini", "settings.json"))?.mcpServers?.relay, auth: () => existsSync(join(H, ".gemini", "oauth_creds.json")) || !!process.env.GEMINI_API_KEY || !!process.env.GOOGLE_API_KEY, login: "gemini   (Google sign-in on first run, or set GEMINI_API_KEY)" },
+  // Gemini CLI was retired 2026-06-18 for free/Pro/Ultra (Google → Antigravity `agy`). Kept as an
+  // optional seat for enterprise/paid-key holders; for everyone else the seat moved to GLM/opencode,
+  // and Gemini lives on only as a Scrooge cheap-model via GEMINI_API_KEY (the API/models aren't retired).
+  { name: "gemini (CLI retired 2026-06-18)", bin: "gemini",   wired: () => !!read(join(H, ".gemini", "settings.json"))?.mcpServers?.relay, auth: () => existsSync(join(H, ".gemini", "oauth_creds.json")) || !!process.env.GEMINI_API_KEY || !!process.env.GOOGLE_API_KEY, login: "Gemini CLI retired 2026-06-18 (free/Pro/Ultra). Crew seat → GLM (opencode) or Antigravity `agy`. Gemini still serves as a Scrooge cheap-model via GEMINI_API_KEY." },
   { name: "kimi",   bin: "kimi",     wired: () => !!read(join(H, ".kimi", "mcp.json"))?.mcpServers?.relay, auth: () => existsSync(join(H, ".kimi", "credentials")), login: "kimi → /login   (Kimi account or Moonshot API key)" },
   { name: "deepseek (via opencode)", bin: "opencode", wired: () => !!read(join(H, ".config", "opencode", "opencode.json"))?.mcp?.relay, auth: () => !!process.env.DEEPSEEK_API_KEY || (existsSync(join(H, ".agent-bus", ".env")) && readFileSync(join(H, ".agent-bus", ".env"), "utf8").includes("DEEPSEEK_API_KEY")) || !!read(join(H, ".local", "share", "opencode", "auth.json")), login: `get a key at platform.deepseek.com, then: echo 'DEEPSEEK_API_KEY=sk-…' >> ~/.agent-bus/.env` },
+  { name: "glm (via opencode · coding plan)", bin: "opencode", wired: () => !!read(join(H, ".config", "opencode", "opencode.json"))?.mcp?.relay, auth: () => !!read(join(H, ".config", "opencode", "opencode.json"))?.provider?.["zai-coding-plan"]?.options?.apiKey, login: `put your Z.ai coding-plan key at ~/.config/opencode/opencode.json → provider["zai-coding-plan"].options.apiKey, then seat: trantor up opencode:zai-coding-plan/glm-5.1` },
 ];
 let installed = 0;
 for (const c of CLIS) {

package/bin/profile.mjs

@@ -12,9 +12,10 @@
 //                  for real builds; the plan's quota is a scarce budget)
 //   max | max-5x | max-20x | ultra — high-tier subscription (cost moot; context horizon decides)
 //   none         — provider not available on this machine
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
 
 const FILE = join(homedir(), ".agent-bus", "profile.json");
 const KNOWN = ["claude", "codex", "gemini", "kimi", "deepseek", "opencode"];
@@ -32,7 +33,11 @@ export function loadProfile() {
 export function tierOf(profile, provider) { return TIER(profile?.providers?.[provider]?.plan); }
 
 const [, , cmd, ...args] = process.argv;
-if (import.meta.url === `file://${process.argv[1]}`) {
+// is-main guard: compare against a PROPERLY ENCODED file URL. A hand-built `file://${argv[1]}` is raw
+// text, but import.meta.url is percent-encoded — so any URL-reserved char in the install path (most
+// commonly a SPACE, e.g. ".../Application Support/...") made this false and silently skipped main (exit 0,
+// no write). pathToFileURL is the canonical Node idiom. See regression in test-handoff.mjs / test.mjs.
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
   const prof = loadProfile();
   prof.providers ||= {};
   if (cmd === "set") {
@@ -42,6 +47,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       prof.providers[prov.toLowerCase()] = { plan: plan.toLowerCase(), tier: TIER(plan) };
     }
     prof.updated = new Date().toISOString().slice(0, 10);
+    mkdirSync(dirname(FILE), { recursive: true });   // `set` creates its own ~/.agent-bus if absent
     writeFileSync(FILE, JSON.stringify(prof, null, 2) + "\n");
     console.log("profile saved →", FILE);
   } else if (cmd && cmd !== "show") {

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, controllingTty, terminalWindowForTty } from "./lib/handoff.mjs";
+import { readConfig, contextUsage, warnFrac, alreadyHandedOff, markHandedOff, controllingTty, terminalWindowForTty } from "./lib/handoff.mjs";
 import { resolveProject, hostId } from "../lib/project.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
@@ -64,6 +64,12 @@ async function maybeEarlyWarn(stdinRaw, session) {
     const child = spawn(process.execPath, [join(HERE, "handoff-now.mjs"), projectDir, sessionId, transcript, "context-warn", windowId, tty],
       { detached: true, stdio: "ignore" });
     child.unref();
+    // Persistent per-window guard — the SAME one precompact uses. Without this the early-warning was
+    // gated ONLY by the 5-minute inflight stamp, so a session parked above the warn line re-fired every
+    // 5 minutes: a STORM of handoffs + a new fresh window + a new baton-close each tick (seen as 8 stacked
+    // handoffs ~5 min apart). markHandedOff makes alreadyHandedOff() short-circuit until the context
+    // actually resets (<70% of where we fired), so it's exactly ONE baton per context window.
+    markHandedOff(sessionId, usage.tokens);
   } catch {}
 }
 

package/hooks/lib/handoff.mjs

@@ -10,7 +10,7 @@
 // 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 { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, 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";
@@ -203,9 +203,31 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
   };
   const file = join(HANDOFF_DIR, `${record.id}.json`);
   writeFileSync(file, JSON.stringify(record, null, 2));
+  supersedeOlderHandoffs(projectName, record.id);
   return { file, record };
 }
 
+// Retire any OTHER still-unconsumed handoff for the same project the moment a newer one lands. The
+// fresh session loads the newest-unconsumed; leaving stale siblings around means a scrambled spawn
+// (or a future session) could load an out-of-date snapshot. Marking them consumed:true + superseded
+// keeps exactly one live handoff per project. Best-effort; never throws into the caller.
+export function supersedeOlderHandoffs(projectName, keepId) {
+  try {
+    if (!existsSync(HANDOFF_DIR)) return;
+    const re = new RegExp("^" + String(projectName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "-(\\d+)\\.json$");
+    for (const f of readdirSync(HANDOFF_DIR)) {
+      if (!re.test(f)) continue;
+      const p = join(HANDOFF_DIR, f);
+      try {
+        const rec = JSON.parse(readFileSync(p, "utf8"));
+        if (rec.id === keepId || rec.consumed) continue;
+        rec.consumed = true; rec.superseded = true; rec.supersededBy = keepId;
+        writeFileSync(p, JSON.stringify(rec, null, 2));
+      } catch {}
+    }
+  } catch {}
+}
+
 // --- 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 "".
@@ -229,7 +251,12 @@ export function terminalWindowForTty(tty) {
     end repeat
     return ""
   end tell`;
-  try { return execSync(`osascript -e ${JSON.stringify(osa)}`, { encoding: "utf8", timeout: 3000 }).trim(); } catch { return ""; }
+  // Pass the MULTI-LINE script via stdin, NOT `-e ${JSON.stringify(osa)}`: a single -e arg keeps the
+  // newlines as literal "\n" (JSON escapes them, the shell's double-quotes don't expand them), so
+  // osascript saw `…"Terminal"\n  repeat…` and died with "27:28: Expected end of line but found unknown
+  // token". stdin gives it real newlines. (This silently returned "" for years → callers always fell
+  // through to frontTerminalWindow, which after a spawn grabs the WRONG window.)
+  try { return execSync(`osascript`, { input: osa, encoding: "utf8", timeout: 3000 }).trim(); } catch { return ""; }
 }
 
 // Arm the baton-close watcher: a DETACHED process that waits until the fresh session consumes the
@@ -301,14 +328,28 @@ export function frontTerminalWindow() {
   } 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 };
+// Resolve the ORIGINAL window (id + tty) to close on takeover. Controlling tty first (if we were
+// invoked with one — heartbeat/precompact have it), else the CURRENT front window (a manual baton
+// runs through the headless Bash tool with no tty; the session you're looking at is frontmost).
+// MUST be called BEFORE spawning the fresh session — once the new window opens it becomes frontmost
+// and this would capture IT instead.
+export function resolveOriginalWindow() {
   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 { windowId, tty };
+}
+
+// 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.
+export function spawnBaton({ projectDir, handoffFile, conf = readConfig(),
+  _resolveWindow = resolveOriginalWindow, _spawnFresh = spawnFresh, _armClose = armBatonClose }) {
+  const { windowId, tty } = _resolveWindow();   // original window FIRST, while it's still frontmost
+  const spawned = _spawnFresh(projectDir);
+  if (!spawned) return { spawned: false, armed: false, windowId: "" };
+  const armed = windowId ? _armClose(handoffFile, windowId, tty, conf) : false;
   return { spawned, armed, windowId };
 }

package/hooks/sessionstart.mjs

@@ -17,7 +17,7 @@ import { resolveProject, hostId } from "../lib/project.mjs";
 // takes it. A compaction-triggered SessionStart (source="compact") is the SAME session
 // that just wrote the handoff for a FRESH window to pick up — it may show the summary
 // for continuity but must NOT claim it, or it steals the handoff from the new window.
-function loadPendingHandoff(projectName, { claim = true } = {}) {
+function loadPendingHandoff(projectName, { claim = true, freshSession = null } = {}) {
   try {
     const dir = join(homedir(), ".agent-bus", "handoffs");
     if (!existsSync(dir)) return null;
@@ -36,7 +36,23 @@ function loadPendingHandoff(projectName, { claim = true } = {}) {
       const p = join(dir, f);
       const rec = JSON.parse(readFileSync(p, "utf8"));
       if (!rec.consumed) {
-        if (claim) { rec.consumed = true; writeFileSync(p, JSON.stringify(rec, null, 2)); }
+        if (claim) {
+          // `consumed` means "injected into THIS fresh session's first-turn context" — which happens
+          // here at hook time, BEFORE the model has actually read anything. So we also record WHO is
+          // taking over (session id + transcript path) and when. baton-close watches that transcript
+          // for the fresh session's first assistant turn and only then closes the original window —
+          // otherwise it pulled the original ~4s after the fresh window booted, "before it even read
+          // the handoff."
+          rec.consumed = true;
+          rec.consumedAt = nowSec();
+          if (freshSession && (freshSession.session_id || freshSession.transcript_path)) {
+            rec.consumedBy = {
+              session_id: freshSession.session_id || "",
+              transcript_path: freshSession.transcript_path || "",
+            };
+          }
+          writeFileSync(p, JSON.stringify(rec, null, 2));
+        }
         return rec;
       }
     }
@@ -44,6 +60,8 @@ function loadPendingHandoff(projectName, { claim = true } = {}) {
   return null;
 }
 
+function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8" }).trim()) || 0; } catch { return 0; } }
+
 function relayUrl() {
   if (process.env.RELAY_URL) return process.env.RELAY_URL;
   try {
@@ -75,8 +93,8 @@ function sanitize(s) {
 
 let additionalContext = "";
 try {
-  let source = "";
-  try { source = (JSON.parse((await readStdin()) || "{}").source) || ""; } catch {}
+  let source = "", stdinObj = {};
+  try { stdinObj = JSON.parse((await readStdin()) || "{}"); source = stdinObj.source || ""; } catch {}
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // Sessions started in the home directory itself aren't project work — registering
   // them spawns a phantom "<username>" project board on the dashboard. Set
@@ -144,7 +162,10 @@ try {
   // compaction-triggered start, DON'T claim it (that's the same session that wrote it;
   // claiming would steal it from the freshly-spawned window) — show it for continuity only.
   const isCompact = source === "compact";
-  const handoff = loadPendingHandoff(basename(projectDir), { claim: !isCompact });
+  const handoff = loadPendingHandoff(basename(projectDir), {
+    claim: !isCompact,
+    freshSession: { session_id: stdinObj.session_id || "", transcript_path: stdinObj.transcript_path || "" },
+  });
   if (handoff) {
     process.stderr.write(`[trantor] ${isCompact ? "showing (not claiming, compact)" : "loaded"} pending handoff ${handoff.id}\n`);
     additionalContext += `<trantor-handoff id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}" trigger="${sanitize(handoff.trigger)}">\n`;

package/package.json

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

package/skills/research/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: research
+description: |
+  Run a real multi-source web/social research pass with the crew's economics: fan out across the
+  internet (Agent-Reach channels when installed — web/Jina, Exa search, GitHub, YouTube/Bilibili
+  transcripts, Twitter, Reddit, RSS, plus the Chinese platforms — else your own web tools), push the
+  cheap per-source reading to Scrooge, and synthesize a cited answer yourself. Use when the user wants
+  to research / deep-dive / "search the web" / "see what people say about X" / look something up across
+  many sources. Trigger: /trantor:research
+user-invocable: true
+---
+
+# Trantor research — fetch wide, read cheap, synthesize sharp
+
+You are the ARCHITECT of a research pass. The shape mirrors the crew playbook: **fan out to fetch,
+delegate the cheap reading, keep the synthesis.** Never burn frontier tokens scrolling raw pages.
+
+## 1. Scope the question
+Restate the question in one line and list the **angles** that need coverage (e.g. official source,
+practitioner discourse, dissent, recency). Underspecified question → ask 1–2 sharp clarifiers first.
+
+## 2. Pick sources (capability, not habit)
+Run `agent-reach doctor --json` if available to see which backends are live, then choose per angle:
+- **Semantic web search** → `mcporter call 'exa.web_search_exa(query: "…", numResults: 5)'` (free, no key)
+- **Read a page/article** → `curl -s "https://r.jina.ai/<URL>"` (clean markdown, no HTML soup)
+- **Code / repos** → `gh search repos "…" --sort stars` · `gh repo view owner/repo`
+- **Video** → `yt-dlp --write-sub --skip-download -o /tmp/%(id)s "<URL>"` (NEVER yt-dlp for Bilibili → `bili …`)
+- **Discussion** → Twitter (`twitter search`), Reddit (`opencli reddit search` / `rdt search`), V2EX
+- **Chinese platforms** (often weeks ahead on AI) → Bilibili, XiaoHongShu, Zhihu, Weibo, Xueqiu via Agent-Reach
+- **No Agent-Reach?** Fall back to your own WebSearch/WebFetch — the method below still holds.
+
+If Agent-Reach isn't installed and the user wants the full reach, tell them once:
+`帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md`
+
+## 3. Fan out + read cheap
+Collect candidate sources **in parallel** across angles. For each non-trivial source, push the
+read-and-extract to a cheap model instead of reading it yourself:
+`scrooge -t summarize -d easy "<extract the claims + numbers + date relevant to: …>" < source.md`
+(or `relay_scrooge` from inside the crew). Many independent small reads → add `--spread N`. The point:
+frontier tokens go to judgment, cheap tokens go to reading. Announce it (`scrooge watch` shows the feed).
+
+## 4. Verify before you trust
+Cross-check any load-bearing claim against a second independent source. Flag what's a single-source
+claim, what's dated, what's contested. Translate non-English sources and keep the original link.
+
+## 5. Synthesize (this part is yours)
+Write a tight, **cited** answer: the finding, the evidence (with links + dates), the disagreements,
+and the confidence. Lead with what the user didn't already know. End with the open questions a
+follow-up pass should chase.