trantor 0.18.32 → 0.18.34

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.32",
+  "version": "0.18.34",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/README.md

@@ -399,9 +399,15 @@ trantor setup | doctor | connect | profile | provider | models
 
 - **`trantor new <name>`** — project genesis in one command: makes the dir under your dev root
   (`TRANTOR_DEV_ROOT` or `~/development`), git on main (or `--from <git-url>`, or `--adopt` an
-  existing folder), seeds CLAUDE.md from `--brief <file>`, installs the auto-card hook, posts
-  the brief to the hub, and opens the first card "genesis: <name>". `--json` for machines.
-  It never spawns a session — firing the crew stays your call.
+  existing folder), installs the auto-card hook, posts the brief to the hub, and opens the first
+  card "genesis: <name>". `--json` for machines. It never spawns a session — firing the crew
+  stays your call. Two paths in: **blank** (no brief) wakes the orchestrator plainly and you work
+  with it iteratively; **from a brief** (`--brief <file>`, or a PRD dropped on the app's Genesis
+  sheet) stores it in `docs/PRD.md` with a small CLAUDE.md pointer, and the wake runs
+  **`/trantor:prd-review`**: every live crew seat plus two Scrooge readers review the PRD
+  independently against one rubric, the orchestrator synthesizes the consensus and asks you,
+  the TDD gets the same review, and only then do the build cards open. A parked project with
+  `docs/PRD.md` and no build cards takes the same path on its next Wake.
 
 - **`trantor provider`** — `list` every crew seat (built-in + brought) with availability + tier ·
   `add <name> --key … [--plan api] [--base-url <url> --models a,b]` to bring any provider (custom

package/bin/baton.mjs

@@ -1,16 +1,42 @@
 #!/usr/bin/env node
-// `trantor handoff` — one-command manual baton (auto-summary variant). Discovers the current session's
-// transcript, writes a whole-session handoff (auto-summary + verbatim in-flight tail), opens a fresh
-// self-announcing session, and closes THIS window once it takes over. Run from inside the session you
-// want to hand off. (The richer MODEL-authored handoff is the /trantor:handoff skill.)
-import { readdirSync, statSync } from "node:fs";
-import { join, basename } from "node:path";
+// `trantor handoff` — one-command manual baton. Discovers the current session's transcript, writes
+// a whole-session handoff (auto-summary + verbatim in-flight tail), opens a fresh self-announcing
+// session, and closes THIS window once it takes over. Run from inside the session you want to hand
+// off. (The richer MODEL-authored handoff is the /trantor:handoff skill.)
+import { readdirSync, statSync, fstatSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
 import { homedir } from "node:os";
-import { resolveProject } from "../lib/project.mjs";
-import { writeHandoff, spawnBaton } from "../hooks/lib/handoff.mjs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { writeHandoff, spawnBaton, resolveHandoffSurface } from "../hooks/lib/handoff.mjs";
 
+// #6074: the skill path (write-handoff.mjs) and this CLI path must share ONE resolution of which
+// project this is and where the session lives. Both call resolveHandoffSurface; the name comes
+// from the session's registration (TRANTOR_ORCH / RELAY_PROJECT / orch-sessions.txt) before the
+// cwd — a subfolder cwd never renames the project.
 const cwd = process.cwd();
-const project = resolveProject(cwd);
+const resolved = resolveHandoffSurface({ projectDir: process.env.CLAUDE_PROJECT_DIR || cwd, sessionId: process.env.CLAUDE_SESSION_ID || "" });
+const project = resolved.project;
+
+// Model-authored handoffs ride THIS binary too (`trantor handoff` — always the global install's
+// CURRENT code, never the plugin-cache copy a session booted with, the stale-0.18.20 bug). A piped
+// stdin (a heredoc, a cat, `<<HANDOFF`) means "here is the handoff markdown" — exactly the skill's
+// contract — so forward to write-handoff.mjs in the SAME package (same version, same resolution)
+// and exit with its status. --latest forwards too. A true pipe is a FIFO; a TTY and /dev/null are
+// character devices, so a plain `trantor handoff` typed at a prompt (or run by a hook with stdin
+// at /dev/null) keeps the auto-summary behavior. Detection must NOT be `!process.stdin.isTTY` —
+// that misreads /dev/null as a handoff and errors where auto-summary used to work.
+function stdinIsPipe() {
+  try { return fstatSync(0).isFIFO(); } catch { return false; }
+}
+if (stdinIsPipe() || process.argv.includes("--latest")) {
+  const helper = join(dirname(fileURLToPath(import.meta.url)), "write-handoff.mjs");
+  const child = spawn(process.execPath, [helper, ...process.argv.slice(2)], { stdio: ["inherit", "inherit", "inherit"] });
+  child.on("exit", (c) => process.exit(c ?? 1));
+  child.on("error", () => process.exit(1));
+} else {
+  autoBaton();
+}
 
 // The active session's transcript = newest *.jsonl directly in this project's Claude dir
 // (~/.claude/projects/<cwd-with-slashes-as-dashes>/), excluding the subagents/ subtree.
@@ -29,20 +55,22 @@ function findTranscript() {
   return best;
 }
 
-const transcript = findTranscript();
-// The transcript's filename IS the writing session's id — record it, or an orchestrator-thread
-// handoff carries no writer and the baton-hold + map-follow logic in sessionstart.mjs can't fire.
-const sessionId = transcript ? basename(transcript, ".jsonl") : "";
-const { file } = writeHandoff({ projectDir: cwd, sessionId, transcript, trigger: "manual-cli", force: true });   // manual = intentional, bypass the storm guard
-console.log(`📋 handoff saved for ${project}: ${file}`);
-// --write-only: the in-app flow (#5509). The app ends the pane's session itself and reopens it
-// through `trantor open`, which claims this handoff — a Terminal window here would be exactly the
-// wrong surface, so the flag writes, announces, and stops.
-if (process.argv.includes("--write-only")) {
-  console.log(`🔄 write-only: no window spawned — the pane takeover (trantor open) claims it next.`);
-  process.exit(0);
+function autoBaton() {
+  const transcript = findTranscript();
+  // The transcript's filename IS the writing session's id — record it, or an orchestrator-thread
+  // handoff carries no writer and the baton-hold + map-follow logic in sessionstart.mjs can't fire.
+  const sessionId = transcript ? basename(transcript, ".jsonl") : "";
+  const { file } = writeHandoff({ projectDir: cwd, sessionId, transcript, trigger: "manual-cli", force: true, projectName: project });   // manual = intentional, bypass the storm guard
+  console.log(`📋 handoff saved for ${project}: ${file}`);
+  // --write-only: the in-app flow (#5509). The app ends the pane's session itself and reopens it
+  // through `trantor open`, which claims this handoff — a Terminal window here would be exactly the
+  // wrong surface, so the flag writes, announces, and stops.
+  if (process.argv.includes("--write-only")) {
+    console.log(`🔄 write-only: no window spawned — the pane takeover (trantor open) claims it next.`);
+    process.exit(0);
+  }
+  const { spawned, armed, windowId } = spawnBaton({ projectDir: cwd, handoffFile: file });
+  console.log(spawned
+    ? `🔄 baton: a fresh session is opening (it'll recap the handoff)${armed ? ` — this window (${windowId}) closes once it takes over` : " — couldn't detect this window; close it yourself once the new one is up"}`
+    : `handoff saved, but couldn't spawn a fresh session (non-macOS or spawn disabled) — open a new session here to take over`);
 }
-const { spawned, armed, windowId } = spawnBaton({ projectDir: cwd, handoffFile: file });
-console.log(spawned
-  ? `🔄 baton: a fresh session is opening (it'll recap the handoff)${armed ? ` — this window (${windowId}) closes once it takes over` : " — couldn't detect this window; close it yourself once the new one is up"}`
-  : `handoff saved, but couldn't spawn a fresh session (non-macOS or spawn disabled) — open a new session here to take over`);

package/bin/cli.mjs

@@ -70,6 +70,7 @@ switch (cmd) {
   case "reconcile": run("bin/reconcile.mjs"); break;
   case "init-hooks": run("bin/init-hooks.mjs"); break;
   case "new": run("bin/new.mjs"); break;
+  case "genesis-kickoff": run("bin/genesis-kickoff.mjs"); break;
   case "balances": case "balance": case "credits": run("bin/balances.mjs"); break;
   case "recost": run("bin/recost.mjs"); break;
   case "handoff": run("bin/baton.mjs"); break;
@@ -209,7 +210,8 @@ switch (cmd) {
   trantor gates       verification gates: "must verify before shipping" claims that survive handoffs — [--all] [--json]
   trantor backfill    card past GIT work onto the board (solo commits that were never carded) — [--since "14 days ago"] [--dry-run]
   trantor init-hooks  install a git post-commit hook so EVERY commit auto-cards on the board (reliable solo-work backstop) — [--uninstall]
-  trantor new         project genesis: new <name> [--from <git-url>] [--brief <file>] [--dir <parent>] [--adopt] [--json] — creates <parent>/<name>, git main, CLAUDE.md from the brief, hooks, hub brief + first card (never spawns a session)
+  trantor new         project genesis: new <name> [--from <git-url>] [--brief <file>] [--dir <parent>] [--adopt] [--json] — creates <parent>/<name>, git main, docs/PRD.md + small CLAUDE.md, hooks, hub brief + first card (never spawns a session)
+  trantor genesis-kickoff  internal wake prompt selector from the checkout + signed project board
   trantor balances    how much credit is left on each CONFIGURED provider (from your profile) — refill before you stall — [--json]
   trantor recost      recompute sub-agent notional cost from on-disk transcripts + reseed the board (repair after upgrade) — [--dry-run]
   trantor handoff     finish this session NOW: write a handoff, open a fresh session that takes over, and close this one (manual baton)

package/bin/connect.mjs

@@ -40,6 +40,10 @@ function patchJson(path, mutate) {
 // while its runner sat on the pinned one — the residual split-brain mechanism (2026-08-20).
 // mcp.mjs resolves the hub from the session's project pin; that resolution must stay in charge.
 const relayEnv = (agent) => ({ RELAY_AGENT: agent });
+// OpenCode hosts several differently-named seats. Its global MCP environment must not stamp all
+// of them "opencode": ambient runner identity wins, while this fallback names a normal interactive
+// OpenCode session that has no RELAY_AGENT/RELAY_SESSION of its own.
+const hostedRelayEnv = (agent) => ({ RELAY_AGENT_FALLBACK: agent });
 
 // ---- Claude Code: plugin handles it; verify only ----
 if (has("claude")) {
@@ -87,7 +91,13 @@ if (has("opencode")) {
   report("opencode", patchJson(p, d => {
     d.$schema ||= "https://opencode.ai/config.json";
     d.mcp ||= {};
-    d.mcp.relay ||= { type: "local", command: ["node", MCP], enabled: true, environment: relayEnv("opencode") };
+    d.mcp.relay ||= { type: "local", command: ["node", MCP], enabled: true };
+    d.mcp.relay.environment ||= {};
+    // Migrate the old generated pin too: `||=` alone left RELAY_AGENT=opencode in every existing
+    // config forever, where OpenCode overlaid it on the qwen/glm/deepseek runner environment.
+    delete d.mcp.relay.environment.RELAY_AGENT;
+    delete d.mcp.relay.environment.RELAY_SESSION;
+    Object.assign(d.mcp.relay.environment, hostedRelayEnv("opencode"));
   }), p);
 }
 

package/bin/crew-runner.mjs

@@ -358,7 +358,7 @@ async function reportFailure(exit, trigger, undelivered = 0) {
   const reason = classify(exit);
   const down = consecFails >= 2;
   const status = down ? `down: ${reason} · ${consecFails} fails` : `errored: ${reason}`;
-  await api("/register", { session: SESSION, project: PROJ, status, llm: AGENT, model: MODEL }).catch(() => {});
+  await api("/register", { session: SESSION, project: PROJ, status, llm: AGENT, model: MODEL, kind: "agent" }).catch(() => {});
   const hint = reason === "exhausted" ? " — needs `trantor swap`"
     : reason === "auth" ? " — check credentials"
     : reason === "backend-error" ? " — provider backend error (NOT quota): retry, or `trantor swap` to another provider"
@@ -446,7 +446,7 @@ async function reportHealthy() {
   consecFails = 0;
   // Recovery is a change too, so the next failure is news again.
   announced = "";
-  await api("/register", { session: SESSION, project: PROJ, status: `active in ${PROJ}`, llm: AGENT, model: MODEL }).catch(() => {});
+  await api("/register", { session: SESSION, project: PROJ, status: `active in ${PROJ}`, llm: AGENT, model: MODEL, kind: "agent" }).catch(() => {});
   await api("/send", { from: SESSION, to: "all", text: `✅ ${SESSION} recovered`, project: PROJ, kind: "status" }).catch(() => {});
   cmuxStatus("ok", "#14b8a6", "check"); herdrAgent("idle");
 }
@@ -510,9 +510,13 @@ async function runTurn(prompt, isFirst, trigger = "kickoff") {
       { detached: true, stdio: "ignore" });
     wd.unref();
   } catch {}
-  const r = spawnSync("/bin/bash", ["-c", `set -o pipefail; { ${inner} ; } 2> >(${SCRUB} --tee2 ${ERRF})`], {
+  // Preserve the CLI's exit before waiting for the stderr process substitution. Without the
+  // explicit wait, a short failing CLI can return while its error is still in the scrub pipe;
+  // under load the classifier then reads an empty ERRF and reports the wrong failure reason.
+  const shell = `set -o pipefail; { ${inner} ; } 2> >(${SCRUB} --tee2 ${ERRF}); turn_exit=$?; wait; exit $turn_exit`;
+  const r = spawnSync("/bin/bash", ["-c", shell], {
     cwd: TURN_DIR, encoding: "utf8", stdio: cli.sid ? ["ignore", "pipe", "inherit"] : "inherit",
-    env: { ...process.env, RELAY_URL: HUB, RELAY_AGENT: AGENT, RELAY_PROJECT: PROJ,
+    env: { ...process.env, RELAY_URL: HUB, RELAY_AGENT: AGENT, RELAY_SESSION: SESSION, RELAY_PROJECT: PROJ,
       // A RUNNER-MANAGED SEAT MUST NEVER HAND ITSELF A BATON.
       //
       // The handoff machinery exists for an INTERACTIVE session: near its context limit it writes a
@@ -527,9 +531,8 @@ async function runTurn(prompt, isFirst, trigger = "kickoff") {
     maxBuffer: 16 * 1024 * 1024,
   });
   try { unlinkSync(STAMPF); } catch {}   // turn over — disarm the watchdog
-  // #5869: scrub AT REST, synchronously, before anything reads the file back. The stderr hop is
-  // a process substitution bash does not wait for, so this pass also catches its tail — the
-  // auth classifier and the empty-output check below must judge REDACTED text and a settled file.
+  // #5869: scrub AT REST, synchronously, before anything reads the file back. The explicit shell
+  // wait above drains the live stderr scrubber first; this pass is defense in depth for redaction.
   try { writeFileSync(ERRF, redactKeys(readFileSync(ERRF, "utf8"))); } catch {}
   // #5868: classify only what the CLI itself said. The transcript replays the whole turn prompt
   // (rules, lessons, the wake text) — and those lines once classified healthy codex turns as
@@ -673,7 +676,11 @@ function askedExcerpt(message) {
   // start cursor at the CURRENT tip so we don't replay history
   let cursor = 0;
   try { const r = await api(`/inbox?session=${encodeURIComponent(SESSION)}&since=0`); cursor = r.cursor || 0; } catch {}
-  await api("/register", { session: SESSION, project: PROJ, status: "crew member booting", llm: AGENT, model: MODEL }).catch(() => {});
+  // kind "agent" on every beat (#6075): the peer row's kind is the hub's OWN record of what a
+  // session is — the overseer's declared-crew exemption reads it, and on the remote hub there is
+  // no crew-windows.txt to fall back to. /register preserves absent fields, so a seat running an
+  // older runner never loses a kind an updated one stamped.
+  await api("/register", { session: SESSION, project: PROJ, status: "crew member booting", llm: AGENT, model: MODEL, kind: "agent" }).catch(() => {});
   // Announce runner-side, signed as THIS seat. Asking the seat to announce itself sent glm's hello
   // out under deepseek's identity whenever opencode seats shared one MCP daemon (lesson on the bus,
   // 2026-07-29): the runner process is per-seat by construction, so its signature cannot be borrowed.
@@ -726,7 +733,12 @@ function askedExcerpt(message) {
     let msgs = [];
     try {
       const r = await api(`/poll?session=${encodeURIComponent(SESSION)}&since=${cursor}&wait=${holdS}`);
-      msgs = r.messages || []; cursor = r.cursor ?? cursor;
+      msgs = r.messages || [];
+      if (r.cursor !== undefined && r.cursor !== null && Number.isFinite(Number(r.cursor))) {
+        const reportedCursor = Number(r.cursor);
+        if (reportedCursor < cursor) log(`cursor rewound by hub ${cursor} -> ${reportedCursor}`);
+        cursor = reportedCursor;
+      }
     } catch (e) {
       // Deadline-abort on the LONG-POLL is not an outage — it means the hold expired with no hub
       // response (stalled event loop, napped machine, dead socket). Reconnect immediately and say

package/bin/genesis-kickoff.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// trantor genesis-kickoff [<project>] — which boot prompt a WOKEN orchestrator gets (#6112).
+//
+// Two paths into a project (operator ruling 2026-09-02 23:15). Path A, blank: the orchestrator
+// wakes plainly and works iteratively with the operator. Path B, from a brief: the PRD sits in
+// docs/PRD.md and the wake CONVENES the crew review (/trantor:prd-review) before anything is
+// built. Waking an adopted project that has docs/PRD.md and no build cards takes path B too, so
+// a project that parked with its PRD in place needs no re-genesis: the next Wake convenes it.
+//
+// The decision needs two facts only the CLI holds together — the checkout's durable docs/PRD.md
+// and the project's SIGNED board — so it lives here. The desktop app (genesis sheet, sidebar
+// Wake, workspace open) runs this in the checkout and relays the one line it prints; on exit 1
+// the app types its own plain wake instead. A board that cannot be read therefore fails CLOSED
+// to the plain wake, never to a review nobody verified was due: the plain-woken orchestrator
+// still sees docs/PRD.md and the CLAUDE.md pointer and can convene by hand.
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadIdentity, signedGet } from "../hooks/lib/api.mjs";
+import { ensureEnrolled as enrollViaOwnerInvite } from "../lib/enroll.mjs";
+import { hostId, resolveHub, resolveProject } from "../lib/project.mjs";
+
+export const PRD_REVIEW_KICKOFF = "docs/PRD.md is the brief; run /trantor:prd-review";
+// Word for word the app's WAKE_KICKOFF_PROMPT (desktop terminal.rs): a project without a brief to
+// review gets exactly the wake it always got.
+export const PLAIN_WAKE_KICKOFF = "You were just woken via Trantor. Catch up from your context — the handoff you were handed if one exists, otherwise the project board and memory — then recap where things stand in at most 3 sentences and wait.";
+
+// Cards that exist BEFORE a build starts, and must not be mistaken for one: the genesis card
+// `trantor new` opens, the review cards this flow opens, and the auto-cards a session sheds
+// (operator prompts, sub-agents) which say a conversation happened, not that work was cut.
+const PRE_BUILD_PHASES = new Set(["genesis", "prd", "tdd"]);
+const PRE_BUILD_TITLE = /^(genesis:|prd review:|tdd review:)/i;
+const CONVERSATION_SOURCES = new Set(["session", "cc-subagent", "cc-bg-agent"]);
+
+export function isBuildCard(task) {
+  if (!task || typeof task !== "object") return false;
+  const phase = String(task.phase || "").trim().toLowerCase();
+  if (phase === "build") return true;
+  if (PRE_BUILD_PHASES.has(phase)) return false;
+  if (CONVERSATION_SOURCES.has(String(task.source || "").trim().toLowerCase())) return false;
+  const title = String(task.title || "").trim();
+  return Boolean(title) && !PRE_BUILD_TITLE.test(title);
+}
+
+// The pure decision: dir = the checkout, tasks = the board (an array), or null when it could not
+// be read. Exported so the drill can pin every branch without a hub.
+export function selectGenesisKickoff({ dir, tasks }) {
+  if (!existsSync(join(dir, "docs", "PRD.md"))) return PLAIN_WAKE_KICKOFF;
+  if (!Array.isArray(tasks)) return PLAIN_WAKE_KICKOFF;
+  return tasks.some(isBuildCard) ? PLAIN_WAKE_KICKOFF : PRD_REVIEW_KICKOFF;
+}
+
+async function readBoard(project) {
+  const hub = resolveHub(project);
+  // Sign as the identity the orchestrator in this checkout will use (RELAY_SESSION when a runner
+  // set one, else host:project). On an enforce hub that identity may be brand new for a project
+  // `trantor new` made seconds ago, and TOFU is refused there — so enrol the way crew seats and
+  // genesis itself do: the operator's owner key mints a project-scoped invite and this identity
+  // spends it. A no-op when the hub already knows us; a soft failure when it does not, in which
+  // case the signed read below reports the refusal and the caller falls back.
+  const session = process.env.RELAY_SESSION
+    || (process.env.RELAY_AGENT ? `${process.env.RELAY_AGENT}:${project}` : `${hostId()}:${project}`);
+  const identity = loadIdentity(session);
+  const enrolment = await enrollViaOwnerInvite(hub, identity, project, { timeoutMs: 4000 });
+  if (!enrolment.ok && enrolment.reason !== "no-owner-key") {
+    console.error(`genesis kickoff: enrolment on ${hub} did not succeed (${enrolment.reason}); trying the read anyway`);
+  }
+  const response = await signedGet(`/tasks?project=${encodeURIComponent(project)}`, { session, project, timeoutMs: 4000 });
+  if (!response.ok) {
+    return { ok: false, hub, reason: response.status ? `hub ${response.status}${response.json?.error ? `: ${response.json.error}` : ""}` : "unreachable" };
+  }
+  const tasks = Array.isArray(response.json) ? response.json : response.json?.tasks;
+  return Array.isArray(tasks) ? { ok: true, hub, tasks } : { ok: false, hub, reason: "malformed /tasks response" };
+}
+
+async function main() {
+  const dir = process.cwd();
+  const project = process.argv[2] || resolveProject(dir);
+  if (!existsSync(join(dir, "docs", "PRD.md"))) {
+    console.log(PLAIN_WAKE_KICKOFF);
+    return;
+  }
+  const board = await readBoard(project);
+  if (!board.ok) {
+    console.error(`genesis kickoff: docs/PRD.md is present but ${project}'s board on ${board.hub} could not be read (${board.reason}) — the app falls back to the plain wake`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(selectGenesisKickoff({ dir, tasks: board.tasks }));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/bin/new.mjs

@@ -6,8 +6,8 @@
 // It makes the project directory at <parent>/<name> — --dir names the PARENT, never the project
 // directory itself (default parent: TRANTOR_DEV_ROOT or ~/development). The name is always
 // appended under it, so `--dir P` with name N creates P/N. Starts git on main (or clones --from,
-// or adopts an existing folder with --adopt), seeds CLAUDE.md from the
-// brief (verbatim brief + the trantor conventions block), installs the same auto-card hook as
+// or adopts an existing folder with --adopt), stores the brief in docs/PRD.md and seeds a small
+// CLAUDE.md pointer plus the trantor conventions block, installs the same auto-card hook as
 // `trantor init-hooks`, posts the brief as the hub project brief (POST /project — the same call
 // relay_project_brief makes), and opens the first card "genesis: <name>" on the new board.
 //
@@ -17,7 +17,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensureEnrolled as enrollTofu, loadIdentity, signedPost } from "../hooks/lib/api.mjs";
 import { ensureEnrolled as enrollViaOwnerInvite } from "../lib/enroll.mjs";
@@ -28,7 +28,7 @@ const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 
 // The trantor conventions block — what every trantor-wired project's CLAUDE.md carries so the
 // first session knows the board, the crew, and the gates exist. Kept SHORT and factual; the
-// brief above it is the project's own voice.
+// project brief stays in docs/PRD.md so a large PRD cannot exceed the harness instruction limit.
 const CONVENTIONS = [
   "",
   "## Trantor conventions",
@@ -94,13 +94,22 @@ if (from) {
   branch = git(["branch", "--show-current"]).stdout.trim() || "main";
 }
 
-// ── CLAUDE.md — verbatim brief + the conventions block ──────────────────────────────────────────
+// ── durable brief + small CLAUDE.md pointer ─────────────────────────────────────────────────────
+if (brief) {
+  const docs = join(dir, "docs");
+  mkdirSync(docs, { recursive: true });
+  writeFileSync(join(docs, "PRD.md"), `${brief}\n`);
+}
+
 const claude = join(dir, "CLAUDE.md");
 if (existsSync(claude)) {
   const current = readFileSync(claude, "utf8");
   if (!current.includes("## Trantor conventions")) appendFileSync(claude, `\n${CONVENTIONS}\n`);
 } else {
-  const head = brief ? `${brief}\n` : `# ${name}\n\n(Genesis — no brief was given. Add this project's what/why/goal here.)\n`;
+  const importedFrom = briefFile ? ` (imported from \`${basename(briefFile)}\`)` : "";
+  const head = brief
+    ? `# ${name}\n\nThe project brief is stored at \`docs/PRD.md\`${importedFrom}. Read and maintain it there.\n`
+    : `# ${name}\n\nNo project brief was supplied. Begin with the operator's first instruction.\n`;
   writeFileSync(claude, `${head}${CONVENTIONS}`);
 }
 
@@ -129,9 +138,14 @@ try {
   // way crew seats do: the operator's owner key mints a project-scoped write invite and the genesis
   // identity spends it. Only when NO owner key is configured (a loopback hub with no owner identity)
   // do we fall back to the plain TOFU enroll.
-  const viaOwner = await enrollViaOwnerInvite(hub, identity, name, { timeoutMs: 8000 });
-  if (!viaOwner.ok && viaOwner.reason === "no-owner-key") await enrollTofu(session, identity, name);
+  const viaOwner = await enrollViaOwnerInvite(hub, identity, name, { timeoutMs: 8000, kind: "tool" });
+  if (!viaOwner.ok && viaOwner.reason === "no-owner-key") await enrollTofu(session, identity, name, { kind: "tool" });
   else if (!viaOwner.ok) console.error(`genesis: enrollment via owner invite failed: ${viaOwner.reason}`);
+  // #6068: say WHAT this session is. The genesis identity exists to post the brief — without a
+  // kind on its peer row the app's seat strip renders it as a seat ("no terminal pane — start it
+  // with trantor up genesis"). /register is presence, not speech: no message rides it, nobody
+  // wakes. The hub stamps kind on the session row and /peers returns it to the app.
+  await signedPost("/register", { session, kind: "tool" }, { session, project: name, timeoutMs: 8000 }).catch(() => {});
   const briefForHub = (brief || `Genesis of ${name} — created by trantor new.`).slice(0, 600);
   const r1 = await signedPost("/project", { project: name, brief: briefForHub, by: session }, { session, project: name, timeoutMs: 8000 });
   if (!r1.ok) throw new Error(`hub ${r1.status} on /project${r1.json?.error ? `: ${r1.json.error}` : ""}`);
@@ -156,7 +170,9 @@ if (json) {
   console.log(JSON.stringify({ name, parent: devRoot, dir, branch, hub, card }));
 } else {
   console.log(`✓ ${dir} (${branch}${from ? ", cloned" : adopt ? ", adopted" : ""})`);
-  console.log(`✓ CLAUDE.md seeded${brief ? " from the brief" : " (no brief — add the project's what/why/goal)"}`);
+  console.log(brief
+    ? "✓ docs/PRD.md seeded from the brief; CLAUDE.md kept small"
+    : "✓ blank project seeded; CLAUDE.md kept small");
   console.log(`✓ auto-card hook installed (trantor init-hooks)`);
   if (card !== null) console.log(`✓ hub ${hub}: brief posted, card #${card} ("genesis: ${name}")`);
   else if (hubError) console.log(`! hub ${hub}: brief/card not posted (${hubError})`);

package/bin/write-handoff.mjs

@@ -6,7 +6,7 @@ import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from
 import { join, basename } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execSync } from "node:child_process";
-import { spawnBaton, handoffMode } from "../hooks/lib/handoff.mjs";
+import { spawnBaton, handoffMode, resolveHandoffSurface } from "../hooks/lib/handoff.mjs";
 import { handoffDir } from "../lib/project.mjs";
 
 const baton = process.argv.includes("--baton");
@@ -14,8 +14,14 @@ const baton = process.argv.includes("--baton");
 // fresh one on stdin", so a session that had just written a 5KB handoff had to write it again to
 // hand it over — 2m28s of regenerated prose on a live scribe session, 2026-08-24.
 const latest = process.argv.includes("--latest");
-const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const name = basename(project);
+// #6074: ONE resolver for which project this is and where the session lives — shared with
+// bin/baton.mjs (the `trantor handoff` CLI path) so the two cannot diverge. The name comes from
+// the session's registration (TRANTOR_ORCH / RELAY_PROJECT / orch-sessions.txt) before the cwd;
+// the witnessed crebral-scribe/ios handoff recorded project "ios" from a subfolder cwd and never
+// found its pane.
+const resolved = resolveHandoffSurface({ sessionId: process.env.CLAUDE_SESSION_ID || "" });
+const project = resolved.projectDir;
+const name = resolved.project;
 let summary = "";
 if (!latest) {
   process.stdin.setEncoding("utf8");

package/deploy/restart-hub.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Guarded production restart: an unhealthy durable writer means RAM contains the only current copy.
+set -euo pipefail
+
+FORCE=0
+if [ "${1:-}" = "--force" ]; then
+  FORCE=1
+  shift
+fi
+if [ "$#" -ne 0 ]; then
+  echo "usage: deploy/restart-hub.sh [--force]" >&2
+  exit 2
+fi
+
+# The hub binds RELAY_HOST (the tailnet IP on netcup, where 127.0.0.1 refuses), so the guard reads the
+# same env the service does; RELAY_HUB_URL still overrides.
+ENV_FILE="${RELAY_ENV_FILE:-$(dirname "$0")/hub.env}"
+if [ -f "$ENV_FILE" ]; then
+  # shellcheck disable=SC1090
+  set -a; . "$ENV_FILE"; set +a
+fi
+HUB_URL="${RELAY_HUB_URL:-http://${RELAY_HOST:-127.0.0.1}:${RELAY_PORT:-4477}}"
+HEALTH=""
+if HEALTH="$(curl --fail --silent --show-error --max-time 5 "$HUB_URL/health")"; then
+  REFUSAL="$(node --input-type=module -e '
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    let health;
+    try { health = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+    catch { process.stdout.write("hub health response was not valid JSON"); process.exit(0); }
+    const p = health.persist;
+    if (!p || p.ok !== false) process.exit(0);
+    const age = Number(p.failingSinceMs || 0);
+    const span = age >= 60000 ? `${Math.floor(age / 60000)}m ${Math.floor((age % 60000) / 1000)}s` : `${Math.floor(age / 1000)}s`;
+    process.stdout.write(`hub persistence has failed for ${span} (${Number(p.retries || 0)} retries): ${String(p.lastError || "unknown error")}. Restarting risks losing every state change since persistence stopped.`);
+  ' <<<"$HEALTH")"
+  if [ -n "$REFUSAL" ] && [ "$FORCE" -ne 1 ]; then
+    echo "REFUSED: $REFUSAL" >&2
+    echo "Resolve persistence first, or rerun with --force to accept the data-loss risk." >&2
+    exit 1
+  fi
+  if [ -n "$REFUSAL" ]; then
+    echo "WARNING: --force accepted: $REFUSAL" >&2
+  fi
+else
+  echo "WARNING: $HUB_URL/health was unreachable; proceeding because no running hub state can be inspected." >&2
+fi
+
+systemctl restart trantor-hub
+echo "restarted trantor-hub"

package/deploy/setup-netcup.sh

@@ -72,10 +72,15 @@ echo "  schema applied"
 # systemd unit
 cp deploy/trantor-hub.service /etc/systemd/system/trantor-hub.service
 systemctl daemon-reload
-systemctl enable --now trantor-hub
+systemctl enable trantor-hub
+if systemctl is-active --quiet trantor-hub; then
+  bash deploy/restart-hub.sh
+else
+  systemctl start trantor-hub
+fi
 
 # crons: daily backup + nightly retention
-chmod +x deploy/backup.sh deploy/retention.sh deploy/restore.sh
+chmod +x deploy/backup.sh deploy/retention.sh deploy/restore.sh deploy/restart-hub.sh
 echo "0 2 * * * root /opt/trantor/deploy/backup.sh" > /etc/cron.d/trantor
 echo "0 3 * * * root /opt/trantor/deploy/retention.sh" >> /etc/cron.d/trantor
 

package/hooks/lib/api.mjs

@@ -112,7 +112,7 @@ function enrolledPath(session) {
   const busDir = process.env.AGENT_BUS_DIR || join(homedir(), ".agent-bus");
   return join(busDir, "keys", `${String(session).replace(/[^A-Za-z0-9_.-]/g, "_")}.enrolled`);
 }
-export async function ensureEnrolled(session, identity, project) {
+export async function ensureEnrolled(session, identity, project, { kind = "agent" } = {}) {
   if (!identity?.pubkey) return;
   const hub = relayUrl(project);
   const stamp = enrolledPath(session);
@@ -126,7 +126,7 @@ export async function ensureEnrolled(session, identity, project) {
     // payload, sets content-type, and signs — so every hook signs identically with zero hand-rolling.
     const r = await sfetchJson(`${hub}/enroll`, {
       method: "POST",
-      payload: { pubkey: identity.pubkey, name: session, kind: "agent" },
+      payload: { pubkey: identity.pubkey, name: session, kind },
       identity,
       signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
     });