trantor 0.17.95 → 0.17.97

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.95",
+  "version": "0.17.97",
   "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/hooks/heartbeat.mjs

@@ -18,13 +18,14 @@ 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, markHandedOff, controllingTty, terminalWindowForTty, subagentsActive } from "./lib/handoff.mjs";
+import { armBaton, readArm, clearArm, 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
 import { signedPost } from "./lib/api.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500);
+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));
 
@@ -83,25 +84,56 @@ async function maybeEarlyWarn(stdinRaw, session) {
 
     // In-flight guard: the detached worker takes ~tens of seconds to summarize;
     // don't launch a second one on the next heartbeat tick meanwhile.
+    // NOTE the ordering: this debounce guards the SPAWN, not the arming. It used to sit here and
+    // return before any of the logic below, which meant the arm/backstop path never ran a second
+    // time and a session that reached no turn boundary would stay armed forever. Arming is cheap
+    // and idempotent; only launching the worker needs debouncing.
     const inflight = join(homedir(), ".agent-bus", `handoff-inflight-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);
-    try { if (existsSync(inflight) && Date.now() - (Number(readFileSync(inflight, "utf8")) || 0) < INFLIGHT_MS) return; } catch {}
-    try { writeFileSync(inflight, String(Date.now())); } catch {}
+    const spawnDebounced = () => {
+      try { if (existsSync(inflight) && Date.now() - (Number(readFileSync(inflight, "utf8")) || 0) < INFLIGHT_MS) return false; } catch {}
+      try { writeFileSync(inflight, String(Date.now())); } catch {}
+      return true;
+    };
 
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     // Detect THIS session's Terminal window NOW (the hook has the controlling tty; the detached worker
     // won't) so the baton-close can replace this exact window once the fresh session takes over.
     const tty = controllingTty();
     const windowId = tty ? terminalWindowForTty(tty) : "";
-    process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% of ${usage.window} — baton pass (window ${windowId || "?"})\n`);
-    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);
+    // ARM, do not fire. This hook is PostToolUse: the only moment it can ever run is between two
+    // tool calls, i.e. mid-turn. Firing here produced a handoff written 36 seconds before the work
+    // it described was committed (2026-08-24), and the successor reported four finished things as
+    // still open. The Stop hook fires it at the next turn boundary, where the turn is complete.
+    //
+    // The window id and tty are captured HERE on purpose: this hook has the controlling tty and the
+    // detached worker does not, so the baton-close can still replace this exact window later.
+    const armed = readArm(sessionId);
+    const age = armed ? Date.now() - (Number(armed.ts) || 0) : 0;
+    if (armed && age < ARM_MAX_MS) {
+      process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% — baton already armed ${Math.round(age / 1000)}s ago, waiting for a turn boundary\n`);
+      return;
+    }
+    if (armed) {
+      // Backstop: a session that never reaches a Stop (parked, or looping without ending a turn)
+      // must still hand off rather than never. Fire it directly and say that is what happened.
+      process.stderr.write(`[trantor] baton armed ${Math.round(age / 60000)}m ago with no turn boundary — firing anyway\n`);
+      clearArm(sessionId);
+      if (spawnDebounced()) {
+        const child = spawn(process.execPath, [join(HERE, "handoff-now.mjs"), projectDir, sessionId, transcript, "context-warn", windowId, tty],
+          { detached: true, stdio: "ignore" });
+        child.unref();
+        markHandedOff(sessionId, usage.tokens);
+      }
+      return;
+    }
+    process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% of ${usage.window} — arming the baton for the next turn boundary (window ${windowId || "?"})\n`);
+    // Arming does NOT markHandedOff. That guard exists so a session parked above the warn line does
+    // not re-fire every tick (8 stacked handoffs ~5 min apart, once observed) — but it makes
+    // alreadyHandedOff() short-circuit this whole block, so marking at ARM time meant no later
+    // heartbeat could ever run the backstop and a session that reached no Stop stayed armed
+    // 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 });
   } 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, readdirSync, statSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, openSync, readSync, fstatSync, closeSync, rmSync } from "node:fs";
 import { join, basename, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execSync, spawn } from "node:child_process";
@@ -116,6 +116,30 @@ function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8"
 // window up (or, before the 2026-06-21 fix, kill the original) while real in-flight agent work is
 // running. INCIDENT 2026-06-21: a 90% baton fired mid 2-agent build and the original session was
 // SIGKILLed mid-flight. Best-effort; returns false on any error.
+// ---- ARMING: the baton waits for a turn boundary --------------------------------------------
+// The heartbeat runs on PostToolUse, so the only moment it can ever fire is BETWEEN TWO TOOL CALLS
+// — the middle of a turn. On 2026-08-24 that produced a handoff written 36 seconds before the work
+// it described was committed, and the successor reported four finished things as still open.
+// subagentsActive() was the only mid-flight guard and it only sees spawned sub-agents, not a
+// session driving tool calls in its own loop.
+//
+// So the threshold ARMS and the Stop hook FIRES: at a Stop the turn is complete, which is the only
+// point where a summary can describe something finished. One resolver for the marker path, used by
+// both hooks, because two hooks disagreeing about a file path is its own recurring bug here.
+export function armPath(sessionId) {
+  const safe = String(sessionId || "s").replace(/[^A-Za-z0-9_.-]/g, "_");
+  return join(process.env.AGENT_BUS_DIR || process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus"), `handoff-armed-${safe}.json`);
+}
+export function armBaton(sessionId, payload) {
+  try { writeFileSync(armPath(sessionId), JSON.stringify({ ts: Date.now(), ...payload })); return true; } catch { return false; }
+}
+export function readArm(sessionId) {
+  try { const p = armPath(sessionId); if (!existsSync(p)) return null; return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+export function clearArm(sessionId) {
+  try { rmSync(armPath(sessionId), { force: true }); } catch {}
+}
+
 export function subagentsActive(transcriptPath, withinMs = 90_000) {
   try {
     if (!transcriptPath) return false;

package/hooks/stop-inbox.mjs

@@ -22,11 +22,16 @@
 //     delivered and then letting the stop through would hide it from the waker too — a silent hole.
 //   * Any error, or a hub that is down -> allow the stop. Never trap a session because of us.
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { signedGet } from "./lib/api.mjs";   // signed: enforce hubs 401 unsigned reads — unsigned, T2 delivery is silently dead
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
+import { readArm, clearArm, markHandedOff } from "./lib/handoff.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
 
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_STOP_TIMEOUT_MS || 1500);
 
@@ -103,6 +108,27 @@ async function main() {
   if (process.env.RELAY_STOP_INBOX === "0") return allow();
 
   const projectDir = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // A Stop IS the turn boundary. If the heartbeat armed a baton while this session was mid-turn,
+  // this is the first honest moment to fire it: the turn is complete, so the summary describes
+  // finished work rather than a session thirty seconds from its own conclusions. Fired detached and
+  // never awaited, and the arming is cleared FIRST so a crash in the worker cannot re-fire it on
+  // every subsequent Stop.
+  try {
+    const armed = readArm(input.session_id || "");
+    if (armed) {
+      clearArm(input.session_id || "");
+      const kid = spawn(process.execPath, [join(HERE, "handoff-now.mjs"),
+        armed.projectDir || projectDir, String(input.session_id || ""), armed.transcript || "",
+        armed.reason || "context-warn", armed.windowId || "", armed.tty || ""],
+        { detached: true, stdio: "ignore" });
+      kid.unref();
+      // Mark it here, on the path that actually fired, so a session parked above the warn line
+      // cannot re-arm and re-fire every tick.
+      try { markHandedOff(String(input.session_id || ""), Number(armed.tokens) || 0); } catch {}
+      process.stderr.write("[trantor] turn boundary reached — firing the armed baton\n");
+    }
+  } catch {}
   // Mirror the other hooks: a home-directory session isn't project work and isn't on the bus.
   if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && projectDir === homedir()) return allow();
 

package/hub.mjs

@@ -2266,6 +2266,25 @@ const server = http.createServer(async (req, res) => {
     // outcome: strictly by `re`, or, for seats that predate it, oldest-open-first. Broadcasts are
     // never contracts. Each open one carries the assignee's presence, because the actionable half
     // of "still waiting" is whether anyone is still on the other end.
+    // ---- /delivered: an endpoint that has actually READ its mail says so ----------------------
+    // The desktop app lists with peek=1 on purpose, so it never steals a message from a session's
+    // delivery hooks. For a HUMAN endpoint there are no hooks — the app is the only reader — so
+    // sasha@mac's deliveredUpTo sat at 0 forever while mail piled up. dutyTick then escalated every
+    // message the human had already read, told the duty seat about it, the seat messaged the human,
+    // and that was undelivered too: about six escalations a minute, all about mail already read.
+    // Peeking stays the default; this lets a reader record delivery explicitly instead.
+    if (req.method === "POST" && P === "/delivered") {
+      const b = await body(req);
+      const session = String(b.session || "");
+      if (!session) return json(res, 400, { error: "session required" });
+      if (auth?.identity && String(auth.identity.name || "") !== session) {
+        return json(res, 403, { error: "session must match signer" });
+      }
+      touch(session, undefined, undefined, undefined, auth);
+      markDelivered(session, Number(b.upTo || 0));
+      return json(res, 200, { ok: true, deliveredUpTo: state.peers[session]?.deliveredUpTo || 0 });
+    }
+
     if (req.method === "GET" && P === "/contracts") {
       const session = String(q.session || "");
       if (!session) return json(res, 400, { error: "session required" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.95",
+  "version": "0.17.97",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -11,7 +11,7 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "test": "node bin/slop-gate.mjs --surface desktop/src && node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-redelivery.mjs && node test-crew-completion.mjs && node test-contracts.mjs && node test-handoff.mjs && node test-handoff-summarizer.mjs && node test-agents.mjs && node test-update.mjs && node test-handoff-guard.mjs && node test-baton-latest.mjs && node test-balances.mjs && node test-subagent-cost.mjs && node test-inbox.mjs && node test-inflight.mjs && node test-notify.mjs && node test-focus.mjs && node test-cardlog.mjs && node test-relay-note.mjs && node test-reaper.mjs && node test-events.mjs && node test-proposals.mjs && node test-scrub.mjs && node test-store-delta.mjs && node test-message-re.mjs && node test-claims.mjs && node test-adopt.mjs && node test-summarize.mjs && node test-identity-core.mjs && node test-identity.mjs && node test-identity-instances.mjs && node test-duty.mjs && node test-duty-seat.mjs && node test-discovery.mjs && node test-doctor.mjs && node test-splitbrain.mjs && node test-overseer.mjs && node test-overseer-lib.mjs && node test-overseer-warn.mjs && node test-provider-keys.mjs && node test-inbox-delivery.mjs && node test-identity-drift.mjs && node test-inbox-staleness.mjs && node test-seats.mjs && node test-seat-identity.mjs && node test-hub-routing.mjs && node test-hook-routing.mjs && node test-relay-wait.mjs && node test-dsh-seat.mjs && node test-kimi-bridge.mjs && node test-kimi-events.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && node test-resources.mjs && node test-patrol.mjs && node test-bridge.mjs && bash test-crew.sh"
+    "test": "node bin/slop-gate.mjs --surface desktop/src && node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-redelivery.mjs && node test-crew-completion.mjs && node test-contracts.mjs && node test-handoff.mjs && node test-handoff-summarizer.mjs && node test-baton-turn-boundary.mjs && node test-agents.mjs && node test-update.mjs && node test-handoff-guard.mjs && node test-baton-latest.mjs && node test-balances.mjs && node test-subagent-cost.mjs && node test-inbox.mjs && node test-inflight.mjs && node test-notify.mjs && node test-focus.mjs && node test-cardlog.mjs && node test-relay-note.mjs && node test-reaper.mjs && node test-events.mjs && node test-proposals.mjs && node test-scrub.mjs && node test-store-delta.mjs && node test-message-re.mjs && node test-claims.mjs && node test-adopt.mjs && node test-summarize.mjs && node test-identity-core.mjs && node test-identity.mjs && node test-identity-instances.mjs && node test-duty.mjs && node test-duty-seat.mjs && node test-discovery.mjs && node test-doctor.mjs && node test-splitbrain.mjs && node test-overseer.mjs && node test-overseer-lib.mjs && node test-overseer-warn.mjs && node test-provider-keys.mjs && node test-inbox-delivery.mjs && node test-identity-drift.mjs && node test-inbox-staleness.mjs && node test-seats.mjs && node test-seat-identity.mjs && node test-hub-routing.mjs && node test-hook-routing.mjs && node test-relay-wait.mjs && node test-dsh-seat.mjs && node test-kimi-bridge.mjs && node test-kimi-events.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && node test-resources.mjs && node test-patrol.mjs && node test-bridge.mjs && bash test-crew.sh"
   },
   "description": "The hub-world for AI agent crews \u2014 orchestrate Claude Code, Codex, GLM, Kimi, DeepSeek & any OpenRouter model as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
   "files": [