trantor 0.15.0

package/deploy/setup.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# trantor one-shot setup: hub service + config + CLI wiring + doctor.
+set -e
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="$(command -v node)"
+[ -z "$NODE" ] && { echo "node >= 18 required"; exit 1; }
+mkdir -p "$HOME/.agent-bus"
+[ -f "$HOME/.agent-bus/config.json" ] || echo '{"url":"http://127.0.0.1:4477"}' > "$HOME/.agent-bus/config.json"
+touch "$HOME/.agent-bus/.env"   # one place for provider API keys (e.g. DEEPSEEK_API_KEY=…)
+if [ "$(uname)" = "Darwin" ]; then
+  PL="$HOME/Library/LaunchAgents/com.trantor.hub.plist"
+  sed -e "s|__NODE__|$NODE|" -e "s|__REPO__|$REPO|" "$REPO/deploy/com.trantor.hub.plist" > "$PL"
+  launchctl bootout "gui/$(id -u)/com.trantor.hub" 2>/dev/null || true
+  launchctl bootstrap "gui/$(id -u)" "$PL"
+  echo "✓ hub installed as launchd service (starts at login, restarts on crash)"
+else
+  echo "Linux: run the hub under systemd/tmux:  RELAY_PORT=4477 node $REPO/hub.mjs"
+fi
+# the economics engine — part of Trantor, installed automatically (it IS the brain)
+if ! command -v scrooge >/dev/null 2>&1 && [ ! -x "$HOME/.local/bin/scrooge" ]; then
+  echo "▸ installing the economics engine (routing + cost ledger)…"
+  curl -fsSL https://raw.githubusercontent.com/sashabogi/token-scrooge/main/install.sh | bash \
+    && echo "✓ economics engine installed" \
+    || echo "  (engine install failed — Trantor still works; the Advisor runs without live pricing. Retry: trantor setup)"
+  case ":$PATH:" in *":$HOME/.local/bin:"*) ;; *) echo "  note: add ~/.local/bin to your PATH";; esac
+fi
+node "$REPO/bin/connect.mjs"
+echo
+node "$REPO/bin/doctor.mjs" || true
+echo
+echo "Next: claude plugin marketplace add sashabogi/trantor && claude plugin install agent-bus"

package/hooks/hooks.json

@@ -0,0 +1,11 @@
+{
+  "description": "agent-bus — auto-register each session + inject live roster (SessionStart); write a handoff before compaction (PreCompact)",
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart.mjs" } ] }
+    ],
+    "PreCompact": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/precompact.mjs" } ] }
+    ]
+  }
+}

package/hooks/precompact.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// agent-bus PreCompact hook — fires right before Claude Code compacts a full
+// context window. Instead of (just) compacting, it writes a rich HANDOFF so you can
+// open a FRESH session that takes over with a new full window. The SessionStart hook
+// detects the pending handoff and loads it.
+//
+// Handoff generation: if `scrooge` is on PATH, it summarizes the recent transcript
+// into a structured handoff cheaply; otherwise it falls back to a raw transcript tail.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } 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";
+
+const HANDOFF_DIR = join(homedir(), ".agent-bus", "handoffs");
+
+function readStdin() {
+  return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => (d += c)); process.stdin.on("end", () => res(d));
+    setTimeout(() => res(d), 100); });
+}
+
+// Pull readable recent conversation text from a Claude Code transcript JSONL.
+function recentTranscript(path, maxChars = 16000) {
+  try {
+    const rows = readFileSync(path, "utf8").split("\n").filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    const turns = [];
+    for (const r of rows) {
+      if (!(r.type === "user" || r.type === "assistant") || !r.message) continue;
+      const c = r.message.content;
+      let text = "";
+      if (typeof c === "string") text = c;
+      else if (Array.isArray(c)) text = c.filter(b => b?.type === "text").map(b => b.text).join("\n");
+      if (text.trim() && !text.startsWith("<task-notification") && !text.startsWith("<command")) {
+        turns.push(`### ${r.type.toUpperCase()}\n${text.slice(0, 2000)}`);
+      }
+    }
+    let out = turns.join("\n\n");
+    if (out.length > maxChars) out = out.slice(out.length - maxChars); // keep the most recent
+    return out;
+  } catch { return ""; }
+}
+
+function haveScrooge() { try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; } }
+
+function summarize(convo) {
+  const sys = "You are writing a SESSION HANDOFF so a fresh Claude Code session can take over without losing context. From the conversation, produce a concise but complete markdown handoff with these sections: TASK (what we're doing + the goal), STATE (done / in-progress), KEY DECISIONS, OPEN THREADS & NEXT STEPS (concrete actions), KEY FILES & locations (exact paths). Be specific. Do not pad.";
+  if (haveScrooge()) {
+    try {
+      return execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, {
+        input: convo, encoding: "utf8", timeout: 45000, maxBuffer: 4 * 1024 * 1024,
+      }).trim();
+    } catch (e) { process.stderr.write(`[agent-bus] scrooge summarize failed: ${e?.message}\n`); }
+  }
+  // fallback: raw recent tail
+  return `*(no summarizer available — raw recent transcript tail)*\n\n${convo.slice(-6000)}`;
+}
+
+try {
+  const input = JSON.parse((await readStdin()) || "{}");
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const projectName = basename(projectDir);
+  const transcript = input.transcript_path || "";
+  const trigger = input.trigger || "auto";
+
+  const convo = transcript && existsSync(transcript) ? recentTranscript(transcript) : "";
+  const summary = convo ? summarize(convo) : "*(no transcript available to summarize)*";
+
+  let gitStatus = "";
+  try { gitStatus = execSync("git -C " + JSON.stringify(projectDir) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
+
+  if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
+  const stamp = (() => { try { return execSync("date +%s", { encoding: "utf8" }).trim(); } catch { return String(process.pid); } })();
+
+  const record = {
+    id: `${projectName}-${stamp}`,
+    project: projectDir, projectName,
+    machine: hostname(),
+    session_id: input.session_id || "",
+    trigger, transcript_path: transcript,
+    stamp: Number(stamp) || 0,
+    summary,
+    gitStatus,
+    consumed: false,
+  };
+  const file = join(HANDOFF_DIR, `${record.id}.json`);
+  writeFileSync(file, JSON.stringify(record, null, 2));
+  process.stderr.write(`[agent-bus] handoff written: ${file} (trigger=${trigger})\n`);
+
+  // best-effort: ping the relay hub so other sessions/machines know a handoff is ready
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    const url = process.env.RELAY_URL || (existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")).url : "") || "http://127.0.0.1:4477";
+    await fetch(`${url}/send`, { method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ from: `${hostname()}:${projectName}`, to: "all", text: `📋 Handoff ready for ${projectName} — open a fresh session here to take over (id ${record.id}).` }),
+      signal: AbortSignal.timeout(2000) }).catch(() => {});
+  } catch {}
+
+  // OPT-IN: on macOS, if config.autoHandoffPrompt is true, ask the user (with a timeout,
+  // default = yes) whether to spawn a FRESH same-agent session that takes over via the
+  // handoff. Detached so it never blocks compaction. Off by default.
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    const conf = existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")) : {};
+    if (conf.autoHandoffPrompt && process.platform === "darwin") {
+      const script = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "handoff-prompt.sh");
+      if (existsSync(script)) {
+        const child = spawn("/bin/bash", [script, projectDir, String(conf.handoffPromptTimeout || 25)], { detached: true, stdio: "ignore" });
+        child.unref();
+        process.stderr.write(`[agent-bus] handoff prompt launched (opt-in)\n`);
+      }
+    }
+  } catch {}
+} catch (err) {
+  process.stderr.write(`[agent-bus] precompact error: ${err?.message || err}\n`);
+}
+process.stdout.write("{}");
+process.exit(0);

package/hooks/sessionstart.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// agent-bus SessionStart hook — every session auto-registers with the hub and
+// gets a roster of OTHER live sessions injected into context, so independent
+// sessions discover each other automatically (locally or across machines).
+//
+// Config resolution (first hit wins):
+//   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 { homedir, hostname } from "node:os";
+
+// Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs).
+function loadPendingHandoff(projectName) {
+  try {
+    const dir = join(homedir(), ".agent-bus", "handoffs");
+    if (!existsSync(dir)) return null;
+    const files = readdirSync(dir).filter(f => f.startsWith(projectName + "-") && f.endsWith(".json")).sort().reverse();
+    for (const f of files) {
+      const p = join(dir, f);
+      const rec = JSON.parse(readFileSync(p, "utf8"));
+      if (!rec.consumed) {
+        rec.consumed = true; writeFileSync(p, JSON.stringify(rec, null, 2)); // claim it
+        return rec;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    if (existsSync(cfg)) { const u = JSON.parse(readFileSync(cfg, "utf8")).url; if (u) return u; }
+  } catch {}
+  return "http://127.0.0.1:4477";
+}
+function readStdin() {
+  return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => (d += c)); process.stdin.on("end", () => res(d));
+    setTimeout(() => res(d), 100); });
+}
+async function jget(u) { const r = await fetch(u, { signal: AbortSignal.timeout(2500) }); return r.json(); }
+async function jpost(u, b) { return fetch(u, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(b), signal: AbortSignal.timeout(2500) }); }
+
+// Strip control chars from untrusted injected text so the hook's JSON stdout (which
+// Claude Code parses) stays valid. Keeps tab/newline/CR; replaces 0x00-0x1F (minus
+// those), DEL, and the JS line/paragraph separators.
+function sanitize(s) {
+  let out = "";
+  for (const ch of String(s ?? "")) {
+    const c = ch.codePointAt(0);
+    const bad = (c < 0x20 && c !== 9 && c !== 10 && c !== 13) || c === 0x7f || c === 0x2028 || c === 0x2029;
+    out += bad ? " " : ch;
+  }
+  return out;
+}
+
+let additionalContext = "";
+try {
+  await readStdin();
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const session = process.env.RELAY_SESSION || `${hostname()}:${basename(projectDir)}`;
+  const url = relayUrl();
+
+  // register self + post an initial presence status (no LLM turn — instant for others to read)
+  await jpost(`${url}/register`, { session, project: basename(projectDir), status: `active in ${basename(projectDir)}` }).catch(() => {});
+
+  // fetch roster of OTHER online sessions
+  let peers = [];
+  try { peers = (await jget(`${url}/peers`)).peers || []; } catch {}
+  const others = peers.filter(p => p.online && p.session !== session);
+
+  process.stderr.write(`[agent-bus] registered as ${session} -> ${url} (${others.length} other live session(s))\n`);
+
+  if (others.length > 0) {
+    additionalContext += `<agent-bus session="${session}" hub="${url}">\n`;
+    additionalContext += `You are connected to agent-bus (the cross-agent session bus) as "${session}". Other LIVE agent sessions are running right now:\n`;
+    for (const p of others) additionalContext += `- ${sanitize(p.session)}\n`;
+    additionalContext += `Use the relay MCP tools (relay_peers, relay_send, relay_inbox, relay_wait) to coordinate with them — hand off work, check for overlap before editing shared files, or ask another session for help. If a sibling session is touching the same project, coordinate before making conflicting changes.\n`;
+    additionalContext += `</agent-bus>\n`;
+  }
+
+  // Pending handoff? A prior session hit the context limit and left a handoff for this
+  // project — take over with this fresh full window instead of starting cold.
+  const handoff = loadPendingHandoff(basename(projectDir));
+  if (handoff) {
+    process.stderr.write(`[agent-bus] loaded pending handoff ${handoff.id}\n`);
+    additionalContext += `<agent-bus-handoff id="${sanitize(handoff.id)}" from="${sanitize(handoff.machine)}" trigger="${sanitize(handoff.trigger)}">\n`;
+    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`;
+    if (handoff.transcript_path) additionalContext += `\n_Full prior transcript: ${sanitize(handoff.transcript_path)}_\n`;
+    additionalContext += `</agent-bus-handoff>\n`;
+  }
+} catch (err) {
+  process.stderr.write(`[agent-bus] sessionstart error: ${err?.message || err}\n`);
+}
+
+// Hook protocol: emit additionalContext via stdout JSON. Self-validate so we never
+// emit something Claude Code can't parse — fall back to sanitized, then to {}.
+function emit(ctx) {
+  const obj = ctx ? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: ctx } } : {};
+  const out = JSON.stringify(obj);
+  try { JSON.parse(out); return out; } catch { /* fall through */ }
+  try { return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: sanitize(ctx) } }); } catch { return "{}"; }
+}
+process.stdout.write(emit(additionalContext));
+process.exit(0);

package/hub.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// agent-bus hub — message bus + presence/status board + SSE push, so independent
+// Claude Code sessions can coordinate (near-instant for watchers, cheap for idle peers).
+// Binds to LOOPBACK (127.0.0.1) by default — local-first and safe (no auth yet). To let other
+// machines reach it (e.g. over a Tailscale tailnet), set RELAY_HOST=0.0.0.0 — but only on a
+// private network, or add auth first. See "Always-on / remote hub" in the README (roadmap).
+import http from "node:http";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PORT = Number(process.env.RELAY_PORT || 4477);
+const HOST = process.env.RELAY_HOST || "127.0.0.1";
+const DATA_DIR = join(homedir(), ".agent-bus");
+const DATA = join(DATA_DIR, "bus.json");
+const ONLINE_MS = Number(process.env.RELAY_ONLINE_MS || 5 * 60 * 1000);
+if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+
+// peers: { session: { lastSeen, status, project } } ; tasks: kanban cards
+// projectMeta: { project: { brief, by, updated } } — the "what & why" blurb per project
+let state = { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [] };
+try {
+  if (existsSync(DATA)) {
+    const loaded = JSON.parse(readFileSync(DATA, "utf8"));
+    state = { messages: loaded.messages || [], peers: {}, seq: loaded.seq || 0, tasks: loaded.tasks || [], taskSeq: loaded.taskSeq || 0, projectMeta: loaded.projectMeta || {}, lessons: loaded.lessons || [] };
+    for (const [s, v] of Object.entries(loaded.peers || {})) // migrate old numeric form
+      state.peers[s] = typeof v === "number" ? { lastSeen: v, status: "", project: "" } : { lastSeen: v.lastSeen || 0, status: v.status || "", project: v.project || "" };
+  }
+} catch {}
+let dirty = false;
+const persist = () => { if (dirty) { try { writeFileSync(DATA, JSON.stringify(state)); dirty = false; } catch {} } };
+setInterval(persist, 1000).unref?.();
+
+// dashboard HTML (read once at startup)
+let UI = "";
+try { UI = readFileSync(new URL("./ui.html", import.meta.url), "utf8"); } catch {}
+
+// open SSE streams: [{ session, res }]
+const streams = [];
+const now = () => Date.now();
+function body(req) { return new Promise(r => { let d = ""; req.on("data", c => (d += c)); req.on("end", () => { try { r(d ? JSON.parse(d) : {}); } catch { r({}); } }); }); }
+function json(res, code, obj) { res.writeHead(code, { "content-type": "application/json", "access-control-allow-origin": "*" }); res.end(JSON.stringify(obj)); }
+function touch(session, status, project) {
+  if (!session || session === "all") return;   // "all" is a wildcard, not a real peer
+  const p = state.peers[session] || { lastSeen: 0, status: "", project: "" };
+  p.lastSeen = now();
+  if (status !== undefined) p.status = String(status).slice(0, 280);
+  if (project) p.project = String(project).slice(0, 80);
+  // derive project from a "host:project" session id if none given
+  if (!p.project && session.includes(":")) p.project = session.split(":").pop().slice(0, 80);
+  state.peers[session] = p; dirty = true;
+}
+function deliverable(m, session) { return (m.to === session || m.to === "all") && m.from !== session; }
+function pushToStreams(msg) {
+  for (const s of streams) if (deliverable(msg, s.session)) { try { s.res.write(`data: ${JSON.stringify(msg)}\n\n`); } catch {} }
+}
+
+const server = http.createServer(async (req, res) => {
+  const u = new URL(req.url, "http://x"); const q = Object.fromEntries(u.searchParams); const P = u.pathname;
+  try {
+    if (req.method === "POST" && P === "/register") { const b = await body(req); touch(b.session, b.status, b.project); return json(res, 200, { ok: true, session: b.session, peers: Object.keys(state.peers) }); }
+    if (req.method === "POST" && P === "/status") { const b = await body(req); touch(b.session, b.status ?? "", b.project); return json(res, 200, { ok: true }); }
+    if (req.method === "GET" && P === "/peers") {
+      const cutoff = now() - ONLINE_MS;
+      return json(res, 200, { peers: Object.entries(state.peers).map(([s, v]) => ({ session: s, lastSeen: v.lastSeen, online: v.lastSeen > cutoff, status: v.status || "", project: v.project || "" })) });
+    }
+    // --- Kanban tasks ---
+    if (req.method === "POST" && P === "/task") {           // create a card
+      const b = await body(req); touch(b.by, undefined, b.project);
+      const st0 = ["todo","doing","testing","failed","done","blocked"].includes(b.status) ? b.status : "todo";
+      const t = { id: ++state.taskSeq, project: String(b.project || "").slice(0,80), title: String(b.title||"").slice(0,200),
+        assignee: b.assignee || "", status: st0,
+        difficulty: ["easy","medium","hard"].includes(b.difficulty) ? b.difficulty : "",
+        model: String(b.model || "").slice(0, 60),
+        deps: Array.isArray(b.deps) ? [...new Set(b.deps.map(Number).filter(n => Number.isInteger(n) && n > 0))].slice(0, 20) : [],
+        by: b.by || "", ts: now(), updated: now(),
+        history: [{ to: st0, by: b.by || "", ts: now() }] };
+      state.tasks.push(t); if (state.tasks.length > 2000) state.tasks.splice(0, 500);
+      dirty = true; return json(res, 200, { ok: true, task: t });
+    }
+    if (req.method === "POST" && P === "/task/update") {    // move/edit a card
+      const b = await body(req); const t = state.tasks.find(x => x.id === Number(b.id));
+      if (!t) return json(res, 404, { error: "no such task" });
+      if (b.status && ["todo","doing","testing","failed","done","blocked"].includes(b.status) && b.status !== t.status) {
+        (t.history ||= []).push({ from: t.status, to: b.status, by: b.by || "", ts: now() });
+        if (t.history.length > 40) t.history.splice(0, 10);
+        t.status = b.status;
+      }
+      if (b.difficulty && ["easy","medium","hard"].includes(b.difficulty)) t.difficulty = b.difficulty;
+      if (b.model !== undefined) t.model = String(b.model).slice(0, 60);
+      if (Array.isArray(b.deps)) t.deps = [...new Set(b.deps.map(Number).filter(n => Number.isInteger(n) && n > 0 && n !== t.id))].slice(0, 20);
+      if (b.assignee !== undefined) t.assignee = b.assignee;
+      if (b.title !== undefined) t.title = String(b.title).slice(0,200);
+      if (b.delete) state.tasks = state.tasks.filter(x => x.id !== t.id);
+      t.updated = now(); dirty = true; return json(res, 200, { ok: true, task: t });
+    }
+    if (req.method === "GET" && P === "/tasks") {
+      const proj = q.project; const ts = proj ? state.tasks.filter(t => t.project === proj) : state.tasks;
+      return json(res, 200, { tasks: ts });
+    }
+    if (req.method === "POST" && P === "/project") {        // set a project's brief (what & why)
+      const b = await body(req); const k = String(b.project || "").slice(0, 80);
+      if (!k) return json(res, 400, { error: "project required" });
+      const m = state.projectMeta[k] || {};
+      if (b.brief !== undefined) m.brief = String(b.brief).slice(0, 600);
+      m.by = b.by || m.by || ""; m.updated = now();
+      state.projectMeta[k] = m; dirty = true;
+      return json(res, 200, { ok: true, project: k, brief: m.brief || "" });
+    }
+    if (req.method === "GET" && P === "/projects") {        // project-grouped view
+      const cutoff = now() - ONLINE_MS; const byProj = {};
+      const proj = p => p || "(unassigned)";
+      const mk = k => (byProj[k] ||= { project: k, brief: (state.projectMeta[k]?.brief) || "", agents: [], tasks: { todo:0,doing:0,testing:0,failed:0,done:0,blocked:0 }, doingTitles: [] });
+      for (const [s, v] of Object.entries(state.peers)) {
+        const k = proj(v.project); mk(k).agents.push({ session: s, online: v.lastSeen > cutoff, status: v.status || "" });
+      }
+      for (const t of state.tasks) { const e = mk(proj(t.project)); e.tasks[t.status] = (e.tasks[t.status]||0)+1; if (t.status === "doing") e.doingTitles.push(t.title); }
+      // derive a one-line phase ("where it is in the process") from the board
+      for (const e of Object.values(byProj)) {
+        const { todo, doing, testing=0, failed=0, done, blocked } = e.tasks; const total = todo+doing+testing+failed+done+blocked;
+        e.phase = total === 0 ? "no cards yet"
+          : failed > 0 ? `${failed} FAILED — fixing`
+          : blocked > 0 ? `blocked on ${blocked} card${blocked>1?"s":""}`
+          : testing > 0 ? `verifying: ${testing} in test`
+          : doing > 0 ? `building: ${e.doingTitles.slice(0,2).join(", ")}${e.doingTitles.length>2?"…":""}`
+          : done === total ? "shipped — all cards done"
+          : todo > 0 ? `planned: ${todo} card${todo>1?"s":""} queued`
+          : "in progress";
+      }
+      return json(res, 200, { projects: Object.values(byProj) });
+    }
+    // --- lessons: cross-agent learning from failures. scope = "global" or an agent brand ("kimi") ---
+    if (req.method === "POST" && P === "/lesson") {
+      const b = await body(req);
+      const text = String(b.text || "").trim().slice(0, 400);
+      const scope = String(b.scope || "global").toLowerCase().slice(0, 40);
+      if (!text) return json(res, 400, { error: "text required" });
+      if (state.lessons.some(l => l.scope === scope && l.text === text)) return json(res, 200, { ok: true, dedup: true });
+      state.lessons.push({ id: state.lessons.length + 1, scope, text, by: b.by || "", ts: now() });
+      if (state.lessons.length > 500) state.lessons.splice(0, 100);
+      dirty = true; return json(res, 200, { ok: true, count: state.lessons.length });
+    }
+    if (req.method === "GET" && P === "/economics") {   // the brain's books, surfaced: scrooge ledger + quota profile
+      const out = { scrooge: null, profile: null };
+      try { out.profile = JSON.parse(readFileSync(join(homedir(), ".agent-bus", "profile.json"), "utf8")).providers || {}; } catch {}
+      try {
+        const since = now() / 1000 - (Number(q.hours || 24) * 3600);
+        const lines = readFileSync(join(homedir(), ".token-scrooge", "calls.jsonl"), "utf8").trim().split("\n").slice(-3000);
+        const calls = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(c => c && c.ts >= since && c.ok);
+        const sum = { calls: calls.length, tokens_in: 0, tokens_out: 0, cost_usd: 0, by_model: {} };
+        for (const c of calls) {
+          sum.tokens_in += c.tokens_in || 0; sum.tokens_out += c.tokens_out || 0; sum.cost_usd += c.cost_usd || 0;
+          const m = sum.by_model[c.model] ||= { calls: 0, cost_usd: 0 };
+          m.calls++; m.cost_usd += c.cost_usd || 0;
+        }
+        // savings vs Opus reference (~$15/M in, $75/M out — same yardstick scrooge ledger uses)
+        sum.opus_equiv_usd = +(sum.tokens_in * 15 / 1e6 + sum.tokens_out * 75 / 1e6).toFixed(2);
+        sum.cost_usd = +sum.cost_usd.toFixed(4);
+        out.scrooge = sum;
+      } catch {}
+      return json(res, 200, out);
+    }
+    if (req.method === "GET" && P === "/lessons") {
+      const agent = (q.agent || "").toLowerCase();
+      const ls = state.lessons.filter(l => l.scope === "global" || (agent && l.scope === agent));
+      return json(res, 200, { lessons: ls });
+    }
+    if (req.method === "POST" && P === "/send") {
+      const b = await body(req);
+      if (!b.from || !String(b.text ?? "").trim()) return json(res, 400, { error: "from and non-empty text required" });
+      touch(b.from);
+      // attribute the message to a project so the dashboard can show it in that project's lane.
+      // explicit b.project wins; else the sender's known project; else parsed from a "host:project" id.
+      const fromProj = state.peers[b.from]?.project || (b.from && b.from.includes(":") ? b.from.split(":").pop() : "");
+      const msg = { id: ++state.seq, ts: now(), from: b.from || "anon", to: b.to || "all", text: String(b.text ?? ""), project: String(b.project || fromProj || "").slice(0, 80) };
+      state.messages.push(msg); if (state.messages.length > 5000) state.messages.splice(0, 1000);
+      dirty = true; pushToStreams(msg);               // <-- instant push to live watchers
+      return json(res, 200, { ok: true, id: msg.id });
+    }
+    if (req.method === "GET" && P === "/inbox") {
+      touch(q.session); const since = Number(q.since || 0);
+      const msgs = state.messages.filter(m => m.id > since && deliverable(m, q.session));
+      return json(res, 200, { messages: msgs, cursor: msgs.length ? msgs[msgs.length - 1].id : since });
+    }
+    if (req.method === "GET" && P === "/poll") {
+      touch(q.session); const since = Number(q.since || 0);
+      const waitMs = Math.min(Number(q.wait || 25), 290) * 1000;   // allow long idle-park
+      const deadline = now() + waitMs;
+      const tick = () => {
+        const msgs = state.messages.filter(m => m.id > since && deliverable(m, q.session));
+        if (msgs.length || now() >= deadline) { touch(q.session); return json(res, 200, { messages: msgs, cursor: msgs.length ? msgs[msgs.length - 1].id : since }); }
+        setTimeout(tick, 300);
+      };
+      return tick();
+    }
+    if (req.method === "GET" && P === "/stream") {                 // SSE — true push, no polling
+      const session = q.session || "all";
+      res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive", "access-control-allow-origin": "*" });
+      res.write(`: connected as ${session}\n\n`);
+      touch(session, q.status);
+      const entry = { session, res };
+      streams.push(entry);
+      const ka = setInterval(() => { try { res.write(": ka\n\n"); touch(session); } catch {} }, 20000);
+      req.on("close", () => { clearInterval(ka); const i = streams.indexOf(entry); if (i >= 0) streams.splice(i, 1); });
+      return;
+    }
+    if (req.method === "GET" && P === "/recent") {   // god-view: last N messages, for the dashboard feed
+      const n = Math.min(Number(q.limit || 50), 200);
+      return json(res, 200, { messages: state.messages.slice(-n) });
+    }
+    if (req.method === "GET" && (P === "/" || P === "/ui")) {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" }); return res.end(UI || "<h1>agent-bus</h1><p>dashboard unavailable</p>");
+    }
+    if (P === "/health") return json(res, 200, { ok: true, peers: Object.keys(state.peers).length, messages: state.messages.length, streams: streams.length });
+    json(res, 404, { error: "not found" });
+  } catch (e) { json(res, 500, { error: String(e?.message || e) }); }
+});
+server.listen(PORT, HOST, () => console.error(`[agent-bus] hub on http://${HOST}:${PORT} (data: ${DATA})`));