trantor 0.17.25 → 0.17.27

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,104 @@
+// trantor update-check — surfaces "a newer Trantor is available" the way desktop software does:
+// a one-time desktop notification (macOS osascript / Linux notify-send) plus an in-session context
+// block so the running model also tells the user the exact update commands.
+//
+// Design constraints (same contract as the other hooks): cheap, fail-silent, never blocks a session.
+//   • The installed version is self-discovered from the hook's OWN plugin.json (the plugin is installed at
+//     …/cache/trantor/trantor/<version>/…), so there's no guessing.
+//   • "latest" comes from the npm dist-tags endpoint — tiny + no auth — and is THROTTLED behind a TTL
+//     (default 6h) cached in ~/.agent-bus/update-check.json, so the vast majority of session starts do
+//     ZERO network. The fetch itself has a 1.5s timeout and any failure falls back to the cached value.
+//   • The desktop notification fires at most ONCE PER NEW VERSION (tracked by notifiedVersion), so it's
+//     not per-session spam — exactly one ping when a release lands, like a real updater.
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));               // <version>/hooks/lib
+const DATA = process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus");
+const STAMP = join(DATA, "update-check.json");
+const DIST_TAGS_URL = "https://registry.npmjs.org/-/package/trantor/dist-tags";
+
+export function readConfig() {
+  try { const p = join(DATA, "config.json"); return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : {}; }
+  catch { return {}; }
+}
+
+function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8" }).trim()) || 0; } catch { return Math.floor(Date.now() / 1000); } }
+function readStamp() { try { return JSON.parse(readFileSync(STAMP, "utf8")); } catch { return {}; } }
+function writeStamp(o) { try { if (!existsSync(DATA)) mkdirSync(DATA, { recursive: true }); writeFileSync(STAMP, JSON.stringify(o, null, 2)); } catch {} }
+
+// The version of the trantor plugin THIS hook is part of (…/hooks/lib → ../../.claude-plugin/plugin.json).
+// Falls back to the package.json (covers running straight from the repo, where both sit at the root).
+export function installedVersion() {
+  for (const rel of ["../../.claude-plugin/plugin.json", "../../package.json"]) {
+    try { const p = join(HERE, rel); if (existsSync(p)) { const v = JSON.parse(readFileSync(p, "utf8")).version; if (v) return v; } } catch {}
+  }
+  return "";
+}
+
+// Numeric a.b.c compare → -1 | 0 | 1. (Pre-release tags aren't used by trantor's release flow, so a
+// plain numeric compare is correct and keeps this dependency-free.)
+export function cmpSemver(a, b) {
+  const pa = String(a).split(".").map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) { if ((pa[i] || 0) < (pb[i] || 0)) return -1; if ((pa[i] || 0) > (pb[i] || 0)) return 1; }
+  return 0;
+}
+
+// Latest published version, throttled by TTL. Returns the cached value on a fresh-enough check or on any
+// network failure; refetches (and re-stamps) only when the cache is stale. Never throws.
+export async function latestVersion(conf = readConfig()) {
+  const ttlH = Number(process.env.TRANTOR_UPDATE_TTL_H || conf.updateCheckTtlHours || 6);
+  const stamp = readStamp();
+  if (stamp.latest && stamp.checkedAt && (nowSec() - stamp.checkedAt) < ttlH * 3600) return stamp.latest;
+  try {
+    const r = await fetch(DIST_TAGS_URL, { signal: AbortSignal.timeout(1500) });
+    const j = await r.json();
+    const latest = j?.latest || stamp.latest || "";
+    writeStamp({ ...stamp, checkedAt: nowSec(), latest });
+    return latest;
+  } catch { return stamp.latest || ""; }
+}
+
+// { available, installed, latest } — `available` true only when installed < latest. Disabled by
+// TRANTOR_NO_UPDATE_CHECK=1 or config.updateCheck:false.
+export async function updateAvailable(conf = readConfig()) {
+  if (process.env.TRANTOR_NO_UPDATE_CHECK === "1" || conf.updateCheck === false) return { available: false, installed: "", latest: "" };
+  const installed = installedVersion();
+  const latest = await latestVersion(conf);
+  if (!installed || !latest) return { available: false, installed, latest };
+  return { available: cmpSemver(installed, latest) < 0, installed, latest };
+}
+
+// Fire a native desktop notification — but only ONCE per new version (so multiple session starts don't
+// each pop one). Returns true if it actually notified. Disabled by TRANTOR_NO_UPDATE_NOTIFY=1 or
+// config.updateDesktopNotify:false. Best-effort; never throws.
+export function maybeNotifyDesktop({ installed, latest } = {}, conf = readConfig()) {
+  try {
+    if (!latest) return false;
+    if (process.env.TRANTOR_NO_UPDATE_NOTIFY === "1" || conf.updateDesktopNotify === false) return false;
+    if (readStamp().notifiedVersion === latest) return false;     // already told them about THIS version
+    const title = "Trantor update available";
+    const msg = `${installed || "?"} → ${latest}. Update: claude plugin update trantor@trantor`;
+    if (process.platform === "darwin") {
+      let done = false;
+      try { execSync("command -v terminal-notifier", { stdio: "ignore" });
+        execSync(`terminal-notifier -title ${JSON.stringify(title)} -message ${JSON.stringify(msg)} -group trantor-update`, { timeout: 3000 });
+        done = true;
+      } catch {}
+      if (!done) {
+        const osa = `display notification ${JSON.stringify(msg)} with title ${JSON.stringify(title)}`;
+        execSync(`osascript -e ${JSON.stringify(osa)}`, { timeout: 3000 });
+      }
+    } else if (process.platform === "linux") {
+      execSync(`notify-send ${JSON.stringify(title)} ${JSON.stringify(msg)}`, { timeout: 3000 });
+    } else {
+      return false;
+    }
+    writeStamp({ ...readStamp(), notifiedVersion: latest });
+    return true;
+  } catch { return false; }
+}

package/hooks/sessionstart.mjs

@@ -11,13 +11,14 @@ import { join, basename } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execSync } from "node:child_process";
 import { resolveProject, hostId } from "../lib/project.mjs";
+import { updateAvailable, maybeNotifyDesktop } from "./lib/update-check.mjs";
 
 // Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs
 // / the heartbeat early-warning). `claim` marks it consumed so exactly one session
 // 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 +37,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 +61,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 +94,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
@@ -139,12 +158,30 @@ try {
     }
   } catch {}
 
+  // Update available? Like a desktop app's "an update is ready" — surface it two ways: a one-time
+  // native desktop notification (once per new version, not per session) AND an in-session context
+  // block so the running model can tell the user the exact update commands. Throttled + fail-silent;
+  // most starts do zero network (6h TTL cache). Disable: TRANTOR_NO_UPDATE_CHECK / _NOTIFY.
+  try {
+    const upd = await updateAvailable();
+    if (upd.available) {
+      maybeNotifyDesktop(upd);
+      additionalContext += `<trantor-update installed="${sanitize(upd.installed)}" latest="${sanitize(upd.latest)}">\n`;
+      additionalContext += `⬆️ **A newer Trantor is available — ${sanitize(upd.installed)} → ${sanitize(upd.latest)}.** Tell the user, and offer the update: \`claude plugin update trantor@trantor\` (plugin) + \`npm i -g trantor@${sanitize(upd.latest)}\` (CLI), then restart to apply.\n`;
+      additionalContext += `</trantor-update>\n`;
+      process.stderr.write(`[trantor] update available: ${upd.installed} -> ${upd.latest}\n`);
+    }
+  } catch {}
+
   // Pending handoff? A prior session hit the context limit and left a handoff for this
   // project — take over with this fresh full window instead of starting cold. On a
   // 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.27",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -10,7 +10,7 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs"
+    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs && node test-update.mjs"
   },
   "description": "The hub-world for AI agent crews \u2014 orchestrate Claude Code, Codex, Gemini, Kimi & DeepSeek as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
   "files": [

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.