trantor 0.18.63 → 0.18.65

package/.claude-plugin/plugin.json

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

@@ -132,6 +132,7 @@ switch (cmd) {
   case "orchestrate": run("bin/orchestrate.mjs"); break;
   case "app": run("bin/app.mjs"); break;
   case "patrol": run("bin/patrol.mjs"); break;
+  case "retire": run("bin/retire.mjs"); break;
   case "identity": {
     const { load, publicView, generate, keyPath } = await import(join(ROOT, "lib/identity.mjs"));
     const sub = args[0], name = args[1] || "human";
@@ -271,6 +272,7 @@ switch (cmd) {
   trantor duty        the always-on fleet duty agent: up | down | status — hub-escalated triage so you are not the switchboard
                       runs on sonnet by default (it never writes code); duty up --model <m> to pick, or --model inherit for the CLI default
   trantor orchestrate a per-project ORCHESTRATOR with a MISSION.md and a pulse: up [--every 10m] | down | status — the loop-orchestrator pattern
+  trantor retire      retire orchestrator panes nothing is using — preview by default [--hours N] [--yes] [--json]
   trantor patrol      machine-wide resource sweep: crews/runners/workspaces/orphans — [--json] [--reap] (reap = dead rows + stale artifacts ONLY)
 
 Claude Code plugin (the orchestrator side):

package/bin/retire.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// `trantor retire` — retire orchestrator panes that nothing is using (#8017). Previews by default;
+// --yes performs it. Liveness, never age alone, decides: a pane mid-turn or holding an in-flight
+// contract is held open whatever its idle age.
+import { execFileSync } from "node:child_process";
+import { turnInFlight, buildSummary, writeHandoff, sessionProcessState } from "../hooks/lib/handoff.mjs";
+import { hostId, resolveHub } from "../lib/project.mjs";
+import { sfetchJson } from "../lib/signed-fetch.mjs";
+import {
+  retireHours, retireEnabled, collectPanes, retireDecision, retirePane,
+  isRetired, humanHours, retiredLedgerPath,
+} from "../lib/retire-panes.mjs";
+
+const D = "\x1b[2m", B = "\x1b[1m", Y = "\x1b[33m", G = "\x1b[32m", R = "\x1b[0m";
+const args = process.argv.slice(2);
+const flag = n => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : null; };
+const APPLY = args.includes("--yes");
+const JSON_OUT = args.includes("--json");
+
+const hours = flag("--hours") !== null ? Number(flag("--hours")) : retireHours();
+if (!retireEnabled(hours)) {
+  console.log(`retirement disabled (threshold ${hours}h) — set TRANTOR_PANE_RETIRE_HOURS or config.paneRetireHours`);
+  process.exit(0);
+}
+
+const host = hostId();
+// Fail CLOSED on the hub: a contract count we could not read must never be taken as zero, or an
+// unreachable hub would retire a pane that is holding work.
+async function contractsFor(session) {
+  try {
+    const res = await sfetchJson(`${resolveHub("")}/contracts?session=${encodeURIComponent(session)}`,
+      { method: "GET", name: session });
+    if (!res.ok) return 1;
+    return Number((await res.json())?.open) || 0;
+  } catch { return 1; }
+}
+
+const panes = collectPanes({ turnInFlight, sessionProcessState, hostId: host }).filter(p => !isRetired(p.sid));
+for (const p of panes) p.openContracts = await contractsFor(`${host}:${p.project}`);
+const decided = panes.map(p => retireDecision(p, { hours }));
+const due = decided.filter(d => d.retire);
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({ hours, applied: APPLY, panes: decided }, null, 2));
+}
+
+if (!JSON_OUT) {
+  console.log(`${B}retire${R} ${D}· threshold ${hours}h · ledger ${retiredLedgerPath()}${R}`);
+  for (const d of decided) {
+    const mark = d.retire ? `${Y}retire${R}` : `${G}hold  ${R}`;
+    const age = d.idleMs === null ? "?" : humanHours(d.idleMs);
+    console.log(`  ${mark} ${d.project.padEnd(18)} ${D}idle ${age.padEnd(7)} ${d.reason}${R}`);
+  }
+  if (!decided.length) console.log(`  ${D}no orchestrator panes in the session map${R}`);
+}
+
+if (!due.length) process.exit(0);
+if (!APPLY) {
+  if (!JSON_OUT) console.log(`\n${D}preview only — rerun with --yes to retire ${due.length} pane(s)${R}`);
+  process.exit(0);
+}
+
+for (const d of due) {
+  const out = await retirePane(d, { by: `retire@${host}`, exec: execFileSync, writeHandoff, buildSummary });
+  console.log(`  ${G}retired${R} ${d.project} ${D}${out.steps.join(" · ")}${R}`);
+  console.log(`    ${D}resume the thread with: claude --resume ${d.sid}${R}`);
+}

package/bin/state-bench.mjs

@@ -616,6 +616,13 @@ export function turnsBeforeCut(rows) {
   return cut >= 0 ? cut : (rows || []).length;
 }
 
+/** Was this run STOPPED, or did it reach its own end? §8.7 is a runway metric and runway only means
+ *  something for a run something cut short (#8066). Kept separate from turnsBeforeCut so that
+ *  function's return shape — and every caller reading it as a number — stays as it was. */
+export function wasCut(rows) {
+  return (rows || []).some(r => r?.cut === true);
+}
+
 /**
  * §8.7 — median turns-per-card on the state path vs the baseline path, over n ≥ MIN_CARDS.
  *
@@ -625,16 +632,35 @@ export function turnsBeforeCut(rows) {
  */
 export function turnsGate(pairs, { minCards = MIN_CARDS } = {}) {
   const usable = (pairs || []).filter(p => p.state?.length && p.baseline?.length)
-    .map(p => ({ card: p.card, state: turnsBeforeCut(p.state), baseline: turnsBeforeCut(p.baseline) }));
+    .map(p => ({
+      card: p.card,
+      state: turnsBeforeCut(p.state), baseline: turnsBeforeCut(p.baseline),
+      state_cut: wasCut(p.state), baseline_cut: wasCut(p.baseline),
+    }));
   const out = { cards: usable, n: usable.length, state_median: median(usable.map(u => u.state)), baseline_median: median(usable.map(u => u.baseline)), ok: false, code: null, message: "" };
   if (usable.length < minCards) {
     out.code = "CARRY_FORWARD";
     out.message = `n=${usable.length} card(s) with both paths recorded; §8.7 wants ≥${minCards}. The medians are recorded on the card and this gate CARRIES FORWARD to the next phase — it is not waived.`;
     return out;
   }
+  // Runway is only a question for a run something STOPPED. A state run that reached its own end has
+  // no runway problem, and scoring it against a baseline that WAS stopped inverts the metric — the
+  // better the state path does, the worse this reads. That is not hypothetical: the first real
+  // Phase-2a run finished card #6448 in ONE turn against a 149-turn baseline that never finished,
+  // and this gate called it FEWER_TURNS (#8066). The regression §8.7 exists to catch is the state
+  // path being cut EARLIER than the prose path, and that still fails below.
+  const stopped = usable.filter(u => u.state_cut);
+  out.cut_n = stopped.length;
+  if (!stopped.length) {
+    out.ok = true;
+    out.message = `no state run was forced to cut across n=${usable.length} card(s) — every card reached its own end, so there is no runway to compare (state median ${out.state_median} turns vs baseline ${out.baseline_median})`;
+    return out;
+  }
+  out.state_median = median(stopped.map(u => u.state));
+  out.baseline_median = median(stopped.map(u => u.baseline));
   out.ok = out.state_median >= out.baseline_median;
   out.code = out.ok ? null : "FEWER_TURNS";
-  out.message = `median turns before a forced cut — state ${out.state_median} vs baseline ${out.baseline_median} over n=${usable.length}`;
+  out.message = `median turns before a forced cut, over the ${stopped.length} card(s) whose state run WAS cut — state ${out.state_median} vs baseline ${out.baseline_median} (n=${usable.length} recorded)`;
   return out;
 }
 
@@ -645,7 +671,14 @@ export function evaluateRun({ project, card, repo = REPO, ...opts }) {
   const gates = [];
   const base = requireBaseline({ project, card, repo });
   gates.push({ n: 1, name: "baseline committed (§7.5)", ok: base.ok, code: base.code ?? null, message: base.ok ? `${base.doc} in HEAD · ${base.rows.length} baseline turns` : base.message });
-  if (!base.ok) return { ok: false, gates, halted: "gate 1", project, card };
+  // §7.5 exists so the >=5x CLAIM cannot be made against a number recorded after the fact, and that
+  // still holds: with no baseline the phase does NOT open and this run cannot pass. But halting here
+  // also blocked gates 3, 5 and 6 — which read the state run alone and never touch the baseline — so
+  // "does the evidence pipeline work at all" was unanswerable for any card without prose-path
+  // history. Since every card that HAS a baseline is now done, that was every card worth asking
+  // about. The unfalsifiability guard is kept where it belongs (gates 4 and 7, the comparisons) and
+  // the mechanism gates are allowed to report.
+  const noBaseline = !base.ok;
 
   const steps = readJsonl(runPath(project, card));
   if (!steps || !steps.length) {
@@ -658,8 +691,15 @@ export function evaluateRun({ project, card, repo = REPO, ...opts }) {
   const cache = checkCache(steps);
   gates.push({ n: 3, name: "cache read > 0 after the first step (§8.3)", ok: cache.ok, code: cache.code, message: cache.message });
 
-  const cost = costGate(steps, base.rows, { weights: opts.weights || null });
-  gates.push({ n: 4, name: `cost: flat curve, ≥${COST_FACTOR}× below baseline (§8.4)`, ok: cost.ok, code: cost.code, message: cost.message, numbers: cost });
+  // The ONE gate §7.5's guard actually protects: no recorded-first baseline, no ratio, no claim.
+  const cost = noBaseline ? null : costGate(steps, base.rows, { weights: opts.weights || null });
+  gates.push({ n: 4, name: `cost: flat curve, ≥${COST_FACTOR}× below baseline (§8.4)`,
+    ok: noBaseline ? false : cost.ok,
+    code: noBaseline ? "NO_BASELINE" : cost.code,
+    message: noBaseline
+      ? "no committed baseline for this card — the ≥5× claim is measured against a number recorded BEFORE the thing that judges it (§7.5), and there is none, so no ratio is computed and none is guessed"
+      : cost.message,
+    numbers: cost });
 
   const dist = disturbanceCheck(steps);
   gates.push({ n: 5, name: "zero recovery after a mid-run disturbance (§8.5)", ok: dist.ok, code: dist.code, message: dist.message, cases: dist.cases });
@@ -673,7 +713,7 @@ export function evaluateRun({ project, card, repo = REPO, ...opts }) {
 
   // §8.4's "at equal-or-better task success": the cache claim can hold while the card gets less far.
   const turns = turnsGate(collectTurnPairs(project));
-  gates.push({ n: 7, name: `turns per card, median over n≥${MIN_CARDS} (§8.7)`, ok: turns.ok, code: turns.code, message: turns.message, numbers: turns });
+  gates.push({ n: 7, name: `turns per card, median over n≥${MIN_CARDS} (§8.7)`, ok: noBaseline ? false : turns.ok, code: noBaseline ? "NO_BASELINE" : turns.code, message: noBaseline ? "no committed baseline for this card — §8.7 pairs the state path against the prose path and has nothing to pair with" : turns.message, numbers: turns });
 
   return { ok: gates.every(g => g.ok), gates, project, card, baseline: base, steps: steps.length };
 }

package/engine/bin/scrooge

@@ -553,14 +553,16 @@ def cmd_call(reg, args):
     try:
         resp = http_post(url, headers, payload)
     except urllib.error.HTTPError as e:
-        body = e.read().decode(errors="replace")[:500]
+        # ONE stderr line naming the status and the model (#6893): a provider body with
+        # newlines must not smear the ✗ across the caller's log — collapse, then clamp.
+        body = " ".join(e.read().decode(errors="replace").split())[:500]
         err(RED("🪙 scrooge ✗ %s/%s HTTP %s: %s" % (provider, model, e.code, body)))
         append_ledger({"ts": int(t0), "provider": provider, "model": model, "task": args.task,
                        "project": proj, "cwd": cwd,
                        "ok": False, "error": "HTTP %s" % e.code, "duration_ms": int((time.time()-t0)*1000)})
         raise SystemExit(2)
     except Exception as e:
-        err(RED("🪙 scrooge ✗ %s/%s: %s" % (provider, model, e)))
+        err(RED("🪙 scrooge ✗ %s/%s: %s" % (provider, model, " ".join(str(e).split()))))
         append_ledger({"ts": int(t0), "provider": provider, "model": model, "task": args.task,
                        "project": proj, "cwd": cwd,
                        "ok": False, "error": str(e), "duration_ms": int((time.time()-t0)*1000)})
@@ -586,6 +588,12 @@ def cmd_call(reg, args):
                              "prompt_preview": preview})
     err(ORANGE("🪙 scrooge ✓ %s/%s · %d→%d tok · ~$%.5f · %.1fs%s" %
                (provider, model, tin, tout, c, dt, (" · ledger#%d" % line_no) if line_no else "")))
+    # A genuinely empty model answer is a SUCCESS the caller must be able to tell from a
+    # failed call (#6893): exit 0, stdout stays EMPTY (not even a newline), and stderr
+    # carries the "empty answer" note — the ✗/exit-2 path is the only other possibility.
+    if not text.strip():
+        err(DIM("🪙 scrooge · empty answer"))
+        return
     sys.stdout.write(text)
     if not text.endswith("\n"):
         sys.stdout.write("\n")

package/hooks/handoff-now.mjs

@@ -14,11 +14,18 @@ try {
   const { file, record } = result;
   process.stderr.write(`[trantor] baton handoff written: ${file}\n`);
   await pingBus(basename(projectDir), record.id, conf);
-  if (maybeSpawn(projectDir, conf)) {                 // open the fresh session that takes over
+  // The handoff file goes in: a pane baton cannot be driven without it (#8089).
+  if (maybeSpawn(projectDir, conf, file)) {           // open the fresh session that takes over
     // AUTO baton: close the original ONLY when config.autoCloseOriginal is true; an auto-close must
-    // never kill an in-flight session, so the default leaves the original alive.
+    // never kill an in-flight session, so the default leaves the original alive. A pane baton
+    // replaces its own pane and resolves no window, so there is nothing here to arm.
     const armed = windowId ? armBatonClose(file, windowId, tty, conf, { auto: true }) : false;
     process.stderr.write(`[trantor] fresh session spawned${armed ? ` · baton-close armed for window ${windowId}` : " · original window left alive (auto-close off by default)"}\n`);
+  } else {
+    // #8089's second half: this used to be an `if` with no `else`, so a declined spawn printed
+    // NOTHING. The record was written, no successor came, and the only evidence was a handoff stuck
+    // at `written`. A path that decides not to act still has to say so.
+    process.stderr.write(`[trantor] NO successor session opened for ${basename(projectDir)} — handoff ${basename(file)} is written but unclaimed; open one to take over\n`);
   }
 } catch (e) {
   process.stderr.write(`[trantor] handoff-now error: ${e?.message || e}\n`);

package/hooks/lib/handoff.mjs

@@ -738,33 +738,130 @@ export async function pingBus(projectName, id, conf = readConfig()) {
 // Spawn a fresh same-agent session (macOS) that takes over via the handoff.
 // Default = ON (prompt with a timeout, default button "Open fresh session").
 // Disable with config.autoHandoffPrompt:false or env TRANTOR_NO_HANDOFF_SPAWN=1.
-export function maybeSpawn(projectDir, conf = readConfig()) {
+export function maybeSpawn(projectDir, conf = readConfig(), handoffFile = "", deps = {}) {
+  // Injection points, for the same reason spawnBaton has them: "A DRILL MUST BE ABLE TO SAY NO —
+  // a path that spawns windows needs an off switch or it cannot be tested honestly." maybeSpawn had
+  // none, so its pane branch was never drilled, and that is exactly where #8089 lived for weeks.
+  const _pane = deps.paneSurfaceEnv || paneSurfaceEnv;
+  const _spawnPane = deps.spawnPaneBaton || spawnPaneBaton;
+  const _hasPane = deps.hasOrchPane || hasOrchPane;
+  const _platform = deps.platform || process.platform;
+  const _env = deps.env || process.env;
+  const _log = deps.log || ((s) => process.stderr.write(s));
   try {
-    if (process.platform !== "darwin") return false;
-    if (process.env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
-    // #6074: a session in a hosted pane never gets a Terminal window — the pane is the successor
-    // surface, and the pane claims the handoff (trantor open) on its own.
-    if (paneSurfaceEnv()) {
-      process.stderr.write(`[trantor] session lives in herdr pane ${paneSurfaceEnv()} — no Terminal window; the pane claims the handoff\n`);
-      return false;
+    if (_platform !== "darwin") return false;
+    if (_env.TRANTOR_NO_HANDOFF_SPAWN === "1") return false;
+    // #8089: a pane session gets NO Terminal window — but it does get a successor. This used to
+    // return false on the theory that "the pane claims the handoff (trantor open) on its own",
+    // and for an ARMED baton nothing was driving that: /trantor:handoff always runs inside a turn,
+    // so it always arms, so this is always the path taken — and spawnPaneBaton, which the direct
+    // path (spawnBaton) calls right here, was never reached. The record was written and the session
+    // sat there. Witnessed on crebral-health 2026-09-19: written 00:18:58, unclaimed, original alive.
+    const paneId = _pane(_env);
+    if (paneId) {
+      if (!handoffFile) {
+        _log(`[trantor] pane ${paneId} needs the handoff file to pass the baton and none was given — no successor opened\n`);
+        return false;
+      }
+      const ok = _spawnPane(projectDir, handoffFile, paneId);
+      _log(`[trantor] herdr pane ${paneId}: ${ok ? "baton driver spawned — it replaces this pane in place" : "baton driver FAILED to spawn — no successor"}\n`);
+      return ok;
     }
     if (conf.autoHandoffPrompt === false) return false;
-    if (hasOrchPane(basename(projectDir))) {
-      process.stderr.write(`[trantor] orch pane hosts ${basename(projectDir)} — no Terminal window; the pane claims the handoff on its next open\n`);
-      return false;
+    if (_hasPane(basename(projectDir))) {
+      // Same correction as above for the cwd-keyed pane: drive the replacement, do not assume
+      // something else will. Without HERDR_PANE_ID the driver resolves the pane from crew-windows.
+      if (!handoffFile) {
+        _log(`[trantor] orch pane hosts ${basename(projectDir)} but no handoff file was given — no successor opened\n`);
+        return false;
+      }
+      const ok = _spawnPane(projectDir, handoffFile);
+      _log(`[trantor] orch pane hosts ${basename(projectDir)}: ${ok ? "baton driver spawned — it replaces the pane in place" : "baton driver FAILED to spawn — no successor"}\n`);
+      return ok;
     }
     const script = join(HERE, "..", "..", "bin", "handoff-prompt.sh");
-    if (!existsSync(script)) { process.stderr.write(`[trantor] handoff-prompt.sh missing\n`); return false; }
+    if (!existsSync(script)) { _log(`[trantor] handoff-prompt.sh missing\n`); return false; }
     const timeout = String(conf.handoffPromptTimeout || 25);
-    const child = spawn("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
-    child.unref();
+    // Injectable for the same reason the pane legs are: this line opens a REAL Terminal window, and
+    // a drill that reaches it opens one per run. That is not hypothetical — test-pane-baton-spawn's
+    // "no pane" case fell through to here and opened a window on every `npm test`, with a comment
+    // above it claiming the drill did not exercise this leg. Four of them were sitting on the
+    // operator's desktop before anyone noticed, and only a non-existent fixture path stopped each
+    // one from starting a live billable session.
+    const child = (deps.spawnPrompt || spawn)("/bin/bash", [script, projectDir, timeout], { detached: true, stdio: "ignore" });
+    if (child && typeof child.unref === "function") child.unref();
     return true;
   } 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/lib/project.mjs

@@ -190,6 +190,26 @@ export function writeOrchSession(project, sid, by = "unknown") {
     return true;
   } catch { return false; }
 }
+// Drop a project's row from the map. A session the map does not name cannot be resolved as a wake
+// recipient (bin/wake-nudge.mjs), which is how a retired pane stops buying turns (#8017).
+export function clearOrchSession(project, by = "unknown") {
+  try {
+    if (!project) return false;
+    const p = orchSessionsPath();
+    if (!existsSync(p)) return false;
+    const rows = readFileSync(p, "utf8").split("\n").filter(Boolean);
+    const prev = rows.find(r => r.split("\t")[0] === project)?.split("\t")[1] || "";
+    if (!prev) return false;
+    const kept = rows.filter(r => r.split("\t")[0] !== project);
+    writeFileSync(p, kept.length ? kept.join("\n") + "\n" : "");
+    try {
+      appendFileSync(join(busDir(), "orch-sessions.log"),
+        `${new Date().toISOString()}\t${project}\t${prev}\t-\t${by}\n`);
+    } catch {}
+    return true;
+  } catch { return false; }
+}
+
 function configPath() { return join(busDir(), "config.json"); }
 
 export function readConfig() {

package/lib/retire-panes.mjs

@@ -0,0 +1,205 @@
+// Retirement for ORCHESTRATOR panes (#8017). The reaper owns crew seats and tracking rows; an
+// orchestrator pane belongs to nobody, so an untouched one stays a wakeable target carrying
+// week-old context. This decides which panes may retire and performs the retirement with the
+// machinery that already exists — the handoff writer, the session map, herdr.
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, statSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { busDir, readConfig, orchSessionsPath, clearOrchSession, checkoutFor } from "./project.mjs";
+
+export const DEFAULT_RETIRE_HOURS = 24;
+const HOUR_MS = 60 * 60 * 1000;
+
+/** Where a deliberate retirement is recorded. Its absence is what makes a gone pane a CRASH. */
+export function retiredLedgerPath(bus = busDir()) { return join(bus, "retired-panes.jsonl"); }
+
+// Idle age alone never retires anything, so the threshold is only ever half the decision. 0 or a
+// negative value disables retirement outright — the operator's off switch.
+export function retireHours({ env = process.env, config = readConfig() } = {}) {
+  const raw = env.TRANTOR_PANE_RETIRE_HOURS ?? config?.paneRetireHours;
+  if (raw === undefined || raw === null || raw === "") return DEFAULT_RETIRE_HOURS;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : DEFAULT_RETIRE_HOURS;
+}
+
+export function retireEnabled(hours) { return Number.isFinite(hours) && hours > 0; }
+
+/** Every project→session row in the orchestrator map. One row per project, TAB separated. */
+export function orchSessionRows(path = orchSessionsPath()) {
+  try {
+    return readFileSync(path, "utf8").split("\n").flatMap(line => {
+      const [project, sid] = line.split("\t");
+      return project && sid && sid.trim() ? [{ project: project.trim(), sid: sid.trim() }] : [];
+    });
+  } catch { return []; }
+}
+
+/** The transcript for a session id, wherever its project slug lives (a renamed dir keeps the old). */
+export function transcriptFor(sid, { claudeProjectsDir = join(homedir(), ".claude", "projects") } = {}) {
+  if (!sid) return "";
+  try {
+    for (const d of readdirSync(claudeProjectsDir)) {
+      const t = join(claudeProjectsDir, d, `${sid}.jsonl`);
+      if (existsSync(t)) return t;
+    }
+  } catch {}
+  return "";
+}
+
+/** How long since this pane's thread was last written to. No transcript = no evidence = null. */
+export function idleMsFor(transcript, now = Date.now()) {
+  try { return Math.max(0, now - statSync(transcript).mtimeMs); } catch { return null; }
+}
+
+// LIVENESS DECIDES, age only qualifies. Every one of these holds a pane open at ANY age: a pane
+// mid-deploy read exactly like its five idle siblings on the morning this card was written.
+export function livenessHold({ turnInFlight = false, agentStatus = "", openContracts = 0, transcriptMissing = false, processState = "unknown" } = {}) {
+  if (transcriptMissing) return "no transcript on disk — nothing to hand off, and nothing proves it idle";
+  // A turn only counts as in flight while something is still running it. A transcript frozen
+  // mid-turn whose process is provably gone is a corpse, and a corpse is not work (#6668).
+  if (turnInFlight && processState !== "dead") return "mid-turn: the transcript's last row still owes a result";
+  if (["working", "busy"].includes(String(agentStatus))) return `herdr reports the agent ${agentStatus}`;
+  if (openContracts > 0) return `${openContracts} contract(s) in flight`;
+  return "";
+}
+
+/** The whole decision for one pane: retire, or hold with a reason a person can read. */
+export function retireDecision(pane, { hours, now = Date.now() } = {}) {
+  const idleMs = pane.idleMs;
+  const hold = livenessHold(pane);
+  if (hold) return { ...pane, retire: false, reason: hold };
+  if (idleMs === null) return { ...pane, retire: false, reason: "idle age unknown" };
+  const thresholdMs = hours * HOUR_MS;
+  if (idleMs < thresholdMs) return { ...pane, retire: false, reason: `idle ${humanHours(idleMs)} — under the ${hours}h threshold` };
+  return { ...pane, retire: true, reason: `idle ${humanHours(idleMs)}, no turn in flight, no open contract` };
+}
+
+export function humanHours(ms) {
+  const h = ms / HOUR_MS;
+  return h < 1 ? `${Math.round(ms / 60000)}m` : `${h.toFixed(h < 10 ? 1 : 0)}h`;
+}
+
+/** Has this project's pane already been retired? The ledger is the retired/crashed discriminator. */
+export function retiredRows(path = retiredLedgerPath()) {
+  try {
+    return readFileSync(path, "utf8").split("\n").flatMap(l => {
+      if (!l.trim()) return [];
+      try { return [JSON.parse(l)]; } catch { return []; }
+    });
+  } catch { return []; }
+}
+
+export function isRetired(sid, path = retiredLedgerPath()) {
+  return !!sid && retiredRows(path).some(r => r?.sid === sid);
+}
+
+export function recordRetirement(entry, path = retiredLedgerPath()) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + "\n");
+    return true;
+  } catch { return false; }
+}
+
+// ---- the live inputs -------------------------------------------------------
+function herdrJson(args, exec = execFileSync) {
+  try { return JSON.parse(exec("herdr", args, { encoding: "utf8", timeout: 15000 })); } catch { return null; }
+}
+
+/** herdr's view of this session: its pane id and what the agent is doing right now. */
+export function herdrAgentFor(sid, { exec = execFileSync } = {}) {
+  const agents = herdrJson(["agent", "list"], exec)?.result?.agents;
+  if (!Array.isArray(agents)) return { pane: "", status: "", proven: false };
+  const found = agents.find(a => a?.agent_session?.value === sid);
+  return { pane: found?.pane_id || "", status: found?.agent_status || "", proven: true };
+}
+
+export function crewWindowsPath(bus = busDir()) { return join(bus, "crew-windows.txt"); }
+
+/** The orchestrator pane herdr hosts for a project — last `orch` row wins, as the baton resolves it. */
+export function orchPaneRow(project, path = crewWindowsPath()) {
+  let pane = "";
+  try {
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      const f = line.split("\t");
+      if (f[0] === project && f[1] === "orch" && f[3] && f[3].trim()) pane = f[3].trim();
+    }
+  } catch {}
+  return pane;
+}
+
+/** Forget the tracked orch row for a retired pane, so no later `up`/`open` treats it as live. */
+export function dropOrchRow(project, path = crewWindowsPath()) {
+  try {
+    if (!existsSync(path)) return false;
+    const rows = readFileSync(path, "utf8").split("\n").filter(Boolean);
+    const kept = rows.filter(r => { const f = r.split("\t"); return !(f[0] === project && f[1] === "orch"); });
+    if (kept.length === rows.length) return false;
+    writeFileSync(path, kept.length ? kept.join("\n") + "\n" : "");
+    return true;
+  } catch { return false; }
+}
+
+/** Gather every orchestrator pane with the facts the decision needs. */
+export function collectPanes({
+  rows = orchSessionRows(), now = Date.now(), turnInFlight, sessionProcessState = () => "unknown",
+  herdrAgent = herdrAgentFor, contracts = () => 0, hostId = "",
+} = {}) {
+  return rows.map(({ project, sid }) => {
+    const transcript = transcriptFor(sid);
+    const agent = herdrAgent(sid);
+    return {
+      project, sid, transcript, pane: agent.pane || orchPaneRow(project),
+      agentStatus: agent.status,
+      idleMs: idleMsFor(transcript, now),
+      transcriptMissing: !transcript,
+      turnInFlight: transcript ? !!turnInFlight(transcript) : false,
+      processState: sessionProcessState(sid),
+      openContracts: contracts(hostId ? `${hostId}:${project}` : project),
+    };
+  });
+}
+
+// ---- the act ---------------------------------------------------------------
+// Order matters and is not negotiable: the handoff and the checkpoint are written FIRST, so a
+// failure anywhere after them still leaves the thread recoverable by `claude --resume <sid>`.
+export async function retirePane(pane, {
+  now = Date.now(), by = "retire", dry = false, exec = execFileSync,
+  writeHandoff, buildSummary, clearMap = clearOrchSession, ledger = retiredLedgerPath(),
+} = {}) {
+  const steps = [];
+  const projectDir = checkoutFor(pane.project) || "";
+  if (dry) {
+    return { ...pane, dry: true, steps: ["handoff", "checkpoint", "unmap", "close-pane"], projectDir };
+  }
+  let handoffFile = "";
+  const summary = buildSummary(pane.transcript);
+  const written = writeHandoff({
+    projectDir: projectDir || pane.project, projectName: pane.project, sessionId: pane.sid,
+    transcript: pane.transcript, trigger: "idle-retire", summary, force: true,
+  });
+  handoffFile = written?.file || "";
+  steps.push(handoffFile ? "handoff" : `handoff-skipped:${written?.reason || "unknown"}`);
+
+  // The checkpoint IS this row: it names the session id, so the conversation is resumable long
+  // after the pane is gone, and its presence is what tells a later boot the pane was retired.
+  const entry = {
+    ts: now, project: pane.project, sid: pane.sid, pane: pane.pane || "",
+    idleMs: pane.idleMs, reason: pane.reason || "", handoff: handoffFile,
+    resume: `claude --resume ${pane.sid}`, by, retired: true,
+  };
+  steps.push(recordRetirement(entry, ledger) ? "checkpoint" : "checkpoint-failed");
+
+  steps.push(clearMap(pane.project, by) ? "unmap" : "unmap-noop");
+
+  // Closing the pane is what stops herdr restoring it at the next boot: a pane that is no longer
+  // in the layout has nothing to resurrect, while a crashed one is still there.
+  if (pane.pane) {
+    const closed = herdrJson(["pane", "close", pane.pane], exec);
+    steps.push(closed && !closed.error ? "close-pane" : "close-pane-failed");
+    if (dropOrchRow(pane.project)) steps.push("drop-orch-row");
+  } else steps.push("close-pane-skipped:no-pane-id");
+
+  return { ...pane, steps, handoff: handoffFile, projectDir, entry };
+}

package/lib/state/derive.mjs

@@ -170,6 +170,12 @@ export function deriveState({ project, seat, card, worktree, handoffText, cardTi
     now: Number.isInteger(now) ? now : Math.floor(Date.now() / 1000),
     by: author,
     files: deriveFiles(worktree),
+    // This build is RECONSTRUCTION, not a seat asserting completion (#8068): a ✅ bullet in the
+    // predecessor's handoff records what it reported done. The evidence rule guards a live claim,
+    // and applying it here would drop the handoff's items on the floor. Credit is withheld the way
+    // the contract already says — deriveFiles marks every path verified:false and `verify` stays
+    // empty — so the successor must still re-earn evidence before anything NEW moves to done.
+    reconstructing: true,
   };
 
   const parsed = parseHandoffState(handoffText);

package/lib/state/driver.mjs

@@ -9,7 +9,7 @@ import { applyTurn } from "./apply.mjs";
 import { assemble } from "./assemble.mjs";
 import { runGate } from "./gate.mjs";
 import { promote } from "./promote.mjs";
-import { commit, gitTouched, hashPaths, readState, STALE } from "./store.mjs";
+import { commit, gitCommittedSince, gitHead, gitTouched, hashPaths, readState, STALE } from "./store.mjs";
 import { fromEnvelope } from "./cost.mjs";
 // The paths and budgets belong to §7.3/§7.5 and P7 published them from bin/state-bench.mjs; importing
 // upward is the deliberate inversion, since no number gets a second home. Its dispatch is guarded.
@@ -150,11 +150,16 @@ export function renderCardTail(rows, card) {
 /** TIER 1 (§4.8, the live half of R12): `touched` from git, and every credited path RE-HASHED with the
  *  credit dropped where the blob moved or the file is gone. Never sets `verified: true`.
  *  @returns {Record<string, {touched?: boolean, verified?: boolean}>} ctx.files for applyTurn */
-export function tier1Files(state, cwd, deps = {}) {
+export function tier1Files(state, cwd, deps = {}, headAtStart = null) {
   const touch = deps.gitTouched || gitTouched;
   const hash = deps.hashPaths || hashPaths;
+  const since = deps.gitCommittedSince || gitCommittedSince;
   const files = {};
-  for (const p of touch(cwd)) {
+  // Three readers, not the two §4.8 named. status and diff-HEAD both measure the working tree
+  // AGAINST HEAD, so a seat that commits carries HEAD along with its work and both read empty —
+  // which is why a turn that rewrote 8,000 lines across 4 commits recorded files:{} (#8069).
+  // The range from this step's starting HEAD is the half that sees committed work.
+  for (const p of [...touch(cwd), ...since(headAtStart, cwd)]) {
     if (typeof p !== "string" || !p || p.length > CAPS.PATH) continue;
     files[p] = { touched: true };
   }
@@ -232,7 +237,7 @@ export async function runStep({
 }) {
   const D = {
     readState, commit, applyTurn, runGate, promote, assemble,
-    gitTouched, hashPaths, appendJsonl,
+    gitTouched, gitCommittedSince, gitHead, hashPaths, appendJsonl,
     callCli: async () => ({ exit: 1, stdout: "" }),
     executeAction: () => undefined,
     ...deps,
@@ -275,6 +280,11 @@ export async function runStep({
   // §7.3's fallback ladder: a MALFORMED patch earns exactly one retry, with the rejection message
   // as the observation. An EVIDENCE rejection is not retried in-turn — the code was wrong, not the
   // grammar, and the seat needs a whole step to fix the code (§4.8).
+  // Where HEAD sat before this step ran anything (#8069). Captured ONCE, outside the retry loop:
+  // a malformed-output retry re-runs the CLI, and commits the first attempt already made are still
+  // this step's work — re-reading HEAD per attempt would silently drop them.
+  const headAtStart = (D.gitHead || gitHead)(cwd);
+
   for (;;) {
     // ---- 2. assemble ----
     trace.push("assemble");
@@ -292,7 +302,7 @@ export async function runStep({
 
     // ---- 4. TIER 1: git touch + credit expiry, EVERY turn, before the apply ----
     trace.push("tier1");
-    const files = tier1Files(state, cwd, D);
+    const files = tier1Files(state, cwd, D, headAtStart);
     ctx = { ...baseCtx, files };
 
     if (!parsed.turn) {

package/lib/state/store.mjs

@@ -83,6 +83,26 @@ function git(args, cwd) {
   }
 }
 
+/** The commit HEAD points at, or null when there is no repo or no commit yet (#8069). Tier 1 records
+ *  this BEFORE the CLI runs so it can later ask what the turn committed. */
+export function gitHead(cwd) {
+  const out = git(["rev-parse", "HEAD"], cwd);
+  const sha = out === null ? "" : out.trim();
+  return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+
+/** Paths changed by the COMMITS made since `sha`, NUL-separated (#8069). The two commands §4.8 named
+ *  — `git status --porcelain` and `git diff --name-only HEAD` — both measure the working tree against
+ *  HEAD, so a seat that commits moves HEAD along with its work and both come back empty. That is not a
+ *  corner case: every seat is told to commit early and often so a cut cannot erase it, which made tier 1
+ *  blind on the ordinary flow. A card that rewrote 8,000 lines across 4 commits recorded files:{}.
+ *  Degrades to [] on any git error, exactly like the other readers — recovery never throws. */
+export function gitCommittedSince(sha, cwd) {
+  if (!sha || !cwd) return [];
+  const out = git(["diff", "--name-only", "-z", `${sha}..HEAD`], cwd);
+  return out === null ? [] : out.split("\0").filter(Boolean);
+}
+
 /** Every path git says changed, from `git status -z -uall`: -z because `--short` C-quotes unusual paths
  *  and a mis-parse credits a file that does not exist; -uall so untracked dirs yield files. A rename yields both paths. */
 export function gitTouched(cwd) {

package/lib/state/validate.mjs

@@ -49,6 +49,40 @@ export function hasEvidence(state, item, ctx = {}) {
   return paths.every(p => ({ ...(state.files[p] || {}), ...(ctxFiles[p] || {}) }).verified === true);
 }
 
+/** The evidence gate for an item ARRIVING in `done`, by whichever op put it there (#8068). Returns the
+ *  rejection, or null when the item may land. `move → done` had this inline and `add … list:"done"` had
+ *  nothing at all, so a seat that completed an item in the turn it did the work — the ordinary flow —
+ *  walked past the verified-done rule entirely. Both doors now lead through this one check; `at` is the
+ *  only thing that differs, so the seat's rejection still names the op it actually wrote. */
+function arrivalInDone(state, item, ctx, at) {
+  if (!item || hasEvidence(state, item, ctx)) return null;
+  // The one exception, and it is reconstruction rather than assertion: derive.mjs rebuilds a
+  // WorkingState from a predecessor's prose handoff, where a ✅ bullet is a RECORD of what was
+  // reported done, not this seat claiming it now. Gating that would delete the handoff's content —
+  // #6528's failure exactly — and the rule it would be enforcing is already kept another way:
+  // CONTRACT-state.md, "a derived state carries no credit … the successor must re-earn its evidence
+  // before anything moves to done". The items arrive uncredited, so the successor still cannot ride
+  // route (b) on them. `ctx` is harness-supplied and a patch cannot write it (§3.0 write matrix),
+  // so a seat cannot set this for itself — which is the only reason a flag is safe here at all.
+  if (ctx.reconstructing === true) return null;
+  // The split that makes §4.8's one-retry bound a fact: a gate that ran and failed looks
+  // exactly like a gate that never ran, unless the driver says which happened.
+  if (ctx.gate_attempted) {
+    const g = ctx.gate_attempted;
+    return {
+      ...reject(ERR.UNVERIFIED_DONE, at,
+        `${at} → done rejected: the gate ran and did not pass (${g.cmd || "gate"}, exit ${g.exit}). ` +
+        `Fix the failure, then land it.`),
+      gate: { cmd: g.cmd, exit: g.exit, tail: g.tail },
+    };
+  }
+  return {
+    ...reject(ERR.NEEDS_GATE, at,
+      `${at} → done needs evidence: no gate has run at this state. Run it, then re-apply.`),
+    gate: { items: [item.id], paths: item.paths || [] },
+  };
+}
+
 /** Stages 1-3: normalised ops on success, the rejection the seat reads on failure. `ctx.gate_attempted`
  *  splits NEEDS_GATE from UNVERIFIED_DONE; without it §4.8's one-retry bound is false. */
 export function validateTurn(state, turn, ctx = {}) {
@@ -154,6 +188,10 @@ export function validateTurn(state, turn, ctx = {}) {
             `${list} is at CAPS.LIST (${CAPS.LIST}) and is a working list: overflow is a rejection, not a silent drop`);
         }
       }
+      if (list === "done") {
+        const bad = arrivalInDone(state, ev.item, ctx, `add:${item.id}`);
+        if (bad) return bad;
+      }
       listOf.set(item.id, list);
       itemOf.set(item.id, ev.item);
       lengths[list]++;
@@ -192,25 +230,8 @@ export function validateTurn(state, turn, ctx = {}) {
       return reject(ERR.CAP, `move:${id}`, `${to} is at CAPS.LIST (${CAPS.LIST})`);
     }
     if (to === "done") {
-      const item = itemOf.get(id);
-      if (item && !hasEvidence(state, item, ctx)) {
-        // The split that makes §4.8's one-retry bound a fact: a gate that ran and failed looks
-        // exactly like a gate that never ran, unless the driver says which happened.
-        if (ctx.gate_attempted) {
-          const g = ctx.gate_attempted;
-          return {
-            ...reject(ERR.UNVERIFIED_DONE, `move:${id}`,
-              `move ${id} → done rejected: the gate ran and did not pass (${g.cmd || "gate"}, exit ${g.exit}). ` +
-              `Fix the failure, then move it.`),
-            gate: { cmd: g.cmd, exit: g.exit, tail: g.tail },
-          };
-        }
-        return {
-          ...reject(ERR.NEEDS_GATE, `move:${id}`,
-            `move ${id} → done needs evidence: no gate has run at this state. Run it, then re-apply.`),
-          gate: { items: [id], paths: item.paths || [] },
-        };
-      }
+      const bad = arrivalInDone(state, itemOf.get(id), ctx, `move:${id}`);
+      if (bad) return bad;
     }
     listOf.set(id, to);
     lengths[from]--;

package/package.json

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