trantor 0.17.61 → 0.17.63

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.61",
+  "version": "0.17.63",
   "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/README.md

@@ -51,7 +51,7 @@ heartbeats, inbox delivery, handoff/baton pass, sub-agent cards):
        "relay": {
          "command": "node",
          "args": ["<absolute-path-to-trantor>/mcp.mjs"],
-         "env": { "RELAY_URL": "http://127.0.0.1:4477", "RELAY_AGENT": "kimi" },
+         "env": { "RELAY_URL": "http://127.0.0.1:4477", "RELAY_AGENT": "kimi-orch" },
          "startupTimeoutMs": 15000,
          "toolTimeoutMs": 150000
        }
@@ -68,6 +68,11 @@ runs your live checkout, so the relay server itself never goes stale. Invoke the
 `/skill:crew`, `/skill:handoff`, `/skill:research`. Set `TRANTOR_DEBUG_HOOKS=1` on the `kimi`
 process to dump raw hook payloads to `~/.agent-bus/kimi-hook-debug.jsonl`.
 
+The orchestrator's bus identity is `kimi-orch:<project>` — deliberately distinct from `kimi:<project>`,
+which belongs to a kimi CREW SEAT (`trantor up kimi`). Same doctrine as the openrouter seat label:
+one bus peer per role, so an orchestrator and its own kimi seat never share a heartbeat, inbox, or
+card attribution.
+
 That's it. (Prefer source? `git clone https://github.com/sashabogi/trantor && cd trantor &&
 npm install && bash deploy/setup.sh` — identical result.)
 

package/bin/app.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// trantor app — install/update the Trantor DESKTOP APP (Tauri) from GitHub Releases.
+//
+// The npm package deliberately does NOT ship desktop/ (a 6MB DMG has no business in node_modules);
+// the app travels as a GitHub Release asset instead. This command is the whole distribution story
+// for a teammate: `npm i -g trantor && trantor app install` → latest DMG lands in /Applications.
+//
+//   trantor app            status: installed version vs latest release
+//   trantor app install    download the latest release DMG and install to /Applications
+//   trantor app update     same as install (re-pulls whatever is latest)
+//
+// Release side (maintainer): build the DMG (cd desktop && npm run tauri build), then
+//   gh release create app-v<ver> desktop/src-tauri/target/release/bundle/dmg/Trantor_<ver>_aarch64.dmg
+// Any release whose assets include a Trantor_*.dmg is an app release; the newest one wins, so app
+// releases interleave freely with code (npm) releases.
+import { execFileSync } from "node:child_process";
+import { createWriteStream, existsSync, rmSync } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const REPO = "sashabogi/trantor";
+const APP = "/Applications/Trantor.app";
+const ARCH_TAG = process.arch === "arm64" ? "aarch64" : "x64";
+const cmd = process.argv[2] || "status";
+
+if (process.platform !== "darwin") { console.error("trantor app: the desktop app is macOS-only for now"); process.exit(1); }
+if (!["status", "install", "update"].includes(cmd)) {
+  console.error("usage: trantor app [status|install|update]"); process.exit(1);
+}
+
+function sh(file, args) { return execFileSync(file, args, { encoding: "utf8" }); }
+
+function installedVersion() {
+  try { return sh("plutil", ["-extract", "CFBundleShortVersionString", "raw", join(APP, "Contents/Info.plist")]).trim(); }
+  catch { return ""; }
+}
+
+// Newest release carrying a Trantor DMG for this arch (falls back to any Trantor DMG — old
+// releases may predate multi-arch naming). GITHUB_TOKEN is honored but not required (public repo).
+async function latestAppRelease() {
+  const headers = { accept: "application/vnd.github+json", "user-agent": "trantor-app" };
+  if (process.env.GITHUB_TOKEN) headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const r = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=30`, { headers, signal: AbortSignal.timeout(15000) });
+  if (!r.ok) throw new Error(`GitHub API ${r.status} — ${(await r.text()).slice(0, 200)}`);
+  const isDmg = a => /^Trantor[_-].*\.dmg$/.test(a.name);
+  for (const rel of await r.json()) {
+    const assets = (rel.assets || []).filter(isDmg);
+    if (!assets.length) continue;
+    const asset = assets.find(a => a.name.includes(`_${ARCH_TAG}`)) || assets[0];
+    if (!asset.name.includes(`_${ARCH_TAG}`)) console.error(`⚠ no ${ARCH_TAG} build in ${rel.tag_name} — using ${asset.name} (may not run on this Mac)`);
+    const version = (asset.name.match(/[_-]([0-9]+(?:\.[0-9]+)*)[_-]/) || [])[1] || rel.tag_name.replace(/^app-v?|^v/, "");
+    return { tag: rel.tag_name, version, asset };
+  }
+  throw new Error("no release with a Trantor DMG asset found");
+}
+
+const rel = await latestAppRelease().catch(e => { console.error(`trantor app: ${e.message}`); process.exit(1); });
+const have = installedVersion();
+
+if (cmd === "status") {
+  console.log(`installed: ${have ? `${have} (${APP})` : "not installed"}`);
+  console.log(`latest:    ${rel.version} (${rel.tag} · ${rel.asset.name})`);
+  console.log(have === rel.version ? "up to date." : `run \`trantor app install\` to get ${rel.version}.`);
+  process.exit(0);
+}
+
+console.log(`↓ ${rel.asset.name} (${(rel.asset.size / 1e6).toFixed(1)}MB) from ${rel.tag}…`);
+const dmg = join(tmpdir(), rel.asset.name);
+const dl = await fetch(rel.asset.browser_download_url, { headers: { "user-agent": "trantor-app" }, signal: AbortSignal.timeout(300000) });
+if (!dl.ok || !dl.body) { console.error(`download failed: HTTP ${dl.status}`); process.exit(1); }
+await pipeline(Readable.fromWeb(dl.body), createWriteStream(dmg));
+
+let mount = "";
+try {
+  // -nobrowse keeps the volume out of Finder; mount point is the last tab-field of the last line.
+  const out = sh("hdiutil", ["attach", "-nobrowse", "-readonly", dmg]);
+  mount = (out.trim().split("\n").pop() || "").split("\t").pop().trim();
+  const src = join(mount, "Trantor.app");
+  if (!mount.startsWith("/Volumes/") || !existsSync(src)) throw new Error(`unexpected DMG layout (mount: ${mount || "none"})`);
+  if (existsSync(APP)) { console.log(`replacing ${APP} (was ${have || "unknown"})`); rmSync(APP, { recursive: true, force: true }); }
+  sh("ditto", [src, APP]);
+  // The download carries quarantine; the user explicitly asked for this install — clear it so
+  // Gatekeeper doesn't refuse the unsigned build on first launch.
+  try { sh("xattr", ["-dr", "com.apple.quarantine", APP]); } catch {}
+  console.log(`✓ Trantor.app ${installedVersion() || rel.version} installed → ${APP}`);
+} catch (e) {
+  console.error(`install failed: ${e.message}`); process.exitCode = 1;
+} finally {
+  if (mount) try { sh("hdiutil", ["detach", mount, "-quiet"]); } catch {}
+  try { rmSync(dmg, { force: true }); } catch {}
+}

package/bin/cli.mjs

@@ -72,6 +72,8 @@ switch (cmd) {
   case "policy": run("bin/policy.mjs"); break;
   case "inbox": run("bin/inbox.mjs"); break;
   case "duty": run("bin/duty.mjs"); break;
+  case "app": run("bin/app.mjs"); break;
+  case "patrol": run("bin/patrol.mjs"); break;
   case "identity": {
     const { load, publicView, generate, keyPath } = await import(join(ROOT, "lib/identity.mjs"));
     const sub = args[0], name = args[1] || "human";
@@ -153,7 +155,9 @@ switch (cmd) {
   trantor models      browse live models behind each seat + the router's pick per difficulty
   trantor up …        spawn a crew here:   trantor up codex kimi deepseek:deepseek glm:zai-coding-plan
   trantor down        tear the crew down (kills processes, closes windows, no dialogs)
+  trantor prune       drop dead crew-window tracking rows (ghost workspaces/panes) without spawning anything
   trantor ui          open the live dashboard (board + flow views)
+  trantor app         the DESKTOP app: status | install | update — pulls the latest DMG from GitHub Releases
   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 gates       verification gates: "must verify before shipping" claims that survive handoffs — [--all] [--json]
@@ -169,6 +173,7 @@ switch (cmd) {
   trantor inbox       THIS session's unread bus messages, signed (works under enforce) — [--all] [--consume] [--json]
   trantor policy      the autonomy ladder: show | set <project> <1-4> | link <a> <b> --reason "<why>"
   trantor duty        the always-on fleet duty agent: up | down | status — hub-escalated triage so you are not the switchboard
+  trantor patrol      machine-wide resource sweep: crews/runners/workspaces/orphans — [--json] [--reap] (reap = dead rows + stale artifacts ONLY)
 
 Claude Code plugin (the orchestrator side):
   claude plugin marketplace add sashabogi/trantor && claude plugin install trantor

package/bin/crew.sh

@@ -245,16 +245,17 @@ case "$CMD" in up|swap|prune) ;; *) echo "usage: crew.sh up <agent...> | crew.sh
 prune_dead_state() {
   [ -f "$STATE" ] || return 0
   [ "$DRY" = "1" ] && return 0
-  local CLIVE=""
+  # CLIVE = live workspace uuids · CLIVE_NAMES = their titles. Seat (`cmux`) rows are validated at
+  # WORKSPACE granularity — is a live workspace named trantor:<their project> still up? — NOT per
+  # surface: `list-pane-surfaces --workspace` only returns the FIRST pane's surfaces, so a
+  # per-surface check reaps every split-created live seat's row (bug shipped 0.17.61, caught
+  # 2026-08-07 when it stripped two live crews' seat rows).
+  local CLIVE="" CLIVE_NAMES=""
   if _cmux_ok; then
-    local wids wid
-    wids="$(_cmux workspace list --id-format both --json 2>/dev/null | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d.slice(d.search(/[\[{]/)));const a=Array.isArray(o)?o:(o.workspaces||[]);console.log(a.map(x=>x.id).filter(Boolean).join(" "))}catch(e){}})')"
-    if [ -n "$wids" ]; then
-      CLIVE="$wids"
-      for wid in $wids; do
-        CLIVE="$CLIVE $(_cmux list-pane-surfaces --workspace "$wid" --id-format uuids --json 2>/dev/null | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d.slice(d.search(/[\[{]/)));const a=o.surfaces||o.panes||o;console.log((Array.isArray(a)?a:[]).map(s=>s.id||s.surface_id).filter(Boolean).join(" "))}catch(e){}})')"
-      done
-    fi
+    local pair
+    pair="$(_cmux workspace list --id-format both --json 2>/dev/null | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d.slice(d.search(/[\[{]/)));const a=Array.isArray(o)?o:(o.workspaces||[]);console.log(a.map(x=>x.id).filter(Boolean).join(" "));console.log("
"+a.map(x=>x.custom_title||x.name||"").filter(Boolean).join("
")+"
")}catch(e){}})')"
+    CLIVE="$(printf '%s' "$pair" | sed -n 1p)"
+    CLIVE_NAMES="$(printf '%s' "$pair" | sed -n 2p)"
   fi
   local tmp="$STATE.tmp" line alive
   : > "$tmp"
@@ -266,8 +267,11 @@ prune_dead_state() {
       [ -n "$(osascript -e "tell application \"Terminal\" to get id of (first window whose id is $RH)" 2>/dev/null)" ] || alive=0
     elif [ "$RK" = "tmux" ]; then
       tmux has-session -t "trantor:$RP" 2>/dev/null || alive=0
-    elif [ "$RK" = "cmuxws" ] || [ "$RK" = "cmux" ]; then
+    elif [ "$RK" = "cmuxws" ]; then
       if [ -n "$CLIVE" ]; then case " $CLIVE " in *" $RH "*) : ;; *) alive=0 ;; esac; fi
+    elif [ "$RK" = "cmux" ]; then
+      # seat row lives exactly as long as its project still has a live crew workspace
+      if [ -n "$CLIVE" ]; then case "$CLIVE_NAMES" in *$'\x01'"trantor:$RP"$'\x01'*) : ;; *) alive=0 ;; esac; fi
     fi
     [ "$alive" = "1" ] && printf '%s\t%s\t%s\t%s\n' "$RP" "$RK" "$RA" "$RH" >> "$tmp"
   done < "$STATE"

package/bin/duty.mjs

@@ -43,7 +43,7 @@ function fleetHub() {
 const AGENT = val("agent", "claude");
 const SESSION = `${AGENT}:fleet`;
 
-const RULES = `Rules: you are ${SESSION}, the trantor fleet DUTY AGENT — the always-on triage seat. You NEVER write code and NEVER edit project files. On every wake: (1) read the message(s) that woke you; (2) triage with your relay tools — relay_peers for who is live/down, relay_board with the project param for any board, relay_inbox for your own backlog; runner logs live at ~/.agent-bus/logs/<agent>-<project>.jsonl if a seat looks dead; (3) ACT: an UNDELIVERED escalation means the recipient is idle, deaf (wrong hub / stale hooks — a known failure mode), or gone — relay the content to a live session that can act, wake a crew seat with a direct message, or post the information into the project lane so the human's app notifies them; an OVERSEER warning means two parties may collide — message them to coordinate; a seat reported down/errored — check its log tail and either resend its contract or report exactly what is needed. (4) Report each action in ONE bus message (<280 chars) to the lane it concerns. If only a human can decide, say exactly that, in that lane, once. Then END YOUR TURN — the runner wakes you for the next event.`;
+const RULES = `Rules: you are ${SESSION}, the trantor fleet DUTY AGENT — the always-on triage seat. You NEVER write code and NEVER edit project files. On every wake: (1) read the message(s) that woke you; (2) patrol: run \`node ${ROOT}/bin/patrol.mjs --json\`; reap only when an orphan is provably dead, and DM sasha about anything ambiguous such as a live orphan runner or dev server older than 24h; (3) triage with your relay tools — relay_peers for who is live/down, relay_board with the project param for any board, relay_inbox for your own backlog; runner logs live at ~/.agent-bus/logs/<agent>-<project>.jsonl if a seat looks dead; (4) ACT: an UNDELIVERED escalation means the recipient is idle, deaf (wrong hub / stale hooks — a known failure mode), or gone — relay the content to a live session that can act, wake a crew seat with a direct message, or post the information into the project lane so the human's app notifies them; an OVERSEER warning means two parties may collide — message them to coordinate; a seat reported down/errored — check its log tail and either resend its contract or report exactly what is needed. (5) Report each action and patrol summary in ONE bus message (<280 chars) to the lane it concerns. If only a human can decide, say exactly that, in that lane, once. Then END YOUR TURN — the runner wakes you for the next event.`;
 
 const KICKOFF = `You are ${SESSION}, the fleet duty agent, freshly started. Do a short patrol: relay_peers (note anything down/errored), then relay_inbox. Handle what is actionable per the Rules, post one line to the bus saying the duty seat is on watch, and end your turn.\n\n${RULES}`;
 

package/bin/patrol.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// trantor patrol — machine-wide crew/resource report. It never kills live processes.
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { join, basename, dirname, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const DAY = 24 * 60 * 60 * 1000;
+
+const emptyResources = {
+  inventory: () => ({ rows: [], runners: [], workspaces: [], devServers: [] }),
+  cleanDead: () => "",
+};
+
+function busDir(env = process.env) {
+  if (env.AGENT_BUS_DIR) return env.AGENT_BUS_DIR;
+  return join(env.RELAY_DATA_DIR || homedir(), ".agent-bus");
+}
+
+function isUnderDir(path, parent) {
+  if (!path || !parent) return false;
+  const child = resolve(String(path));
+  const root = resolve(String(parent));
+  return child === root || child.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+function isBusInternalRunner(runner, bus) {
+  return isUnderDir(runner?.dir, bus);
+}
+
+function safeArray(v) { return Array.isArray(v) ? v : []; }
+function displayProject(p) { return p || "<legacy>"; }
+function runnerProject(r) { return String(r?.project || (r?.dir ? basename(String(r.dir)) : "") || ""); }
+function workspaceProject(w) {
+  const m = /^trantor:([^/]+)$/.exec(String(w?.title || ""));
+  return m ? m[1] : "";
+}
+function rowProject(row) { return String(row?.project || ""); }
+function rowMatchesRunner(row, runner) {
+  if (String(row?.agent || "") !== String(runner?.agent || "")) return false;
+  const rp = rowProject(row);
+  return !rp || rp === runnerProject(runner);
+}
+
+function sortedProjects(projects) {
+  return [...projects].sort((a, b) => displayProject(a).localeCompare(displayProject(b)));
+}
+
+export function buildPatrolReport(rawInventory = {}, reaped = [], { bus = busDir() } = {}) {
+  const rows = safeArray(rawInventory.rows);
+  const runners = safeArray(rawInventory.runners);
+  const workspaces = safeArray(rawInventory.workspaces);
+  const devServers = safeArray(rawInventory.devServers);
+  const projects = new Set();
+  for (const row of rows) projects.add(rowProject(row));
+  for (const runner of runners) projects.add(runnerProject(runner));
+  for (const ws of workspaces) {
+    const p = workspaceProject(ws);
+    if (p) projects.add(p);
+  }
+  for (const dev of devServers) if (dev?.project) projects.add(String(dev.project));
+
+  const out = {};
+  for (const p of sortedProjects(projects)) out[p] = { rows: [], runners: [], workspaces: [], devServers: [] };
+  const ensure = (p) => (out[p] ||= { rows: [], runners: [], workspaces: [], devServers: [] });
+
+  for (const row of rows) ensure(rowProject(row)).rows.push(row);
+  for (const runner of runners) ensure(runnerProject(runner)).runners.push(runner);
+  for (const ws of workspaces) {
+    const p = workspaceProject(ws);
+    if (p) ensure(p).workspaces.push(ws);
+  }
+  for (const dev of devServers) if (dev?.project) ensure(String(dev.project)).devServers.push(dev);
+
+  const workspaceIds = new Set(workspaces.map(w => String(w?.id || "")).filter(Boolean));
+  const orphans = [];
+  const ambiguous = [];
+
+  for (const runner of runners) {
+    if (isBusInternalRunner(runner, bus)) continue;
+    const p = runnerProject(runner);
+    if (!p) {
+      ambiguous.push({ type: "runner-without-project", pid: runner.pid, agent: runner.agent, dir: runner.dir });
+    } else if (!rows.some(row => rowMatchesRunner(row, runner))) {
+      orphans.push({ type: "live-runner-without-row", project: p, agent: runner.agent, pid: runner.pid, dir: runner.dir });
+    }
+  }
+
+  for (const ws of workspaces) {
+    const p = workspaceProject(ws);
+    if (!p) {
+      ambiguous.push({ type: "non-trantor-workspace", id: ws.id, title: ws.title });
+    } else if (!runners.some(r => runnerProject(r) === p)) {
+      orphans.push({ type: "workspace-without-live-runner", project: p, id: ws.id, title: ws.title });
+    }
+  }
+
+  for (const row of rows) {
+    const p = rowProject(row);
+    const kind = String(row?.kind || "");
+    let live = runners.some(runner => rowMatchesRunner(row, runner));
+    if (kind === "cmuxws") live = workspaceIds.has(String(row?.handle || ""));
+    if (!live) {
+      orphans.push({
+        type: "dead-tracking-row",
+        project: p,
+        kind: row.kind,
+        agent: row.agent,
+        handle: row.handle,
+      });
+    } else if (!p) {
+      ambiguous.push({ type: "legacy-tracking-row", kind: row.kind, agent: row.agent, handle: row.handle });
+    }
+  }
+
+  for (const p of Object.keys(out)) {
+    const project = out[p];
+    project.counts = {
+      rows: project.rows.length,
+      runners: project.runners.length,
+      workspaces: project.workspaces.length,
+      devServers: project.devServers.length,
+    };
+  }
+
+  return { projects: out, orphans, ambiguous, reaped };
+}
+
+function oldEnough(path, now, maxAgeMs) {
+  try { return now - statSync(path).mtimeMs > maxAgeMs; } catch { return false; }
+}
+
+function liveSeatFiles(runners) {
+  const keys = new Set();
+  for (const r of safeArray(runners)) {
+    const p = runnerProject(r);
+    const agent = String(r?.agent || "");
+    if (p && agent) keys.add(`${p}-${agent}.sh`);
+  }
+  return keys;
+}
+
+export function reapStaleArtifacts({ bus = busDir(), runners = [], now = Date.now(), remove = rmSync } = {}) {
+  const reaped = [];
+  const seats = join(bus, "seats");
+  const liveSeats = liveSeatFiles(runners);
+  try {
+    for (const name of readdirSync(seats)) {
+      if (!name.endsWith(".sh")) continue;
+      const path = join(seats, name);
+      if (liveSeats.has(name) || !oldEnough(path, now, 14 * DAY)) continue;
+      remove(path, { force: true });
+      reaped.push({ type: "seat-script", path, reason: "no matching live runner and mtime >14d" });
+    }
+  } catch {}
+
+  try {
+    for (const name of readdirSync(bus)) {
+      const startup = /^kimi-startup-.*\.txt\.consumed$/.test(name) || /^startup-.*\.txt\.consumed$/.test(name);
+      if (!startup) continue;
+      const path = join(bus, name);
+      if (!oldEnough(path, now, 7 * DAY)) continue;
+      remove(path, { force: true });
+      reaped.push({ type: "startup-stash", path, reason: "consumed startup stash mtime >7d" });
+    }
+  } catch {}
+  return reaped;
+}
+
+export async function loadResources() {
+  try {
+    return await import(pathToFileURL(join(ROOT, "hooks/lib/resources.mjs")).href);
+  } catch {
+    return emptyResources;
+  }
+}
+
+function humanList(items, fmt, empty = "none") {
+  return items.length ? items.map(fmt).join(", ") : empty;
+}
+
+export function formatHuman(report) {
+  const lines = ["trantor patrol report"];
+  const projectNames = sortedProjects(Object.keys(report.projects || {}));
+  if (projectNames.length === 0) lines.push("projects: none");
+  for (const p of projectNames) {
+    const project = report.projects[p];
+    lines.push(`\nproject ${displayProject(p)}`);
+    lines.push(`  rows: ${humanList(project.rows, r => `${r.agent || "?"}/${r.kind || "?"}:${r.handle || "?"}`)}`);
+    lines.push(`  live runners: ${humanList(project.runners, r => `${r.agent || "?"}(pid ${r.pid || "?"})`)}`);
+    lines.push(`  cmux workspaces: ${humanList(project.workspaces, w => `${w.title || "?"}:${w.id || "?"}`)}`);
+    if (project.devServers?.length) lines.push(`  dev servers: ${humanList(project.devServers, d => `${d.pid || "?"} ${d.cmd || ""}`.trim())}`);
+  }
+  lines.push(`\norphans: ${report.orphans.length}`);
+  for (const item of report.orphans) lines.push(`  - ${item.type}: ${displayProject(item.project)} ${item.agent || item.title || item.handle || item.id || ""}`.trimEnd());
+  lines.push(`ambiguous: ${report.ambiguous.length}`);
+  for (const item of report.ambiguous) lines.push(`  - ${item.type}: ${item.agent || item.title || item.dir || item.id || ""}`.trimEnd());
+  lines.push(`reaped: ${report.reaped.length}`);
+  for (const item of report.reaped) lines.push(`  - ${item.type}: ${item.path || item.output || ""}`.trimEnd());
+  return `${lines.join("\n")}\n`;
+}
+
+export async function runPatrol({ args = [], resources = null, env = process.env, now = Date.now(), remove = rmSync } = {}) {
+  const json = args.includes("--json");
+  const reap = args.includes("--reap");
+  const res = resources || await loadResources();
+  let inv = { rows: [], runners: [], workspaces: [], devServers: [] };
+  try { inv = await res.inventory?.(null) || inv; } catch {}
+  const reaped = [];
+  if (reap) {
+    try {
+      const output = await res.cleanDead?.(null);
+      if (output) reaped.push({ type: "cleanDead", output: String(output).trim() });
+    } catch {}
+    reaped.push(...reapStaleArtifacts({ bus: busDir(env), runners: inv.runners, now, remove }));
+  }
+  const report = buildPatrolReport(inv, reaped, { bus: busDir(env) });
+  return json ? `${JSON.stringify(report, null, 2)}\n` : formatHuman(report);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) {
+  runPatrol({ args: process.argv.slice(2) })
+    .then(s => process.stdout.write(s))
+    .catch(() => process.stdout.write(formatHuman(buildPatrolReport())));
+}

package/hooks/lib/resources.mjs

@@ -0,0 +1,167 @@
+// trantor — resource inventory (INTERSESSION-OPS-CONTRACT #4214). PURE DETECTION: what crew
+// tracking rows exist, which crew runners are actually alive, which cmux workspaces are open,
+// which dev servers run under a directory. Sessions ADOPT live crews; boots clean the provably
+// dead. Provably dead = no live process AND no bus heartbeat AND no owning session — one signal
+// is never proof, and NOTHING here ever kills a process. The only mutation is cleanDead(), which
+// shells `crew.sh prune` (drops dead TRACKING ROWS, never processes).
+//
+// Hard rules (contract-frozen): every export is fail-silent ([] / "" on any error, never throws)
+// and every subprocess has a ≤2s timeout. Hooks run inside the user's tool loop — a throw or a
+// hang breaks a session.
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { gitRoot } from "../../lib/project.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));            // <pkg>/hooks/lib
+const PKGROOT = join(HERE, "..", "..");
+const CMUX_APP_BIN = "/Applications/cmux.app/Contents/Resources/bin/cmux";
+const TIMEOUT = 2000;                                            // contract: every subprocess ≤2s
+
+const busDir = () => process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus");
+
+// Run a subprocess, return stdout; "" on ANY failure (missing binary, nonzero exit, timeout).
+function run(cmd, args, env = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: "utf8", timeout: TIMEOUT,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, ...env },
+    });
+  } catch { return ""; }
+}
+
+// Same, but reports ENOENT separately so callers can fall back to an alternate binary path
+// WITHOUT masking a real failure of a binary that exists (a cmux that ran and said "socket off"
+// must yield [], not trigger a retry against a second cmux).
+function runMaybeMissing(cmd, args, env = {}) {
+  try {
+    return { out: execFileSync(cmd, args, {
+      encoding: "utf8", timeout: TIMEOUT,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, ...env },
+    }), missing: false };
+  } catch (e) { return { out: "", missing: e && e.code === "ENOENT" }; }
+}
+
+// ~/.agent-bus/crew-windows.txt → [{project,kind,agent,handle}]. Row schema (crew.sh v3):
+// PROJECT<TAB>KIND<TAB>AGENT<TAB>HANDLE, KIND ∈ win|attach|tmux|cmux|cmuxws. Legacy v2 rows are
+// bare AGENT<TAB>WID (2 fields, no project) → {project:"",kind:"win"}. Anything else is skipped.
+export function listCrewRows() {
+  try {
+    const f = join(busDir(), "crew-windows.txt");
+    if (!existsSync(f)) return [];
+    const out = [];
+    for (const line of readFileSync(f, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      const p = line.split("\t");
+      if (p.length >= 4) out.push({ project: p[0], kind: p[1], agent: p[2], handle: p[3] });
+      else if (p.length === 2 && p[0]) out.push({ project: "", kind: "win", agent: p[0], handle: p[1] });
+    }
+    return out;
+  } catch { return []; }
+}
+
+// Parse `ps -axo pid=,command=` once; shared by liveRunners() and devServers().
+function psTable() {
+  const out = run("ps", ["-axo", "pid=,command="]);
+  const rows = [];
+  for (const line of out.split("\n")) {
+    const m = line.match(/^\s*(\d+)\s+(\S.*)$/);
+    if (m) rows.push({ pid: Number(m[1]), cmd: m[2] });
+  }
+  return rows;
+}
+
+// Live crew-runner processes → [{pid,agent,dir}]. Runner argv (crew.sh RUN_CMD) is
+// `node …/crew-runner.mjs <agent> <dir>` — dir is the LAST argument, so the regex is anchored
+// on end-of-string. project=null → all runners; project given → only runners whose dir resolves
+// to that project. Resolution is the lib/project.mjs walk (git-root basename, else dir basename)
+// compared with EXACT equality — a substring/prefix test would let …/proj match a runner in
+// …/proj2 (the sibling-project reap bug).
+export function liveRunners(project = null) {
+  try {
+    const out = [];
+    for (const { pid, cmd } of psTable()) {
+      const m = cmd.match(/crew-runner\.mjs\s+(\S+)\s+(\S+)\s*$/);
+      if (!m) continue;
+      const [, agent, dir] = m;
+      if (project != null) {
+        const name = basename(gitRoot(dir) || dir);
+        if (name !== project) continue;
+      }
+      out.push({ pid, agent, dir });
+    }
+    return out;
+  } catch { return []; }
+}
+
+// Open cmux workspaces → [{id,title}] via `cmux workspace list --json` (CMUX_QUIET=1). The socket
+// may be off or cmux uninstalled — both are []. The CLI can print notice chatter before the JSON,
+// so parse from the first [ or { (same trick as crew.sh).
+export function cmuxWorkspaces() {
+  try {
+    let r = runMaybeMissing("cmux", ["workspace", "list", "--json"], { CMUX_QUIET: "1" });
+    if (r.missing) r = runMaybeMissing(CMUX_APP_BIN, ["workspace", "list", "--json"], { CMUX_QUIET: "1" });
+    if (!r.out) return [];
+    const i = r.out.search(/[\[{]/);
+    if (i < 0) return [];
+    const o = JSON.parse(r.out.slice(i));
+    const a = Array.isArray(o) ? o : (o.workspaces || []);
+    if (!Array.isArray(a)) return [];
+    return a
+      .map(w => ({ id: String(w?.id ?? ""), title: String(w?.custom_title ?? w?.name ?? w?.title ?? "") }))
+      .filter(w => w.id);
+  } catch { return []; }
+}
+
+// Dev-ish processes (next dev | vite | npm run dev | tail -f) whose CWD is under dir →
+// [{pid,cmd}]. CWD comes from `lsof -a -p <pid> -d cwd -Fn`. "Under" is anchored: cwd === dir or
+// cwd starts with dir + path separator — never a bare prefix (…/proj must not swallow …/proj2).
+const DEV_RE = /(?:^|\/)next\s+dev(?:\s|$)|(?:^|\s|\/)vite(?:\s|$)|\bnpm\s+run\s+dev\b|\btail\s+-f\b/;
+export function devServers(dir) {
+  try {
+    if (!dir) return [];
+    const root = String(dir).replace(/\/+$/, "");
+    if (!root) return [];
+    const out = [];
+    for (const { pid, cmd } of psTable()) {
+      if (!DEV_RE.test(cmd)) continue;
+      const lsof = run("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]);
+      const cwd = (lsof.match(/^n(.+)$/m) || [])[1]?.replace(/\/+$/, "") || "";
+      if (cwd && (cwd === root || cwd.startsWith(root + "/"))) out.push({ pid, cmd });
+    }
+    return out;
+  } catch { return []; }
+}
+
+// Compose the full inventory. project=null → machine-wide; devServers only when a directory for
+// the project is actually known (a live runner's dir, or our own cwd when it resolves to the
+// project) — else [].
+export function inventory(project = null) {
+  try {
+    const rows = listCrewRows();
+    const runners = liveRunners(project);
+    const workspaces = cmuxWorkspaces();
+    let devs = [];
+    if (project != null) {
+      let dir = runners[0]?.dir || "";
+      if (!dir) {
+        const cwd = process.cwd();
+        if (basename(gitRoot(cwd) || cwd) === project) dir = cwd;
+      }
+      if (dir) devs = devServers(dir);
+    }
+    return { rows, runners, workspaces, devServers: devs };
+  } catch { return { rows: [], runners: [], workspaces: [], devServers: [] }; }
+}
+
+// The ONLY mutation: `bash <pkgroot>/bin/crew.sh prune` — drops crew-windows.txt rows whose
+// handles are provably dead (never touches a process). RELAY_PROJECT is set when a project is
+// given. Returns the command's stdout; "" on any failure.
+export function cleanDead(project = null) {
+  return run("bash", [join(PKGROOT, "bin", "crew.sh"), "prune"],
+    project ? { RELAY_PROJECT: String(project) } : {});
+}

package/hooks/sessionstart.mjs

@@ -7,9 +7,10 @@
 //   env RELAY_URL  →  ~/.agent-bus/config.json {"url": "..."}  →  http://127.0.0.1:4477
 // Identity: env RELAY_SESSION  →  "<hostname>:<basename(cwd)>"  (stable per project/machine)
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
-import { execSync } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { resolveProject, hostId } from "../lib/project.mjs";
 import { formatSubagentManifest } from "../lib/subagent-manifest.mjs";
 import { updateAvailable, maybeNotifyDesktop, readConfig } from "./lib/update-check.mjs";
@@ -94,6 +95,11 @@ function sanitize(s) {
   return out;
 }
 
+// Fail-silent wrapper for the optional #4214 resources detection lib (hooks/lib/resources.mjs).
+// A throwing detector — or a half-landed lib whose export isn't a function yet — must never break
+// session start; this returns dft on any error. The lib is itself fail-silent, this is defense-in-depth.
+function safeInv(fn, dft = []) { try { const r = fn(); return r == null ? dft : r; } catch { return dft; } }
+
 // Session title for the picker / `claude --resume` / Claude mobile. Claude Code otherwise names a session
 // after its FIRST PROMPT (the `ai-title` transcript entry) — so several sessions started with the same
 // prompt (or sibling sessions in different projects) all look alike. We name it "<project> · <current work>"
@@ -156,6 +162,64 @@ try {
     additionalContext += `</trantor>\n`;
   }
 
+  // ── ADOPT live crews (intersession-ops S1+S2, contract #4215) ─────────────────
+  // Every boot inventories leftover crew resources via the #4214 detection lib and steers the
+  // session toward ADOPTING a live crew rather than `trantor up`-ing over it (replace-in-place
+  // kills the seats' accumulated context). Detection is sync + fail-silent; the dead-row cleanup
+  // runs in a detached, unref'd child so it NEVER blocks session start. The lib import is OPTIONAL
+  // on purpose — until kimi lands #4214 this whole block is a no-op rather than a hard import
+  // error that would break every session start. Added latency <300ms; everything wrapped; all
+  // injected text is sanitized; block kept ≤12 lines.
+  let res = null;
+  try { res = await import("./lib/resources.mjs"); } catch {}
+  if (res) {
+    try {
+      const __t0 = process.hrtime.bigint();
+      const __elapsedMs = () => Number(process.hrtime.bigint() - __t0) / 1e6;
+      const runners  = safeInv(() => (typeof res.liveRunners === "function" ? res.liveRunners(project) : []), []);
+      const rows     = safeInv(() => (typeof res.listCrewRows  === "function" ? res.listCrewRows()        : []), []);
+      const projRows = (Array.isArray(rows) ? rows : []).filter(r => r && r.project === project);
+      // Only touch the (relatively) costly devServers/lsof when we're actually emitting a block.
+      if ((Array.isArray(runners) && runners.length > 0) || projRows.length > 0) {
+        // devServers is "report only" and (per kimi's #4214 impl) costs ~180ms via per-match lsof.
+        // Include it only while the <300ms hard latency budget still has room; otherwise defer to the
+        // duty patrol (#4216), which inventories dev servers machine-wide. A solo session (no crew →
+        // liveRunners ~50ms) always gets the dev-server line; a live multi-seat crew usually defers.
+        let devSrv = [];
+        if (__elapsedMs() < 120) devSrv = safeInv(() => (typeof res.devServers === "function" ? res.devServers(projectDir) : []), []);
+        else process.stderr.write(`[trantor] devServers deferred to patrol (${__elapsedMs().toFixed(0)}ms elapsed, <300ms budget)\n`);
+        const seats = (Array.isArray(runners) ? runners : [])
+          .map(r => `${sanitize(r.agent || "?")}(${r.pid || "?"})`).filter(Boolean).join(", ");
+        const devs = (Array.isArray(devSrv) ? devSrv : [])
+          .map(d => `${sanitize(String(d.cmd || "dev").trim().split(/\s+/)[0] || "dev")}(${d.pid || "?"})`).join(", ");
+        const adopt = [];
+        if (Array.isArray(runners) && runners.length > 0) {
+          adopt.push(`A LIVE crew for "${sanitize(project)}" is already running (seats: ${seats}).`);
+          adopt.push(`ADOPT it: read \`relay_board\`, announce yourself to the seats over the bus, and continue their in-flight work.`);
+          adopt.push(`Do NOT run \`trantor up\` over healthy seats — replace-in-place kills their context.`);
+          if (devs) adopt.push(`Dev servers already up: ${devs} (report only — leave them running).`);
+          adopt.push(`Provably-dead tracking rows are being cleaned up in the background.`);
+        } else {
+          adopt.push(`No live crew for "${sanitize(project)}", but ${projRows.length} stale tracking row(s) exist from a prior session.`);
+          adopt.push(`Background cleanup is verifying them and dropping only the provably-dead (no live process AND no heartbeat AND no owning session).`);
+          if (devs) adopt.push(`Dev servers up: ${devs} (report only).`);
+        }
+        additionalContext += `<trantor-resources>\n${adopt.join("\n")}\n</trantor-resources>\n`;
+        process.stderr.write(`[trantor] crew inventory: ${runners.length} live, ${projRows.length} stale row(s) for ${project}\n`);
+      }
+    } catch {}
+    // Fire-and-forget dead-row cleanup — detached + unref'd + stdio ignored, NEVER awaited. We call
+    // cleanDead(project) by name through the #4214 lib; a missing/half-landed lib → child exits
+    // silently. This is the ONLY mutation and it drops dead tracking rows, nothing live.
+    try {
+      const modPath = join(dirname(fileURLToPath(import.meta.url)), "lib", "resources.mjs");
+      const kid = spawn(process.execPath, ["--input-type=module", "-e",
+        `import(${JSON.stringify(modPath)}).then(m=>{try{if(typeof m.cleanDead==="function")m.cleanDead(${JSON.stringify(project)})}catch{}}).catch(()=>{})`
+      ], { detached: true, stdio: "ignore", env: { ...process.env, RELAY_PROJECT: project } });
+      kid.unref();
+    } catch {}
+  }
+
   // CATCH-UP: a project is a DURABLE, continuous lane — not a session. Before doing
   // anything, this session reconciles with the living board: what's been built, what's
   // in flight, what's queued, plus the latest commits. So a fresh window resumes the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.61",
+  "version": "0.17.63",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -11,7 +11,7 @@
     "pg": "^8.22.0"
   },
   "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-handoff-guard.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-reaper.mjs && node test-events.mjs && node test-scrub.mjs && node test-store-delta.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-inbox-delivery.mjs && node test-hub-routing.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && bash test-crew.sh"
+    "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 && node test-inflight.mjs && node test-notify.mjs && node test-focus.mjs && node test-reaper.mjs && node test-events.mjs && node test-scrub.mjs && node test-store-delta.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-inbox-delivery.mjs && node test-hub-routing.mjs && python3 engine/test-routing.py && node test-reconcile.mjs && node test-resources.mjs && node test-patrol.mjs && bash test-crew.sh"
   },
   "description": "The hub-world for AI agent crews — 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": [