trantor 0.17.29 → 0.17.31

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// trantor agents [sessionId] [--json] — the LIVE sub-agent manifest for a session.
+//
+// What were this session's sub-agents (Agent/Task tool, Workflow swarms, agent-teams) doing —
+// what was each tasked with, did it return, what did it write, and do those files still survive
+// on disk? Derived fresh from the on-disk transcripts every run (so it reflects CURRENT disk,
+// catching files an agent finished that were later clobbered — the 2026-06-21 kill corrupted a
+// completed 30KB lib down to a 17-byte stub).
+//
+//   trantor agents                 → the session of the newest handoff for THIS project (the
+//                                     predecessor a fresh session is taking over from)
+//   trantor agents <sessionId>     → that specific session
+//   trantor agents --json          → structured manifest (for tools)
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { deriveSubagentManifest, formatSubagentManifest, resolveTranscriptForSid } from "../lib/subagent-manifest.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const sid = args.find((a) => !a.startsWith("--"));
+
+const HANDOFF_DIR = join(process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus"), "handoffs");
+
+// Newest handoff record whose project matches the cwd — gives us the predecessor's transcript
+// path + project root directly (no glob needed), so `trantor agents` with no arg "just works"
+// for a fresh session taking over.
+function newestHandoffForCwd() {
+  try {
+    if (!existsSync(HANDOFF_DIR)) return null;
+    const cwd = process.cwd(), name = basename(cwd);
+    const recs = readdirSync(HANDOFF_DIR)
+      .filter((f) => /-\d+\.json$/.test(f))
+      .map((f) => { try { return JSON.parse(readFileSync(join(HANDOFF_DIR, f), "utf8")); } catch { return null; } })
+      .filter((r) => r && (r.project === cwd || r.projectName === name))
+      .sort((a, b) => (Number(b.stamp) || 0) - (Number(a.stamp) || 0));
+    return recs[0] || null;
+  } catch { return null; }
+}
+
+let transcript = "", projectRoot = process.cwd();
+if (sid) {
+  transcript = resolveTranscriptForSid(sid);
+  if (!transcript) {
+    console.error(`No transcript found for session ${sid} under ~/.claude/projects/*/.`);
+    process.exit(1);
+  }
+} else {
+  const h = newestHandoffForCwd();
+  if (!h) {
+    console.error(`No handoff found for this project. Pass a session id explicitly: trantor agents <sessionId>`);
+    process.exit(1);
+  }
+  transcript = h.transcript_path || resolveTranscriptForSid(h.session_id);
+  projectRoot = h.project || projectRoot;
+}
+
+const manifest = deriveSubagentManifest(transcript, { projectRoot });
+if (json) {
+  process.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+} else {
+  process.stdout.write(formatSubagentManifest(manifest) + "\n");
+}

package/bin/baton-close.mjs

@@ -2,15 +2,25 @@
 // trantor baton-close — the second half of the baton pass. Runs DETACHED, armed by the handoff hook.
 // Waits until the FRESH session has consumed the handoff (consumed:true on the handoff file = it
 // started and loaded the context), THEN closes the ORIGINAL session's Terminal window — so you're never
-// left with two live sessions on one project, and never a gap where neither is alive. Defensive: aborts
-// if the fresh session never shows (timeout), and re-validates the window's tty before closing so it can
-// NEVER close the wrong window. Args: <handoffFile> <originalWindowId> <originalTty>
-import { readFileSync, existsSync } from "node:fs";
+// left with two live sessions on one project, and never a gap where neither is alive.
+//
+// NON-DESTRUCTIVE by contract (incident 2026-06-21): this NEVER force-kills a session. It only ever
+// runs for an OPT-IN auto-close (config.autoCloseOriginal) or a manual /trantor:handoff, and before
+// closing it (a) waits for the fresh session's first real turn, (b) re-validates the window's tty so it
+// can never close the wrong window, and (c) ABORTS if the original session is still working (recent
+// transcript activity or live sub-agents) — leaving it alive for you to close yourself. The old code
+// SIGKILLed every process on the original tty the instant the fresh session emitted one turn, which
+// killed an in-flight 2-agent build mid-flight. Args: <handoffFile> <originalWindowId> <originalTty>
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
+import { subagentsActive } from "../hooks/lib/handoff.mjs";
 
 const [, , handoffFile, windowId, originalTty] = process.argv;
 const POLL_MS = 1500, TIMEOUT_MS = 180_000;
+// The original session counts as "still working" if its OWN transcript was written within this window
+// (it's mid-turn / mid-tool-call) — we leave it alone rather than risk closing live work.
+const ORIG_QUIET_MS = 12_000, SUBAGENT_ACTIVE_MS = 90_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
@@ -56,6 +66,18 @@ async function waitForTakeover() {
   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`);
 }
 
+// True if the ORIGINAL session is still doing real work — its own transcript was written very recently
+// (mid-turn / mid-tool-call) or it has sub-agents running. We NEVER close a working session; if this is
+// true at takeover time we abort and leave the window alive. Exported for headless regression testing.
+export function originalStillWorking(rec, { quietMs = ORIG_QUIET_MS, subWithinMs = SUBAGENT_ACTIVE_MS } = {}) {
+  try {
+    const tp = rec?.transcript_path;
+    if (!tp || !existsSync(tp)) return false;
+    try { if (Date.now() - statSync(tp).mtimeMs < quietMs) return true; } catch {}
+    return subagentsActive(tp, subWithinMs);
+  } catch { return false; }
+}
+
 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})`)}`,
@@ -70,10 +92,12 @@ function closeWindow(id, tty) {
     return false;
   }
   try {
-    // SIGKILL the processes on that tty first (claude traps SIGTERM; a live login makes close() pop a dialog)
+    // Gently ask the processes on that tty to exit (SIGTERM — never SIGKILL; we do not force-kill a
+    // session). We only reach here once the original is confirmed idle (no in-flight work), so claude
+    // exits cleanly. If something ignores SIGTERM the window close below still tidies up.
     const dev = (tty || cur).replace(/^\/dev\//, "");
     for (const pid of execSync(`ps -t ${dev} -o pid= 2>/dev/null || true`, { encoding: "utf8" }).trim().split("\n").filter(Boolean)) {
-      try { execSync(`kill -9 ${pid.trim()} 2>/dev/null || true`); } catch {}
+      try { execSync(`kill -TERM ${pid.trim()} 2>/dev/null || true`); } catch {}
     }
   } catch {}
   try { execSync(`osascript -e ${JSON.stringify(`tell application "Terminal" to close (first window whose id is ${id})`)}`, { timeout: 3000 }); return true; } catch { return false; }
@@ -88,6 +112,12 @@ if (isMain) (async () => {
   while (Date.now() < deadline) {
     if (consumed()) {
       await waitForTakeover(); // don't close until the fresh session has actually produced its recap turn
+      // Final safety gate: never close a session that's still working. If the original is mid-turn or has
+      // live sub-agents, abort and leave it alive — the user closes it when ready (incident 2026-06-21).
+      if (originalStillWorking(handoff())) {
+        process.stderr.write(`[trantor] baton-close: original session still working (recent activity / live sub-agents) — leaving it alive, NOT closing\n`);
+        process.exit(0);
+      }
       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/cli.mjs

@@ -26,6 +26,7 @@ switch (cmd) {
   case "hub":     run("hub.mjs"); break;
   case "watch":   run("bin/relay-watch.mjs"); break;
   case "catchup": run("bin/catchup.mjs"); break;
+  case "agents":  run("bin/agents.mjs"); break;
   case "backfill": run("bin/git-backfill.mjs"); break;
   case "handoff": run("bin/baton.mjs"); break;
   case "ui": {
@@ -48,6 +49,7 @@ switch (cmd) {
   trantor down        tear the crew down (kills processes, closes windows, no dialogs)
   trantor ui          open the live dashboard (board + flow views)
   trantor catchup     "where are we?" — the continuous board + git, with a synthesized brief
+  trantor agents      what this session's sub-agents did (task · returned? · files written · survived on disk) — [<sessionId>] [--json]
   trantor backfill    card past GIT work onto the board (solo commits that were never carded) — [--since "14 days ago"] [--dry-run]
   trantor handoff     finish this session NOW: write a handoff, open a fresh session that takes over, and close this one (manual baton)
   trantor advise      ask the Advisor directly (JSON on stdin; --demo to see it)

package/hooks/handoff-now.mjs

@@ -16,8 +16,11 @@ try {
   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
-    const armed = windowId ? armBatonClose(file, windowId, tty, conf) : false;  // close the original once fresh confirms
-    process.stderr.write(`[trantor] fresh session spawned${armed ? ` · baton-close armed for window ${windowId}` : " · no original-window close (none detected / disabled)"}\n`);
+    // AUTO baton: close the original ONLY if explicitly opted in (config.autoCloseOriginal:true).
+    // Default = leave the original alive (the fresh window takes over; you close the old one). This is
+    // the 2026-06-21 fix — an auto-close must never kill an in-flight session.
+    const armed = windowId ? armBatonClose(file, windowId, tty, conf, { auto: true }) : false;
+    process.stderr.write(`[trantor] fresh session spawned${armed ? ` · baton-close armed for window ${windowId}` : " · original window left alive (auto-close off by default)"}\n`);
   }
 } catch (e) {
   process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);

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, markHandedOff, controllingTty, terminalWindowForTty } from "./lib/handoff.mjs";
+import { readConfig, contextUsage, warnFrac, alreadyHandedOff, markHandedOff, controllingTty, terminalWindowForTty, subagentsActive } from "./lib/handoff.mjs";
 import { resolveProject, hostId } from "../lib/project.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
@@ -49,6 +49,16 @@ async function maybeEarlyWarn(stdinRaw, session) {
     if (usage.frac < warnFrac(conf)) return;
     if (alreadyHandedOff(sessionId, usage.tokens)) return;
 
+    // Mid-build guard (incident 2026-06-21): never fire an auto baton-pass while this session is
+    // actively orchestrating sub-agents — popping a fresh window (or, before the fix, killing the
+    // original) mid 2-agent build is exactly the failure we must prevent. Defer: the next heartbeat
+    // re-checks once the agents finish, and PreCompact remains the at-the-wall backstop. We do NOT
+    // markHandedOff here, so the baton genuinely retries later instead of being silently skipped.
+    if (subagentsActive(transcript)) {
+      process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% but sub-agents active — deferring baton pass\n`);
+      return;
+    }
+
     // In-flight guard: the detached worker takes ~tens of seconds to summarize;
     // don't launch a second one on the next heartbeat tick meanwhile.
     const inflight = join(homedir(), ".agent-bus", `handoff-inflight-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);

package/hooks/lib/handoff.mjs

@@ -10,11 +10,12 @@
 // 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, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, 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";
 import { fileURLToPath } from "node:url";
+import { deriveSubagentManifest } from "../../lib/subagent-manifest.mjs";
 
 export const HANDOFF_DIR = join(process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus"), "handoffs");
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -105,6 +106,34 @@ export function markHandedOff(sessionId, curTokens = 0) {
 
 function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8" }).trim()) || 0; } catch { return 0; } }
 
+// ---- in-flight guard --------------------------------------------------------
+// True when this session is actively orchestrating sub-agents (Agent/Task tool, Workflow swarms,
+// agent-teams): any `agent-*.jsonl` under <transcriptDir>/<sid>/subagents/ (incl. workflows/) was
+// written within `withinMs`. The auto baton-pass uses this to DEFER — we must never yank a fresh
+// 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.
+export function subagentsActive(transcriptPath, withinMs = 90_000) {
+  try {
+    if (!transcriptPath) return false;
+    const sub = join(dirname(transcriptPath), basename(transcriptPath).replace(/\.jsonl$/i, ""), "subagents");
+    if (!existsSync(sub)) return false;
+    const cutoff = Date.now() - withinMs;
+    const stack = [sub];
+    while (stack.length) {
+      const d = stack.pop();
+      let entries; try { entries = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+      for (const e of entries) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) { stack.push(p); continue; }
+        if (!/^agent-.*\.jsonl$/i.test(e.name)) continue;
+        try { if (statSync(p).mtimeMs >= cutoff) return true; } catch {}
+      }
+    }
+    return false;
+  } catch { return false; }
+}
+
 // ---- whole-session summary --------------------------------------------------
 function collectTurns(transcriptPath) {
   const rows = readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean)
@@ -192,6 +221,12 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
   try { gitStatus = execSync("git -C " + JSON.stringify(projectDir) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
   const narrative = summary ?? buildSummary(transcript);
   const tail = verbatimRecentTail(transcript);
+  // Sub-agent manifest SNAPSHOT (fallback). The successor should re-derive it LIVE via
+  // `trantor agents <sid>` (catches files an agent finished that were clobbered AFTER this
+  // snapshot — the kill that motivated this corrupted a completed 30KB lib post-handoff). This
+  // baked copy is just orientation if the live command isn't available. Best-effort; never throws.
+  let subagents = null;
+  try { subagents = deriveSubagentManifest(transcript, { projectRoot: projectDir }); } catch {}
   const record = {
     id: `${projectName}-${stamp}`,
     project: projectDir, projectName, machine: hostname(),
@@ -199,7 +234,7 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     transcript_path: transcript || "", stamp: Number(stamp) || 0,
     // narrative + a verbatim recent-exchange block so exact in-flight state always survives
     summary: narrative + (tail ? `\n\n---\n## Verbatim recent exchange (exact in-flight state — continue from here)\n${tail}` : ""),
-    gitStatus, consumed: false,
+    gitStatus, subagents, consumed: false,
   };
   const file = join(HANDOFF_DIR, `${record.id}.json`);
   writeFileSync(file, JSON.stringify(record, null, 2));
@@ -262,10 +297,17 @@ export function terminalWindowForTty(tty) {
 // Arm the baton-close watcher: a DETACHED process that waits until the fresh session consumes the
 // handoff (consumed:true), then closes the original Terminal window. Never closes blind: aborts on
 // timeout (fresh never showed) and re-validates the window's tty before closing.
-export function armBatonClose(handoffFile, originalWindowId, originalTty, conf = readConfig()) {
+export function armBatonClose(handoffFile, originalWindowId, originalTty, conf = readConfig(), { auto = false } = {}) {
   try {
     if (process.platform !== "darwin" || !originalWindowId) return false;
     if (process.env.TRANTOR_NO_BATON_CLOSE === "1" || conf.batonClose === false) return false;
+    // SAFETY (incident 2026-06-21): an AUTOMATIC baton must NEVER close the original session. At 90%
+    // (10% headroom) mid 2-agent build, auto-close SIGKILLed the original window's processes and killed
+    // in-flight work — the scariest possible failure. Auto-close is now strictly opt-in
+    // (config.autoCloseOriginal:true). The default auto baton just opens the fresh window and LEAVES the
+    // original alive. Manual /trantor:handoff still closes (the user explicitly invoked a wrap-up) — and
+    // even that is now non-destructive (baton-close never SIGKILLs and aborts if the original is busy).
+    if (auto && conf.autoCloseOriginal !== true) return false;
     const closer = join(HERE, "..", "..", "bin", "baton-close.mjs");
     if (!existsSync(closer)) return false;
     const child = spawn(process.execPath, [closer, handoffFile, String(originalWindowId), originalTty || ""], { detached: true, stdio: "ignore" });

package/hooks/precompact.mjs

@@ -37,11 +37,13 @@ try {
     process.stderr.write(`[trantor] fresh session already spawned for this window — handoff refreshed only\n`);
   } else if (maybeSpawn(projectDir, conf)) {
     markHandedOff(sessionId, cur);
-    // baton pass: arm the close of THIS window once the fresh session takes over (we have the tty here)
+    // baton pass: at-the-wall fresh session. Close THIS window ONLY if opted in
+    // (config.autoCloseOriginal:true) — default leaves the original alive (2026-06-21 fix: an auto
+    // baton must never kill a session). We have the controlling tty here for the opt-in case.
     const tty = controllingTty();
     const windowId = tty ? terminalWindowForTty(tty) : "";
-    const armed = windowId ? armBatonClose(file, windowId, tty, conf) : false;
-    process.stderr.write(`[trantor] fresh-session spawned (PreCompact)${armed ? ` · baton-close armed for window ${windowId}` : ""}\n`);
+    const armed = windowId ? armBatonClose(file, windowId, tty, conf, { auto: true }) : false;
+    process.stderr.write(`[trantor] fresh-session spawned (PreCompact)${armed ? ` · baton-close armed for window ${windowId}` : " · original window left alive (auto-close off by default)"}\n`);
   }
 } catch (err) {
   process.stderr.write(`[trantor] precompact error: ${err?.message || err}\n`);

package/hooks/sessionstart.mjs

@@ -11,6 +11,7 @@ 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 { formatSubagentManifest } from "../lib/subagent-manifest.mjs";
 import { updateAvailable, maybeNotifyDesktop, readConfig } from "./lib/update-check.mjs";
 
 // Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs
@@ -198,6 +199,17 @@ try {
     additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch.\n\n`;
     additionalContext += `## Handoff summary\n${sanitize(handoff.summary)}\n`;
     if (handoff.gitStatus) additionalContext += `\n## Git working-tree at handoff\n\`\`\`\n${sanitize(handoff.gitStatus)}\n\`\`\`\n`;
+    // Sub-agent manifest: LIVE-primary, snapshot-as-fallback. The prior session may have had
+    // sub-agents (Agent/Task, Workflow) building things you can't see in its narrative — and a
+    // kill can corrupt an agent's finished file on disk. Direct the successor to re-derive LIVE
+    // (reconciles against current disk) and trust that over the baked snapshot.
+    if (handoff.subagents && handoff.subagents.counts && handoff.subagents.counts.total) {
+      const sa = handoff.subagents;
+      additionalContext += `\n## Sub-agents the prior session ran (${sa.counts.total}: ${sa.counts.completed} completed, ${sa.counts.inFlight} in-flight at handoff)\n`;
+      additionalContext += `**Before continuing, get the LIVE manifest** — run \`trantor agents ${sanitize(handoff.session_id)}\` (or \`trantor agents\` from this project). It re-derives from CURRENT disk, flagging any file an agent finished that was later clobbered — do NOT assume "nothing survived"; recover from the agent's transcript. Trust the live command over the snapshot below.\n`;
+      if (sa.counts.suspectFiles) additionalContext += `⚠️ ${sa.counts.suspectFiles} file(s) an agent wrote looked CLOBBERED at handoff time — verify with the live command and recover.\n`;
+      additionalContext += `\n\`\`\`\n${sanitize(formatSubagentManifest(sa, { heading: false }))}\n\`\`\`\n`;
+    }
     if (handoff.transcript_path) additionalContext += `\n_Full prior transcript: ${sanitize(handoff.transcript_path)}_\n`;
     additionalContext += `</trantor-handoff>\n`;
   }

package/lib/subagent-manifest.mjs

@@ -0,0 +1,175 @@
+// trantor sub-agent manifest — reconstruct what a session's sub-agents (Agent/Task tool,
+// Workflow swarms, agent-teams) were doing, purely from on-disk transcripts. No new runtime
+// instrumentation: it's a READ-TIME projection of primary sources, so it can't drift and the
+// successor can re-derive it itself (that's the point — live-primary, snapshot-as-fallback).
+//
+// Born from the 2026-06-21 incident: an auto baton-pass SIGKILLed a session mid 2-agent build.
+// The fresh session had no idea two agents were even running, and one agent's COMPLETED 30KB
+// implementation had been clobbered on disk to a 17-byte stub by the kill — so the successor
+// rebuilt it from scratch believing "nothing survived." The manifest surfaces exactly that:
+// what each agent was tasked with, whether it returned, what it wrote, and — via a disk
+// reconcile — whether the files it wrote still survive or look clobbered.
+//
+// Four primary sources (all already on disk under ~/.claude/projects/<proj>/<sid>/):
+//   1. subagents/*.meta.json        → {name, agentType, description (the task), toolUseId}
+//   2. parent <sid>.jsonl           → tool_result ids ⇒ which agents RETURNED (completed)
+//   3. each subagents/agent-*.jsonl → files written, last activity, the result it reported
+//   4. disk reconcile               → agent wrote X@N bytes; does X still exist & match? (suspect)
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { join, dirname, basename, relative } from "node:path";
+import { homedir } from "node:os";
+
+const EDIT_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit)$/;
+
+function parseLines(path) {
+  let raw; try { raw = readFileSync(path, "utf8"); } catch { return []; }
+  const out = [];
+  for (const ln of raw.split("\n")) { if (!ln) continue; try { out.push(JSON.parse(ln)); } catch {} }
+  return out;
+}
+
+// Resolve a bare session id to its transcript path by scanning ~/.claude/projects/*/<sid>.jsonl.
+export function resolveTranscriptForSid(sid) {
+  if (!sid) return "";
+  const base = join(homedir(), ".claude", "projects");
+  try {
+    for (const proj of readdirSync(base)) {
+      const p = join(base, proj, `${sid}.jsonl`);
+      if (existsSync(p)) return p;
+    }
+  } catch {}
+  return "";
+}
+
+// Walk subagents/ (recursing into workflows/<wf>/) collecting every *.meta.json paired with its
+// .jsonl. `workflow` is the workflow id when the agent lives under workflows/<wf>/, else null.
+function collectMetas(subdir) {
+  const out = [];
+  const walk = (dir, workflow) => {
+    let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { walk(p, e.name === "workflows" ? workflow : e.name); continue; }
+      if (!e.name.endsWith(".meta.json")) continue;
+      let meta; try { meta = JSON.parse(readFileSync(p, "utf8")); } catch { continue; }
+      out.push({ ...meta, jsonlPath: p.replace(/\.meta\.json$/, ".jsonl"), workflow: workflow || null });
+    }
+  };
+  walk(subdir, null);
+  return out;
+}
+
+function shortPath(absPath, projectRoot) {
+  try {
+    if (projectRoot && absPath.startsWith(projectRoot)) return relative(projectRoot, absPath) || absPath;
+  } catch {}
+  return absPath.split("/").slice(-4).join("/");
+}
+
+// Does the file the agent wrote still survive intact? agentBytes = the size the agent last wrote.
+// suspect = the file is gone, or shrank far below what the agent wrote (clobbered, e.g. by a kill).
+function reconcileFile(absPath, agentBytes, projectRoot) {
+  let onDiskNow = null, suspect = false;
+  try {
+    if (existsSync(absPath)) {
+      onDiskNow = statSync(absPath).size;
+      if (agentBytes > 200 && onDiskNow < Math.min(agentBytes * 0.5, agentBytes - 200)) suspect = true;
+    } else {
+      onDiskNow = 0;
+      suspect = agentBytes > 200; // the agent wrote real content but the file is gone
+    }
+  } catch {}
+  return { path: shortPath(absPath, projectRoot), agentBytes, onDiskNow, suspect };
+}
+
+function analyzeAgent(meta, completedIds, projectRoot) {
+  const wrote = new Map(); // absPath → last-write byte length
+  let lastMs = 0, result = "";
+  for (const r of parseLines(meta.jsonlPath)) {
+    const ts = r.timestamp ? Date.parse(r.timestamp) || 0 : 0;
+    if (ts > lastMs) lastMs = ts;
+    const c = r?.message?.content;
+    if (!Array.isArray(c)) continue;
+    for (const b of c) {
+      if (b?.type === "tool_use" && EDIT_TOOLS.test(b.name) && b.input?.file_path) {
+        const content = b.input.content ?? b.input.new_string ?? "";
+        wrote.set(b.input.file_path, content.length); // last write to a path wins
+      }
+      if (b?.type === "text" && typeof b.text === "string" && b.text.trim()) result = b.text.trim();
+    }
+  }
+  const status = meta.toolUseId && completedIds.has(meta.toolUseId) ? "completed" : "in-flight";
+  return {
+    name: meta.name || basename(meta.jsonlPath).replace(/\.jsonl$/, ""),
+    agentType: meta.agentType || "",
+    task: meta.description || "",
+    workflow: meta.workflow || null,
+    status,
+    wrote: [...wrote.entries()].map(([p, n]) => reconcileFile(p, n, projectRoot)),
+    lastActivity: lastMs ? new Date(lastMs).toISOString() : null,
+    lastActivityMs: lastMs,
+    transcript: meta.jsonlPath,
+    result: result.slice(0, 400),
+  };
+}
+
+// Derive the full manifest for a session from its parent transcript path. projectRoot (the repo
+// dir) is used only to shorten displayed file paths. Returns { sessionId, subagents[], counts }.
+export function deriveSubagentManifest(parentTranscript, { projectRoot } = {}) {
+  const out = { sessionId: "", subagents: [], counts: { total: 0, completed: 0, inFlight: 0, suspectFiles: 0 } };
+  try {
+    if (!parentTranscript || !existsSync(parentTranscript)) return out;
+    const sid = basename(parentTranscript).replace(/\.jsonl$/i, "");
+    out.sessionId = sid;
+    const subdir = join(dirname(parentTranscript), sid, "subagents");
+    if (!existsSync(subdir)) return out;
+
+    // (2) parent transcript → tool_result ids = agents that returned a result.
+    const completedIds = new Set();
+    for (const r of parseLines(parentTranscript)) {
+      const c = r?.message?.content;
+      if (Array.isArray(c)) for (const b of c) if (b?.type === "tool_result" && b.tool_use_id) completedIds.add(b.tool_use_id);
+    }
+
+    const metas = collectMetas(subdir);
+    out.subagents = metas.map((m) => analyzeAgent(m, completedIds, projectRoot))
+      .sort((a, b) => (a.lastActivityMs || 0) - (b.lastActivityMs || 0));
+
+    out.counts.total = out.subagents.length;
+    out.counts.completed = out.subagents.filter((s) => s.status === "completed").length;
+    out.counts.inFlight = out.subagents.filter((s) => s.status === "in-flight").length;
+    out.counts.suspectFiles = out.subagents.reduce((n, s) => n + s.wrote.filter((w) => w.suspect).length, 0);
+  } catch {}
+  return out;
+}
+
+// Human-readable rendering (the `trantor agents` output, and the handoff snapshot block).
+export function formatSubagentManifest(m, { heading = true } = {}) {
+  if (!m || !m.subagents.length) return "No sub-agents found for this session.";
+  const L = [];
+  if (heading) {
+    L.push(`Sub-agent manifest — ${m.counts.total} agents (${m.counts.completed} completed, ${m.counts.inFlight} in-flight at handoff)`);
+    if (m.counts.suspectFiles) {
+      L.push(`⚠️  ${m.counts.suspectFiles} file(s) an agent wrote look CLOBBERED on disk (gone or far smaller than written) — RECOVER from the agent's transcript before assuming the work was never done.`);
+    }
+  }
+  for (const s of m.subagents) {
+    const badge = s.status === "completed" ? "✅ completed" : "🛑 IN-FLIGHT at handoff";
+    L.push("");
+    L.push(`• ${s.name}  [${s.agentType}]${s.workflow ? ` · wf:${s.workflow}` : ""}  ${badge}`);
+    if (s.task) L.push(`    task: ${s.task}`);
+    if (s.wrote.length) {
+      for (const w of s.wrote) {
+        const size = w.onDiskNow != null ? (w.onDiskNow === 0 && w.suspect ? "MISSING" : `${w.onDiskNow}B on disk`) : "?";
+        const flag = w.suspect ? `   ⚠️ SUSPECT — agent wrote ${w.agentBytes}B, recover from transcript` : "";
+        L.push(`    wrote: ${w.path} (${size})${flag}`);
+      }
+    } else {
+      L.push(`    wrote: (no file edits)`);
+    }
+    L.push(`    transcript: ${s.transcript}`);
+  }
+  L.push("");
+  L.push(`Read any agent's transcript for its full reasoning/sourcing before trusting OR discarding its work.`);
+  return L.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.29",
+  "version": "0.17.31",
   "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-update.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"
   },
   "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": [