trantor 0.17.12 → 0.17.14

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + context-handoff for independent AI coding agents (Claude, Codex, Gemini, …)",
-    "version": "0.17.12"
+    "version": "0.17.14"
   },
   "plugins": [
     {
       "name": "trantor",
       "source": "./",
       "description": "The hub-world for AI agent crews. Say \"fire up the crew\" and Claude becomes the architect: a plan-aware Advisor routes the work (solo / cheap inline calls / live crew of Codex, Gemini, Kimi & DeepSeek in their own terminal windows), a Kanban/flow command center with a testing gate tracks it, and an economics brain (Scrooge) keeps the receipts. 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.17.12",
+      "version": "0.17.14",
       "author": {
         "name": "Sasha Bogojevic"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.12",
+  "version": "0.17.14",
   "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

@@ -13,12 +13,13 @@
 
 **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.**
+actual plans, supervised on a live + historical board you can scroll back through, 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)
+![Tests](https://img.shields.io/badge/tests-80%2F80-2DD4BF)
 
 </div>
 
@@ -99,9 +100,11 @@ project takes over with a full window (and a PreCompact hook does this automatic
    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.
+   terminal window per agent. `agent:model` pins a model; `agent:provider --difficulty hard`
+   picks the **best live model** for the work at spawn (capability × cost), enumerated from the
+   CLI itself — never a guessed endpoint. **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
@@ -110,22 +113,45 @@ project takes over with a full window (and a PreCompact hook does this automatic
 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
+5. **Failures surface in real time.** A crew agent whose turn fails (credits exhausted, auth,
+   crash) no longer re-parks silently — it classifies the failure, posts a ⚠️ to the bus, and
+   flips its dashboard chip **red** (escalating to 🛑 if it keeps failing). `trantor swap <old>
+   <new>` tears down an exhausted agent and spawns a live-selected replacement, ready for a fresh
+   contract.
+6. **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.
+A live command center at `http://127.0.0.1:4477`, grouped by **project** — and a *durable,
+self-maintaining record*, not just a snapshot. Dead sessions self-prune (no more graveyard of
+stale boards), and the project order is **stable**: a working board updates in place instead of
+jumping to the top while you're reading it.
+
+Three views per project (your choice sticks):
+
+- **BOARD** — Kanban with the testing gate, difficulty + model badges per card, agent chips with
+  provider logos, live status, quota-pool tags, and **red / 🛑 chips for errored / down agents**.
+- **FLOW** — a **development timeline**: every card laid left→right in **build order** across
+  **agent lanes**, each card a readable block segmented by the time it spent in each status, with
+  dependency edges converging where parallel work merged. Scroll the project's whole history
+  left/right. **Click any card** to open its full story — the contract it was given, the agent's
+  plan, its build report, the files it changed — reconstructed from that agent's own bus messages.
+- **TIMELINE** — the same history as a chronological event log.
+
+Plus:
+
+- **🧠 Learning sidebar** — the self-learning loop, made visible: lessons (global / per-agent /
+  per-project), **per-LLM reliability** (turns, fail-rate, trend charts) from real turn telemetry,
+  and the guardrails baked into each model's prompts. Watch the platform get smarter over time.
+- **🪙 savings pill** — a lifetime running total of what cheap-model routing has saved vs running
+  the frontier model, with a selectable window (24h / week / month / quarter / year).
 - **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.
+  global live feed and a composer so *you* can message the bus (or any single agent).
+
+Every session registers automatically — **crew or not** — and a solo session's own todo list
+shows up on the board as cards, so the dashboard reflects *all* the work on a project, not just
+crew runs.
 
 ## The brain — plan-aware economics
 
@@ -160,7 +186,7 @@ rate, not work rate.
 | `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_add(title, …, difficulty, model, deps, project?)` | Cards with difficulty/model badges + DAG edges; `project` targets another board when you orchestrate from elsewhere |
 | `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 |
@@ -170,13 +196,15 @@ rate, not work rate.
 ## The CLI
 
 ```
-trantor setup | doctor | connect | profile | up <agents…> | down | ui | advise | hub | watch
+trantor setup | doctor | connect | profile | up <agents…> | swap <old> <new> | 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.
+`trantor up` notes: `agent:model` pins a model (`deepseek:deepseek-v4-pro`); `agent:provider
+--task <k> --difficulty <d>` picks the **best live model** for the work at spawn
+(`opencode:zai-coding-plan --difficulty hard`); 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
+swap <oldAgent> <newSpec>` replaces an exhausted agent with a live-selected one. `trantor down`
+kills crew processes via their ttys and closes windows without macOS "Terminate?" dialogs.
 
 ## Works with any MCP agent
 
@@ -192,10 +220,10 @@ server auto-registers the session, so presence works before the model says a wor
         │ advise/contracts        │ one turn, exit; runner long-polls (free) + resumes with context
         └───────────┬─────────────┴──────────────┴────────────────┴────────────────┘
                     ▼
-              hub.mjs  ←— plain HTTP + SSE · presence/messages/board/lessons/economics
+              hub.mjs  ←— plain HTTP + SSE · presence/messages/board/history/lessons/learning/economics
               (Node built-ins only · state in ~/.agent-bus/bus.json · loopback by default)
                     ▲
-              dashboard (ui.html) · BOARD/FLOW · conversation lanes · 🪙 ledger
+              dashboard (ui.html) · BOARD/FLOW/TIMELINE · 🧠 Learning · 🪙 savings · conversation lanes
 ```
 
 Config: `RELAY_URL` env → `~/.agent-bus/config.json` → `http://127.0.0.1:4477`.
@@ -223,9 +251,10 @@ The `relay_*` tool names and the `~/.agent-bus` state dir remain until a later r
 ## 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
+npm test    # 80 checks: unit + protocol-level scenario drills with mock agents (no LLMs, seconds, $0):
+            # honest presence + TTL prune, spawn no-shows, the testing gate, bounce trails, lessons,
+            # /history + backfill, /learning shape, /todos sync, /card detail, advisor decisions across
+            # plan tiers, deps validation, virgin-machine doctor, and failure-classification drills
 ```
 
 ## License

package/bin/catchup.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// trantor catchup — "where are we on this project?" on demand. Reads the continuous
+// board (the durable, cross-session project record), the recent git log, and — if
+// scrooge is on PATH — synthesizes a short narrative. The SessionStart hook already
+// injects the structured snapshot every start; this is the richer brief you ask for
+// when you want it. Run from inside a project: `trantor catchup`.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { resolveProject } from "../lib/project.mjs";
+
+function relayUrl() {
+  if (process.env.RELAY_URL) return process.env.RELAY_URL;
+  try { const c = join(homedir(), ".agent-bus", "config.json"); if (existsSync(c)) { const u = JSON.parse(readFileSync(c, "utf8")).url; if (u) return u; } } catch {}
+  return "http://127.0.0.1:4477";
+}
+const haveScrooge = () => { try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; } };
+
+const dir = process.cwd();
+const project = resolveProject(dir);
+const url = relayUrl();
+
+let cu = null;
+try { cu = await (await fetch(`${url}/catchup?project=${encodeURIComponent(project)}`, { signal: AbortSignal.timeout(4000) })).json(); } catch (e) { console.error(`could not reach hub at ${url}: ${e.message}`); }
+let gitlog = "";
+try { gitlog = execSync(`git -C ${JSON.stringify(dir)} log --oneline -12 2>/dev/null`, { encoding: "utf8" }).trim(); } catch {}
+
+const line = (arr) => (arr || []).map(t => `  #${t.id} ${String(t.title).slice(0, 80)}${t.assignee ? ` @${t.assignee}` : ""}`).join("\n");
+console.log(`\n📋 trantor catchup — ${project}\n${"─".repeat(48)}`);
+if (cu && cu.total > 0) {
+  if (cu.brief) console.log(`Brief: ${cu.brief}\n`);
+  const c = cu.counts;
+  console.log(`Cards: ${cu.total} — ${c.done} done · ${c.doing} doing · ${c.testing} testing · ${c.todo} todo · ${c.failed} failed · ${c.blocked} blocked`);
+  if (cu.doing?.length)      console.log(`\nIn progress:\n${line(cu.doing)}`);
+  if (cu.testing?.length)    console.log(`\nIn testing:\n${line(cu.testing)}`);
+  if (cu.failed?.length)     console.log(`\nFailed (needs attention):\n${line(cu.failed)}`);
+  if (cu.blocked?.length)    console.log(`\nBlocked:\n${line(cu.blocked)}`);
+  if (cu.todo?.length)       console.log(`\nQueued:\n${line(cu.todo)}`);
+  if (cu.recentDone?.length) console.log(`\nRecently done:\n${line(cu.recentDone)}`);
+} else {
+  console.log(`No cards on the board for "${project}" yet.`);
+}
+if (gitlog) console.log(`\nRecent commits:\n${gitlog.split("\n").map(l => "  " + l).join("\n")}`);
+
+if (haveScrooge() && (cu?.total || gitlog)) {
+  const ctx = `PROJECT: ${project}\n\nBOARD:\n${JSON.stringify(cu, null, 2)}\n\nRECENT COMMITS:\n${gitlog}`;
+  const sys = "You are briefing someone resuming this project. From the board state + git log, write a SHORT 'where are we' narrative: what's built, what's in flight, what's next, and any risk (failed/blocked cards, or a stale card whose work looks already done elsewhere). 6-10 lines. No preamble.";
+  try {
+    console.log(`\n${"─".repeat(48)}\nWhere we are:\n`);
+    console.log(execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, { input: ctx, encoding: "utf8", timeout: 60000, maxBuffer: 4 * 1024 * 1024 }).trim());
+  } catch (e) { console.error(`(scrooge brief skipped: ${e.message})`); }
+} else if (!haveScrooge()) {
+  console.log(`\n(install scrooge for a synthesized narrative)`);
+}
+console.log("");

package/bin/cli.mjs

@@ -25,6 +25,7 @@ switch (cmd) {
   case "swap":    spawn("/bin/bash", [join(ROOT, "bin/crew.sh"), "swap", ...args], { 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 "catchup": run("bin/catchup.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 {}
@@ -44,6 +45,7 @@ switch (cmd) {
   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 catchup     "where are we?" — the continuous board + git, with a synthesized brief
   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

package/bin/crew-runner.mjs

@@ -12,10 +12,15 @@ import { execSync, spawnSync } from "node:child_process";
 import { readFileSync, existsSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
+import { resolveProject } from "../lib/project.mjs";
 
 const AGENT = process.argv[2];
 const DIR = process.argv[3] || process.cwd();
-const PROJ = basename(DIR);
+// Crew agents MUST share the orchestrator's project key (one repo = one lane).
+// RELAY_PROJECT is inherited from crew.sh (the host's resolved key); else fall
+// back to the git-repo-root basename — never a loose dir basename that could
+// fork the host's "builtbetter.ai" into a separate "builtbetter" lane.
+const PROJ = process.env.RELAY_PROJECT || resolveProject(DIR);
 const SESSION = `${AGENT}:${PROJ}`;
 if (!AGENT) { console.error("usage: crew-runner.mjs <agent> [project-dir]"); process.exit(1); }
 

package/bin/crew.sh

@@ -16,7 +16,10 @@
 set -u
 CMD="${1:-up}"; shift 2>/dev/null || true
 DIR="$(pwd)"
-PROJ="$(basename "$DIR")"
+# Canonical project key: the orchestrator's RELAY_PROJECT wins, else the GIT REPO ROOT
+# basename (stable across subdirs), else the cwd basename. The crew inherits this exact
+# key so one repo = one lane (no host "builtbetter.ai" vs crew "builtbetter" split).
+PROJ="${RELAY_PROJECT:-$(basename "$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null || echo "$DIR")")}"
 BUS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 STATE="$HOME/.agent-bus/crew-windows.txt"
 mkdir -p "$HOME/.agent-bus"
@@ -143,7 +146,7 @@ spawn_grid() {  # $@ = agents — (re)computes the grid for THIS batch and spawn
     local X1=$(( GX + C * CW )) Y1=$(( GY + R * CH )) WID=""
     WID="$(osascript \
       -e 'tell application "Terminal"' \
-      -e "  set w to do script \"cd $DIR && clear && CREW_MODEL=$MODEL node $BUS_DIR/bin/crew-runner.mjs $AGENT $DIR\"" \
+      -e "  set w to do script \"cd $DIR && clear && CREW_MODEL=$MODEL RELAY_PROJECT=$PROJ node $BUS_DIR/bin/crew-runner.mjs $AGENT $DIR\"" \
       -e "  set custom title of w to \"$(echo "$AGENT" | tr '[:lower:]' '[:upper:]') — trantor crew\"" \
       -e "  set theWin to first window whose tabs contains w" \
       -e "  set bounds of theWin to {$X1, $Y1, $(( X1 + CW )), $(( Y1 + CH ))}" \

package/hooks/handoff-now.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// trantor — detached handoff worker. The PostToolUse heartbeat spawns this when a
+// session crosses its context warn threshold, so the (up to ~60s) scrooge summary
+// never blocks a tool call. Writes a whole-session handoff and prompts to open a
+// fresh session. Args: <projectDir> <sessionId> <transcriptPath> [trigger]
+import { readConfig, writeHandoff, pingBus, maybeSpawn,
+         contextUsage, alreadyHandedOff, markHandedOff } from "./lib/handoff.mjs";
+import { basename } from "node:path";
+
+const [, , projectDir = process.cwd(), sessionId = "", transcript = "", trigger = "context-warn"] = process.argv;
+try {
+  const conf = readConfig();
+  const cur = contextUsage(transcript, conf)?.tokens || 0;
+  if (alreadyHandedOff(sessionId, cur)) process.exit(0); // another path beat us to it
+  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
+  process.stderr.write(`[trantor] early handoff written: ${file} (frac warn)\n`);
+  await pingBus(basename(projectDir), record.id, conf);
+  if (maybeSpawn(projectDir, conf)) markHandedOff(sessionId, cur);
+} catch (e) {
+  process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);
+}
+process.exit(0);

package/hooks/heartbeat.mjs

@@ -14,11 +14,54 @@
 // We POST /register WITHOUT a status field so the session's meaningful status is preserved
 // (the hub only overwrites status when one is supplied).
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readConfig, contextUsage, warnFrac, alreadyHandedOff } from "./lib/handoff.mjs";
+import { resolveProject } from "../lib/project.mjs";
 
 const HEARTBEAT_MS = Number(process.env.RELAY_HEARTBEAT_MS || 60 * 1000);
 const FETCH_TIMEOUT_MS = Number(process.env.RELAY_HEARTBEAT_TIMEOUT_MS || 1500);
+const INFLIGHT_MS = 5 * 60 * 1000;
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+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), 80); });
+}
+
+// Proactive early-warning: when the live context occupancy crosses the warn
+// fraction of a KNOWN window (env RELAY_CONTEXT_WINDOW / config.contextWindow —
+// the transcript can't reveal 200k vs 1M, so it must be declared), hand off
+// BEFORE the compaction wall. The heavy summary runs in a detached worker so we
+// never block this tool call. No-op when the window is unknown.
+async function maybeEarlyWarn(stdinRaw, session) {
+  try {
+    const conf = readConfig();
+    const input = JSON.parse(stdinRaw || "{}");
+    const transcript = input.transcript_path || "";
+    const sessionId = input.session_id || "";
+    if (!transcript) return;
+    const usage = contextUsage(transcript, conf);
+    if (!usage || !usage.window || usage.frac == null) return; // window unknown → only PreCompact guards
+    if (usage.frac < warnFrac(conf)) return;
+    if (alreadyHandedOff(sessionId, usage.tokens)) return;
+
+    // In-flight guard: the detached worker takes ~tens of seconds to summarize;
+    // don't launch a second one on the next heartbeat tick meanwhile.
+    const inflight = join(homedir(), ".agent-bus", `handoff-inflight-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);
+    try { if (existsSync(inflight) && Date.now() - (Number(readFileSync(inflight, "utf8")) || 0) < INFLIGHT_MS) return; } catch {}
+    try { writeFileSync(inflight, String(Date.now())); } catch {}
+
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    process.stderr.write(`[trantor] context ${Math.round(usage.frac * 100)}% of ${usage.window} — launching early handoff\n`);
+    const child = spawn(process.execPath, [join(HERE, "handoff-now.mjs"), projectDir, sessionId, transcript, "context-warn"],
+      { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {}
+}
 
 function relayUrl() {
   if (process.env.RELAY_URL) return process.env.RELAY_URL;
@@ -29,7 +72,7 @@ function relayUrl() {
   return "http://127.0.0.1:4477";
 }
 
-async function main() {
+async function main(stdinRaw) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // Mirror sessionstart.mjs: home-directory sessions aren't project work — don't register
   // them (would spawn a phantom "<username>" board). Opt in with RELAY_SESSION/RELAY_PROJECT.
@@ -38,11 +81,11 @@ async function main() {
   // Mirror mcp.mjs identity resolution EXACTLY so we refresh the same peer the relay
   // registered (not a phantom): RELAY_PROJECT wins for project; RELAY_SESSION wins for
   // identity, else a RELAY_AGENT brand ("codex","kimi",…) per project, else hostname:project.
-  const project = process.env.RELAY_PROJECT || basename(projectDir);
+  const project = resolveProject(projectDir);
   const session = process.env.RELAY_SESSION
     || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostname()}:${project}`);
 
-  // Throttle: only ping if HEARTBEAT_MS has elapsed since the last ping for THIS session.
+  // Throttle: only act if HEARTBEAT_MS has elapsed since the last tick for THIS session.
   const stamp = join(homedir(), ".agent-bus", `hb-${session.replace(/[^A-Za-z0-9_.-]/g, "_")}.stamp`);
   try {
     if (existsSync(stamp)) {
@@ -62,7 +105,11 @@ async function main() {
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
   } catch {}
+
+  // Same cadence as the presence ping: check context pressure and hand off early
+  // if we've crossed the warn threshold of a known window.
+  await maybeEarlyWarn(stdinRaw, session);
 }
 
 // Never block or break the tool flow: swallow everything, always exit clean.
-main().catch(() => {}).finally(() => process.exit(0));
+readStdin().then(main).catch(() => {}).finally(() => process.exit(0));

package/hooks/lib/handoff.mjs

@@ -0,0 +1,225 @@
+// trantor handoff core — shared by the PreCompact hook (at-the-wall) and the
+// PostToolUse heartbeat (proactive early-warning). One place that knows how to:
+//   • read a session's live context occupancy from its transcript usage,
+//   • build a WHOLE-SESSION summary (not just the tail),
+//   • write a handoff record, and
+//   • spawn a fresh same-agent session in a new terminal that takes it over.
+//
+// Why this exists: PreCompact fires only at the compaction wall and cannot stop
+// compaction, so the only way to continue with a full window is to open a NEW
+// session that loads the handoff. The heartbeat path lets us do that BEFORE the
+// wall when we know the window size. Both paths share a per-session guard so we
+// never write/spawn twice for the same context window.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir, hostname } from "node:os";
+import { execSync, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const HANDOFF_DIR = join(homedir(), ".agent-bus", "handoffs");
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function readConfig() {
+  try {
+    const cfg = join(homedir(), ".agent-bus", "config.json");
+    return existsSync(cfg) ? JSON.parse(readFileSync(cfg, "utf8")) : {};
+  } catch { return {}; }
+}
+
+export function relayUrl(conf = readConfig()) {
+  return process.env.RELAY_URL || conf.url || "http://127.0.0.1:4477";
+}
+
+// ---- context occupancy ------------------------------------------------------
+// Read only the tail of the (potentially huge, append-only) transcript and find
+// the most recent assistant turn's usage. Current context tokens ≈ input +
+// cache_read + cache_creation (the cached prompt IS part of the window).
+export function contextUsage(transcriptPath, conf = readConfig()) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+  let buf = "";
+  try {
+    const fd = openSync(transcriptPath, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const tail = Math.min(size, 1_500_000); // last ~1.5MB is plenty for recent turns
+      const b = Buffer.alloc(tail);
+      readSync(fd, b, 0, tail, size - tail);
+      buf = b.toString("utf8");
+    } finally { closeSync(fd); }
+  } catch { return null; }
+
+  const lines = buf.split("\n").filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let r; try { r = JSON.parse(lines[i]); } catch { continue; }
+    const u = r?.message?.usage;
+    if (r?.type === "assistant" && u) {
+      const tokens = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+      if (tokens <= 0) continue;
+      const model = r.message.model || "";
+      const window = resolveWindow(model, conf);
+      return { tokens, window, frac: window ? tokens / window : null, model };
+    }
+  }
+  return null;
+}
+
+// The transcript logs the model WITHOUT the [1m] marker, so we cannot tell a
+// 200k window from a 1M one. There is therefore no safe universal default — the
+// window must be declared (env RELAY_CONTEXT_WINDOW or config.contextWindow) for
+// the proactive early-warning to activate. Returns 0 when unknown (→ no warning).
+export function resolveWindow(model = "", conf = readConfig()) {
+  const explicit = Number(process.env.RELAY_CONTEXT_WINDOW || conf.contextWindow || 0);
+  if (explicit > 0) return explicit;
+  if (/\[1m\]|-1m\b|:1m\b/i.test(model)) return 1_000_000; // honored if ever present
+  return 0;
+}
+
+export function warnFrac(conf = readConfig()) {
+  const f = Number(process.env.RELAY_CONTEXT_WARN_FRAC || conf.contextWarnFrac || 0.85);
+  return f > 0 && f < 1 ? f : 0.85;
+}
+
+// ---- per-session guard (shared by both paths) -------------------------------
+// One handoff+spawn per context window. Re-arms after a compaction resets the
+// context (tokens drop well below where we fired).
+function guardPath(sessionId) {
+  const safe = String(sessionId || "nosession").replace(/[^A-Za-z0-9_.-]/g, "_");
+  return join(homedir(), ".agent-bus", `handoff-fired-${safe}.json`);
+}
+export function alreadyHandedOff(sessionId, curTokens = 0) {
+  try {
+    const p = guardPath(sessionId);
+    if (!existsSync(p)) return false;
+    const g = JSON.parse(readFileSync(p, "utf8"));
+    // Re-arm if context clearly reset (e.g. after a compaction) — well below the fire point.
+    if (curTokens && g.atTokens && curTokens < g.atTokens * 0.7) return false;
+    return true;
+  } catch { return false; }
+}
+export function markHandedOff(sessionId, curTokens = 0) {
+  try {
+    if (!existsSync(dirname(guardPath(sessionId)))) mkdirSync(dirname(guardPath(sessionId)), { recursive: true });
+    writeFileSync(guardPath(sessionId), JSON.stringify({ at: nowSec(), atTokens: curTokens || 0 }));
+  } catch {}
+}
+
+function nowSec() { try { return Number(execSync("date +%s", { encoding: "utf8" }).trim()) || 0; } catch { return 0; } }
+
+// ---- whole-session summary --------------------------------------------------
+function collectTurns(transcriptPath) {
+  const rows = readFileSync(transcriptPath, "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");
+    text = (text || "").trim();
+    if (!text || text.startsWith("<task-notification") || text.startsWith("<command")) continue;
+    turns.push(`### ${r.type.toUpperCase()}\n${text.slice(0, 2400)}`);
+  }
+  return turns;
+}
+
+// Build a digest that spans the WHOLE session: the opening turns (the task &
+// goal framing), an even sample of the middle (the arc of the work), and a
+// fuller recent tail (current state). The old hook kept only the last 16KB —
+// on a multi-hour session that captured only the final moments.
+function digest(turns, budget = 56_000) {
+  const joined = turns.join("\n\n");
+  if (joined.length <= budget) return joined;
+
+  const headN = Math.min(6, turns.length);
+  const tailN = Math.min(24, Math.max(0, turns.length - headN));
+  const head = turns.slice(0, headN);
+  const tail = turns.slice(turns.length - tailN);
+  const midPool = turns.slice(headN, turns.length - tailN);
+
+  // Evenly sample the middle so the summarizer sees the whole trajectory.
+  const midKeep = 18;
+  const mid = [];
+  if (midPool.length > 0) {
+    const step = Math.max(1, Math.floor(midPool.length / midKeep));
+    for (let i = 0; i < midPool.length && mid.length < midKeep; i += step) mid.push(midPool[i]);
+  }
+  let out = [
+    ...head,
+    midPool.length ? "### … (mid-session, evenly sampled) …" : "",
+    ...mid,
+    tail.length ? "### … (recent) …" : "",
+    ...tail,
+  ].filter(Boolean).join("\n\n");
+  if (out.length > budget) out = out.slice(out.length - budget); // never blow the budget
+  return out;
+}
+
+function haveScrooge() {
+  if (process.env.TRANTOR_NO_SCROOGE === "1") return false; // opt out (tests / no-LLM summary)
+  try { execSync("command -v scrooge", { stdio: "ignore" }); return true; } catch { return false; }
+}
+
+export function buildSummary(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return "*(no transcript available to summarize)*";
+  let convo = "";
+  try { convo = digest(collectTurns(transcriptPath)); } catch { convo = ""; }
+  if (!convo) return "*(transcript unreadable)*";
+  const sys = "You are writing a SESSION HANDOFF so a fresh Claude Code session can take over without losing context. The text spans an entire (possibly multi-hour) session: opening turns, an even sample of the middle, and the recent tail. 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. Cover the whole arc, not just the end. Do not pad.";
+  if (haveScrooge()) {
+    try {
+      return execSync(`scrooge -t summarize -d medium --system ${JSON.stringify(sys)}`, {
+        input: convo, encoding: "utf8", timeout: 60_000, maxBuffer: 8 * 1024 * 1024,
+      }).trim() || `*(empty summary — raw recent tail)*\n\n${convo.slice(-8000)}`;
+    } catch (e) { process.stderr.write(`[trantor] scrooge summarize failed: ${e?.message}\n`); }
+  }
+  return `*(no summarizer available — representative transcript digest)*\n\n${convo.slice(-12000)}`;
+}
+
+// ---- write + announce + spawn ----------------------------------------------
+export function writeHandoff({ projectDir, sessionId, transcript, trigger, summary }) {
+  const projectName = basename(projectDir);
+  if (!existsSync(HANDOFF_DIR)) mkdirSync(HANDOFF_DIR, { recursive: true });
+  const stamp = nowSec() || Date.now();
+  let gitStatus = "";
+  try { gitStatus = execSync("git -C " + JSON.stringify(projectDir) + " status --short 2>/dev/null | head -30", { encoding: "utf8" }).trim(); } catch {}
+  const record = {
+    id: `${projectName}-${stamp}`,
+    project: projectDir, projectName, machine: hostname(),
+    session_id: sessionId || "", trigger: trigger || "auto",
+    transcript_path: transcript || "", stamp: Number(stamp) || 0,
+    summary: summary ?? buildSummary(transcript),
+    gitStatus, consumed: false,
+  };
+  const file = join(HANDOFF_DIR, `${record.id}.json`);
+  writeFileSync(file, JSON.stringify(record, null, 2));
+  return { file, record };
+}
+
+export async function pingBus(projectName, id, conf = readConfig()) {
+  try {
+    await fetch(`${relayUrl(conf)}/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 ${id}).` }),
+      signal: AbortSignal.timeout(2000),
+    }).catch(() => {});
+  } catch {}
+}
+
+// Spawn a fresh same-agent session (macOS) that takes over via the handoff.
+// Default = ON (prompt with a timeout, default button "Open fresh session").
+// Disable with config.autoHandoffPrompt:false or env TRANTOR_NO_HANDOFF_SPAWN=1.
+export function maybeSpawn(projectDir, conf = readConfig()) {
+  try {
+    if (process.platform !== "darwin") return false;
+    if (process.env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
+    if (conf.autoHandoffPrompt === false) return false;
+    const script = join(HERE, "..", "..", "bin", "handoff-prompt.sh");
+    if (!existsSync(script)) { process.stderr.write(`[trantor] handoff-prompt.sh missing\n`); return false; }
+    const timeout = String(conf.handoffPromptTimeout || 25);
+    const child = spawn("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch (e) { process.stderr.write(`[trantor] maybeSpawn error: ${e?.message}\n`); return false; }
+}

package/hooks/precompact.mjs

@@ -1,18 +1,14 @@
 #!/usr/bin/env node
-// trantor 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");
+// trantor PreCompact hook — fires right before Claude Code compacts a full context
+// window. A PreCompact hook CANNOT stop compaction; the current window is always
+// compacted. So its job is to write a rich WHOLE-SESSION handoff and (on macOS, by
+// default) prompt to open a FRESH session in a new terminal that takes over with a
+// full window. The new session's SessionStart hook loads the handoff. This is the
+// at-the-wall backstop; the heartbeat hook can also fire this earlier when the
+// context window size is known (see hooks/lib/handoff.mjs).
+import { readConfig, writeHandoff, pingBus, maybeSpawn,
+         contextUsage, alreadyHandedOff, markHandedOff } from "./lib/handoff.mjs";
+import { basename } from "node:path";
 
 function readStdin() {
   return new Promise(res => { let d = ""; process.stdin.setEncoding("utf8");
@@ -20,97 +16,29 @@ function readStdin() {
     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(`[trantor] 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 sessionId = input.session_id || "";
+  const conf = readConfig();
 
-  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));
+  const { file, record } = writeHandoff({ projectDir, sessionId, transcript, trigger });
   process.stderr.write(`[trantor] 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 {}
+  await pingBus(projectName, record.id, conf);
 
-  // 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(`[trantor] handoff prompt launched (opt-in)\n`);
-      }
-    }
-  } catch {}
+  // Spawn a fresh session UNLESS the heartbeat early-warning already did so for this
+  // window (shared guard). The handoff file is always refreshed above regardless.
+  const cur = contextUsage(transcript, conf)?.tokens || 0;
+  if (alreadyHandedOff(sessionId, cur)) {
+    process.stderr.write(`[trantor] fresh session already spawned for this window — handoff refreshed only\n`);
+  } else if (maybeSpawn(projectDir, conf)) {
+    markHandedOff(sessionId, cur);
+    process.stderr.write(`[trantor] fresh-session prompt launched (PreCompact)\n`);
+  }
 } catch (err) {
   process.stderr.write(`[trantor] precompact error: ${err?.message || err}\n`);
 }

package/hooks/sessionstart.mjs

@@ -9,9 +9,15 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir, hostname } from "node:os";
+import { execSync } from "node:child_process";
+import { resolveProject } from "../lib/project.mjs";
 
-// Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs).
-function loadPendingHandoff(projectName) {
+// Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs
+// / the heartbeat early-warning). `claim` marks it consumed so exactly one session
+// takes it. A compaction-triggered SessionStart (source="compact") is the SAME session
+// that just wrote the handoff for a FRESH window to pick up — it may show the summary
+// for continuity but must NOT claim it, or it steals the handoff from the new window.
+function loadPendingHandoff(projectName, { claim = true } = {}) {
   try {
     const dir = join(homedir(), ".agent-bus", "handoffs");
     if (!existsSync(dir)) return null;
@@ -20,7 +26,7 @@ function loadPendingHandoff(projectName) {
       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
+        if (claim) { rec.consumed = true; writeFileSync(p, JSON.stringify(rec, null, 2)); }
         return rec;
       }
     }
@@ -59,7 +65,8 @@ function sanitize(s) {
 
 let additionalContext = "";
 try {
-  await readStdin();
+  let source = "";
+  try { source = (JSON.parse((await readStdin()) || "{}").source) || ""; } catch {}
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   // Sessions started in the home directory itself aren't project work — registering
   // them spawns a phantom "<username>" project board on the dashboard. Set
@@ -69,7 +76,7 @@ try {
     process.stdout.write("{}");
     process.exit(0);
   }
-  const project = process.env.RELAY_PROJECT || basename(projectDir);
+  const project = resolveProject(projectDir);
   const session = process.env.RELAY_SESSION
     || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostname()}:${project}`);
   const url = relayUrl();
@@ -92,11 +99,44 @@ try {
     additionalContext += `</trantor>\n`;
   }
 
+  // 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
+  // SAME project where it stands instead of starting blind. Cheap + LLM-free.
+  try {
+    const cu = await jget(`${url}/catchup?project=${encodeURIComponent(project)}`).catch(() => null);
+    let gitlog = "";
+    try { gitlog = execSync(`git -C ${JSON.stringify(projectDir)} log --oneline -5 2>/dev/null`, { encoding: "utf8", timeout: 2500 }).trim(); } catch {}
+    if ((cu && cu.total > 0) || gitlog) {
+      const line = (arr) => (arr || []).map(t => `#${t.id} ${String(t.title).slice(0, 72)}${t.assignee ? ` @${t.assignee}` : ""}`).join("\n  ");
+      additionalContext += `<trantor-project-state project="${sanitize(project)}">\n`;
+      additionalContext += `📋 **Catching up on the continuous "${sanitize(project)}" board** (this project's living record across all sessions — read it before starting; don't duplicate done work).\n`;
+      if (cu && cu.brief) additionalContext += `\n**Brief:** ${sanitize(cu.brief)}\n`;
+      if (cu && cu.total > 0) {
+        const c = cu.counts;
+        additionalContext += `\n**Cards:** ${cu.total} total — ${c.done} done · ${c.doing} doing · ${c.testing} testing · ${c.todo} todo · ${c.failed} failed · ${c.blocked} blocked.\n`;
+        if (cu.doing?.length)   additionalContext += `\n_In progress:_\n  ${sanitize(line(cu.doing))}\n`;
+        if (cu.testing?.length) additionalContext += `\n_In testing:_\n  ${sanitize(line(cu.testing))}\n`;
+        if (cu.failed?.length)  additionalContext += `\n_Failed (needs attention):_\n  ${sanitize(line(cu.failed))}\n`;
+        if (cu.blocked?.length) additionalContext += `\n_Blocked:_\n  ${sanitize(line(cu.blocked))}\n`;
+        if (cu.todo?.length)    additionalContext += `\n_Queued (todo):_\n  ${sanitize(line(cu.todo))}\n`;
+        if (cu.recentDone?.length) additionalContext += `\n_Recently done:_\n  ${sanitize(line(cu.recentDone))}\n`;
+      }
+      if (gitlog) additionalContext += `\n**Recent commits:**\n\`\`\`\n${sanitize(gitlog)}\n\`\`\`\n`;
+      additionalContext += `\nFor a synthesized "where are we" narrative on demand, run \`trantor catchup\`.\n`;
+      additionalContext += `</trantor-project-state>\n`;
+      process.stderr.write(`[trantor] injected project-state catch-up for ${project} (${cu?.total || 0} cards)\n`);
+    }
+  } catch {}
+
   // 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));
+  // project — take over with this fresh full window instead of starting cold. On a
+  // compaction-triggered start, DON'T claim it (that's the same session that wrote it;
+  // claiming would steal it from the freshly-spawned window) — show it for continuity only.
+  const isCompact = source === "compact";
+  const handoff = loadPendingHandoff(basename(projectDir), { claim: !isCompact });
   if (handoff) {
-    process.stderr.write(`[trantor] loaded pending handoff ${handoff.id}\n`);
+    process.stderr.write(`[trantor] ${isCompact ? "showing (not claiming, compact)" : "loaded"} pending handoff ${handoff.id}\n`);
     additionalContext += `<trantor-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`;

package/hub.mjs

@@ -50,11 +50,11 @@ function scanTelemetry() {
 
 // 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: [], cardEvents: [], cardEventsBackfilled: false };
+let state = { messages: [], peers: {}, seq: 0, tasks: [], taskSeq: 0, projectMeta: {}, lessons: [], cardEvents: [], cardEventsBackfilled: false, aliases: {} };
 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 || [], cardEvents: Array.isArray(loaded.cardEvents) ? loaded.cardEvents : [], cardEventsBackfilled: !!loaded.cardEventsBackfilled };
+    state = { messages: loaded.messages || [], peers: {}, seq: loaded.seq || 0, tasks: loaded.tasks || [], taskSeq: loaded.taskSeq || 0, projectMeta: loaded.projectMeta || {}, lessons: loaded.lessons || [], cardEvents: Array.isArray(loaded.cardEvents) ? loaded.cardEvents : [], cardEventsBackfilled: !!loaded.cardEventsBackfilled, aliases: (loaded.aliases && typeof loaded.aliases === "object") ? loaded.aliases : {} };
     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 || "" };
   }
@@ -104,14 +104,23 @@ const now = () => Date.now();
 const fmtAge = ms => { const m = Math.floor(ms / 60000); return m > 48 * 60 ? `${Math.floor(m / 1440)}d ago` : m > 90 ? `${Math.floor(m / 60)}h ago` : `${m}m ago`; };
 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)); }
+// Canonical project name: follow the alias chain so historically-divergent keys
+// (e.g. "builtbetter" → "builtbetter.ai") fold into one lane on every read AND
+// write. Cycle-guarded. Empty/"all" pass through untouched.
+function canon(name) {
+  let n = String(name || "").slice(0, 80);
+  const seen = new Set();
+  while (n && state.aliases[n] && !seen.has(n)) { seen.add(n); n = state.aliases[n]; }
+  return n;
+}
 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);
+  if (project) p.project = canon(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);
+  if (!p.project && session.includes(":")) p.project = canon(session.split(":").pop().slice(0, 80));
   state.peers[session] = p; dirty = true;
 }
 // Derive a coarse health from the free-text status the runner sets on a failed turn
@@ -159,7 +168,7 @@ const server = http.createServer(async (req, res) => {
     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),
+      const t = { id: ++state.taskSeq, project: canon(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),
@@ -196,7 +205,7 @@ const server = http.createServer(async (req, res) => {
     if (req.method === "POST" && P === "/todos") {
       const b = await body(req);
       const session = String(b.session || b.by || "").slice(0, 120);
-      const project = String(b.project || "").slice(0, 80);
+      const project = canon(String(b.project || "").slice(0, 80));
       if (!session || !project) return json(res, 400, { error: "session and project required" });
       touch(session, undefined, project);
       const ST = { pending: "todo", in_progress: "doing", completed: "done" };
@@ -228,13 +237,14 @@ const server = http.createServer(async (req, res) => {
       return json(res, 200, { ok: true, count: todos.length });
     }
     if (req.method === "GET" && P === "/tasks") {
-      const proj = q.project; const ts = proj ? state.tasks.filter(t => t.project === proj) : state.tasks;
+      const proj = q.project ? canon(q.project) : ""; const ts = proj ? state.tasks.filter(t => canon(t.project) === proj) : state.tasks;
       return json(res, 200, { tasks: ts });
     }
     if (req.method === "GET" && P === "/history") {
       const requestedLimit = Number(q.limit || 200);
       const limit = Math.min(Math.max(Number.isFinite(requestedLimit) ? requestedLimit : 200, 0), 1000);
-      const events = (q.project ? state.cardEvents.filter(e => e.project === q.project) : state.cardEvents).slice(-limit);
+      const proj = q.project ? canon(q.project) : "";
+      const events = (proj ? state.cardEvents.filter(e => canon(e.project) === proj) : state.cardEvents).slice(-limit);
       return json(res, 200, { events });
     }
     // A single card's FULL story for the detail panel: the card itself, its status events, and the
@@ -252,7 +262,7 @@ const server = http.createServer(async (req, res) => {
       return json(res, 200, { task: meta, events, messages });
     }
     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);
+      const b = await body(req); const k = canon(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);
@@ -271,10 +281,52 @@ const server = http.createServer(async (req, res) => {
       dirty = true;   // the project reappears cleanly if an agent ever registers it again
       return json(res, 200, { ok: true, project: k, removed: { tasks: nt - state.tasks.length, peers: np - Object.keys(state.peers).length, messages: nm - state.messages.length } });
     }
+    // Fold one project lane into another: rewrite all stored project fields from→to AND
+    // record an alias so future writes under `from` canonicalize to `to`. Idempotent.
+    // This is how a fragmented project (one repo, two lane keys) becomes one continuous lane.
+    if (req.method === "POST" && P === "/project/merge") {
+      const b = await body(req);
+      const from = String(b.from || "").slice(0, 80), to = String(b.to || "").slice(0, 80);
+      if (!from || !to || from === to) return json(res, 400, { error: "distinct from+to required" });
+      let cards = 0, events = 0, peers = 0, msgs = 0;
+      for (const t of state.tasks) if (t.project === from) { t.project = to; cards++; }
+      for (const e of state.cardEvents) if (e.project === from) { e.project = to; events++; }
+      for (const v of Object.values(state.peers)) if (v.project === from) { v.project = to; peers++; }
+      for (const m of state.messages) if ((m.project || "") === from) { m.project = to; msgs++; }
+      if (state.projectMeta[from]) {
+        if (!state.projectMeta[to]) state.projectMeta[to] = state.projectMeta[from];
+        else if (!state.projectMeta[to].brief && state.projectMeta[from].brief) state.projectMeta[to].brief = state.projectMeta[from].brief;
+        delete state.projectMeta[from];
+      }
+      state.aliases[from] = to;                       // future writes fold automatically
+      for (const [k, v] of Object.entries(state.aliases)) if (v === from) state.aliases[k] = to; // re-point chains
+      dirty = true;
+      return json(res, 200, { ok: true, from, to, moved: { cards, events, peers, messages: msgs } });
+    }
+    // Catch-up snapshot: everything a NEW session needs to resume a project's continuous
+    // lane — the brief, card counts, what's in-flight (doing/testing/todo) and the most
+    // recent done work, plus last activity. Cheap + LLM-free; the SessionStart hook injects it.
+    if (req.method === "GET" && P === "/catchup") {
+      const proj = canon(q.project || "");
+      if (!proj) return json(res, 400, { error: "project required" });
+      const mine = state.tasks.filter(t => canon(t.project) === proj);
+      const counts = { todo:0, doing:0, testing:0, failed:0, done:0, blocked:0 };
+      for (const t of mine) counts[t.status] = (counts[t.status] || 0) + 1;
+      const pick = (st, n) => mine.filter(t => t.status === st).sort((a,b)=>(b.updated||0)-(a.updated||0)).slice(0, n)
+        .map(t => ({ id: t.id, title: t.title, assignee: t.assignee || "", updated: t.updated || 0 }));
+      const lastActivity = mine.reduce((mx,t)=>Math.max(mx, t.updated||0), state.projectMeta[proj]?.updated || 0);
+      return json(res, 200, {
+        project: proj, brief: state.projectMeta[proj]?.brief || "",
+        counts, total: mine.length,
+        doing: pick("doing", 8), testing: pick("testing", 8), failed: pick("failed", 8),
+        blocked: pick("blocked", 8), todo: pick("todo", 10), recentDone: pick("done", 8),
+        lastActivity,
+      });
+    }
     if (req.method === "GET" && P === "/projects") {        // project-grouped view
       prunePeers();
       const cutoff = now() - ONLINE_MS; const byProj = {};
-      const proj = p => p || "(unassigned)";
+      const proj = p => canon(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: [], lastActivity: 0 });
       for (const [s, v] of Object.entries(state.peers)) {
         const k = proj(v.project); const e = mk(k); e.agents.push({ session: s, online: v.lastSeen > cutoff, status: v.status || "", health: healthOf(v.status) });

package/lib/project.mjs

@@ -0,0 +1,23 @@
+// trantor — canonical project identity (client side).
+// One repo = one lane. The loose `basename(cwd)` used everywhere before let a
+// project fragment into multiple lanes (e.g. the host registered "builtbetter.ai"
+// while its crew registered "builtbetter"). We now key by the GIT REPO ROOT
+// basename, which is stable across subdirectories and sessions. An explicit
+// RELAY_PROJECT always wins (deliberate override / crew inheritance). The hub
+// applies an alias map on top of this to fold any historical divergence.
+import { execSync } from "node:child_process";
+import { basename } from "node:path";
+
+export function gitRoot(dir) {
+  try {
+    return execSync(`git -C ${JSON.stringify(dir)} rev-parse --show-toplevel`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 }).trim();
+  } catch { return ""; }
+}
+
+// Stable project key for a working directory. RELAY_PROJECT > git-root basename > cwd basename.
+export function resolveProject(cwd = process.cwd()) {
+  if (process.env.RELAY_PROJECT) return process.env.RELAY_PROJECT.slice(0, 80);
+  const root = gitRoot(cwd);
+  return basename(root || cwd).slice(0, 80);
+}

package/mcp.mjs

@@ -10,6 +10,7 @@ import { join, basename } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execSync, spawnSync } from "node:child_process";
 import { advise } from "./bin/advise.mjs";
+import { resolveProject } from "./lib/project.mjs";
 import { z } from "zod";
 
 function relayUrl() {
@@ -21,7 +22,9 @@ function relayUrl() {
   return "http://127.0.0.1:4477";
 }
 const URL_BASE = relayUrl();
-const PROJECT = process.env.RELAY_PROJECT || basename(process.env.CLAUDE_PROJECT_DIR || process.cwd());
+// Stable project key: RELAY_PROJECT > git-repo-root basename > cwd basename. Keying by
+// the git root (not a loose cwd basename) stops one repo fragmenting into several lanes.
+const PROJECT = resolveProject(process.env.CLAUDE_PROJECT_DIR || process.cwd());
 // Identity: RELAY_SESSION wins; else RELAY_AGENT ("codex", "kimi", …) brands the session per-project
 // (set it once in the CLI's global MCP config — works in every project); else hostname:project.
 const SESSION = process.env.RELAY_SESSION

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.12",
+  "version": "0.17.14",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -10,7 +10,7 @@
     "zod": "^4.4.3"
   },
   "scripts": {
-    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs"
+    "test": "node test.mjs && node test-scenarios.mjs && node test-failure.mjs && node test-handoff.mjs"
   },
   "description": "The hub-world for AI agent crews \u2014 orchestrate Claude Code, Codex, Gemini, Kimi & DeepSeek as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).",
   "files": [
@@ -19,6 +19,7 @@
     "ui.html",
     "bin/",
     "hooks/",
+    "lib/",
     "skills/",
     "deploy/",
     "configs/",