trantor 0.17.13 → 0.17.15

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, hostId } 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,9 +76,9 @@ 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}`);
+    || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
   const url = relayUrl();
 
   // register self + post an initial presence status (no LLM turn — instant for others to read)
@@ -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: {}, phaseMeta: {} };
 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 : {}, phaseMeta: (loaded.phaseMeta && typeof loaded.phaseMeta === "object") ? loaded.phaseMeta : {} };
     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
@@ -145,6 +154,95 @@ function appendCardEvent(type, task, by, from = null, to = null) {
   if (state.cardEvents.length > 5000) state.cardEvents.splice(0, state.cardEvents.length - 5000);
 }
 
+// --- FLOW v2: derive a project's PHASES (the orchestrator-rooted flowchart spine) ---
+// Real data is deps-sparse (most cards carry no deps), so we DON'T derive phases from the
+// dependency graph. Instead: a card's phase = its title-prefix family (P5a/P5b → "P5",
+// CBv2-1/CBfix → "CB", FA-comp1 → "FA", …) when present; otherwise it's clustered with its
+// time-neighbours into a "Setup N" round (gap > 8h opens a new round). Phases are ordered by
+// first-seen. The orchestrator (host session, "machine:project") vs crew ("brand:project")
+// split gives each phase its fan-out actors; the plan/integrate spine nodes are synthetic
+// because real per-phase orchestrator cards are rare. `sparse` flags a board that's mostly
+// un-prefixed (the UI shows an "inferred phases" notice — never a silent blob).
+const PHASE_GAP_MS = 8 * 60 * 60 * 1000;
+const agentBrand = (a) => { const s = String(a || ""); const i = s.indexOf(":"); return i > 0 ? s.slice(0, i) : (s || ""); };
+// Crew = a known helper-CLI brand; anything else with a brand (a machine hostname like
+// "MacBook-Pro-M1.local" or "MacBookPro.hsd1.fl.comcast.net", or a generic "host") is the
+// orchestrator. Brand-based (not hostname-pattern) so it's robust to hostname instability.
+const CREW_BRANDS = /^(codex|gemini|kimi|deepseek|claude|qwen|grok|glm|mistral|llama)$/i;
+const isOrchAssignee = (a) => { const b = agentBrand(a); return !!b && !CREW_BRANDS.test(b); };
+function phaseFamily(title) {
+  const s = String(title || "").trim();
+  // "P5a Structured…", "P4-construction", "P3 Quantity" → P5/P4/P3 (group all P5a/b/c/d together).
+  // The trailing letter and the separator must NOT be swallowed by \b (P5a has none between 5 and a).
+  let m;
+  if ((m = s.match(/^P(\d+)[a-z]?(?:[\s\-:.]|$)/i))) return "P" + m[1];
+  if (/^CBv?\d/i.test(s) || /^CBfix/i.test(s) || /^CB[\s\-:.]/i.test(s)) return "CB";
+  if (/^FA[\s\-:.\d]/i.test(s)) return "FA";
+  if (/^RunCost/i.test(s)) return "RunCost";
+  return null;
+}
+function phaseStatus(counts) {
+  if (counts.failed) return "failed";
+  if (counts.doing || counts.testing) return "active";
+  const total = counts.todo + counts.doing + counts.testing + counts.failed + counts.done + counts.blocked;
+  if (total > 0 && counts.done === total) return "done";
+  if (counts.blocked) return "blocked";
+  if (counts.todo === total) return "planned";
+  return "active";
+}
+// A human "what is this phase about" line derived from the cards themselves: strip the phase-prefix
+// token, take the subject before the first em/en-dash, dedupe, join the first few. Retroactive — no
+// captured plan needed. An explicit phase goal (phaseMeta) overrides this in the /phases endpoint.
+function phaseTheme(cards) {
+  const subs = [];
+  const seen = new Set();
+  for (const c of cards) {
+    let s = String(c.title || "")
+      // drop the phase token INCLUDING any sub-index (P3.5, P5a, CBv2-1) + separators, so no "1"/".5" leaks
+      .replace(/^\s*(P\d+[a-z]?(?:[.\-]\d+)?|CBv?\d+(?:[.\-]\d+)?|CBfix|FA[-\s:]?\w*|RunCost)[\s:\-–—#]*/i, "")
+      .split(/[—–]| - /)[0].trim();                                                    // subject before a dash
+    if (!s) continue;
+    const k = s.toLowerCase().slice(0, 22);
+    if (seen.has(k)) continue;
+    seen.add(k); subs.push(s.slice(0, 48));
+    if (subs.length >= 3) break;
+  }
+  return subs.join(" · ").slice(0, 120);
+}
+function derivePhases(tasks) {
+  const sorted = [...tasks].sort((a, b) => (a.ts || 0) - (b.ts || 0));
+  let miscRound = 0, lastMiscTs = 0;
+  for (const t of sorted) {
+    // an explicit phase tag (set at plan time) wins; else infer from the title prefix; else time-cluster.
+    const explicit = t.phase && String(t.phase).trim();
+    const fam = explicit || phaseFamily(t.title);
+    if (fam) { t._phase = fam; }
+    else {
+      if (!lastMiscTs || (t.ts || 0) - lastMiscTs > PHASE_GAP_MS) miscRound++;
+      lastMiscTs = t.ts || lastMiscTs;
+      t._phase = `Setup ${miscRound}`;
+    }
+  }
+  const byPhase = new Map();
+  for (const t of sorted) { if (!byPhase.has(t._phase)) byPhase.set(t._phase, []); byPhase.get(t._phase).push(t); }
+  const phases = [...byPhase.entries()].map(([key, cards]) => {
+    const counts = { todo:0, doing:0, testing:0, failed:0, done:0, blocked:0 };
+    for (const c of cards) counts[c.status] = (counts[c.status] || 0) + 1;
+    const node = (c) => ({ id: c.id, title: c.title, assignee: c.assignee || "", agent: agentBrand(c.assignee), model: c.model || "", status: c.status, difficulty: c.difficulty || "", ts: c.ts || 0, updated: c.updated || c.ts || 0, deps: Array.isArray(c.deps) ? c.deps : [] });
+    const crew = cards.filter(c => !isOrchAssignee(c.assignee)).map(node);
+    const orchestrators = cards.filter(c => isOrchAssignee(c.assignee)).map(node);
+    return {
+      key, label: key, theme: phaseTheme(cards),
+      start: Math.min(...cards.map(c => c.ts || 0)), end: Math.max(...cards.map(c => c.updated || c.ts || 0)),
+      counts, total: cards.length, status: phaseStatus(counts),
+      agents: [...new Set(crew.map(c => c.agent).filter(Boolean))],
+      crew, orchestrators,
+    };
+  }).sort((a, b) => a.start - b.start);
+  const miscCount = sorted.filter(t => /^Setup /.test(t._phase)).length;
+  return { phases, total: sorted.length, sparse: sorted.length > 0 && miscCount / sorted.length > 0.5, derivedBy: "title-prefix + time-cluster" };
+}
+
 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 {
@@ -159,8 +257,9 @@ 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,
+        phase: String(b.phase || "").slice(0, 40),   // explicit phase tag (FLOW v2) — wins over title-prefix inference
         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) : [],
@@ -196,7 +295,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 +327,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 +352,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 +371,74 @@ 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,
+      });
+    }
+    // FLOW v2: the orchestrator-rooted phase flowchart. Returns the project's cards grouped into
+    // ordered phases (title-prefix + time-cluster), each with its crew fan-out + orchestrator nodes.
+    if (req.method === "GET" && P === "/phases") {
+      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 out = derivePhases(mine);
+      for (const p of out.phases) p.goal = state.phaseMeta[`${proj}::${p.key}`]?.goal || "";   // explicit goal overrides the derived theme
+      return json(res, 200, { project: proj, brief: state.projectMeta[proj]?.brief || "", ...out });
+    }
+    // Set a phase's explicit GOAL — what this phase needs to do (the orchestrator captures this at plan
+    // time, like a per-phase brief). Surfaces in the FLOW v2 header in place of the derived theme.
+    if (req.method === "POST" && P === "/phase") {
+      const b = await body(req);
+      const proj = canon(String(b.project || "").slice(0, 80)), phase = String(b.phase || "").slice(0, 40);
+      if (!proj || !phase) return json(res, 400, { error: "project + phase required" });
+      const k = `${proj}::${phase}`; const m = state.phaseMeta[k] || {};
+      if (b.goal !== undefined) m.goal = String(b.goal).slice(0, 400);
+      m.by = b.by || m.by || ""; m.updated = now();
+      state.phaseMeta[k] = m; dirty = true;
+      return json(res, 200, { ok: true, project: proj, phase, goal: m.goal || "" });
+    }
     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,46 @@
+// 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 { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { basename, join, dirname } from "node:path";
+import { homedir, hostname } from "node:os";
+
+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);
+}
+
+// Stable machine identity. os.hostname() is network-dependent — the same Mac reports
+// "MacBook-Pro-M1.local" on one network and "MacBookPro.hsd1.fl.comcast.net" on another, which
+// forks one machine into two session identities on the bus. Resolve a stable id ONCE and persist it
+// to ~/.agent-bus/machine-id so it never drifts: RELAY_HOST_ID > persisted id > macOS LocalHostName
+// (stable, no domain) > hostname() without its domain suffix.
+let _hostId = null;
+export function hostId() {
+  if (_hostId) return _hostId;
+  if (process.env.RELAY_HOST_ID) return (_hostId = process.env.RELAY_HOST_ID.slice(0, 60));
+  const f = join(homedir(), ".agent-bus", "machine-id");
+  try { if (existsSync(f)) { const v = readFileSync(f, "utf8").trim(); if (v) return (_hostId = v.slice(0, 60)); } } catch {}
+  let id = "";
+  if (process.platform === "darwin") {
+    try { id = execSync("scutil --get LocalHostName", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 1500 }).trim(); } catch {}
+  }
+  if (!id) id = String(hostname() || "host").split(".")[0];
+  id = id.slice(0, 60) || "host";
+  try { mkdirSync(dirname(f), { recursive: true }); writeFileSync(f, id); } catch {}
+  return (_hostId = id);
+}

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, hostId } from "./lib/project.mjs";
 import { z } from "zod";
 
 function relayUrl() {
@@ -21,11 +22,13 @@ 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
-  || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${PROJECT}` : `${hostname()}:${PROJECT}`);
+  || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${PROJECT}` : `${hostId()}:${PROJECT}`);
 let cursor = 0;
 
 async function api(method, path, payload) {
@@ -45,11 +48,19 @@ server.tool("relay_whoami", "Show this session's relay identity, project, and th
 });
 
 server.tool("relay_task_add", "Add a Kanban card to a project's board on the dashboard (what you're about to work on). Defaults: THIS project, assigned to you, status 'todo'. Pass `project` to target another board — e.g. when you orchestrate a crew that runs in a different directory than the one you launched Claude from. Keep the team's progress visible.",
-  { title: z.string().describe("short task title"), status: z.enum(["todo","doing","testing","failed","done","blocked"]).optional(), assignee: z.string().optional().describe("session id to assign (default: you)"), difficulty: z.enum(["easy","medium","hard"]).optional().describe("difficulty tag — drives model/agent routing (relay_advise) and shows on the board"), model: z.string().optional().describe("the model this card is routed to (from relay_advise routing, or the CLI default) — shown on the card"), deps: z.array(z.number()).optional().describe("card ids this card depends on — drawn as edges in the Flow view (e.g. integration depends on every crew card)"), project: z.string().optional().describe("board to add to (default: this session's project). Set to the crew's project when you orchestrate from a different directory") },
-  async ({ title, status, assignee, difficulty, model, deps, project }) => {
+  { title: z.string().describe("short task title"), status: z.enum(["todo","doing","testing","failed","done","blocked"]).optional(), assignee: z.string().optional().describe("session id to assign (default: you)"), difficulty: z.enum(["easy","medium","hard"]).optional().describe("difficulty tag — drives model/agent routing (relay_advise) and shows on the board"), model: z.string().optional().describe("the model this card is routed to (from relay_advise routing, or the CLI default) — shown on the card"), deps: z.array(z.number()).optional().describe("card ids this card depends on — drawn as branch edges in the Flow view (e.g. integration depends on every crew card)"), phase: z.string().optional().describe("phase/milestone this card belongs to (e.g. 'P5', 'Auth', 'Launch') — groups it in the Flow view's phase flowchart. Optional; otherwise inferred from the title prefix + time."), project: z.string().optional().describe("board to add to (default: this session's project). Set to the crew's project when you orchestrate from a different directory") },
+  async ({ title, status, assignee, difficulty, model, deps, phase, project }) => {
     const proj = project || PROJECT;
-    const { task } = await api("POST", "/task", { project: proj, title, status: status || "todo", assignee: assignee || SESSION, difficulty, model, deps, by: SESSION });
-    return { content: [{ type: "text", text: `card #${task.id} added to ${proj}: "${title}" [${task.status}]` }] };
+    const { task } = await api("POST", "/task", { project: proj, title, status: status || "todo", assignee: assignee || SESSION, difficulty, model, deps, phase, by: SESSION });
+    return { content: [{ type: "text", text: `card #${task.id} added to ${proj}: "${title}" [${task.status}]${phase?` · phase ${phase}`:""}` }] };
+  });
+
+server.tool("relay_phase_goal", "Set what a PHASE is for — its goal — shown as the phase header in the Flow view (overrides the theme auto-derived from card titles). Capture this when you plan a phase so the board says what each milestone needs to do, not just 'P5'. Phase keys match relay_task_add's `phase` (or the inferred title-prefix family like 'P5').",
+  { phase: z.string().describe("the phase key (e.g. 'P5', 'Auth', 'Launch')"), goal: z.string().describe("1-2 sentences: what this phase delivers + done-criteria"), project: z.string().optional().describe("board (default: this session's project)") },
+  async ({ phase, goal, project }) => {
+    const proj = project || PROJECT;
+    await api("POST", "/phase", { project: proj, phase, goal, by: SESSION });
+    return { content: [{ type: "text", text: `phase "${phase}" goal set for ${proj}` }] };
   });
 
 server.tool("relay_task_move", "Move a Kanban card as you progress: todo -> doing -> testing -> done. NEVER move straight to done: move to 'testing' when you finish, run the project's tests/typecheck, then 'done' only if green — or 'failed' (with a relay_send explaining what broke) if not. The orchestrator bounces failed cards back to doing. blocked = waiting on something external.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.13",
+  "version": "0.17.15",
   "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/",