trantor 0.17.25 → 0.17.26

package/.claude-plugin/plugin.json

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

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.25",
+  "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.