trantor 0.18.64 → 0.18.65

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.64",
+  "version": "0.18.65",
   "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/baton-pane.mjs

@@ -33,7 +33,7 @@ const log = (s) => { try { appendFileSync(logFile, `${new Date().toISOString()}
 
 // Same text as the app's kickoff (lib.rs KICKOFF_PROMPT) — one boot prompt so the successor
 // recaps unprompted instead of sitting idle until a human types (the 15-minute silence, #5649).
-const KICKOFF_PROMPT = "You have just taken over via handoff. Recap now per your instructions.";
+const KICKOFF_PROMPT = "You have just taken over via handoff. FIRST open every file it names as read-first — memory, PRD, TDD — before you answer or touch anything; the summary points at them, it does not replace them (#8162). THEN recap per your instructions.";
 
 // The pane, resolved exactly like the app does (orch_pane_from_rows): last orch row wins.
 export function orchPane(rows, project) {

package/hooks/lib/handoff.mjs

@@ -794,9 +794,74 @@ export function maybeSpawn(projectDir, conf = readConfig(), handoffFile = "", de
   } catch (e) { process.stderr.write(`[trantor] maybeSpawn error: ${e?.message}\n`); return false; }
 }
 
+/** The files a handoff tells its successor to read before doing anything (#8162).
+ *
+ *  A handoff has always been able to SAY "read these first" — crebral-health's named three memory
+ *  files on 2026-09-19 and the successor opened none of them. Saying it was the whole mechanism.
+ *  This pulls the list out as data so something downstream can check it.
+ *
+ *  Recognised: a `READ FIRST` / `READ-FIRST` / `Read first:` heading or line, and every path-looking
+ *  token on it and the lines beneath it until the next blank line or heading. Deliberately narrow —
+ *  a handoff that mentions a file in passing is not asking anyone to read it, and a gate that fires
+ *  on every path in a 4k summary would be noise the successor learns to ignore.
+ *  @returns {string[]} project-relative or absolute paths, de-duplicated, capped
+ */
+export function readFirstPaths(summary, { max = 12 } = {}) {
+  const text = String(summary || "");
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  let collecting = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    const opens = /read[\s-]?first/i.test(line);
+    if (!collecting && !opens) continue;
+    if (collecting && (line === "" || /^#{1,6}\s/.test(line))) break;
+    collecting = true;
+    // Paths: a token with a slash or a known doc/memory extension, stripped of markdown furniture.
+    for (const m of line.matchAll(/[`"'(\[]?([~./\w-]*[\w-]+\.(?:md|mjs|js|ts|tsx|json|sql|rs|py|sh|txt))[`"')\]]?/g)) {
+      const p = m[1].replace(/^[`"'(\[]+|[`"')\]]+$/g, "");
+      if (p && !out.includes(p)) out.push(p);
+      if (out.length >= max) return out;
+    }
+  }
+  return out;
+}
+
+/** Which of `paths` this session actually OPENED, read off its own transcript (#8162).
+ *
+ *  Ground truth rather than testimony, the same rule the state gate learned the hard way: a
+ *  successor saying "I have read the handoff" is not evidence that it did. A Read/Grep/Glob tool
+ *  call naming the path is. Matches on basename as well as full path, because a handoff written by
+ *  a model may name `revenue-integrity-build.md` where the Read call carries the absolute path.
+ *  @returns {{read: string[], missed: string[]}}
+ */
+export function pathsReadIn(transcriptPath, paths) {
+  const want = (paths || []).filter(Boolean);
+  if (!want.length) return { read: [], missed: [] };
+  let body = "";
+  try { body = readFileSync(transcriptPath, "utf8"); } catch { return { read: [], missed: want }; }
+  // Only the tool CALLS count. A path quoted in the injected handoff summary, or in the model's own
+  // prose, must never read as "opened" — that is precisely the proxy this card exists to kill.
+  const opened = new Set();
+  for (const m of body.matchAll(/"name"\s*:\s*"(Read|Grep|Glob|NotebookRead)"\s*,\s*"input"\s*:\s*\{([^}]*)\}/g)) {
+    for (const f of m[2].matchAll(/"(?:file_path|path|pattern)"\s*:\s*"([^"]+)"/g)) opened.add(f[1]);
+  }
+  const hit = (p) => {
+    const base = p.split("/").pop();
+    for (const o of opened) if (o === p || o.endsWith("/" + p) || (base && o.endsWith("/" + base)) || o === base) return true;
+    return false;
+  };
+  const read = want.filter(hit);
+  return { read, missed: want.filter(p => !read.includes(p)) };
+}
+
 // The self-announcing fresh session command (single-quoted so it survives osascript→shell un-escaped).
-// Brevity is part of the prompt: a takeover that answers with 5k-character status dumps loses the operator.
-export const RECAP_CMD = "claude 'Recap the handoff you just took over — task, state, next step — in at most 3 sentences. Then wait for me. Keep all replies short by default: no status tables, no headers, no walls of text unless I explicitly ask for detail.'";
+// Brevity is part of the prompt: a takeover that answers with 5k-character status dumps loses the
+// operator. But brevity is about what you SAY, and #8162 found it had quietly become permission not
+// to READ: the summary is injected at SessionStart, so a 3-sentence recap is producible without
+// opening a file, and a successor doing exactly as asked never opened one. Three days of takeovers
+// went straight to code off a summary. So the order is now read-then-recap, and the recap stays short.
+export const RECAP_CMD = "claude 'You have just taken over via handoff. FIRST open every file the handoff names as read-first — its memory files, its PRD and TDD — and do not answer until you have. They are the context the handoff exists to carry, and the summary is a pointer to them, not a substitute. THEN recap in at most 3 sentences: task, state, next step. Then wait for me. Keep all replies short by default: no status tables, no headers, no walls of text unless I explicitly ask for detail.'";
 
 // ONE suppression check for every path that can open a terminal window: two names for it once let a
 // drill set the wrong one and open eight live sessions in deleted temp directories, so both are honoured.

package/hooks/sessionstart.mjs

@@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url";
 import { resolveProject, hostId, resolveHubInfo, knownProjects, nonSeatReason, nestedProjects, handoffDir, readOrchSession, writeOrchSession } from "../lib/project.mjs";
 import { formatSubagentManifest } from "../lib/subagent-manifest.mjs";
 import { updateAvailable, maybeNotifyDesktop, readConfig } from "./lib/update-check.mjs";
-import { renderStateBlock } from "./lib/handoff.mjs";
+import { renderStateBlock, readFirstPaths} from "./lib/handoff.mjs";
 import { maybeCheckBalances } from "./lib/balance-check.mjs";
 import { getJSON, signedGet, signedPost, loadIdentity } from "./lib/api.mjs";
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
@@ -78,8 +78,11 @@ function loadPendingHandoff(projectName, { claim = true, freshSession = null } =
             try {
               // #5645: the mandate rides the stamp too, so prompt-focus's recap reminder pins
               // the SAME rec.mode the injection below announces (attended=WAIT / unattended=RESUME).
+              // #8162: the READ-FIRST list rides the stamp as DATA, so the Stop hook can check the
+              // successor opened it instead of accepting a reply as proof it understood anything.
+              const readFirst = readFirstPaths(rec.summary || "");
               writeFileSync(join(dir, `recap-pending-${String(freshSession.session_id).replace(/[^A-Za-z0-9_.-]/g, "_")}.json`),
-                JSON.stringify({ handoffId: rec.id, ts: nowSec(), mode: rec.mode === "unattended" ? "unattended" : "attended" }));
+                JSON.stringify({ handoffId: rec.id, ts: nowSec(), mode: rec.mode === "unattended" ? "unattended" : "attended", readFirst }));
             } catch {}
           }
         }
@@ -499,9 +502,9 @@ try {
     // attended (default) = recap-then-WAIT; unattended = recap-then-RESUME — the handoff's OPEN
     // THREADS are the work order ("handoffs must never be a break").
     if (handoff.mode === "unattended") {
-      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit, in UNATTENDED (long-run) mode.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch. Recap the task, state, and next step in at most 3 sentences, then RESUME the open threads immediately — they are your work order. Do NOT wait for the user; keep building. Keep replies short: no status tables, no headers, no walls of text.\n\n`;
+      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit, in UNATTENDED (long-run) mode.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch.\n\n**READ BEFORE YOU BUILD (#8162).** This summary is a POINTER to the project's context, not a replacement for it. Open every file this handoff names as read-first — its memory files, its PRD and its TDD — BEFORE you touch code. Reading is not waiting, and it is not optional: three days running, successors recapped from this summary alone and went straight to code, burning a fifth of a context window rediscovering what was already written down. The ledger now checks which files you opened, not whether you replied.\n\nThen recap the task, state, and next step in at most 3 sentences, then RESUME the open threads — they are your work order. Do NOT wait for the user; keep building. Keep replies short: no status tables, no headers, no walls of text.\n\n`;
     } else {
-      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch. Recap the task, state, and next step in at most 3 sentences, then wait. Keep replies short: no status tables, no headers, no walls of text unless the user explicitly asks for detail.\n\n`;
+      additionalContext += `🔄 **You are taking over from a prior session that hit its context limit.** This is a fresh full window. Resume the work below — the prior session's summary, git state, and a pointer to its full transcript (searchable; Foundation/Gaia has it ingested) follow. Continue from "OPEN THREADS & NEXT STEPS"; do not restart from scratch.\n\n**READ BEFORE YOU ANSWER (#8162).** This summary is a POINTER to the project's context, not a replacement for it. Open every file this handoff names as read-first — its memory files, its PRD and its TDD — before you recap. A 3-sentence recap is producible from this summary alone, which is exactly how three days of takeovers went straight to code without opening anything. The ledger now checks which files you opened, not whether you replied.\n\nThen recap the task, state, and next step in at most 3 sentences, then wait. Keep replies short: no status tables, no headers, no walls of text unless the user explicitly asks for detail.\n\n`;
     }
     // Verification gates FIRST — these are structured "must verify before shipping" claims the prior
     // session couldn't independently prove. They go above the summary on purpose: a safety-critical

package/hooks/stop-inbox.mjs

@@ -11,7 +11,7 @@ import { homedir } from "node:os";
 import { resolveProject, hostId, handoffDir, busDir } from "../lib/project.mjs";
 import { signedGet } from "./lib/api.mjs";   // signed: enforce hubs 401 unsigned reads — unsigned, T2 delivery is silently dead
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
-import { readArm, clearArm, markHandedOff, appendHandoffState, subagentsActive } from "./lib/handoff.mjs";
+import { readArm, clearArm, markHandedOff, appendHandoffState, subagentsActive, pathsReadIn} from "./lib/handoff.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -162,9 +162,27 @@ async function main() {
       if (existsSync(stampPath)) {
         try {
           const stamp = JSON.parse(readFileSync(stampPath, "utf8"));
-          appendHandoffState(stamp.handoffId, "recapped", sid);
-        } catch {}
-        try { unlinkSync(stampPath); } catch {}
+          // #8162: RECAPPED used to mean "a reply exists by Stop time", which a successor satisfies
+          // from the injected summary alone — so a handoff naming read-first files certified a
+          // takeover that opened none of them, three days running. Now the ledger asks the same
+          // question the state gate learned to ask: ground truth, not testimony. A Read/Grep tool
+          // call naming the path is evidence; the successor's own say-so is not.
+          const want = Array.isArray(stamp.readFirst) ? stamp.readFirst : [];
+          const { missed } = want.length
+            ? pathsReadIn(input.transcript_path || "", want)
+            : { missed: [] };
+          if (missed.length) {
+            // The stamp STAYS. Not recapped, so the next boundary asks again — and the successor is
+            // told exactly what it skipped rather than left to discover it when the operator does.
+            process.stderr.write(
+              `[trantor] handoff ${stamp.handoffId}: NOT recapped — the handoff named ${want.length} file(s) to read first and ${missed.length} ${missed.length === 1 ? "was" : "were"} never opened: ${missed.join(", ")}. Read them before going further; this is the context the handoff exists to carry.\n`);
+          } else {
+            appendHandoffState(stamp.handoffId, "recapped", sid);
+            try { unlinkSync(stampPath); } catch {}
+          }
+        } catch {
+          try { unlinkSync(stampPath); } catch {}
+        }
       }
     }
   } catch {}

package/package.json

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