trantor 0.15.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "agent-bus",
+  "owner": { "name": "Sasha Bogojevic", "email": "hello@hivedigitalllc.com" },
+  "metadata": {
+    "description": "Live message bus, presence, project Kanban + context-handoff for independent AI coding agents (Claude, Codex, Gemini, …)",
+    "version": "0.14.0"
+  },
+  "plugins": [
+    {
+      "name": "agent-bus",
+      "source": "./",
+      "description": "Let independent AI coding sessions — Claude Code, Codex, Gemini, any MCP agent — talk to each other live: auto-register, see the live roster, message/coordinate, and watch it all on a project-grouped Kanban dashboard. Includes the relay MCP, a SessionStart auto-discovery hook, and a PreCompact context-handoff so a fresh session can take over a full window instead of compacting.",
+      "version": "0.14.0",
+      "author": { "name": "Sasha Bogojevic" },
+      "category": "development",
+      "keywords": ["multi-agent", "coordination", "mcp", "hooks", "kanban", "context-handoff", "message-bus", "claude-code", "codex", "gemini"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "agent-bus",
+  "version": "0.14.0",
+  "description": "Live message bus, presence, project Kanban + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
+  "mcpServers": {
+    "relay": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp.mjs"]
+    }
+  },
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sasha Bogojevic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+<div align="center">
+
+```
+████████╗██████╗  █████╗ ███╗   ██╗████████╗ ██████╗ ██████╗
+╚══██╔══╝██╔══██╗██╔══██╗████╗  ██║╚══██╔══╝██╔═══██╗██╔══██╗
+   ██║   ██████╔╝███████║██╔██╗ ██║   ██║   ██║   ██║██████╔╝
+   ██║   ██╔══██╗██╔══██║██║╚██╗██║   ██║   ██║   ██║██╔══██╗
+   ██║   ██║  ██║██║  ██║██║ ╚████║   ██║   ╚██████╔╝██║  ██║
+   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+```
+
+### The hub-world for AI agent crews.
+
+**One Advisor decides how your work runs — solo, cheap inline calls, or a live crew of
+Claude Code, Codex, Gemini, Kimi & DeepSeek in their own terminal windows — routed by your
+actual plans, supervised on a live board, learning from every failure.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+![Node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)
+![Agents](https://img.shields.io/badge/crew-Claude%20%C2%B7%20Codex%20%C2%B7%20Gemini%20%C2%B7%20Kimi%20%C2%B7%20DeepSeek-D97757)
+![Tests](https://img.shields.io/badge/tests-37%2F37-2DD4BF)
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install -g trantor
+trantor setup        # hub becomes an always-on service + config + wires your AI CLIs + doctor
+```
+
+Then give Claude Code (the orchestrator) the plugin:
+
+```bash
+claude plugin marketplace add sashabogi/trantor
+claude plugin install agent-bus
+```
+
+That's it. (Prefer source? `git clone https://github.com/sashabogi/trantor && cd trantor &&
+npm install && bash deploy/setup.sh` — identical result.)
+
+## What to expect on first run
+
+`trantor setup` ends with the **doctor** — an honest map of where you stand:
+
+```
+TRANTOR DOCTOR
+
+core
+  ✓ node 22.x
+  ✓ hub up at http://127.0.0.1:4477
+claude (the orchestrator)
+  ✗ plugin not installed
+      → claude plugin marketplace add sashabogi/trantor && claude plugin install agent-bus
+crew CLIs (install any subset — seats follow the work)
+  ✓ codex: wired to the bus
+  ✗ codex: NOT authenticated — it will join the bus but fail on its first turn
+      → codex   (sign in with your ChatGPT account on first run)
+  – kimi: not installed (optional)
+the brain
+  ✗ quota profile not set → trantor profile set claude=max codex=plus deepseek=api
+```
+
+Fix the `→` lines (each CLI's own sign-in happens once, in that CLI), re-run `trantor doctor`
+until it's clean, then open a Claude session in any project and say **"fire up the crew."**
+
+Provider API keys (e.g. `DEEPSEEK_API_KEY`) live in one file: **`~/.agent-bus/.env`** — the
+crew runners source it automatically.
+
+## What happens when you fire up a crew
+
+1. **The Advisor moment.** Your Claude cuts the work into difficulty-tagged packages, calls
+   `relay_advise`, and shows you the full picture *before spending anything*: mode
+   (`solo | scrooge | crew | hybrid`), a routing table with a **reason per package**, why
+   that many seats ("seats follow the work, not the install list"), and a real-money estimate
+   with quota-pool accounting. You say go.
+2. **Windows open.** `trantor up codex gemini kimi deepseek:deepseek-v4-pro` spawns one titled
+   terminal window per agent (`agent:model` pins a model), **serialized and then verified on
+   the bus** — the launcher ends with "crew verified" or names the no-shows loudly. The
+   orchestrator never gets a green lie.
+3. **Work flows over the bus.** Contracts arrive as messages; each agent owns its own files;
+   coordination happens in <280-char messages you can read on the dashboard. Crew members
+   live under a **runner**: the CLI works one turn and exits, the runner long-polls the bus
+   for free (it's also the heartbeat) and resumes the CLI — with full context — when the next
+   message lands. **Idle agents cost zero tokens and never die.**
+4. **The board tells the truth.** Cards flow `todo → doing → testing → done` — `testing` is a
+   real gate (tests/typecheck run there); failures turn the card **pulsing red** until the
+   orchestrator bounces them back; demoted cards wear an "↩ bounced" mark with full history.
+5. **It learns.** Failures become lessons (`relay_lesson`), stored on the hub and **injected
+   into every future crew's prompts** — global or per-CLI. Your crew gets smarter every run.
+
+## The dashboard — `trantor ui`
+
+A live command center at `http://127.0.0.1:4477`, grouped by **project**:
+
+- **BOARD view** — Kanban with the testing gate, difficulty + model badges per card, agent
+  chips with provider logos, live status, and quota-pool tags.
+- **FLOW view** — the same work as an n8n-style dependency graph: parallel streams fanning
+  out and converging into integration, edges lighting up as work flows (green = done feeding
+  forward, animated blue = active), **red ↩n loops where work bounced back**. Drag nodes to
+  rearrange, ⌘+scroll / pinch to zoom, FIT/AUTO controls. Pick per project; your choice sticks.
+- **Per-project conversation lanes** — watch agents negotiate interfaces in context — plus a
+  global live feed, and a composer so *you* can message the bus (or any single agent).
+- **🪙 economics pill** — live Scrooge ledger: real spend, savings vs frontier pricing.
+
+## The brain — plan-aware economics
+
+Trantor's economics engine ([Scrooge](https://github.com/sashabogi/token-scrooge) — installed
+automatically by `trantor setup`) knows model capabilities, per-1M costs, and keeps the
+ledger; Trantor turns that into decisions:
+
+- **Declare your plans once:** `trantor profile set claude=max codex=plus gemini=tier kimi=coding-plan deepseek=api`
+- The Advisor routes by **your economics**: API-billed orchestrator → offload everything;
+  $20-tier plan → the crew *is* the only way a real build fits; max-tier → context horizon
+  decides. **Quota pooling**: one build spread across your separate subscription buckets —
+  measured example: a five-vendor 3D game build, API-equivalent $200–600, **actual spend $2.29**.
+- **Fractal delegation** (`relay_scrooge`): the architect *and* crew members push stateless
+  grunt work to cheap models, with ledger receipts.
+
+## Context handoff — sessions that never hit the wall
+
+A PreCompact hook writes a rich handoff before Claude Code compacts; a fresh session in the
+same project **takes over with a brand-new full context window**. Works manually from any
+agent via `relay_handoff`. Optional macOS auto-prompt (`autoHandoffPrompt` in
+`~/.agent-bus/config.json`) offers to open the fresh session for you, with a timeout.
+
+Why crews never exhaust the orchestrator: bus messages are **by reference** (~70 tokens),
+work products stay in each agent's own context — the orchestrator burns at coordination
+rate, not work rate.
+
+## The tools (MCP — every agent on the bus gets these)
+
+| Tool | What it does |
+|---|---|
+| `relay_advise(task, packages, horizon?)` | **The Advisor** — mode + reasoned per-package routing + cost estimate + ready-to-use card args |
+| `relay_send(to, text)` / `relay_inbox` / `relay_wait(t)` | Live messaging: direct, read-new, long-poll wake |
+| `relay_peers` / `relay_status(text)` / `relay_whoami` | Presence: who's alive (honest, heartbeat-backed), doing what |
+| `relay_project_brief(text)` | The project's what/why on the dashboard |
+| `relay_task_add(title, …, difficulty, model, deps)` | Cards with difficulty/model badges + DAG edges for the flow view |
+| `relay_task_move(id, status)` | `todo → doing → testing → done` (the gate), `failed`, `blocked` |
+| `relay_board` | The project's full board, as text |
+| `relay_scrooge(prompt, task?, difficulty?)` | Fractal cheap-model delegation, with the ledger receipt |
+| `relay_lesson(text, scope?)` | Record a failure lesson — auto-injected into all future crews |
+| `relay_handoff(summary)` | Full-window session succession |
+
+## The CLI
+
+```
+trantor setup | doctor | connect | profile | up <agents…> | down | ui | advise | hub | watch
+```
+
+`trantor up` notes: `agent:model` pins a model (`deepseek:deepseek-v4-pro`); spawns are
+verified on the bus with one retry; geometry auto-detects the screen you're working on
+(`CREW_RECT="X,Y,W,H"` to override); `trantor down` kills crew processes via their ttys and
+closes windows without macOS "Terminate?" dialogs.
+
+## Works with any MCP agent
+
+Claude Code, Codex CLI, Gemini CLI, Kimi Code CLI, OpenCode (DeepSeek) are wired by
+`trantor connect` automatically (idempotent, backed-up, never overwrites your customizations).
+Anything else that speaks MCP: point it at `mcp.mjs` with `RELAY_AGENT=<brand>` — loading the
+server auto-registers the session, so presence works before the model says a word.
+
+## How it works
+
+```
+ Claude (architect/plugin)   codex ─ runner   gemini ─ runner   kimi ─ runner   deepseek ─ runner
+        │ advise/contracts        │ one turn, exit; runner long-polls (free) + resumes with context
+        └───────────┬─────────────┴──────────────┴────────────────┴────────────────┘
+                    ▼
+              hub.mjs  ←— plain HTTP + SSE · presence/messages/board/lessons/economics
+              (Node built-ins only · state in ~/.agent-bus/bus.json · loopback by default)
+                    ▲
+              dashboard (ui.html) · BOARD/FLOW · conversation lanes · 🪙 ledger
+```
+
+Config: `RELAY_URL` env → `~/.agent-bus/config.json` → `http://127.0.0.1:4477`.
+Identity: `RELAY_SESSION` → `RELAY_AGENT:<project-folder>` → `<hostname>:<project-folder>`.
+
+**Local-first and safe:** the hub binds loopback; no accounts, no cloud, no exposure. An
+always-on/remote hub (private tailnet, or public with auth) is on the roadmap — never expose
+the hub publicly without auth.
+
+*Heritage note: Trantor grew out of **agent-bus** — package internals still carry some
+`agent-bus`/`relay_*` identifiers; they migrate in one planned breaking release.*
+
+## Honest limits
+
+- You can't interrupt an agent **mid-turn**; messages land when its current turn ends (idle
+  agents wake instantly via their runner).
+- Window spawning is macOS (Terminal.app); on Linux the launcher prints per-agent commands
+  to run in your own terminals. Hub/MCP/dashboard are cross-platform.
+- The hub is deliberately tiny (in-memory + JSON file) — a coordination bus, not a message queue.
+- Each CLI's sign-in is its own (ChatGPT, Google, Kimi accounts) — the doctor detects state
+  and names the fix, but can't log in for you.
+
+## Tests
+
+```bash
+npm test    # unit + 37 protocol-level scenario drills with mock agents (no LLMs, seconds, $0):
+            # honest presence, spawn no-shows, the testing gate, bounce trails, lessons,
+            # advisor decisions across plan tiers, deps validation, virgin-machine doctor
+```
+
+## License
+
+[MIT](./LICENSE) © 2026 Sasha Bogojevic · Built with [Claude Code](https://claude.com/claude-code) ·
+Brain by [Scrooge](https://github.com/sashabogi/token-scrooge)

package/bin/advise.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// The Advisor — the brain's front door. Given work packages, decide HOW to execute:
+// solo | scrooge | crew | hybrid — from task shape × plan economics × context horizon.
+//
+//   echo '{"task":"build X","packages":[{"title":"engine","difficulty":"hard"},…]}' | node bin/advise.mjs
+//   node bin/advise.mjs --demo            # canned example
+//
+// Reads (all read-only):
+//   ~/.agent-bus/profile.json             — the user's declared plans (bin/profile.mjs)
+//   ~/.token-scrooge/registry.json        — Scrooge's models {cost_in, cost_out, good_for}
+//   ~/.token-scrooge/capabilities.json    — per-model quality scores
+// Exposed to agents as the MCP tool `relay_advise`; the crew skill calls it at kickoff.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+
+const H = homedir();
+const read = (p, fb) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fb; } };
+
+export function loadWorld() {
+  const profile = read(join(H, ".agent-bus", "profile.json"), { providers: {} });
+  const registry = read(join(H, ".token-scrooge", "registry.json"), { models: {}, tasks: {} });
+  const caps = read(join(H, ".token-scrooge", "capabilities.json"), {});
+  const has = (c) => { try { execSync(`command -v ${c}`, { stdio: "ignore", shell: "/bin/sh" }); return true; } catch { return false; } };
+  const agents = ["codex", "gemini", "kimi", "deepseek"].filter(a => has(a === "deepseek" ? "opencode" : a));
+  return { profile, registry, caps, agents, scrooge: has("scrooge") };
+}
+
+const tierOf = (profile, prov) => profile?.providers?.[prov]?.tier || "api";
+
+// pick the cheapest Scrooge model that clears the difficulty floor for a task kind
+export function scroogeModelFor(registry, caps, kind = "code", difficulty = "easy") {
+  const floor = { easy: 0, medium: 35, hard: 55 }[difficulty] ?? 0;
+  const cands = Object.entries(registry.models || {})
+    .filter(([, m]) => (m.good_for || []).includes(kind))
+    .filter(([id]) => (caps[id]?.coding ?? caps[id]?.intelligence ?? 40) >= floor)
+    .sort((a, b) => (a[1].cost_in + a[1].cost_out) - (b[1].cost_in + b[1].cost_out));
+  return cands[0] ? { model: cands[0][0], cost_in: cands[0][1].cost_in, cost_out: cands[0][1].cost_out } : null;
+}
+
+// crude per-package token forecast (input+output through the executor)
+const FORECAST = { easy: 0.3e6, medium: 1.5e6, hard: 6e6 };  // tokens
+// crew agent preference per difficulty: frontier subs take hard, cheap takes easy
+const CREW_PREF = { hard: ["codex", "gemini", "kimi", "deepseek"], medium: ["kimi", "gemini", "codex", "deepseek"], easy: ["deepseek", "kimi", "gemini", "codex"] };
+
+export function advise(input, world = loadWorld()) {
+  const { profile, registry, caps, agents, scrooge } = world;
+  const pkgs = (input.packages || []).map(p => ({ title: p.title || "work", difficulty: ["easy", "medium", "hard"].includes(p.difficulty) ? p.difficulty : "medium", kind: p.kind || "code", owner: p.owner === "self" ? "self" : (/(foundation|integration|scaffold)/i.test(p.title) ? "self" : "") }));
+  const horizon = input.horizon || (pkgs.length >= 4 ? "long" : pkgs.length >= 2 ? "medium" : "short");
+  const orchTier = tierOf(profile, "claude");
+  const n = pkgs.length, hard = pkgs.filter(p => p.difficulty === "hard").length, easy = pkgs.filter(p => p.difficulty === "easy").length;
+
+  // ---- mode decision ----
+  let mode, why = [];
+  if (n <= 1 && hard === 0 && horizon === "short") {
+    if (n === 1 && pkgs[0].difficulty === "easy" && scrooge) { mode = "scrooge"; why.push("single small stateless package — a cheap inline call beats spinning up anything"); }
+    else { mode = "solo"; why.push("one small package, short horizon — orchestrator handles it directly"); }
+  } else if (orchTier === "api") {
+    mode = "crew"; why.push("orchestrator is API-billed: every token here is money — be a thin foreman, run all work on crew quotas + Scrooge");
+  } else if (orchTier === "capped-sub" && n >= 2) {
+    mode = "crew"; why.push("orchestrator is on a capped plan: a real build can't fit in this session — spend the scarce budget on architecture + verification only");
+  } else if (n >= 3 || hard >= 1 || horizon === "long") {
+    mode = "crew"; why.push(`${n} packages${hard ? `, ${hard} hard` : ""}, ${horizon} horizon — crew isolates work in separate contexts so this session burns at coordination rate, not work rate`);
+  } else {
+    mode = "solo"; why.push("small enough to do inline without hurting the context horizon");
+  }
+  // hybrid: crew + easy packages that should be scrooge'd instead of occupying an agent
+  if (mode === "crew" && easy > 0 && scrooge) { mode = "hybrid"; why.push(`${easy} easy package(s) routed to Scrooge inline — don't burn a crew seat on grunt work`); }
+
+  // ---- routing per package ----
+  const used = {};
+  const routing = pkgs.map(p => {
+    if ((mode === "hybrid" || mode === "scrooge") && p.difficulty === "easy" && scrooge) {
+      const m = scroogeModelFor(registry, caps, p.kind, p.difficulty);
+      const tok = FORECAST.easy;
+      const cost = m ? +(tok * 0.6 * m.cost_in / 1e6 + tok * 0.4 * m.cost_out / 1e6).toFixed(3) : null;
+      return { ...p, executor: "scrooge", model: m?.model, pool: "api", est_cost_usd: cost,
+        reason: `easy + stateless → cheapest capable model (${m?.model}); not worth a crew seat` };
+    }
+    if (p.owner === "self") return { ...p, executor: "orchestrator", pool: tierOf(profile, "claude"), reason: "architect-owned (foundation/integration doctrine) — the orchestrator keeps the shared contract in its own hands" };
+    if (mode === "solo") return { ...p, executor: "orchestrator", pool: tierOf(profile, "claude"), reason: "small enough to do inline" };
+    const pref = CREW_PREF[p.difficulty].filter(a => agents.includes(a));
+    const agent = pref.sort((a, b) => (used[a] || 0) - (used[b] || 0))[0] || "deepseek";
+    used[agent] = (used[agent] || 0) + 1;
+    const pool = tierOf(profile, agent === "deepseek" ? "deepseek" : agent);
+    let est = null;
+    if (pool === "api") { // deepseek API etc — estimate real $ via registry
+      const m = registry.models?.["deepseek-v4-flash"] || { cost_in: 0.14, cost_out: 0.28 };
+      est = +((FORECAST[p.difficulty] * 0.85 * m.cost_in + FORECAST[p.difficulty] * 0.15 * m.cost_out) / 1e6).toFixed(2);
+    }
+    const why_r = p.difficulty === "hard"
+      ? `hard → strongest available coder (${agent}); its ${pool} pool means ${pool === "api" ? "real $ but cheapest capable" : "$0 marginal on existing quota"}`
+      : p.difficulty === "medium"
+        ? `medium → solid mid-tier (${agent}) keeps frontier seats free for hard work; ${pool === "api" ? "metered" : "quota"} pool`
+        : `easy → cheapest seat (${agent})`;
+    return { ...p, executor: agent, pool, est_cost_usd: est, reason: why_r };
+  });
+  // crew-size rationale: seats are EMERGENT from the work, and we say so
+  const seats = [...new Set(routing.filter(r => !["scrooge", "orchestrator"].includes(r.executor)).map(r => r.executor))];
+  const crew = {
+    seats: seats.length, of_available: agents.length, members: seats,
+    why: seats.length === 0 ? "no crew needed" :
+      `${routing.filter(r => seats.includes(r.executor)).length} crew-bound package(s) → ${seats.length} seat(s), one per concurrent work stream (load-balanced); ${agents.length - seats.length > 0 ? `${agents.length - seats.length} installed CLI(s) left idle — seats follow the work, not the install list` : "all installed CLIs engaged because the work fans that wide"}`
+  };
+
+  const apiCost = +(routing.reduce((s, r) => s + (r.est_cost_usd || 0), 0)).toFixed(2);
+  const pools = [...new Set(routing.map(r => `${r.executor}:${r.pool}`))];
+  const summary =
+    `Recommendation: ${mode.toUpperCase()}. ${why.join("; ")}. ` +
+    (mode === "crew" || mode === "hybrid"
+      ? `Routing: ${routing.map(r => `${r.title}→${r.executor}${r.model ? `(${r.model})` : ""}`).join(", ")}. ` +
+        `Estimated real-money cost ≈ $${apiCost} (everything on a subscription pool is $0 marginal — quota pooling across ${pools.length} pools).`
+      : "");
+  const table = ["| package | diff | executor (model) | pool | est $ | reason |", "|---|---|---|---|---|---|",
+    ...routing.map(r => `| ${r.title} | ${r.difficulty} | ${r.executor}${r.model ? ` (${r.model})` : ""} | ${r.pool} | ${r.est_cost_usd ?? "—"} | ${r.reason} |`)].join("\n");
+  // card_args are born as a DAG: crew cards depend on architect-owned foundation card(s);
+  // integration-titled architect cards depend on every crew card. (Indices are 1-based card
+  // creation order — the architect substitutes real ids as it creates them.)
+  const selfPkgs = routing.filter(r => r.executor === "orchestrator");
+  const foundationIdx = selfPkgs.length ? [1] : [];
+  const cards = routing.map((r, i) => ({
+    order: i + 1, title: r.title, difficulty: r.difficulty,
+    assignee: r.executor === "scrooge" || r.executor === "orchestrator" ? undefined : `${r.executor}:<project>`,
+    model: r.model || (["scrooge", "orchestrator"].includes(r.executor) ? undefined : `${r.executor}-default`),
+    via: r.executor === "scrooge" ? "relay_scrooge" : "relay_task_add",
+    deps_orders: r.executor === "orchestrator" && /integrat/i.test(r.title)
+      ? routing.map((x, j) => j + 1).filter(j => j !== i + 1)
+      : (r.executor !== "orchestrator" ? foundationIdx.filter(f => f !== i + 1) : []) }));
+  return { mode, why, crew, routing, routing_table_md: table, card_args: cards, est_api_cost_usd: apiCost, quota_pools: pools, summary, orchestrator_tier: orchTier, agents_available: agents };
+}
+
+// ---- CLI ----
+if (import.meta.url === `file://${process.argv[1]}`) {
+  let input;
+  if (process.argv.includes("--demo")) {
+    input = { task: "neon asteroids game", packages: [
+      { title: "engine+integration", difficulty: "hard" }, { title: "render/bloom", difficulty: "hard" },
+      { title: "combat+ui", difficulty: "medium" }, { title: "audio", difficulty: "medium" },
+      { title: "readme+badges", difficulty: "easy" } ] };
+  } else {
+    const stdin = readFileSync(0, "utf8").trim();
+    input = stdin ? JSON.parse(stdin) : { packages: [] };
+  }
+  const out = advise(input);
+  console.log(JSON.stringify(out, null, 2));
+}

package/bin/cli.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// trantor — the command. Thin dispatcher over the toolkit so a global npm install
+// gives you everything:  trantor setup | doctor | connect | profile | advise | up | down | hub | ui
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const [, , cmd, ...args] = process.argv;
+const run = (file, runner = process.execPath) => {
+  const child = spawn(runner, [join(ROOT, file), ...args], { stdio: "inherit", cwd: process.cwd() });
+  child.on("exit", (c) => process.exit(c ?? 0));
+};
+
+switch (cmd) {
+  case "setup":   run("deploy/setup.sh", "/bin/bash"); break;
+  case "doctor":  run("bin/doctor.mjs"); break;
+  case "connect": run("bin/connect.mjs"); break;
+  case "profile": run("bin/profile.mjs"); break;
+  case "advise":  run("bin/advise.mjs"); break;
+  case "verify":  run("bin/crew-verify.mjs"); break;
+  case "up":      process.argv.splice(2, 1); spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "up", ...args], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
+  case "down":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "down"], { stdio: "inherit", cwd: process.cwd() }).on("exit", c => process.exit(c ?? 0)); break;
+  case "hub":     run("hub.mjs"); break;
+  case "watch":   run("bin/relay-watch.mjs"); break;
+  case "ui": {
+    let url = "http://127.0.0.1:4477";
+    try { url = JSON.parse(readFileSync(join(process.env.HOME || "", ".agent-bus", "config.json"), "utf8")).url || url; } catch {}
+    spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    console.log(`dashboard → ${url}`);
+    break;
+  }
+  case "version": case "-v": case "--version":
+    console.log(JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version); break;
+  default:
+    console.log(`trantor — the hub-world for AI agent crews
+
+  trantor setup       one-shot install: hub as an always-on service + config + CLI wiring + doctor
+  trantor doctor      where do I stand? hub/plugin/CLIs/auth/keys/profile, with copy-paste fixes
+  trantor connect     (re)wire every installed AI CLI to the bus
+  trantor profile     declare your plans:  trantor profile set claude=max codex=plus deepseek=api
+  trantor up …        spawn a crew here:   trantor up codex gemini kimi deepseek:deepseek-v4-pro
+  trantor down        tear the crew down (kills processes, closes windows, no dialogs)
+  trantor ui          open the live dashboard (board + flow views)
+  trantor advise      ask the Advisor directly (JSON on stdin; --demo to see it)
+  trantor hub         run the hub in the foreground (setup installs it as a service instead)
+  trantor watch       live bus feed in the terminal
+
+Claude Code plugin (the orchestrator side):
+  claude plugin marketplace add sashabogi/trantor && claude plugin install agent-bus
+Docs: https://github.com/sashabogi/trantor`);
+}

package/bin/connect.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// agent-bus connect — wire every AI coding CLI on this machine to the bus, in one shot.
+//
+//   node bin/connect.mjs            # detect installed CLIs, patch each one's MCP config (idempotent)
+//   node bin/connect.mjs --dry-run  # show what would change, touch nothing
+//
+// Each CLI keeps its own MCP config file/format; this writes the one "relay" entry into each
+// (with a timestamped .bak backup the first time it changes a file). Claude Code is handled by
+// the plugin (claude plugin install agent-bus), so it's only verified here, not patched.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const DRY = process.argv.includes("--dry-run");
+const MCP = join(dirname(dirname(fileURLToPath(import.meta.url))), "mcp.mjs");
+const URL_ = process.env.RELAY_URL || "http://127.0.0.1:4477";
+const has = (cmd) => { try { execSync(`command -v ${cmd}`, { stdio: "ignore", shell: "/bin/sh" }); return true; } catch { return false; } };
+const stamp = new Date().toISOString().slice(0, 10);
+const backup = (p) => { const b = `${p}.bak-${stamp}`; if (!existsSync(b)) copyFileSync(p, b); return b; };
+const out = [];
+const report = (cli, status, detail = "") => out.push({ cli, status, detail });
+
+function patchJson(path, mutate) {
+  const exists = existsSync(path);
+  const d = exists ? JSON.parse(readFileSync(path, "utf8")) : {};
+  const before = JSON.stringify(d);
+  mutate(d);
+  if (JSON.stringify(d) === before) return "already wired";
+  if (!DRY) {
+    if (exists) backup(path); else mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(d, null, 2) + "\n");
+  }
+  return exists ? "wired" : "wired (new config)";
+}
+
+const relayEnv = (agent) => ({ RELAY_URL: URL_, RELAY_AGENT: agent });
+
+// ---- Claude Code: plugin handles it; verify only ----
+if (has("claude")) {
+  let st = "plugin not detected — run: claude plugin marketplace add sashabogi/trantor && claude plugin install agent-bus";
+  try {
+    const s = JSON.parse(readFileSync(join(homedir(), ".claude", "settings.json"), "utf8"));
+    if (Object.keys(s.enabledPlugins || {}).some(k => k.startsWith("agent-bus@"))) st = "plugin installed ✓";
+  } catch {}
+  report("claude", st);
+}
+
+// ---- Codex (TOML append — no TOML lib needed) ----
+if (has("codex")) {
+  const p = join(homedir(), ".codex", "config.toml");
+  const cur = existsSync(p) ? readFileSync(p, "utf8") : "";
+  if (cur.includes("[mcp_servers.relay]")) report("codex", "already wired");
+  else {
+    const block = `\n# agent-bus — auto-registers each Codex session on the bus + adds relay_* tools\n[mcp_servers.relay]\ncommand = "node"\nargs = ["${MCP}"]\nenv = { RELAY_URL = "${URL_}", RELAY_AGENT = "codex" }\n`;
+    if (!DRY) { if (existsSync(p)) backup(p); else mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, cur + block); }
+    report("codex", cur ? "wired" : "wired (new config)", p);
+  }
+}
+
+// ---- Gemini CLI ----  (existing relay entries are never overwritten — user customization wins)
+if (has("gemini")) {
+  const p = join(homedir(), ".gemini", "settings.json");
+  report("gemini", patchJson(p, d => {
+    d.mcpServers ||= {};
+    d.mcpServers.relay ||= { command: "node", args: [MCP], env: relayEnv("gemini") };
+  }), p);
+}
+
+// ---- Kimi CLI ----
+if (has("kimi")) {
+  const p = join(homedir(), ".kimi", "mcp.json");
+  report("kimi", patchJson(p, d => {
+    d.mcpServers ||= {};
+    d.mcpServers.relay ||= { command: "node", args: [MCP], env: relayEnv("kimi") };
+  }), p);
+}
+
+// ---- OpenCode ----
+if (has("opencode")) {
+  const p = join(homedir(), ".config", "opencode", "opencode.json");
+  report("opencode", patchJson(p, d => {
+    d.$schema ||= "https://opencode.ai/config.json";
+    d.mcp ||= {};
+    d.mcp.relay ||= { type: "local", command: ["node", MCP], enabled: true, environment: relayEnv("opencode") };
+  }), p);
+}
+
+const found = out.length;
+console.log(`agent-bus connect${DRY ? " (dry run)" : ""} — hub: ${URL_}`);
+for (const r of out) console.log(`  ${r.cli.padEnd(9)} ${r.status}${r.detail ? `  (${r.detail})` : ""}`);
+if (!found) console.log("  no supported CLIs found on PATH (claude, codex, gemini, kimi, opencode)");
+console.log(DRY ? "\nRun without --dry-run to apply." : "\nDone. New sessions of each CLI auto-join the bus.");