trantor 0.17.39 → 0.17.41

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

package/.claude-plugin/plugin.json

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

@@ -30,7 +30,7 @@ function findTranscript() {
 }
 
 const transcript = findTranscript();
-const { file } = writeHandoff({ projectDir: cwd, sessionId: "", transcript, trigger: "manual-cli" });
+const { file } = writeHandoff({ projectDir: cwd, sessionId: "", transcript, trigger: "manual-cli", force: true });   // manual = intentional, bypass the storm guard
 console.log(`📋 handoff saved for ${project}: ${file}`);
 const { spawned, armed, windowId } = spawnBaton({ projectDir: cwd, handoffFile: file });
 console.log(spawned

package/hooks/handoff-now.mjs

@@ -12,7 +12,9 @@ import { basename } from "node:path";
 const [, , projectDir = process.cwd(), sessionId = "", transcript = "", trigger = "context-warn", windowId = "", tty = ""] = process.argv;
 try {
   const conf = readConfig();
-  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
+  const result = writeHandoff({ projectDir, sessionId, transcript, trigger });   // auto path — honors the hub storm guard
+  if (result.skipped) { process.stderr.write(`[trantor] handoff SKIPPED by storm-guard (${result.reason}; ${result.sinceSec ?? "?"}s since last) — no fresh window spawned\n`); process.exit(0); }
+  const { file, record } = result;
   process.stderr.write(`[trantor] baton handoff written: ${file}\n`);
   await pingBus(basename(projectDir), record.id, conf);
   if (maybeSpawn(projectDir, conf)) {                 // open the fresh session that takes over

package/hooks/heartbeat.mjs

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { readConfig, contextUsage, warnFrac, alreadyHandedOff, markHandedOff, controllingTty, terminalWindowForTty, subagentsActive } from "./lib/handoff.mjs";
 import { resolveProject, hostId } from "../lib/project.mjs";
+import { installedVersion } from "./lib/update-check.mjs";   // report our hook version so the hub can flag stale sessions
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500);
@@ -121,7 +122,7 @@ async function main(stdinRaw) {
     await fetch(`${relayUrl()}/register`, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ session, project }),
+      body: JSON.stringify({ session, project, hookVersion: (() => { try { return installedVersion(); } catch { return ""; } })() }),
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
   } catch {}

package/hooks/hooks.json

@@ -1,11 +1,12 @@
 {
-  "description": "trantor — auto-register each session + inject live roster (SessionStart); heartbeat presence on every tool call + mirror the session's TodoWrite list onto the board as cards (PostToolUse); write a handoff before compaction (PreCompact); card each sub-agent's notional API cost when it finishes (SubagentStop)",
+  "description": "trantor — auto-register each session + inject live roster (SessionStart); heartbeat presence on every tool call + deliver unread bus messages to a busy session mid-turn + mirror the session's TodoWrite list onto the board as cards (PostToolUse); write a handoff before compaction (PreCompact); card each sub-agent's notional API cost when it finishes (SubagentStop)",
   "hooks": {
     "SessionStart": [
       { "matcher": "", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart.mjs" } ] }
     ],
     "PostToolUse": [
       { "matcher": "", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/heartbeat.mjs" } ] },
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/inbox-deliver.mjs" } ] },
       { "matcher": "TodoWrite", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/todo-sync.mjs" } ] }
     ],
     "PreCompact": [

package/hooks/inbox-deliver.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// trantor PostToolUse inbox delivery — surface bus messages to a BUSY session.
+//
+// The bug this fixes: Trantor message delivery is pure pull-on-demand. relay_send only
+// enqueues on the hub; the recipient learns of a message ONLY when the model itself
+// chooses to call relay_inbox/relay_wait. A session grinding through a long tool-use loop
+// never makes that choice, so it sits "online" (the heartbeat keeps lastSeen fresh) but
+// DEAF — a peer can ping it twice over 10 minutes and get no reply. (Observed 2026-06-23:
+// a new session pinged a mid-build sibling; the sibling never answered because it was busy
+// and never polled.)
+//
+// The fix, hook-side (don't trust the model to poll): a busy session IS firing tool calls,
+// so this PostToolUse hook runs constantly. Each run polls /inbox and injects any NEW peer
+// messages via hookSpecificOutput.additionalContext — which Claude Code delivers as a
+// system reminder the model acts on IN THE SAME TURN, between its own tool calls. So a ping
+// lands within a few seconds even mid-build, and the model can reply via relay_send without
+// waiting for the human to prompt it.
+//
+// Cheap + fail-silent by contract: a per-session poll stamp gates the network call, a short
+// fetch timeout means we never add real latency, and we ALWAYS exit clean with valid stdout.
+// First run initialises the cursor to "now" (current max id) and injects NOTHING, so a
+// session is never flooded with the whole backlog of old broadcasts on its first tool call.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveProject, hostId } from "../lib/project.mjs";
+
+const POLL_MS = Number(process.env.RELAY_INBOX_POLL_MS || 4000);
+const FETCH_TIMEOUT_MS = Number(process.env.RELAY_INBOX_TIMEOUT_MS || 1500);
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    if (existsSync(cfg)) { const u = JSON.parse(readFileSync(cfg, "utf8")).url; if (u) return u; }
+  } catch {}
+  return "http://127.0.0.1:4477";
+}
+
+// Keep injected text safe to embed in JSON: drop control chars that could corrupt the
+// additionalContext payload (the model still gets the readable message).
+function sanitize(s) { return String(s == null ? "" : s).replace(/[\x00-\x1f\x7f-\x9f]/g, " "); }
+
+async function getInbox(url, session, since) {
+  const r = await fetch(`${url}/inbox?session=${encodeURIComponent(session)}&since=${since}`,
+    { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!r.ok) throw new Error(`hub ${r.status}`);
+  return r.json();   // { messages: [...], cursor }
+}
+
+// PostToolUse hands us the tool-input JSON on stdin. We don't need it, but we must DRAIN it:
+// a large tool input (e.g. a big Write) can exceed the 64KB pipe buffer and block the parent's
+// write if nobody reads. Consume + discard, with a short timeout so we never hang.
+function drainStdin() {
+  return new Promise(res => {
+    try { process.stdin.resume(); process.stdin.on("data", () => {}); process.stdin.on("end", res); }
+    catch { res(); }
+    setTimeout(res, 80);
+  });
+}
+
+// Self-validating stdout: model-facing additionalContext only when we actually deliver.
+function emit(ctx) {
+  if (!ctx) return "{}";
+  const obj = { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: ctx } };
+  const out = JSON.stringify(obj);
+  try { JSON.parse(out); return out; } catch { return "{}"; }
+}
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // Mirror heartbeat.mjs / sessionstart.mjs: a home-directory session isn't project work and
+  // isn't on the bus — nothing to deliver. Opt in with RELAY_SESSION / RELAY_PROJECT.
+  if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && projectDir === homedir()) return "{}";
+
+  // Resolve THIS session's identity EXACTLY as mcp.mjs / heartbeat.mjs do, so we poll the
+  // same peer the relay registered (RELAY_SESSION wins; else RELAY_AGENT brand; else host:project).
+  const project = resolveProject(projectDir);
+  const session = process.env.RELAY_SESSION
+    || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
+
+  const safe = session.replace(/[^A-Za-z0-9_.-]/g, "_");
+  const dir = join(homedir(), ".agent-bus");
+  const pollStamp = join(dir, `inbox-poll-${safe}.stamp`);
+  const cursorFile = join(dir, `inbox-cursor-${safe}.id`);
+
+  // Throttle: poll the hub at most once per POLL_MS. Write the stamp BEFORE the network call
+  // so a burst of parallel tool calls doesn't all fire (and double-deliver).
+  try {
+    if (existsSync(pollStamp)) {
+      const last = Number(readFileSync(pollStamp, "utf8")) || 0;
+      if (Date.now() - last < POLL_MS) return "{}";   // within window — skip
+    }
+  } catch {}
+  try { writeFileSync(pollStamp, String(Date.now())); } catch {}
+
+  const url = relayUrl();
+
+  // First run: no cursor yet. Initialise to the current max deliverable id and inject NOTHING,
+  // so we start listening "from now" instead of replaying the whole backlog of old broadcasts.
+  if (!existsSync(cursorFile)) {
+    try {
+      const { cursor } = await getInbox(url, session, 0);
+      writeFileSync(cursorFile, String(cursor || 0));
+    } catch {}
+    return "{}";
+  }
+
+  let cursor = 0;
+  try { cursor = Number(readFileSync(cursorFile, "utf8")) || 0; } catch {}
+
+  let messages = [], next = cursor;
+  try {
+    const res = await getInbox(url, session, cursor);
+    messages = Array.isArray(res.messages) ? res.messages : [];
+    next = res.cursor || cursor;
+  } catch { return "{}"; }   // hub down / timeout — never block the tool flow
+
+  if (!messages.length) return "{}";
+
+  // Advance the cursor immediately so we don't re-inject these on the next tool call.
+  try { writeFileSync(cursorFile, String(next)); } catch {}
+
+  const lines = messages.map(m => {
+    const direct = m.to === session;
+    const tag = direct ? "📨 DIRECT" : "📣 broadcast";
+    const when = (() => { try { return new Date(m.ts).toLocaleTimeString(); } catch { return ""; } })();
+    return `- ${tag} from ${sanitize(m.from)}${when ? ` (${when})` : ""}: ${sanitize(m.text)}`;
+  });
+
+  const ctx =
+    `<trantor-inbox count="${messages.length}">\n` +
+    `📬 ${messages.length} new bus message(s) arrived while you were working (you did not poll for these — Trantor surfaced them automatically):\n` +
+    lines.join("\n") + `\n` +
+    `If a peer is asking you something or waiting on you, reply now with the relay_send tool (to their session id). ` +
+    `If a message just needs an ack, send a short one. You can keep working after responding.\n` +
+    `</trantor-inbox>\n`;
+
+  return emit(ctx);
+}
+
+// Never block or break the tool flow: drain stdin, swallow everything, always emit valid stdout.
+drainStdin()
+  .then(main)
+  .then(out => { try { process.stdout.write(out || "{}"); } catch {} })
+  .catch(() => { try { process.stdout.write("{}"); } catch {} })
+  .finally(() => process.exit(0));

package/hooks/lib/handoff.mjs

@@ -213,8 +213,21 @@ export function verbatimRecentTail(transcript, chars = 7000) {
 }
 
 // ---- write + announce + spawn ----------------------------------------------
-export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary }) {
+export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary, force = false }) {
   const projectName = basename(projectDir);
+  // Server-side storm guard: a session running OLD hooks (before the local markHandedOff guard) re-fires
+  // context-warn handoffs every few minutes — the crebral-cortex storm (9 in 49 min, each spawning a
+  // window). Ask the hub for clearance (rate-limit per project+session); a non-forced handoff inside the
+  // cooldown is SKIPPED — no file, no spawn. Manual (/trantor:handoff) + at-wall (precompact) handoffs
+  // force through. Fail-OPEN if the hub is unreachable, so a legit handoff is never blocked.
+  if (!force) {
+    try {
+      const body = JSON.stringify({ project: projectName, session: sessionId || "", trigger: trigger || "auto" });
+      const out = execSync(`curl -s --max-time 2 -X POST -H 'content-type: application/json' -d ${JSON.stringify(body)} ${JSON.stringify(relayUrl() + "/handoff")}`, { encoding: "utf8", timeout: 2500 });
+      const r = JSON.parse(out);
+      if (r && r.allow === false) return { skipped: true, reason: r.reason || "storm-guard", sinceSec: r.sinceSec };
+    } catch {}
+  }
   if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
   const stamp = nowSec() || Date.now();
   let gitStatus = "";

package/hooks/precompact.mjs

@@ -25,7 +25,7 @@ try {
   const sessionId = input.session_id || "";
   const conf = readConfig();
 
-  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
+  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger, force: true });   // at-wall backstop — must never be storm-guard-suppressed
   process.stderr.write(`[trantor] handoff written: ${file} (trigger=${trigger})\n`);
 
   await pingBus(projectName, record.id, conf);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.39",
+  "version": "0.17.41",
   "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 && node test-agents.mjs && node test-update.mjs && node test-balances.mjs && node test-subagent-cost.mjs"
+    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs && node test-agents.mjs && node test-update.mjs && node test-handoff-guard.mjs && node test-balances.mjs && node test-subagent-cost.mjs && node test-inbox.mjs"
   },
   "description": "The hub-world for AI agent crews — 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/ui.html

@@ -53,6 +53,7 @@ main:not(.learn-open) .learn-body{display:none}
 .agents{display:flex;gap:6px;flex-wrap:wrap}
 .agent{display:flex;align-items:center;gap:5px;background:var(--card);border:1px solid var(--line);border-radius:16px;padding:2px 9px 2px 6px;font-size:11.5px;color:var(--mut)}
 .agent .nm{color:var(--tx)}
+.agent .stale{font-size:9.5px;font-weight:700;color:#ffb454;background:#2a1f10;border:1px solid #5a3c1a;border-radius:7px;padding:1px 5px;cursor:help}
 .agent svg{flex:none}
 .agent.offl{opacity:.42}
 .agent.err{border-color:#ef4444;color:#ef4444}
@@ -768,7 +769,7 @@ async function render(){
     const pmsgs = msgs.filter(m=>projOf(m)===p.project);
     const done=pt.filter(t=>t.status==='done').length;
     const pct=pt.length?Math.round(done/pt.length*100):0;
-    const agents=p.agents.sort((a,b)=>b.online-a.online).map(a=>`<span class="agent ${a.online?'':'offl'}${a.health==='down'?' down':a.health==='errored'?' err':''}" title="${esc(a.session)}${a.online?' · online':' · offline'}${a.health&&a.health!=='ok'?' · '+a.health:''}">${iconFor(a.session,15)}<span class="nm">${esc(a.session)}</span>${a.status?` <span class="ast">· ${esc(a.status)}</span>`:''}${poolOf(a.session)?` <span class="ast" style="opacity:.7">[${esc(poolOf(a.session))}]</span>`:''}</span>`).join('');
+    const agents=p.agents.sort((a,b)=>b.online-a.online).map(a=>`<span class="agent ${a.online?'':'offl'}${a.health==='down'?' down':a.health==='errored'?' err':''}" title="${esc(a.session)}${a.online?' · online':' · offline'}${a.health&&a.health!=='ok'?' · '+a.health:''}${a.staleHooks?' · OLD Trantor hooks ('+esc(a.hookVersion)+') — restart this session to get the baton safety fixes':''}">${iconFor(a.session,15)}<span class="nm">${esc(a.session)}</span>${a.staleHooks?` <span class="stale" title="running old Trantor hooks (${esc(a.hookVersion)}) — restart to load the baton storm/kill safety fixes">⚠ old hooks</span>`:''}${a.status?` <span class="ast">· ${esc(a.status)}</span>`:''}${poolOf(a.session)?` <span class="ast" style="opacity:.7">[${esc(poolOf(a.session))}]</span>`:''}</span>`).join('');
     const cols=COLS.map(([k,label])=>{
       let cards=pt.filter(t=>k==='testing'?(t.status==='testing'||t.status==='failed'):t.status===k);
       if(k==='done')cards=[...cards].sort((a,b)=>(b.updated||0)-(a.updated||0)); // newest finished on top