trantor 0.17.55 → 0.17.56

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "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, GLM, 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.55",
+      "version": "0.17.56",
       "author": {
         "name": "Sasha Bogojevic"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.55",
+  "version": "0.17.56",
   "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/bin/cli.mjs

@@ -68,6 +68,8 @@ switch (cmd) {
   case "handoff": run("bin/baton.mjs"); break;
   case "adopt": run("bin/adopt.mjs"); break;
   case "summarize": run("bin/summarize.mjs"); break;
+  case "policy": run("bin/policy.mjs"); break;
+  case "inbox": run("bin/inbox.mjs"); break;
   case "identity": {
     const { load, publicView, generate, keyPath } = await import(join(ROOT, "lib/identity.mjs"));
     const sub = args[0], name = args[1] || "human";
@@ -162,6 +164,8 @@ switch (cmd) {
   trantor hub         run the hub in the foreground (setup installs it as a service instead)
                       …or manage per-project hub pins: hub list · hub set <project> <url> · hub unset <project>
   trantor watch       live bus feed in the terminal
+  trantor inbox       THIS session's unread bus messages, signed (works under enforce) — [--all] [--consume] [--json]
+  trantor policy      the autonomy ladder: show | set <project> <1-4> | link <a> <b> --reason "<why>"
 
 Claude Code plugin (the orchestrator side):
   claude plugin marketplace add sashabogi/trantor && claude plugin install trantor

package/bin/inbox.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// trantor inbox — read THIS session's bus messages from the terminal, signed.
+//
+//   trantor inbox              peek at unread (does NOT consume — hooks still deliver them)
+//   trantor inbox --all        the full history for this session (peek)
+//   trantor inbox --consume    read AND advance the delivery cursor (marks them delivered)
+//   trantor inbox --json       raw JSON out
+//   trantor inbox --limit N    show at most N messages (default 30)
+//
+// Born from the 2026-07-30 agent-UX gap: a session asked to "check your messages" had NO way to —
+// the MCP tools 401'd on the enforce hub and there was no CLI. Reads here are SIGNED with the same
+// session keypair the hooks and MCP server use, so they work under RELAY_AUTH=enforce; the hub's
+// scope filtering (own project + direct messages) is the intended behavior, not a limitation.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveProject, hostId, resolveHub } from "../lib/project.mjs";
+import { loadOrCreate } from "../lib/identity.mjs";
+import { sfetchJson } from "../lib/signed-fetch.mjs";
+
+const argv = process.argv.slice(2);
+const has = (k) => argv.includes(`--${k}`);
+const val = (k) => { const i = argv.indexOf(`--${k}`); return i >= 0 ? (argv[i + 1] ?? "") : ""; };
+
+const project = resolveProject(process.cwd());
+const session = process.env.RELAY_SESSION
+  || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
+const hub = resolveHub(project);
+const identity = loadOrCreate(session, "agent");
+
+// Default `since` = the SAME cursor file the delivery hooks keep, so "trantor inbox" means
+// "what have my hooks not handed me yet" — not a 2,000-message historical replay.
+const safe = session.replace(/[^A-Za-z0-9_.-]/g, "_");
+const cursorFile = join(process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus"), `inbox-cursor-${safe}.id`);
+let since = 0;
+if (!has("all")) { try { since = Number(readFileSync(cursorFile, "utf8")) || 0; } catch {} }
+
+const peek = !has("consume");
+const url = `${hub}/inbox?session=${encodeURIComponent(session)}&since=${since}${peek ? "&peek=1" : ""}`;
+let r;
+try { r = await sfetchJson(url, { method: "GET", identity, signal: AbortSignal.timeout(8000) }); }
+catch (e) { console.error(`hub unreachable at ${hub}: ${e.message}`); process.exit(1); }
+if (!r.ok) {
+  console.error(`hub ${r.status} on /inbox — ${r.status === 401 ? "this identity isn't enrolled on the hub (RELAY_ENROLL=invite?)" : "read failed"}`);
+  process.exit(1);
+}
+const { messages = [], cursor = since } = await r.json();
+
+if (has("json")) { console.log(JSON.stringify({ session, hub, cursor, messages }, null, 2)); }
+else {
+  const limit = Math.max(1, Number(val("limit")) || 30);
+  const show = messages.slice(-limit);
+  console.log(`${session} @ ${hub} — ${messages.length} message(s)${messages.length > show.length ? `, showing last ${show.length}` : ""}${peek ? " (peek)" : ""}`);
+  for (const m of show) {
+    const when = new Date(m.ts).toLocaleString();
+    console.log(`\n#${m.id} ${when}  ${m.from} -> ${m.to}`);
+    console.log(`  ${String(m.text || "").split("\n").join("\n  ")}`);
+  }
+  if (!messages.length) console.log("(inbox empty — you're caught up)");
+}
+
+// --consume: the hub's shared delivery ledger already advanced (non-peek read); mirror it into the
+// local cursor file so the delivery hooks agree these are handled and don't re-inject them.
+if (!peek && cursor > since) { try { writeFileSync(cursorFile, String(cursor)); } catch {} }

package/bin/overseer-narrate.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// trantor overseer-narrate — narrate overseer.warn events with plain-language action text.
+//
+//   trantor overseer-narrate [--limit N] [--dry] [--quiet]
+//
+// The overseer tick emits overseer.warn events as mechanical, computed facts (kind, sessions, files,
+// detail). This worker gives each un-narrated warning a one-line action text ("coordinate over the
+// bus / split files / declare a link") written by a CHEAP model, then POSTs it back to the hub.
+// Economics by design: candidates are unnarrated overseer.warn events, batched into ONE cheap-model
+// call per hub, difficulty easy. Runs ambiently from the heartbeat and on demand.
+import { execSync, spawnSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { loadOrCreate } from "../lib/identity.mjs";
+import { sfetchJson } from "../lib/signed-fetch.mjs";
+
+const argv = process.argv.slice(2);
+const val = (k) => { const i = argv.indexOf(`--${k}`); return i >= 0 ? (argv[i + 1] ?? "") : ""; };
+const has = (k) => argv.includes(`--${k}`);
+const QUIET = has("quiet");
+const say = (...a) => { if (!QUIET) console.log(...a); };
+
+const BUS_DIR = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
+let config = {}; try { config = JSON.parse(readFileSync(join(BUS_DIR, "config.json"), "utf8")); } catch {}
+const LIMIT = Math.max(1, Number(val("limit")) || 100);
+const OWNER = config.ownerIdentity || "admin";
+const ownerId = loadOrCreate(OWNER, "human");
+
+const scroogeBin = () => process.env.SCROOGE_BIN
+  || (() => { try { return execSync("command -v scrooge", { encoding: "utf8" }).trim(); } catch {} })()
+  || (existsSync(new URL("../engine/bin/scrooge", import.meta.url)) ? new URL("../engine/bin/scrooge", import.meta.url).pathname : "");
+
+const hubs = new Set([config.url || "http://127.0.0.1:4477", ...Object.values(config.hubs || {})]);
+const get = async (hub, path) => (await sfetchJson(`${hub}${path}`, { method: "GET", identity: ownerId, signal: AbortSignal.timeout(8000) })).json();
+
+let narrated = 0, considered = 0;
+for (const hub of hubs) {
+  let events = [];
+  try { events = (await get(hub, `/events?type=overseer.&limit=${LIMIT}`)).events ?? []; }
+  catch { continue; }
+  const unnarrated = events.filter(e => !e.narrated && e.detail);
+  considered += unnarrated.length;
+  if (!unnarrated.length) continue;
+  say(`${hub}: ${unnarrated.length} overseer warning(s) need narration`);
+
+  const blocks = unnarrated.map(e =>
+    `EVENT #${e.id} [${e.project}]\nKIND: ${e.kind}\nSESSIONS: ${(e.sessions || []).join(", ")}\nFILES: ${(e.files || []).join(", ")}\nDETAIL: ${e.detail}`
+  );
+
+  const prompt = `You write one-line action narratives for AI-agent collision warnings. For EACH event below, write what the sessions should do — coordinate over the bus, split files, declare a link. <=200 chars. Cite sessions/files/projects from the detail. Return ONLY a JSON array: [{"eventId":<number>,"text":"..."}]
+
+${blocks.join("\n\n")}`;
+
+  const bin = scroogeBin();
+  if (!bin) { console.error("scrooge not found (set SCROOGE_BIN) — cannot narrate."); process.exit(1); }
+  const res = spawnSync(bin, ["-t", "reason", "-d", "easy", "--json"], { input: prompt, encoding: "utf8", timeout: 120000 });
+  if (res.error || (res.status !== 0 && !res.stdout)) { console.error(`scrooge failed: ${(res.stderr || res.error?.message || "").slice(-200)}`); continue; }
+  let rows = [];
+  try { const out = res.stdout || ""; rows = JSON.parse(out.slice(out.indexOf("["), out.lastIndexOf("]") + 1)); }
+  catch { console.error(`unparseable narrator output: ${(res.stdout || "").slice(0, 200)}`); continue; }
+
+  const byId = new Map(unnarrated.map(e => [e.id, e]));
+  for (const r of rows) {
+    const e = byId.get(Number(r.eventId));
+    const text = String(r.text || "").trim().slice(0, 200);
+    if (!e || !text) continue;
+    if (has("dry")) { say(`  event #${e.id} would become: ${text}`); continue; }
+    try {
+      const res = await sfetchJson(`${hub}/overseer/narrate`, { identity: ownerId, payload: { eventId: e.id, text }, signal: AbortSignal.timeout(8000) });
+      if (!res.ok) { say(`  event #${e.id} POST failed: ${res.status}`); continue; }
+      narrated++;
+      say(`  event #${e.id} → ${text}`);
+    } catch (e2) { say(`  event #${e.id} write failed: ${e2.message}`); }
+  }
+}
+say(`\n${has("dry") ? "[dry] " : ""}${narrated} narration(s) written · ${considered} event(s) considered`);

package/bin/policy.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// trantor policy — the autonomy ladder's admin surface (PRD §6): show levels + links,
+// set a project's level, declare that two projects are codependent.
+//   trantor policy show | set <project> <1-4> | link <a> <b> --reason "<why>"
+// Drafted by scrooge (deepseek-v4-flash), integrated by the orchestrator.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { loadOrCreate } from "../lib/identity.mjs";
+import { sfetchJson } from "../lib/signed-fetch.mjs";
+
+const BUS_DIR = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
+let config;
+try { config = JSON.parse(readFileSync(join(BUS_DIR, "config.json"), "utf8")); } catch { config = {}; }
+
+const OWNER = config.ownerIdentity || "admin";
+const ownerId = loadOrCreate(OWNER, "human");
+const hubs = new Set([config.url || "http://127.0.0.1:4477", ...Object.values(config.hubs || {})]);
+
+const get = async (hub) => {
+  const res = await sfetchJson(`${hub}/policy`, { method: "GET", identity: ownerId, signal: AbortSignal.timeout(8000) });
+  return res.json();
+};
+const post = async (hub, payload) => {
+  const res = await sfetchJson(`${hub}/policy`, { method: "POST", identity: ownerId, payload, signal: AbortSignal.timeout(8000) });
+  const json = await res.json();
+  if (!res.ok || json.error) throw new Error(json.error || `HTTP ${res.status}`);
+  return json;
+};
+
+const legend = { 1: "1 observe", 2: "2 warn", 3: "3 gate", 4: "4 auto" };
+function usage() {
+  console.log('usage: trantor policy show | set <project> <1-4> | link <a> <b> --reason "<why>"');
+  process.exit(1);
+}
+
+const [,, cmd, arg1, arg2] = process.argv;
+
+if (cmd === "show" || !cmd) {
+  for (const hub of hubs) {
+    try {
+      const data = await get(hub);
+      console.log(hub);
+      console.log("  autonomy:");
+      for (const [proj, level] of Object.entries(data.autonomy || {})) console.log(`    ${proj}: ${legend[level] || level}`);
+      console.log("  links:");
+      for (const l of data.links || []) console.log(`    ${l.projects.join(" ↔ ")} — ${l.reason} (by ${l.declaredBy})`);
+      if (!(data.links || []).length) console.log("    (none)");
+    } catch (err) { console.warn(`  ⚠ ${hub}: ${err.message}`); }
+  }
+  process.exit(0);
+}
+
+if (cmd === "set") {
+  if (!arg1 || !["1", "2", "3", "4"].includes(arg2)) usage();
+  for (const hub of hubs) {
+    try { await post(hub, { autonomy: { [arg1]: Number(arg2) } }); console.log(`✓ ${arg1} → ${legend[Number(arg2)]} on ${hub}`); }
+    catch (err) { console.warn(`⚠ ${hub}: ${err.message}`); }
+  }
+  process.exit(0);
+}
+
+if (cmd === "link") {
+  const reasonIdx = process.argv.indexOf("--reason");
+  const reason = reasonIdx >= 0 ? process.argv[reasonIdx + 1] : null;
+  if (!arg1 || !arg2 || !reason) usage();
+  for (const hub of hubs) {
+    try { await post(hub, { link: { projects: [arg1, arg2], reason } }); console.log(`✓ ${arg1} ↔ ${arg2} on ${hub}`); }
+    catch (err) { console.warn(`⚠ ${hub}: ${err.message}`); }
+  }
+  process.exit(0);
+}
+
+usage();

package/bin/summarize.mjs

@@ -45,7 +45,12 @@ const machineTitled = (t) =>
 
 const hubs = new Set([config.url || "http://127.0.0.1:4477", ...Object.values(config.hubs || {})]);
 const get = async (hub, path) => (await sfetchJson(`${hub}${path}`, { method: "GET", identity: ownerId, signal: AbortSignal.timeout(8000) })).json();
-const post = async (hub, path, payload) => (await sfetchJson(`${hub}${path}`, { identity: ownerId, payload, signal: AbortSignal.timeout(8000) })).json();
+const post = async (hub, path, payload) => {
+  const r = await sfetchJson(`${hub}${path}`, { identity: ownerId, payload, signal: AbortSignal.timeout(8000) });
+  const j = await r.json();
+  if (!r.ok || j?.error) throw new Error(`${path} → ${r.status} ${j?.error || ""}`);
+  return j;
+};
 
 let wrote = 0, considered = 0;
 for (const hub of hubs) {

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "trantor — auto-register each session + inject live roster (SessionStart); turn each substantive user prompt into the session's live 'focus' card so a regular session's own work shows IN PROGRESS (UserPromptSubmit); post an in-flight 'doing' card when a sub-agent is dispatched + claim each file edit on the bus and hand the model a warning when ANOTHER live session is touching the same file (PreToolUse) and enrich it with the native agent_id + parent session when the sub-agent spawns (SubagentStart); heartbeat presence on every tool call + deliver unread bus messages to a busy session mid-turn + mirror the session's TodoWrite list onto the board as cards (PostToolUse); write a handoff before compaction (PreCompact); surface CC's own background/child agents (fork/--agent/subtask) on the board when they need input or complete (Notification); card each sub-agent's notional API cost when it finishes (SubagentStop); refuse to go idle while a peer's DIRECT message sits unread, handing it to the model instead (Stop)",
+  "description": "trantor — auto-register each session + inject live roster + overseer landscape warning: linked projects, live peers, files in flight, collisions (SessionStart); turn each substantive user prompt into the session's live 'focus' card so a regular session's own work shows IN PROGRESS (UserPromptSubmit); post an in-flight 'doing' card when a sub-agent is dispatched + claim each file edit on the bus and hand the model a warning when ANOTHER live session is touching the same file (PreToolUse) and enrich it with the native agent_id + parent session when the sub-agent spawns (SubagentStart); heartbeat presence on every tool call + deliver unread bus messages to a busy session mid-turn + mirror the session's TodoWrite list onto the board as cards (PostToolUse); write a handoff before compaction (PreCompact); surface CC's own background/child agents (fork/--agent/subtask) on the board when they need input or complete (Notification); card each sub-agent's notional API cost when it finishes (SubagentStop); refuse to go idle while a peer's DIRECT message sits unread, handing it to the model instead (Stop)",
   "hooks": {
     "SessionStart": [
       {
@@ -8,6 +8,10 @@
           {
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart.mjs"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/overseer-warn.mjs"
           }
         ]
       }

package/hooks/lib/api.mjs

@@ -119,6 +119,28 @@ export async function getJSON(pathOrUrl, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}
   } catch { return { ok: false, status: 0, json: null }; }
 }
 
+// Signed GET → { ok, status, json|null }. Never throws. The "one-liner" the getJSON comment
+// promised: for reads that MUST work under RELAY_AUTH=enforce (which 401s unsigned reads).
+// First user: the overseer-warn hook's /overseer/context — a project-scoped read, so the
+// enforce hub's own-project scope filtering is the correct behavior, not a loss. Roster-style
+// reads (/peers, /catchup cross-project discovery) stay on getJSON on purpose — see above.
+export async function signedGet(pathOrUrl, { timeoutMs = DEFAULT_TIMEOUT_MS, session } = {}) {
+  const sess = session || sessionContext().session;
+  const id = loadIdentity(sess);
+  await ensureEnrolled(sess, id);
+  try {
+    const r = await sfetchJson(toUrl(pathOrUrl), {
+      method: "GET",
+      identity: id,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!r.ok) return { ok: false, status: r.status, json: null };
+    const text = await r.text();
+    let json = null; try { json = text ? JSON.parse(text) : null; } catch {}
+    return { ok: true, status: r.status, json };
+  } catch { return { ok: false, status: 0, json: null }; }
+}
+
 // Signed POST → { ok, status, json|null }. Never throws.
 export async function signedPost(pathOrUrl, payload, { timeoutMs = DEFAULT_TIMEOUT_MS, session } = {}) {
   const sess = session || sessionContext().session;

package/hooks/overseer-warn.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// trantor SessionStart overseer-warn — a session hears about collisions through its OWN harness.
+//
+// THE doctrine (docs/OVERSEER-CONTRACT.md): detection is MECHANICAL and lives in the hub
+// (GET /overseer/context computes level/links/peers/inflight/warnings); this hook only NARRATES
+// what the hub already knows, at the one moment narration is cheap and useful — session start.
+// A session never reaches into another session's process; context arrives via its own hook.
+//
+// Deliberately INFORMATIONAL below level 3, and never blocking at any level: the hook emits
+// additionalContext or nothing. Warn mode annotates, it does not gate (see hub: "warn mode
+// NEVER blocks").
+//
+// Fail-open is a contract, not a convenience: a hook that throws or hangs breaks the user's
+// session. Hub down, timeout (1500ms), malformed payload, missing project — all resolve to {}.
+// signedGet, not getJSON: RELAY_AUTH=enforce hubs 401 unsigned reads, and this hook fails open —
+// an unsigned read here means the overseer warning silently NEVER reaches a session in production.
+// /overseer/context is project-scoped, so enforce's own-project read filtering is correct for it.
+import { relayUrl, sessionContext, signedGet } from "./lib/api.mjs";
+
+const silent = () => { process.stdout.write("{}"); process.exit(0); };
+
+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), 400);
+  });
+}
+
+const ago = s => (s < 60 ? `${s}s` : s < 3600 ? `${Math.round(s / 60)}m` : `${Math.round(s / 3600)}h`);
+
+try {
+  const raw = await readStdin();
+  const input = JSON.parse(raw || "{}");
+  const ctx = sessionContext(input.cwd);
+  if (!ctx.project) silent();
+
+  const r = await signedGet(`${relayUrl(ctx.project)}/overseer/context?project=${encodeURIComponent(ctx.project)}`, { session: ctx.session });
+  if (!r.ok || !r.json || typeof r.json !== "object") silent();
+  const c = r.json;
+
+  const level = Number(c.level || 1);
+  const warnings = Array.isArray(c.warnings) ? c.warnings : [];
+  const inflight = Array.isArray(c.inflight) ? c.inflight : [];
+  const links = Array.isArray(c.links) ? c.links : [];
+  const peers = Array.isArray(c.peers) ? c.peers : [];
+
+  // level<2 is observe: the hub still logs, but sessions are not narrated at. And at any level,
+  // nothing to say -> silence (an empty warning is noise that trains sessions to ignore real ones).
+  if (level < 2 || (!warnings.length && !inflight.length && !links.length)) silent();
+
+  const parts = [];
+  if (links.length) {
+    parts.push("Linked projects (declared codependence): " +
+      links.map(l => `${(l.projects || []).join(" + ")} — ${l.reason || "linked"}`).join("; ") + ".");
+  }
+  if (peers.length) {
+    parts.push("Live sessions on this/linked projects: " +
+      peers.map(p => `${p.session}${p.llm ? ` (${[p.llm, p.model].filter(Boolean).join("·")})` : ""}${p.status ? `, ${p.status}` : ""}`).join(", ") + ".");
+  }
+  if (inflight.length) {
+    parts.push("Files in flight right now: " +
+      inflight.map(f => `${f.file} — ${f.session} (${ago(Number(f.agoSec) || 0)} ago)`).join(", ") + ".");
+  }
+  if (warnings.length) {
+    parts.push("Overseer warnings: " +
+      warnings.map(w => w.detail || w.kind).filter(Boolean).join("; ") + ".");
+  }
+  parts.push("Before editing a file another session has in flight, coordinate over the bus (relay_send) or split the work.");
+
+  let text = parts.join(" ");
+  if (text.length > 900) text = text.slice(0, 897) + "…";
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: `⚠️ trantor overseer: ${text}`,
+    },
+  }));
+  process.exit(0);
+} catch {
+  silent();
+}

package/hub.mjs

@@ -203,6 +203,59 @@ async function reloadFromStore() {
     if (reloadAgain) { reloadAgain = false; scheduleStoreReload(); }
   }
 }
+// --- the OVERSEER (levels 1-2 + the level-3 gate) -------------------------------------------
+// Detection is MECHANICAL (lib/overseer.mjs, pure); the LLM only narrates (bin/overseer-narrate).
+// Lazy import: the engine module lands from a crew seat in parallel — the hub runs without it and
+// picks it up on next restart. Warnings dedup on a 10-minute window so a standing collision does
+// not spam the feed; at level >= 3 a file-conflict opens a verify gate (the go/no-go primitive).
+let _overseer = null;
+import("./lib/overseer.mjs").then(m => { _overseer = m; }).catch(() => {});
+const OVERSEER_TICK_MS = Number(process.env.RELAY_OVERSEER_TICK_MS || 30 * 1000);
+const OVERSEER_DEDUP_MS = Number(process.env.RELAY_OVERSEER_DEDUP_MS || 10 * 60 * 1000);
+const overseerWarned = new Map();   // dedup key -> ts
+function overseerPolicy() {
+  const p = state.orgPolicy && typeof state.orgPolicy === "object" ? state.orgPolicy : {};
+  return {
+    autonomy: { "*": 1, ...(p.autonomy || {}) },
+    links: Array.isArray(p.links) ? p.links : [],
+  };
+}
+function overseerInputs() {
+  return {
+    peers: Object.entries(state.peers).map(([session, v]) => ({
+      session, project: v.project || "", lastSeen: v.lastSeen || 0,
+      llm: v.llm || "", model: v.model || "", status: v.status || "",
+    })),
+    claims: [...fileClaims.values()],
+    ...overseerPolicy(),
+    now: now(),
+  };
+}
+function overseerTick() {
+  if (!_overseer?.detectCollisions) return;
+  let collisions = [];
+  try { collisions = _overseer.detectCollisions(overseerInputs()) || []; } catch { return; }
+  const cut = now() - OVERSEER_DEDUP_MS;
+  for (const [k, ts] of overseerWarned) if (ts < cut) overseerWarned.delete(k);
+  const pol = overseerPolicy();
+  for (const c of collisions) {
+    const key = `${c.project} ${c.kind} ${(c.sessions || []).join(",")} ${(c.files || []).join(",")}`;
+    if (overseerWarned.has(key)) continue;
+    overseerWarned.set(key, now());
+    appendEvent("overseer.warn", c.project, "overseer",
+      { kind: c.kind, sessions: c.sessions || [], files: c.files || [], detail: c.detail || "", narrated: false });
+    const level = _overseer.levelFor ? _overseer.levelFor(c.project, pol.autonomy) : 1;
+    if (level >= 3 && c.kind === "file-conflict") {
+      const g = { id: ++state.verifyGateSeq, project: c.project, status: "open", ts: now(),
+        by: "overseer", claim: `file conflict: ${(c.files || []).join(", ")} — ${(c.sessions || []).join(" vs ")}`,
+        why: c.detail || "two live sessions on the same file", howToVerify: "decide who proceeds; coordinate over the bus" };
+      state.verifyGates.push(g); dirty = true;
+      appendEvent("verify.gate.opened", c.project, "overseer", { gateId: g.id, claim: g.claim, why: g.why });
+    }
+  }
+}
+setInterval(overseerTick, OVERSEER_TICK_MS).unref?.();
+
 if (durableStore?.subscribeChanges) {
   durableStore.subscribeChanges((p) => {
     if (p && p.src === HUB_SRC) return;
@@ -404,8 +457,8 @@ function cmpSemver(a, b) {
 }
 const AUTH_HEADERS = ["x-trantor-pubkey", "x-trantor-sig", "x-trantor-ts", "x-trantor-nonce"];
 const PUBLIC_ENDPOINTS = new Set(["/", "/ui", "/health", "/enroll"]);
-const OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import"]);
-const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims"]);
+const OWNER_ENDPOINTS = new Set(["/project/delete", "/sweep", "/reconcile", "/invite", "/import", "/policy"]);
+const READ_ENDPOINTS = new Set(["/peers", "/tasks", "/events", "/inbox", "/peer", "/card", "/stream", "/history", "/projects", "/catchup", "/phases", "/recent", "/handoffs", "/verify-gates", "/claims", "/overseer/context"]);
 const roleRank = { read: 1, write: 2, owner: 3 };
 const hasAuthHeaders = (req) => AUTH_HEADERS.some(h => !!req.headers[h]);
 const authPath = (u) => `${u.pathname}${u.search || ""}`;
@@ -463,15 +516,24 @@ async function authenticate(req, path) {
     return { ok: false, code: 401, error: "signature required" };
   }
   const raw = req.method === "GET" || req.method === "HEAD" ? undefined : await rawBody(req);
+  // WARN MODE NEVER BLOCKS — it annotates. That is its entire contract: an observation period
+  // where the hub records what WOULD fail under enforce. The restarted local hub proved the
+  // failure mode: signed requests from a not-yet-enrolled identity got 401 "unknown identity"
+  // while UNSIGNED requests passed — punishing exactly the clients that already do the right
+  // thing. Under warn: bad signature, replay and unknown identity all pass with a warning;
+  // under enforce they are the hard failures they should be.
+  const soft = (warning) => AUTH_MODE === "warn"
+    ? { ok: true, mode: AUTH_MODE, trusted: false, warning }
+    : { ok: false, code: 401, error: warning };
   const verified = verifyRequest({ headers: req.headers, method: req.method, path, body: raw });
-  if (!verified.ok) return { ok: false, code: 401, error: verified.reason || "bad signature" };
+  if (!verified.ok) return soft(verified.reason || "bad signature");
   const nonceKey = `${verified.pubkey}:${verified.nonce}`;
   for (const [k, ts] of seenNonces) if (Math.abs(now() - ts) > 120000) seenNonces.delete(k);
-  if (seenNonces.has(nonceKey)) return { ok: false, code: 401, error: "replay" };
+  if (seenNonces.has(nonceKey)) return soft("replay");
   seenNonces.set(nonceKey, verified.ts);
   if (seenNonces.size > 10000) seenNonces.delete(seenNonces.keys().next().value);
   const identity = findIdentity(verified.pubkey);
-  if (!identity) return { ok: false, code: 401, error: "unknown identity" };
+  if (!identity) return soft("unknown identity");
   return { ok: true, mode: AUTH_MODE, trusted: true, pubkey: verified.pubkey, identity };
 }
 function authorize(auth, method, P, project) {
@@ -863,6 +925,60 @@ const server = http.createServer(async (req, res) => {
       appendEvent("project.adopted", proj, String(b.by || ""), { counts: added });
       return json(res, 200, { ok: true, ...added });
     }
+    if (req.method === "GET" && P === "/policy") {
+      return json(res, 200, overseerPolicy());
+    }
+    if (req.method === "POST" && P === "/policy") {
+      const b = await body(req);
+      const p = state.orgPolicy && typeof state.orgPolicy === "object" ? state.orgPolicy : {};
+      p.autonomy = { ...(p.autonomy || {}) };
+      p.links = Array.isArray(p.links) ? p.links : [];
+      if (b.autonomy && typeof b.autonomy === "object") {
+        for (const [proj, lvl] of Object.entries(b.autonomy)) {
+          const n = Number(lvl);
+          if ([1, 2, 3, 4].includes(n)) p.autonomy[canon(String(proj).slice(0, 80))] = n;
+        }
+      }
+      if (b.link && Array.isArray(b.link.projects) && b.link.projects.length >= 2 && b.link.reason) {
+        const projects = b.link.projects.slice(0, 4).map(x => canon(String(x).slice(0, 80))).sort();
+        const key = projects.join(" ");
+        if (!p.links.some(l => (l.projects || []).slice().sort().join(" ") === key)) {
+          p.links.push({ projects, reason: String(b.link.reason).slice(0, 140),
+            declaredBy: auth?.identity?.name || String(b.by || ""), ts: now() });
+        }
+      }
+      state.orgPolicy = p; dirty = true;
+      return json(res, 200, { ok: true, ...overseerPolicy() });
+    }
+    // What a session arriving on <project> needs to know: its autonomy level, who else is live,
+    // which files are in flight, which projects are declared codependent, current collisions.
+    if (req.method === "GET" && P === "/overseer/context") {
+      const proj = canon(String(q.project || "").slice(0, 80));
+      if (!proj) return json(res, 400, { error: "project required" });
+      const pol = overseerPolicy();
+      const level = _overseer?.levelFor ? _overseer.levelFor(proj, pol.autonomy) : (pol.autonomy[proj] ?? pol.autonomy["*"] ?? 1);
+      const links = pol.links.filter(l => (l.projects || []).includes(proj));
+      const linked = new Set(links.flatMap(l => l.projects).filter(x => x !== proj));
+      const cutoff = now() - ONLINE_MS;
+      const peersOut = Object.entries(state.peers)
+        .filter(([, v]) => v.lastSeen > cutoff && (v.project === proj || linked.has(v.project)))
+        .map(([session, v]) => ({ session, project: v.project || "", llm: v.llm || "", model: v.model || "", status: v.status || "" }));
+      pruneClaims();
+      const inflight = [...fileClaims.values()].filter(c => c.project === proj)
+        .map(c => ({ file: c.file, session: c.session, agoSec: Math.round((now() - c.ts) / 1000) }));
+      let warnings = [];
+      try { warnings = (_overseer?.detectCollisions ? _overseer.detectCollisions(overseerInputs()) : [])
+        .filter(c => c.project === proj || linked.has(c.project)); } catch {}
+      return json(res, 200, { level, links: links.map(l => ({ projects: l.projects, reason: l.reason })), peers: peersOut, inflight, warnings });
+    }
+    if (req.method === "POST" && P === "/overseer/narrate") {
+      const b = await body(req);
+      const ev = state.events.find(e => e.id === Number(b.eventId) && e.type === "overseer.warn");
+      if (!ev) return json(res, 404, { error: "no such overseer.warn event" });
+      ev.narrated = true; ev.narration = String(b.text || "").slice(0, 300);
+      dirty = true;
+      return json(res, 200, { ok: true });
+    }
     if (req.method === "POST" && P === "/claim") {
       const b = await body(req);
       const proj = canon(String(b.project || "").slice(0, 80));

package/lib/overseer.mjs

@@ -0,0 +1,140 @@
+const PEER_LIVE_MS = 5 * 60 * 1000;
+const CLAIM_LIVE_MS = 10 * 60 * 1000;
+
+const KINDS = new Set(["same-project-sessions", "file-conflict", "linked-activity"]);
+
+const asArray = (v) => Array.isArray(v) ? v : [];
+const clean = (v) => String(v ?? "").trim();
+const finiteNumber = (v) => Number.isFinite(Number(v)) ? Number(v) : null;
+
+function isLevel(v) {
+  return v === 1 || v === 2 || v === 3 || v === 4;
+}
+
+export function levelFor(project, autonomy = {}) {
+  const key = clean(project);
+  const direct = autonomy?.[key];
+  if (isLevel(direct)) return direct;
+  const fallback = autonomy?.["*"];
+  return isLevel(fallback) ? fallback : 1;
+}
+
+function isFresh(ts, now, ttl) {
+  const n = finiteNumber(ts);
+  return n != null && now - n <= ttl;
+}
+
+function sortedStrings(items) {
+  return [...new Set(Array.from(items ?? []).map(clean).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function pushCollision(out, collision) {
+  if (!collision.project || !KINDS.has(collision.kind) || collision.sessions.length === 0) return;
+  out.push({
+    project: collision.project,
+    kind: collision.kind,
+    sessions: sortedStrings(collision.sessions),
+    files: sortedStrings(collision.files ?? []),
+    detail: collision.detail,
+  });
+}
+
+function collisionKey(c) {
+  return [
+    c.project,
+    c.kind,
+    c.files[0] ?? "",
+    c.sessions[0] ?? "",
+    c.detail,
+  ].join("\u0000");
+}
+
+function sortCollisions(collisions) {
+  return [...collisions].sort((a, b) =>
+    a.project.localeCompare(b.project) ||
+    a.kind.localeCompare(b.kind) ||
+    (a.files[0] ?? "").localeCompare(b.files[0] ?? "") ||
+    (a.sessions[0] ?? "").localeCompare(b.sessions[0] ?? "") ||
+    a.detail.localeCompare(b.detail)
+  );
+}
+
+export function detectCollisions({ peers = [], claims = [], links = [], autonomy = {}, now } = {}) {
+  const at = finiteNumber(now) ?? 0;
+  const out = [];
+
+  const livePeers = [];
+  const seenPeers = new Set();
+  for (const peer of asArray(peers)) {
+    const session = clean(peer?.session);
+    const project = clean(peer?.project);
+    if (!session || !project || !isFresh(peer?.lastSeen, at, PEER_LIVE_MS)) continue;
+    const key = `${project}\u0000${session}`;
+    if (seenPeers.has(key)) continue;
+    seenPeers.add(key);
+    livePeers.push({ ...peer, session, project });
+  }
+
+  const sessionsByProject = new Map();
+  for (const peer of livePeers) {
+    const sessions = sessionsByProject.get(peer.project) ?? [];
+    sessions.push(peer.session);
+    sessionsByProject.set(peer.project, sessions);
+  }
+
+  for (const project of sortedStrings(sessionsByProject.keys())) {
+    const sessions = sortedStrings(sessionsByProject.get(project));
+    if (sessions.length < 2) continue;
+    pushCollision(out, {
+      project,
+      kind: "same-project-sessions",
+      sessions,
+      files: [],
+      detail: `${sessions.join(", ")} are live on project ${project}.`,
+    });
+  }
+
+  const claimSessionsByFile = new Map();
+  for (const claim of asArray(claims)) {
+    const project = clean(claim?.project);
+    const file = clean(claim?.file);
+    const session = clean(claim?.session);
+    if (!project || !file || !session || !isFresh(claim?.ts, at, CLAIM_LIVE_MS)) continue;
+    const key = `${project}\u0000${file}`;
+    const sessions = claimSessionsByFile.get(key) ?? new Set();
+    sessions.add(session);
+    claimSessionsByFile.set(key, sessions);
+  }
+
+  for (const key of [...claimSessionsByFile.keys()].sort()) {
+    const [project, file] = key.split("\u0000");
+    const sessions = sortedStrings(claimSessionsByFile.get(key));
+    if (sessions.length < 2) continue;
+    pushCollision(out, {
+      project,
+      kind: "file-conflict",
+      sessions,
+      files: [file],
+      detail: `${sessions.join(", ")} have live claims on ${project}/${file}.`,
+    });
+  }
+
+  for (const link of asArray(links)) {
+    const projects = sortedStrings(link?.projects ?? []);
+    if (projects.length < 2) continue;
+    const activeProjects = projects.filter((project) => (sessionsByProject.get(project) ?? []).length > 0);
+    if (activeProjects.length < 2) continue;
+    const sessions = sortedStrings(activeProjects.flatMap((project) => sessionsByProject.get(project) ?? []));
+    pushCollision(out, {
+      project: activeProjects[0],
+      kind: "linked-activity",
+      sessions,
+      files: [],
+      detail: `Linked projects ${activeProjects.join(", ")} have live sessions ${sessions.join(", ")}.`,
+    });
+  }
+
+  const deduped = new Map();
+  for (const collision of sortCollisions(out)) deduped.set(collisionKey(collision), collision);
+  return [...deduped.values()];
+}

package/mcp.mjs

@@ -11,7 +11,7 @@ import { homedir, hostname } from "node:os";
 import { execSync, spawnSync } from "node:child_process";
 import { advise } from "./bin/advise.mjs";
 import { resolveProject, hostId, resolveHub } from "./lib/project.mjs";
-import { signedPost, getJSON } from "./hooks/lib/api.mjs";
+import { signedPost, signedGet } from "./hooks/lib/api.mjs";
 import { assertNoSecrets } from "./lib/scrub.mjs";
 import { z } from "zod";
 
@@ -43,14 +43,16 @@ async function seedCursor() {
   } catch { /* hub down: the subsequent real call surfaces the error; leave cursor at 0 */ }
 }
 
-// Every hub WRITE is SIGNED with this session's Ed25519 keypair (TDD §7.3) via the shared client in
-// hooks/lib/api.mjs — that is what binds /send's `from` to the signer and closes the self-asserted
-// `from` hole (the 2026-07-28 RCE). Reads go unsigned for now (pending the hub's DM scope-filtering
-// fix — see hooks/lib/api.mjs:getJSON). The client fail-opens on a down hub (returns {ok:false}); we
-// surface that as a thrown Error so individual tools can .catch it exactly as they did for a bare fetch.
+// Every hub call is SIGNED with this session's Ed25519 keypair (TDD §7.3) via the shared client in
+// hooks/lib/api.mjs. Writes: that is what binds /send's `from` to the signer and closes the
+// self-asserted `from` hole (the 2026-07-28 RCE). Reads TOO (the 2026-07-30 agent-UX gap): an
+// enforce hub 401s unsigned reads, which made relay_inbox/board/peers dead for the very agents the
+// bus exists for. Signed reads are scope-filtered by the hub to this identity's grants — for a
+// session reading its own project + DMs that is the intended behavior. The client fail-opens on a
+// down hub (returns {ok:false}); we surface that as a thrown Error so individual tools .catch it.
 async function api(method, path, payload) {
   const r = method.toUpperCase() === "GET"
-    ? await getJSON(path)
+    ? await signedGet(path, { session: SESSION })
     : await signedPost(path, payload, { session: SESSION });
   if (!r.ok) throw new Error(`hub ${r.status} on ${path}`);
   return r.json;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.17.55",
+  "version": "0.17.56",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"