trantor 0.17.64 → 0.17.66

package/.claude-plugin/plugin.json

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

@@ -147,6 +147,22 @@ async function main(stdinRaw) {
     }
   } catch {}
 
+  // Overseer narration, same ambient pattern (10-min machine-wide stamp): the narrate worker was
+  // built "to run ambiently from the heartbeat" but was never actually wired in — warns sat
+  // mechanical forever unless someone ran it by hand. The worker exits in one cheap signed GET per
+  // hub when nothing is unnarrated; Scrooge is only invoked when there IS a warn to explain.
+  try {
+    const narStamp = join(homedir(), ".agent-bus", "narrate.stamp");
+    const last = existsSync(narStamp) ? Number(readFileSync(narStamp, "utf8")) || 0 : 0;
+    if (Date.now() - last > 10 * 60 * 1000) {
+      writeFileSync(narStamp, String(Date.now()));
+      const worker = spawn(process.execPath, [join(HERE, "..", "bin", "overseer-narrate.mjs"), "--quiet"], {
+        detached: true, stdio: "ignore",
+      });
+      worker.unref();
+    }
+  } catch {}
+
   // Same cadence as the presence ping: check context pressure and hand off early
   // if we've crossed the warn threshold of a known window.
   await maybeEarlyWarn(stdinRaw, session);

package/hub.mjs

@@ -212,8 +212,20 @@ async function reloadFromStore() {
 let _overseer = null;
 import("./lib/overseer.mjs").then(m => { _overseer = m; }).catch(() => {});
 const OVERSEER_TICK_MS = Number(process.env.RELAY_OVERSEER_TICK_MS || 30 * 1000);
-const OVERSEER_DEDUP_MS = Number(process.env.RELAY_OVERSEER_DEDUP_MS || 10 * 60 * 1000);
-const overseerWarned = new Map();   // dedup key -> ts
+// How long a condition must be ABSENT before we consider the episode over. This is NOT a re-warn
+// timer: see overseerTick.
+const OVERSEER_CLEAR_MS = Number(process.env.RELAY_OVERSEER_CLEAR_MS || process.env.RELAY_OVERSEER_DEDUP_MS || 10 * 60 * 1000);
+// Standing conditions, keyed by collision identity -> { since, lastTick }. A collision is a STATE,
+// not an event: it persists. Emitting on a 10-minute timer turned the watcher into a metronome —
+// 500 events for 4 distinct conditions (2026-08-12 audit), each one also waking the duty seat for a
+// full turn. Now an episode fires ONCE when it starts and stays quiet while it holds; the entry is
+// forgotten only after the condition has been gone for OVERSEER_CLEAR_MS, so a genuine recurrence
+// warns again.
+const overseerActive = new Map();
+// Heartbeat for the WATCHER itself: /overseer/status must distinguish "fleet is clear" from "the
+// overseer stopped ticking" — a monitor that cannot prove it is alive reads as clear when dead.
+let overseerLastTick = 0;
+let overseerLastCollisions = [];
 function overseerPolicy() {
   const p = state.orgPolicy && typeof state.orgPolicy === "object" ? state.orgPolicy : {};
   return {
@@ -236,13 +248,18 @@ function overseerTick() {
   if (!_overseer?.detectCollisions) return;
   let collisions = [];
   try { collisions = _overseer.detectCollisions(overseerInputs()) || []; } catch { return; }
-  const cut = now() - OVERSEER_DEDUP_MS;
-  for (const [k, ts] of overseerWarned) if (ts < cut) overseerWarned.delete(k);
+  const t = now();
+  overseerLastTick = t;
   const pol = overseerPolicy();
+  const seen = new Set();
   for (const c of collisions) {
     const key = `${c.project} ${c.kind} ${(c.sessions || []).join(",")} ${(c.files || []).join(",")}`;
-    if (overseerWarned.has(key)) continue;
-    overseerWarned.set(key, now());
+    c.key = key;
+    seen.add(key);
+    const standing = overseerActive.get(key);
+    if (standing) { standing.lastTick = t; c.since = standing.since; continue; }   // holds — stay quiet
+    overseerActive.set(key, { since: t, lastTick: t });
+    c.since = t;
     appendEvent("overseer.warn", c.project, "overseer",
       { kind: c.kind, sessions: c.sessions || [], files: c.files || [], detail: c.detail || "", narrated: false });
     if (DUTY_SESSION) hubSend(DUTY_SESSION, `⚠️ OVERSEER ${c.kind} [${c.project}]: ${c.detail || ""} — if the parties are not already coordinating, message them.`, c.project);
@@ -255,8 +272,18 @@ function overseerTick() {
       appendEvent("verify.gate.opened", c.project, "overseer", { gateId: g.id, claim: g.claim, why: g.why });
     }
   }
+  // Episode end: a condition gone for the whole clear window is over, so a LATER recurrence is a
+  // new episode and warns again. Without this the map would grow forever and nothing could re-fire.
+  for (const [k, v] of overseerActive) {
+    if (!seen.has(k) && t - v.lastTick > OVERSEER_CLEAR_MS) overseerActive.delete(k);
+  }
+  overseerLastCollisions = collisions;
 }
 setInterval(overseerTick, OVERSEER_TICK_MS).unref?.();
+// setInterval waits a FULL period before its first call, so for 30s after every restart the watcher
+// had no lastTick and honestly reported itself stalled. Tick once shortly after boot (the delay lets
+// the lazy lib import land) so a restarted hub proves it is alive immediately.
+setTimeout(overseerTick, 2000).unref?.();
 
 // --- the DUTY AGENT feed (deterministic escalation; the seat itself is bin/duty.mjs) -----------
 // RELAY_DUTY_SESSION names the always-on triage seat (e.g. "claude:fleet"). The hub DMs it when:
@@ -495,7 +522,7 @@ function cmpSemver(a, b) {
 const AUTH_HEADERS = ["x-trantor-pubkey", "x-trantor-sig", "x-trantor-ts", "x-trantor-nonce"];
 const PUBLIC_ENDPOINTS = new Set(["/", "/ui", "/health", "/enroll"]);
 const OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import", "/policy"]);
-const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims", "/overseer/context"]);
+const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims", "/overseer/context", "/overseer/status"]);
 const roleRank = { read: 1, write: 2, owner: 3 };
 const hasAuthHeaders = (req) => AUTH_HEADERS.some(h => !!req.headers[h]);
 const authPath = (u) => `${u.pathname}${u.search || ""}`;
@@ -1013,6 +1040,34 @@ const server = http.createServer(async (req, res) => {
     }
     // What a session arriving on <project> needs to know: its autonomy level, who else is live,
     // which files are in flight, which projects are declared codependent, current collisions.
+    if (req.method === "GET" && P === "/overseer/status") {
+      // The Overseer view's backbone: is the watcher ALIVE, and what is it watching right now.
+      // `warnings` is the LIVE detection result from the last tick (pre-dedup), not the event log —
+      // the log answers "what did it do", this answers "what does it see".
+      const pol = overseerPolicy();
+      const cutoff = now() - ONLINE_MS;
+      const livePeers = Object.entries(state.peers).filter(([, v]) => v.lastSeen > cutoff);
+      pruneClaims();
+      return json(res, 200, {
+        engine: !!_overseer?.detectCollisions,
+        lastTickTs: overseerLastTick,
+        tickMs: OVERSEER_TICK_MS,
+        clearMs: OVERSEER_CLEAR_MS,
+        dutySession: DUTY_SESSION || "",
+        watching: {
+          sessions: livePeers.length,
+          projects: new Set(livePeers.map(([, v]) => v.project).filter(Boolean)).size,
+          claims: fileClaims.size,
+          links: pol.links.length,
+        },
+        autonomy: pol.autonomy,
+        links: pol.links,
+        // `since` turns a detection into a duration — "standing 4h" reads very differently from
+        // "just started", and that distinction is the whole point of episode-based warning.
+        warnings: overseerLastCollisions.map(c => ({ ...c, since: c.since || 0 })),
+        standing: overseerActive.size,
+      });
+    }
     if (req.method === "GET" && P === "/overseer/context") {
       const proj = canon(String(q.project || "").slice(0, 80));
       if (!proj) return json(res, 400, { error: "project required" });

package/lib/overseer.mjs

@@ -1,5 +1,12 @@
-const PEER_LIVE_MS = 5 * 60 * 1000;
-const CLAIM_LIVE_MS = 10 * 60 * 1000;
+// Windows are read from env ONCE at load (calls stay pure): without an override, a test cannot
+// observe a condition CLEARING — peers stay "live" for five minutes no matter what the test does,
+// so the episode-recurrence path was untestable and therefore unproven.
+const PEER_LIVE_MS = Number(process.env.RELAY_OVERSEER_PEER_LIVE_MS || 5 * 60 * 1000);
+const CLAIM_LIVE_MS = Number(process.env.RELAY_OVERSEER_CLAIM_LIVE_MS || 10 * 60 * 1000);
+// "Actively executing", not merely "window open" — the same 90s bar the desktop app calls `busy`
+// (the heartbeat fires on tool calls, so a fresher-than-90s peer is mid-turn). Presence alone is
+// too weak a signal to call a collision: see the linked-activity note below.
+const WORK_LIVE_MS = Number(process.env.RELAY_OVERSEER_WORK_LIVE_MS || 90 * 1000);
 
 const KINDS = new Set(["same-project-sessions", "file-conflict", "linked-activity"]);
 
@@ -119,18 +126,40 @@ export function detectCollisions({ peers = [], claims = [], links = [], autonomy
     });
   }
 
+  // A link is DECLARED — the operator already told us these projects move together. Warning merely
+  // because both have a session OPEN restates that declaration, and it stays true for hours:
+  // crebral-health ↔ crebral-scribe produced 468 identical warnings across 8 days (2026-08-12
+  // audit), which is how a monitor teaches you to ignore it. The signal worth raising is
+  // CONCURRENT WORK — each side actually executing (heartbeat inside WORK_LIVE_MS) or holding a
+  // fresh file claim. Two idle-open windows are not a collision.
+  const workingByProject = new Map();
+  for (const peer of livePeers) {
+    if (!isFresh(peer?.lastSeen, at, WORK_LIVE_MS)) continue;
+    const sessions = workingByProject.get(peer.project) ?? [];
+    sessions.push(peer.session);
+    workingByProject.set(peer.project, sessions);
+  }
+  for (const claim of asArray(claims)) {
+    const project = clean(claim?.project);
+    const session = clean(claim?.session);
+    if (!project || !session || !isFresh(claim?.ts, at, CLAIM_LIVE_MS)) continue;
+    const sessions = workingByProject.get(project) ?? [];
+    sessions.push(session);
+    workingByProject.set(project, sessions);
+  }
+
   for (const link of asArray(links)) {
     const projects = sortedStrings(link?.projects ?? []);
     if (projects.length < 2) continue;
-    const activeProjects = projects.filter((project) => (sessionsByProject.get(project) ?? []).length > 0);
+    const activeProjects = projects.filter((project) => (workingByProject.get(project) ?? []).length > 0);
     if (activeProjects.length < 2) continue;
-    const sessions = sortedStrings(activeProjects.flatMap((project) => sessionsByProject.get(project) ?? []));
+    const sessions = sortedStrings(activeProjects.flatMap((project) => workingByProject.get(project) ?? []));
     pushCollision(out, {
       project: activeProjects[0],
       kind: "linked-activity",
       sessions,
       files: [],
-      detail: `Linked projects ${activeProjects.join(", ")} have live sessions ${sessions.join(", ")}.`,
+      detail: `Linked projects ${activeProjects.join(", ")} are being worked on at the same time by ${sessions.join(", ")}.`,
     });
   }
 

package/package.json

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