trantor 0.17.80 → 0.17.93

package/hooks/sessionstart.mjs

@@ -11,11 +11,11 @@ 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";
-import { resolveProject, hostId } from "../lib/project.mjs";
+import { resolveProject, hostId, resolveHubInfo, knownProjects, nonSeatReason, handoffDir } from "../lib/project.mjs";
 import { formatSubagentManifest } from "../lib/subagent-manifest.mjs";
 import { updateAvailable, maybeNotifyDesktop, readConfig } from "./lib/update-check.mjs";
 import { maybeCheckBalances } from "./lib/balance-check.mjs";
-import { relayUrl, getJSON, signedGet, signedPost } from "./lib/api.mjs";
+import { getJSON, signedGet, signedPost } from "./lib/api.mjs";
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
 
 // Load the most recent UNCONSUMED handoff for this project (written by precompact.mjs
@@ -25,7 +25,7 @@ import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox
 // for continuity but must NOT claim it, or it steals the handoff from the new window.
 function loadPendingHandoff(projectName, { claim = true, freshSession = null } = {}) {
   try {
-    const dir = join(homedir(), ".agent-bus", "handoffs");
+    const dir = handoffDir();   // NEVER join(homedir(), …) here: a drill pointed at a temp bus dir must not claim the real handoffs
     if (!existsSync(dir)) return null;
     // Match ONLY this project's handoffs: "<projectName>-<numeric stamp>.json".
     // NOT a loose startsWith() — that also caught leaked test fixtures like
@@ -134,12 +134,46 @@ try {
   // session resolved two different projects — and therefore two different hubs — so half a
   // session's work recorded on a hub nobody was reading.
   const projectDir = stdinObj.cwd || 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
-  // RELAY_SESSION (or RELAY_PROJECT) to deliberately put a home-dir session on the bus.
-  if (!process.env.RELAY_SESSION && !process.env.RELAY_PROJECT && projectDir === homedir()) {
-    process.stderr.write("[trantor] session in the home directory — not registering on the bus (set RELAY_SESSION to opt in)\n");
-    process.stdout.write("{}");
+  // NOT A SEAT — say so, loudly, to BOTH the user and the model.
+  //
+  // A session started outside a project (the home directory, a non-repo like ~/development, the
+  // plugin cache) is not project work, and registering it mints a phantom "<username>" board that,
+  // being unpinned, lands on the LOCAL hub while the real crew lives on the remote one. Declining
+  // to register was always right. Doing it via a stderr line NOBODY READS was not: the session
+  // then spends an hour believing it is the crebral-health seat and eventually reports "Trantor is
+  // unreachable" — with every hub healthy. That is what a macOS reboot produces every time, since
+  // reopened Terminal windows come back in $HOME and `claude --resume` restores the conversation
+  // but not the directory. So: no registration, and an unmissable explanation of what this session
+  // is not, what it therefore cannot do, and the one command that fixes it.
+  const notSeat = nonSeatReason(projectDir);
+  if (notSeat) {
+    const known = knownProjects();
+    const O = "\x1b[1;38;5;208m", R = "\x1b[0m";
+    const banner = `🟠 ${O}Not a Trantor seat${R} — ${projectDir} is ${notSeat}. `
+      + `It is NOT on the bus: no board, no peers, no inbox. `
+      + `Start it from the project directory instead:  ${O}cd <project> && claude${R}`;
+    let ctx = `<trantor-not-a-seat cwd="${sanitize(projectDir)}" reason="${sanitize(notSeat)}">\n`;
+    ctx += `⚠️ **This session is NOT registered on Trantor.** Its working directory `;
+    ctx += `(\`${sanitize(projectDir)}\`) is ${sanitize(notSeat)} — not a project — so no seat was created for it.\n\n`;
+    ctx += `**What that means — do not work around it, and do not report the bus as broken:**\n`;
+    ctx += `- You have no project board, no peers, and no inbox. \`relay_peers\` will look empty and \`relay_send\` reaches nobody.\n`;
+    ctx += `- Messages other sessions address to this project are NOT lost — they are waiting on the hub for a real seat.\n`;
+    ctx += `- The hubs are almost certainly healthy. "Trantor is unreachable" is the WRONG diagnosis here; the right one is "this window is in the wrong directory".\n\n`;
+    ctx += `**Tell the user this, in your first reply, before doing anything else.** The fix is to close this window and start Claude from the project directory (\`cd <project> && claude\`), which is what makes it a seat. A session can also be forced onto the bus with \`RELAY_PROJECT=<project> claude\`, but only when there is a reason it cannot run from the directory itself.\n`;
+    if (known.length) ctx += `\nProjects pinned on this machine: ${sanitize(known.slice(0, 24).join(", "))}${known.length > 24 ? ", …" : ""}.\n`;
+    // If the operator has DECLARED seats, recovery is one command — name it rather than making
+    // them remember which directory each project lives in.
+    try {
+      const { readSeats } = await import("../lib/seats.mjs");
+      const declared = Object.keys(readSeats());
+      if (declared.length) {
+        ctx += `\nDeclared seats on this machine: ${sanitize(declared.slice(0, 24).join(", "))}. `;
+        ctx += `\`trantor seats\` shows which are missing and \`trantor seats up\` reopens each one in its own directory.\n`;
+      }
+    } catch {}
+    ctx += `</trantor-not-a-seat>\n`;
+    process.stderr.write(`[trantor] ${notSeat} — not registering on the bus (set RELAY_PROJECT to opt in)\n`);
+    process.stdout.write(emit(ctx, banner, ""));
     process.exit(0);
   }
   const project = resolveProject(projectDir);
@@ -148,7 +182,9 @@ try {
     || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
   // relayUrl() with no project resolves from the hook process's cwd, which is not always the
   // project the session is about. Pass it, or every call below can address the wrong hub.
-  const url = relayUrl(project);
+  // resolveHubInfo carries HOW the hub was chosen so an unpinned project can be flagged below
+  // instead of silently routing to the default.
+  const { url, via: hubVia } = resolveHubInfo(project);
 
   // register self + post an initial presence status (no LLM turn — instant for others to read)
   await jpost(`${url}/register`, { session, project, status: `active in ${project}` }, session).catch(() => {});
@@ -158,7 +194,25 @@ try {
   try { peers = (await jget(`${url}/peers`, session)).peers || []; hubAnswered = true; } catch {}
   const others = peers.filter(p => p.online && p.session !== session);
 
-  process.stderr.write(`[trantor] registered as ${session} -> ${url} (${others.length} other live session(s))\n`);
+  process.stderr.write(`[trantor] registered as ${session} -> ${url} (via ${hubVia}, ${others.length} other live session(s))\n`);
+
+  // UNPINNED → the hub was a FALLBACK, not a decision. This session is on the bus, but possibly not
+  // the bus its crew is on: pins route the known projects to the remote hub, and anything unpinned
+  // drops to the global default. Two seats that believe they are the same project then read and
+  // write different stores, each looking perfectly healthy. Never let that be silent.
+  if (hubVia === "global" || hubVia === "default") {
+    const known = knownProjects();
+    const O = "\x1b[1;38;5;208m", R = "\x1b[0m";
+    const line = `🟠 ${O}"${project}" is not pinned to a hub${R} — falling back to ${url}. `
+      + `If the crew is on another hub this seat cannot see them. Pin it:  ${O}trantor hub set ${project} <url>${R}`;
+    userBanner = userBanner ? `${userBanner}\n${line}` : line;
+    additionalContext += `<trantor-hub-unpinned project="${sanitize(project)}" hub="${sanitize(url)}" via="${sanitize(hubVia)}">\n`;
+    additionalContext += `⚠️ **The project "${sanitize(project)}" has no hub pin.** This seat fell back to \`${sanitize(url)}\` (${hubVia === "global" ? "the global default" : "the built-in local default"}), which is a guess, not a routing decision.\n`;
+    additionalContext += `If the rest of the crew is pinned to a different hub, you will see an empty board and no peers while every hub is healthy — do NOT diagnose that as "Trantor is down". Confirm with \`trantor hub list\`, and pin this project with \`trantor hub set ${sanitize(project)} <url>\` so the routing is deliberate.\n`;
+    if (known.length) additionalContext += `\nPinned projects: ${sanitize(known.slice(0, 24).join(", "))}${known.length > 24 ? ", …" : ""}.\n`;
+    additionalContext += `</trantor-hub-unpinned>\n`;
+    process.stderr.write(`[trantor] WARNING: project "${project}" is unpinned; hub ${url} chosen via ${hubVia}\n`);
+  }
 
   if (others.length > 0) {
     additionalContext += `<trantor session="${session}" hub="${url}">\n`;

package/hooks/stop-inbox.mjs

@@ -42,6 +42,56 @@ function readStdin() {
   });
 }
 
+
+// ---- the metronome: never park while a dispatched contract is stalled ----------------------
+// An empty inbox is not the same as nothing outstanding. A session that dispatched work to a seat
+// that then died sees silence and parks, and the human becomes the one who remembers, which is the
+// complaint this exists to answer. So before letting a stop through we ask the hub what this
+// session is still owed, and refuse ONCE if any of it has gone quiet.
+//
+// Deliberately narrow: only a contract whose assignee is offline, or one that is overdue, blocks.
+// An open contract with a healthy seat working on it is exactly what "in progress" looks like, and
+// nagging about it every stop would be worse than saying nothing. Fail-open throughout: a hub that
+// is down or slow must never trap a session.
+const OVERDUE_MS = (() => {
+  const raw = process.env.TRANTOR_CONTRACT_OVERDUE_MS;
+  const n = raw === undefined || raw === "" ? NaN : Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 10 * 60 * 1000;
+})();
+
+async function stalledContractCheck({ session, project, instanceId }) {
+  if (process.env.RELAY_STOP_CONTRACTS === "0") return allow();
+  let contracts = [];
+  try {
+    const r = await signedGet(`/contracts?session=${encodeURIComponent(session)}&project=${encodeURIComponent(project)}`,
+      { timeoutMs: FETCH_TIMEOUT_MS, session, instance: instanceId, project });
+    if (!r.ok) return allow();
+    contracts = r.json?.contracts || [];
+  } catch { return allow(); }
+
+  const stalled = contracts.filter(c => !c.answered && (!c.assigneeOnline || c.ageMs >= OVERDUE_MS));
+  if (!stalled.length) return allow();
+
+  const mins = (ms) => (ms >= 60000 ? `${Math.round(ms / 60000)}m` : `${Math.round(ms / 1000)}s`);
+  const lines = stalled.slice(0, 6).map(c => {
+    const health = c.assigneeOnline ? `online, status "${sanitize(c.assigneeStatus || "?")}"`
+      : c.assigneeLastSeenMs == null ? "never seen on the bus"
+      : `LAST SEEN ${mins(c.assigneeLastSeenMs)} ago`;
+    return `- ${sanitize(c.to)} (${health}) — asked ${mins(c.ageMs)} ago: "${sanitize(String(c.text).slice(0, 120))}"`;
+  }).join("\n");
+
+  const reason =
+    `You dispatched ${stalled.length} contract(s) that have gone quiet, and you were about to go idle:\n` +
+    lines + `\n\n` +
+    `Do not just wait, and do not ask the human to check. Use relay_contracts to see everything you are owed, ` +
+    `relay_peers to see whether the seat is alive, and relay_send to ask it directly. If a seat is down, say so and ` +
+    `either swap it (\`trantor swap <agent>\`) or reassign the work. If the work is genuinely still running, say that ` +
+    `plainly and stop. This check will not block you a second time.`;
+
+  process.stdout.write(JSON.stringify({ decision: "block", reason }));
+  process.exit(0);
+}
+
 async function main() {
   const raw = await readStdin();
   let input = {};
@@ -97,7 +147,7 @@ async function main() {
   } catch { return allow(); }        // hub down — never trap the session
 
   const direct = messages.filter(m => m.to === session);
-  if (!direct.length) return allow();
+  if (!direct.length) return stalledContractCheck({ session, project, instanceId });
 
   // Committed now: claim delivery for real so neither inbox-deliver nor the deferred waker repeats it.
   let next = cursor;

package/hub.mjs

@@ -2241,7 +2241,11 @@ const server = http.createServer(async (req, res) => {
       // attribute the message to a project so the dashboard can show it in that project's lane.
       // explicit b.project wins; else the sender's known project; else parsed from a "host:project" id.
       const fromProj = state.peers[b.from]?.project || (b.from && b.from.includes(":") ? b.from.split(":").pop() : "");
-      const msg = { id: ++state.seq, ts: now(), from: b.from || "anon", to: b.to || "all", text, project: String(b.project || fromProj || "").slice(0, 80) };
+      // `re` threads an OUTCOME back to the CONTRACT it answers. Without it "what am I still owed"
+      // is guesswork: a seat still working and a seat that died look identical from the sender's
+      // side, which is how an orchestrator ends up waiting forever on a dead peer.
+      const re = Number.isFinite(Number(b.re)) && Number(b.re) > 0 ? Number(b.re) : 0;
+      const msg = { id: ++state.seq, ts: now(), from: b.from || "anon", to: b.to || "all", text, project: String(b.project || fromProj || "").slice(0, 80), ...(re ? { re } : {}) };
       state.messages.push(msg); if (state.messages.length > 5000) state.messages.splice(0, 1000);
       dirty = true; pushToStreams(msg);               // <-- instant push to live watchers
       // Mirror onto the unified log. `refs` = the card ids this message cites (#3701), which is what
@@ -2251,6 +2255,46 @@ const server = http.createServer(async (req, res) => {
       appendEvent("message", msg.project, msg.from, { msgId: msg.id, toSession: msg.to, text: msg.text.slice(0, 2000), refs });
       return json(res, 200, { ok: true, id: msg.id });
     }
+    // ---- /contracts: what this session dispatched and has not been answered on ----------------
+    // A contract is a DIRECT message from you to one peer. It closes when that peer sends you an
+    // outcome: strictly by `re`, or, for seats that predate it, oldest-open-first. Broadcasts are
+    // never contracts. Each open one carries the assignee's presence, because the actionable half
+    // of "still waiting" is whether anyone is still on the other end.
+    if (req.method === "GET" && P === "/contracts") {
+      const session = String(q.session || "");
+      if (!session) return json(res, 400, { error: "session required" });
+      const proj = String(q.project || "");
+      const windowMs = Math.max(60000, Number(q.windowMs || 24 * 3600 * 1000));
+      const cutoff = now() - windowMs;
+      const mine = state.messages.filter(m => m.from === session && m.to && m.to !== "all" && m.ts >= cutoff && (!proj || m.project === proj));
+      const replies = state.messages.filter(m => m.to === session && m.from !== session && m.ts >= cutoff);
+      const byRe = new Map();
+      for (const r of replies) if (r.re) byRe.set(Number(r.re), r);
+      const looseByPeer = new Map();
+      for (const r of replies) if (!r.re) { if (!looseByPeer.has(r.from)) looseByPeer.set(r.from, []); looseByPeer.get(r.from).push(r); }
+      for (const arr of looseByPeer.values()) arr.sort((a, b) => a.ts - b.ts);
+      const out = [];
+      for (const c of mine.sort((a, b) => a.ts - b.ts)) {
+        let answer = byRe.get(c.id) || null;
+        if (!answer) {
+          const pool = looseByPeer.get(c.to) || [];
+          const i = pool.findIndex(r => r.ts > c.ts);
+          if (i >= 0) answer = pool.splice(i, 1)[0];
+        }
+        const peer = state.peers[c.to] || null;
+        const seen = peer?.lastSeen || 0;
+        out.push({
+          id: c.id, to: c.to, text: c.text, ts: c.ts, ageMs: now() - c.ts,
+          answered: !!answer,
+          answer: answer ? { id: answer.id, ts: answer.ts, text: answer.text } : null,
+          assigneeOnline: !!seen && (now() - seen) < ONLINE_MS,
+          assigneeStatus: String(peer?.status || ""),
+          assigneeLastSeenMs: seen ? now() - seen : null,
+        });
+      }
+      return json(res, 200, { session, contracts: out, open: out.filter(c => !c.answered).length });
+    }
+
     if (req.method === "GET" && P === "/inbox") {
       if (!canUseInboxSession(auth, q.session)) return json(res, 403, { error: "forbidden" });
       touch(q.session, undefined, undefined, undefined, auth); const since = Number(q.since || 0);

package/lib/project.mjs

@@ -6,7 +6,7 @@
 // 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 { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { basename, join, dirname } from "node:path";
 import { homedir, hostname } from "node:os";
 
@@ -33,7 +33,16 @@ export function resolveProject(cwd = process.cwd()) {
 // local default. Never throws: hooks run inside the user's tool loop and MUST fail open.
 export const DEFAULT_HUB_URL = "http://127.0.0.1:4477";
 
-function busDir() { return process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus"); }
+// The bus directory, resolved in ONE place. Both override names are honoured because both are
+// already in use across the hooks (AGENT_BUS_DIR in api/prompt-focus/file-claim, RELAY_DATA_DIR in
+// handoff/resources/update-check); a reader that honours neither will happily mutate the user's
+// REAL state during a test. That is not hypothetical: on 2026-08-23 a pre-flight drill pointed at
+// a temp bus dir and still CLAIMED two live pending handoffs, because the handoff reader joined
+// homedir() directly while the writer honoured RELAY_DATA_DIR.
+export function busDir() {
+  return process.env.AGENT_BUS_DIR || process.env.RELAY_DATA_DIR || join(homedir(), ".agent-bus");
+}
+export function handoffDir() { return join(busDir(), "handoffs"); }
 function configPath() { return join(busDir(), "config.json"); }
 
 export function readConfig() {
@@ -41,18 +50,76 @@ export function readConfig() {
   return {};
 }
 
-export function resolveHub(project, env = process.env) {
+// HOW a hub was chosen, not merely which one. The silent fallback is the most expensive failure
+// this system has: an unpinned project resolves to the global default, nothing errors, the seat
+// looks healthy, and its work records on a hub nobody reads (2026-08-19 and again 2026-08-23,
+// after a reboot reopened every window in $HOME). Provenance is therefore part of the answer, so
+// callers that can warn — sessionstart, doctor, relay_whoami — can say WHY.
+//   via "env"     → RELAY_URL (explicit override: tests, crew seats)
+//   via "pin"     → config hubs[project]  (the only DELIBERATE routing)
+//   via "global"  → config url            (fallback — the project was never pinned)
+//   via "default" → built-in local        (fallback — there is no config at all)
+export function resolveHubInfo(project, env = process.env) {
   try {
-    if (env.RELAY_URL) return env.RELAY_URL;
+    if (env.RELAY_URL) return { url: env.RELAY_URL, via: "env" };
     const cfg = readConfig();
     const name = project || resolveProject();
     const u = cfg?.hubs?.[name];
-    if (u && typeof u === "string") return u;
-    if (cfg?.url && typeof cfg.url === "string") return cfg.url;
+    if (u && typeof u === "string") return { url: u, via: "pin" };
+    if (cfg?.url && typeof cfg.url === "string") return { url: cfg.url, via: "global" };
   } catch {}
-  return DEFAULT_HUB_URL;
+  return { url: DEFAULT_HUB_URL, via: "default" };
+}
+
+export function resolveHub(project, env = process.env) {
+  return resolveHubInfo(project, env).url;
+}
+
+// Every project the operator has deliberately pinned — the "expected one of these" list a
+// misplaced session needs in order to fix itself.
+export function knownProjects() {
+  try { const h = readConfig()?.hubs; return h && typeof h === "object" ? Object.keys(h).sort() : []; } catch { return []; }
 }
 
+// How many IMMEDIATE children of `dir` are git repos. Bounded (first 200 entries) and fail-safe:
+// this runs in every session start, inside the user's tool loop.
+function countChildRepos(dir) {
+  try {
+    let n = 0;
+    for (const e of readdirSync(dir, { withFileTypes: true }).slice(0, 200)) {
+      if (!e.isDirectory() || e.name.startsWith(".")) continue;
+      if (existsSync(join(dir, e.name, ".git"))) { n++; if (n >= 2) return n; }
+    }
+    return n;
+  } catch { return 0; }
+}
+
+// Is this directory a real project seat, and if not, WHY not? Returns "" for a seat, otherwise a
+// short human reason. A non-seat must never register: it mints a phantom "<username>" or
+// "development" board, and because that name is unpinned it lands on the local hub while the crew
+// lives on the remote one — the exact split that makes an agent report "Trantor is unreachable"
+// while every hub is healthy. An explicit RELAY_SESSION/RELAY_PROJECT is the deliberate opt-in.
+export function nonSeatReason(dir = process.cwd(), env = process.env) {
+  try {
+    if (env.RELAY_SESSION || env.RELAY_PROJECT) return "";
+    const home = homedir();
+    if (dir === home) return "the home directory";
+    const claudeDir = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+    if (dir.startsWith(join(claudeDir, "plugins", "cache"))) return "the plugin cache";
+    // A WORKSPACE CONTAINER (~/development): not a repo itself, but holding several. This is the
+    // directory a reopened window most often lands in after the home directory, and it is the
+    // worst case — it registers as project "development", which nothing pins, so the seat lands
+    // on the fallback hub while its crew is on the pinned one. Both look healthy. A plain non-git
+    // directory is NOT disqualified: plenty of real projects have no repo yet.
+    if (!gitRoot(dir) && countChildRepos(dir) >= 2) return "a folder of projects, not a project";
+  } catch {}
+  return "";
+}
+
+// Public writer for callers that own their own slice of config.json (lib/seats.mjs). Kept as a
+// named export rather than exposing the internal one, so the file stays the single writer.
+export function writeConfigPublic(cfg) { writeConfig(cfg); }
+
 function writeConfig(cfg) {
   mkdirSync(busDir(), { recursive: true });
   writeFileSync(configPath(), JSON.stringify(cfg, null, 2));

package/lib/seats.mjs

@@ -0,0 +1,155 @@
+// trantor — DECLARED SEATS: which project belongs in which directory, and whether it is running.
+//
+// A session's identity is positional (lib/project.mjs): a window IS whatever folder it stands in.
+// That is fine while nothing moves it. A macOS reboot moves all of them: reopened Terminal windows
+// come back in $HOME, `claude --resume` restores the conversation but not the directory, and every
+// seat quietly becomes a non-seat (2026-08-23 — two crebral windows spent an hour believing they
+// were still seats and finally reported the bus as down).
+//
+// 0.17.81 made that state LOUD. This makes it RECOVERABLE: the operator declares, once, that
+// "crebral-health" lives in ~/development/crebral-health, and afterwards a single command — or a
+// login agent — puts every missing seat back in its own directory. Nothing here guesses: a seat
+// exists because it was declared, and it is live because a real process is standing in its dir.
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readConfig, writeConfigPublic, resolveProject, resolveHubInfo } from "./project.mjs";
+
+// ── the registry ────────────────────────────────────────────────────────────────
+// config.json gains `seats: { <project>: { dir } }`. Same file as `hubs`, same shape of decision:
+// a deliberate operator statement, not an inference.
+export function readSeats() {
+  try {
+    const s = readConfig()?.seats;
+    if (!s || typeof s !== "object") return {};
+    const out = {};
+    for (const [p, v] of Object.entries(s)) {
+      const dir = typeof v === "string" ? v : v?.dir;
+      const agent = (typeof v === "object" && typeof v?.agent === "string" && v.agent) ? v.agent : "claude";
+      if (typeof dir === "string" && dir) out[p] = { dir, agent };
+    }
+    return out;
+  } catch { return {}; }
+}
+
+export function declareSeat(project, dir, agent = "claude") {
+  if (!project || typeof project !== "string") throw new Error("project required");
+  const abs = resolve(dir || process.cwd());
+  if (!existsSync(abs)) throw new Error(`directory does not exist: ${abs}`);
+  const cfg = readConfig();
+  cfg.seats = { ...(cfg.seats && typeof cfg.seats === "object" ? cfg.seats : {}), [project]: { dir: abs, agent } };
+  writeConfigPublic(cfg);
+  return { project, dir: abs, agent };
+}
+
+export function undeclareSeat(project) {
+  const cfg = readConfig();
+  if (!cfg.seats || typeof cfg.seats !== "object" || !(project in cfg.seats)) return false;
+  delete cfg.seats[project];
+  if (!Object.keys(cfg.seats).length) delete cfg.seats;
+  writeConfigPublic(cfg);
+  return true;
+}
+
+// ── liveness ────────────────────────────────────────────────────────────────────
+// A seat is live when a real agent process is STANDING IN ITS DIRECTORY. Deliberately local and
+// deliberately not the hub's presence list: the hub says a peer named "crebral-health" checked in,
+// which is exactly the claim that was false all along (a home-dir session can assert any name, and
+// a stale registration outlives the process). A cwd is not assertable.
+//
+// `ps` gives the candidate pids; lsof resolves each one's cwd. Both are bounded and fail-soft —
+// this runs in a CLI and, via `seats status`, in a login agent.
+export function liveAgentDirs(binaries = ["claude", "codex", "opencode"]) {
+  const out = [];   // [{ pid, comm, cwd }]
+  let rows = "";
+  try {
+    rows = execFileSync("/bin/ps", ["-axo", "pid=,comm="], { encoding: "utf8", timeout: 4000 });
+  } catch { return out; }
+  const self = String(process.pid);
+  for (const line of rows.split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(.*)$/);
+    if (!m) continue;
+    const [, pid, comm] = m;
+    if (pid === self) continue;
+    const base = comm.split("/").pop();
+    if (!binaries.includes(base)) continue;
+    let cwd = "";
+    try {
+      const fn = execFileSync("/usr/sbin/lsof", ["-a", "-p", pid, "-d", "cwd", "-Fn"],
+        { encoding: "utf8", timeout: 4000, stdio: ["ignore", "pipe", "ignore"] });
+      const hit = fn.split("\n").find(l => l.startsWith("n"));
+      if (hit) cwd = hit.slice(1);
+    } catch { /* process died, or lsof is unavailable — treat as unknown, never as live */ }
+    if (cwd) out.push({ pid: Number(pid), comm: base, cwd });
+  }
+  return out;
+}
+
+// Status of every declared seat: live (with the pid holding it) or missing (with why).
+// `live` is injectable so a drill can pin the mapping without spawning processes named "claude".
+export function seatStatus(live = liveAgentDirs()) {
+  const seats = readSeats();
+  return Object.entries(seats).map(([project, { dir, agent }]) => {
+    // The seat is held only by the agent it was DECLARED for. A crew seat (opencode, codex) working
+    // in the same repo is not the operator's Claude session, and counting it "live" would silently
+    // refuse to restore the very window that went missing — a false green in the one place this
+    // feature exists to prevent. Report the other occupant, never mistake it for the seat.
+    const inDir = live.filter(p => p.cwd === dir);
+    const holder = inDir.find(p => p.comm === agent);
+    const others = inDir.filter(p => p.comm !== agent);
+    const exists = existsSync(dir);
+    return {
+      project, dir, exists, agent,
+      live: !!holder,
+      pid: holder?.pid || null,
+      others,
+      hub: resolveHubInfo(project).url,
+      via: resolveHubInfo(project).via,
+      why: holder ? ""
+        : !exists ? "directory does not exist"
+        : others.length ? `no ${agent} here (${others.map(o => `${o.comm} ${o.pid}`).join(", ")} is, but that is not this seat)`
+        : `no ${agent} process in this directory`,
+    };
+  }).sort((a, b) => a.project.localeCompare(b.project));
+}
+
+// Seats that are declared, whose directory exists, and that nothing is standing in.
+export function missingSeats(live) { return seatStatus(live).filter(s => !s.live && s.exists); }
+
+// ── recovery ────────────────────────────────────────────────────────────────────
+// Open a NEW terminal window in the seat's directory running the agent. macOS-only by design (the
+// same osascript bin/open-session.sh has always used); elsewhere we print the command instead of
+// pretending. Returns { launched, command }.
+export function launchSeat(seat, { command, dryRun = false } = {}) {
+  const cmd = `cd ${JSON.stringify(seat.dir)} && ${command || seat.agent || "claude"}`;
+  if (dryRun || process.platform !== "darwin") return { launched: false, command: cmd };
+  const osa = `tell application "Terminal"\n  do script ${JSON.stringify(cmd)}\nend tell\n`;
+  try {
+    const kid = spawn("/usr/bin/osascript", ["-e", osa], { detached: true, stdio: "ignore" });
+    kid.unref();
+    return { launched: true, command: cmd };
+  } catch (e) {
+    return { launched: false, command: cmd, error: e?.message || String(e) };
+  }
+}
+
+// Seed the registry from what is already true: every pinned project whose name matches a directory
+// under a workspace root. Suggestion only — the caller confirms before anything is written, because
+// a guessed seat is exactly the kind of inference this file exists to replace.
+export function suggestSeats(workspace) {
+  const cfg = readConfig();
+  const pinned = cfg?.hubs && typeof cfg.hubs === "object" ? Object.keys(cfg.hubs) : [];
+  const declared = readSeats();
+  const out = [];
+  for (const project of pinned) {
+    if (declared[project]) continue;
+    const dir = resolve(workspace, project);
+    if (existsSync(dir)) out.push({ project, dir });
+  }
+  return out;
+}
+
+// The project a directory would register as — so `seats add` can warn when the declared name and
+// the directory's own identity disagree (they must match, or the seat comes up under a name the
+// operator did not declare and nothing routes to it).
+export function projectForDir(dir) { return resolveProject(dir); }

package/lib/store-contract.mjs

@@ -100,8 +100,14 @@ CREATE TABLE IF NOT EXISTS messages (
   project  TEXT,
   text     TEXT NOT NULL,
   refs     JSONB DEFAULT '[]'::jsonb,
+  re       BIGINT,                        -- the message id this one ANSWERS (a contract outcome).
+                                          -- Without it /contracts cannot close the right contract
+                                          -- after a restart and silently falls back to guessing
+                                          -- oldest-open-first.
   PRIMARY KEY (org_id, id)
 );
+-- additive migration for hubs whose messages table predates the reply link
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS re BIGINT;
 CREATE INDEX IF NOT EXISTS messages_org_to ON messages (org_id, to_session, id DESC);
 
 CREATE TABLE IF NOT EXISTS peers (

package/lib/store-pg.mjs

@@ -76,6 +76,9 @@ function msgFromRow(row) {
     project: row.project || "",
     text: row.text || "",
     refs: Array.isArray(row.refs) ? row.refs : [],
+    // absent rather than 0/null when there is no reply link, so `if (m.re)` reads the same as it
+    // does on a message the hub minted this session.
+    re: row.re == null ? undefined : Number(row.re),
   };
 }
 
@@ -268,9 +271,9 @@ export class PgStore {
     const refs = Array.isArray(msg.refs) ? msg.refs : [];
     const r = await this.pool.query(
       `WITH next_id AS (SELECT COALESCE(MAX(id),0)+1 AS id FROM messages WHERE org_id=$1)
-       INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs)
-       SELECT id, $1, $2, $3, $4, $5, $6, $7::jsonb FROM next_id RETURNING id`,
-      [orgId, ms(msg.ts), msg.from || msg.from_session || "anon", msg.to || msg.to_session || "all", msg.project || "", String(msg.text ?? ""), JSON.stringify(refs)],
+       INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs, re)
+       SELECT id, $1, $2, $3, $4, $5, $6, $7::jsonb, $8 FROM next_id RETURNING id`,
+      [orgId, ms(msg.ts), msg.from || msg.from_session || "anon", msg.to || msg.to_session || "all", msg.project || "", String(msg.text ?? ""), JSON.stringify(refs), Number(msg.re) > 0 ? Number(msg.re) : null],
     );
     return Number(r.rows[0].id);
   }
@@ -431,11 +434,11 @@ export class PgStore {
       await c.query("SELECT setval(pg_get_serial_sequence('events','id'), GREATEST((SELECT COALESCE(MAX(id),0) FROM events), 1), true)");
       for (const m of state.messages || []) {
         await c.query(
-          `INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs)
-           VALUES($1,$2,$3,$4,$5,$6,$7,$8::jsonb)
+          `INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs, re)
+           VALUES($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9)
            ON CONFLICT(org_id, id) DO UPDATE SET ts=EXCLUDED.ts, from_session=EXCLUDED.from_session, to_session=EXCLUDED.to_session,
-             project=EXCLUDED.project, text=EXCLUDED.text, refs=EXCLUDED.refs`,
-          [Number(m.id), orgId, ms(m.ts), m.from || "anon", m.to || "all", m.project || "", String(m.text ?? ""), JSON.stringify(Array.isArray(m.refs) ? m.refs : [])],
+             project=EXCLUDED.project, text=EXCLUDED.text, refs=EXCLUDED.refs, re=EXCLUDED.re`,
+          [Number(m.id), orgId, ms(m.ts), m.from || "anon", m.to || "all", m.project || "", String(m.text ?? ""), JSON.stringify(Array.isArray(m.refs) ? m.refs : []), Number(m.re) > 0 ? Number(m.re) : null],
         );
       }
       await c.query(
@@ -549,11 +552,11 @@ export class PgStore {
       if (events.upserts.length) await c.query("SELECT setval(pg_get_serial_sequence('events','id'), GREATEST((SELECT COALESCE(MAX(id),0) FROM events), 1), true)");
       for (const m of messages.upserts) {
         await c.query(
-          `INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs)
-           VALUES($1,$2,$3,$4,$5,$6,$7,$8::jsonb)
+          `INSERT INTO messages(id, org_id, ts, from_session, to_session, project, text, refs, re)
+           VALUES($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9)
            ON CONFLICT (org_id, id) DO UPDATE SET ts=EXCLUDED.ts, from_session=EXCLUDED.from_session, to_session=EXCLUDED.to_session,
-             project=EXCLUDED.project, text=EXCLUDED.text, refs=EXCLUDED.refs`,
-          [Number(m.id), orgId, ms(m.ts), m.from || "anon", m.to || "all", m.project || "", String(m.text ?? ""), JSON.stringify(Array.isArray(m.refs) ? m.refs : [])],
+             project=EXCLUDED.project, text=EXCLUDED.text, refs=EXCLUDED.refs, re=EXCLUDED.re`,
+          [Number(m.id), orgId, ms(m.ts), m.from || "anon", m.to || "all", m.project || "", String(m.text ?? ""), JSON.stringify(Array.isArray(m.refs) ? m.refs : []), Number(m.re) > 0 ? Number(m.re) : null],
         );
       }
       if (messages.deletes.length) await c.query("DELETE FROM messages WHERE org_id=$1 AND id = ANY($2::bigint[])", [orgId, messages.deletes]);