trantor 0.17.30 → 0.17.31

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.30",
+  "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/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/lib/handoff.mjs

@@ -15,6 +15,7 @@ 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));
@@ -220,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(),
@@ -227,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));

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.30",
+  "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": [