trantor 0.18.50 → 0.18.51

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.50",
+  "version": "0.18.51",
   "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/crew-runner.mjs

@@ -469,10 +469,40 @@ async function parkSeat(reason, undelivered, resetHint = 0) {
     if (orch !== SESSION) await api("/send", { from: SESSION, to: orch, text, project: PROJ, kind: "alert" }).catch(() => {});
   }
   log(`\x1b[31mparked (${reason})${when ? ` — retrying after ${when}` : " — no reset time in the output; waiting for a restart"}\x1b[0m`);
+  // The two /send calls above are the whole escalation, and on 2026-09-09 that was not enough:
+  // the DUTY seat parked on a quota read, held 48 messages for 21.9 hours, and announced it over
+  // the very bus that had stopped moving, to an orchestrator that was idle and therefore could not
+  // receive it. The alarm for "the bus is stuck" cannot itself be a bus message. So park also
+  // rings a bell the operator can actually hear, out of band, once per park.
+  notifyOperator(`Trantor: ${SESSION} PARKED (${reason})`,
+    `${undelivered} message(s) held${when ? ` — retrying after ${when}` : ` — needs \`trantor up ${AGENT}\``}`);
   // No reset time means no timer can clear it: hold until the operator restarts the seat.
   return resetAt || Number.MAX_SAFE_INTEGER;
 }
 
+/**
+ * Reach the operator on a channel that does not depend on the bus, the hub, or a live session.
+ * Best-effort and strictly non-fatal: a seat must never die because a notifier is missing.
+ * Silence-able with TRANTOR_NO_DESKTOP_NOTIFY=1 for headless boxes and test runs.
+ */
+function notifyOperator(title, body) {
+  if (process.env.TRANTOR_NO_DESKTOP_NOTIFY === "1") return;
+  try {
+    // Always leave a durable trace first: a notification can be missed or suppressed, a file cannot.
+    // This is what `trantor doctor` reads, so the escalation survives a machine nobody was sitting at.
+    const alertsPath = join(homedir(), ".agent-bus", "alerts.jsonl");
+    appendFileSync(alertsPath, `${JSON.stringify({ ts: Date.now(), session: SESSION, title, body })}\n`);
+  } catch {}
+  try {
+    if (process.platform === "darwin") {
+      // osascript is present on every mac; no dependency to install and nothing to keep running.
+      const esc = (s) => String(s).replace(/["\\]/g, "\\$&");
+      spawnSync("osascript", ["-e", `display notification "${esc(body)}" with title "${esc(title)}"`],
+        { timeout: 5000, stdio: "ignore" });
+    }
+  } catch {}
+}
+
 // The seat's own balance rows, for the #6131 read: a stalled turn that printed nothing on a seat
 // whose plan is spent is exhaustion, not a crash. Bounded and best-effort — a slow provider API
 // must never hold up the failure path, and an unreachable one just leaves the reason as it was.
@@ -887,7 +917,24 @@ function isRunnerSession(session) {
   return /^[a-z0-9_.-]+$/.test(label) && !label.startsWith("hub:");
 }
 
+// A hub staleness alert describes a condition that was true for a moment: "#16909 has been
+// UNDELIVERED for 2m — go nudge someone". Acting on it 22 hours later is meaningless, and the queue
+// had no expiry, so on 2026-09-09 the duty seat's backlog became SELF-POISONING: the hub kept
+// noticing undelivered mail and sending more alerts, duty could not work them off, and a restart
+// faithfully redelivered 49 dead nudges and re-wedged the seat. 46 of those 49 were hub alerts, the
+// oldest 22.1 hours old, every one describing a two-minute condition.
+//
+// So these EXPIRE. Deliberately narrow: only messages the HUB generated about staleness, never a
+// message from a peer. A real contract is never dropped for being old — a seat that misses a
+// teammate's request is the failure this bus exists to prevent, and no backlog is worth causing it.
+const HUB_ALERT_TTL_MS = Number(process.env.TRANTOR_HUB_ALERT_TTL_MS || 30 * 60_000);
+const isExpiredHubAlert = (m) =>
+  m?.from === "hub:duty" &&
+  Number.isFinite(m?.ts) &&
+  Date.now() - m.ts > HUB_ALERT_TTL_MS;
+
 function shouldWake(message) {
+  if (isExpiredHubAlert(message)) return false;
   if (isReceipt(message) || isStatusBroadcast(message)) return false;
   // #6134: the SENDER decides. `wake:false` says "this is context, not a contract" — it batches
   // into the next turn's prompt like a broadcast and never buys a CLI session of its own.
@@ -957,8 +1004,14 @@ function askedExcerpt(message) {
   // broadcasts batched behind them. Restored from disk first: a runner that was killed mid-turn
   // (or a machine that rebooted) still owes those messages, and the hub will never send them again.
   const restored = loadPending();
+  // Say what the restore SHED, not just what it kept. A queue that quietly halves itself on restart
+  // is indistinguishable from one that lost real work, and this is the moment the expiry above
+  // actually bites — a wedged seat comes back carrying only what still means something.
+  const shed = restored.wake.filter(isExpiredHubAlert).length +
+               restored.bcast.filter(isExpiredHubAlert).length;
   let pendingWake = restored.wake.filter(shouldWake);
-  let pendingBcast = restored.bcast.filter(m => !isReceipt(m) && !isStatusBroadcast(m));
+  let pendingBcast = restored.bcast.filter(m => !isExpiredHubAlert(m) && !isReceipt(m) && !isStatusBroadcast(m));
+  if (shed) log(`\x1b[33mdropped ${shed} expired hub staleness alert(s) older than ${Math.round(HUB_ALERT_TTL_MS / 60000)}m — they describe conditions that have long since changed\x1b[0m`);
   let retryAt = 0;            // 0 = deliver at the next opportunity
   let deliveryFails = 0;      // consecutive failed attempts at the SAME pending batch
   if (pendingWake.length) log(`\x1b[33m${pendingWake.length} message(s) survived from a previous run — redelivering\x1b[0m`);
@@ -1183,6 +1236,21 @@ function askedExcerpt(message) {
       const parkReason = PARKING_REASONS.has(reason) ? reason : (lastTurnCut ? "time-box" : "api-error");
       if (PARKING_REASONS.has(reason) || deliveryFails >= 2) {
         retryAt = await parkSeat(parkReason, pendingWake.length, quotaReset);
+        // A supervised seat does not have to sit parked until someone notices. RUNNER_PARK_MAX_MS
+        // is set only by `trantor duty up`, which runs the seat under a launchd keepalive: past the
+        // ceiling, exit and let the supervisor restart it clean — a fresh process re-reads auth and
+        // redelivers the queue from disk, which is exactly what un-wedged the 2026-09-09 incident
+        // when the operator finally ran `trantor duty up` by hand 21.9 hours late.
+        // Unsupervised seats keep the old behaviour: exiting would just kill them for good.
+        const parkMax = Number(process.env.RUNNER_PARK_MAX_MS || 0);
+        if (parkMax > 0) {
+          const wakeIn = Math.max(0, Math.min(retryAt - Date.now(), parkMax));
+          log(`\x1b[33msupervised seat: exiting in ${Math.round(wakeIn / 1000)}s so the keepalive restarts it clean\x1b[0m`);
+          setTimeout(() => {
+            log("parked past the ceiling — exiting for the keepalive to relaunch");
+            process.exit(0);   // 0, not 1: this is a deliberate hand-off, not a crash
+          }, wakeIn).unref?.();
+        }
         await notifyAssigners(assigners,
           `⛔ your contract is PARKED on ${SESSION} (${parkReason}) — not retrying · asked: "${asked}"`);
         lastTurnAt = Date.now();

package/bin/doctor.mjs

@@ -3,7 +3,7 @@
 // Checks: runtime, hub, plugin, each CLI (installed? wired? AUTHENTICATED?), API keys,
 // quota profile, optional Scrooge brain. Prints a checklist with copy-paste fixes.
 //   node bin/doctor.mjs
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
@@ -304,6 +304,66 @@ prof?.providers && Object.keys(prof.providers).length
   ? ok(`quota profile set (${Object.entries(prof.providers).map(([k, v]) => `${k}=${v.plan}`).join(", ")})`)
   : warn("quota profile not set — the Advisor will assume API billing everywhere", `node ${join(ROOT, "bin", "profile.mjs")} set claude=max codex=plus deepseek=api …  (use YOUR real plans)`);
 
+// fleet — is the crew actually OPERATING, not just installed?
+//
+// Added 2026-09-09, because on that morning this command reported nine issues, every one about
+// provider keys and billing attribution, while the duty seat had been holding 48 undelivered
+// messages for 21.9 hours and the orchestrator had slept through a night of finished crew work.
+// Doctor checked whether credentials EXIST. Nothing checked whether the fleet was MOVING. These
+// two signals are both already on disk, written by the runner itself — nobody was reading them.
+section("the fleet (is it actually running?)");
+{
+  const busDir = join(H, ".agent-bus");
+  // 1. Undelivered queues. crew-runner persists pending-<agent>-<project>.json on every failed
+  //    delivery and unlinks it when the queue drains, so a file with an old head means mail is
+  //    stuck for that seat — whatever its process table says.
+  let stuck = 0;
+  const abandonedSeats = [];
+  try {
+    for (const f of readdirSync(busDir).filter(n => n.startsWith("pending-") && n.endsWith(".json"))) {
+      const j = read(join(busDir, f));
+      const held = [...(j?.wake || []), ...(j?.bcast || [])];
+      if (!held.length) continue;
+      const stamps = held.map(m => m?.ts).filter(Number.isFinite);
+      const oldest = stamps.length ? Math.min(...stamps) : j?.ts;
+      const hours = (Date.now() - oldest) / 3.6e6;
+      const seat = f.replace(/^pending-|\.json$/g, "");
+      // Three bands, because one flat warning per stuck queue is its own failure: this machine has
+      // leftovers from projects that ended weeks ago, and a doctor that cries about ten of them
+      // every run teaches you to skim past the one that matters. Under an hour is the retry ladder
+      // doing its job. Over a week is an abandoned seat, worth tidying, not worth alarming about.
+      // The band between is the live stall — the shape of the 2026-09-09 incident.
+      const abandoned = hours >= 24 * 7;
+      if (hours >= 1 && !abandoned) {
+        stuck++;
+        warn(`${seat}: ${held.length} message(s) undelivered, oldest ${hours.toFixed(1)}h old — mail is not moving`,
+          `the runner parks on quota/api failure and only a restart un-parks it: trantor up ${seat.split("-")[0]}   (duty: trantor duty up)`);
+      } else if (abandoned) {
+        abandonedSeats.push(`${seat} (${(hours / 24).toFixed(0)}d)`);
+      } else {
+        note(`${seat}: ${held.length} queued, oldest ${hours.toFixed(1)}h — within the retry ladder`);
+      }
+    }
+    if (abandonedSeats.length) {
+      note(`${abandonedSeats.length} abandoned queue(s) older than a week: ${abandonedSeats.join(", ")} — leftovers from finished work, safe to delete`);
+    }
+    if (!stuck) ok("no live seat is sitting on undelivered mail");
+  } catch { note(`no bus directory at ${busDir} yet — nothing has run`); }
+
+  // 2. Park alerts. notifyOperator appends one line per park, so a park that happened while nobody
+  //    was at the machine is still visible here afterwards — the point of writing it to disk.
+  try {
+    const alerts = readFileSync(join(busDir, "alerts.jsonl"), "utf8").trim().split("\n").filter(Boolean);
+    const recent = alerts.map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(a => a && Date.now() - a.ts < 24 * 3.6e6);
+    if (recent.length) {
+      const last = recent[recent.length - 1];
+      warn(`${recent.length} seat park alert(s) in the last 24h — most recent: ${last.title}`,
+        `read them: tail ~/.agent-bus/alerts.jsonl   — then restart the seat named above`);
+    } else ok("no seat has parked in the last 24h");
+  } catch { ok("no seat has parked in the last 24h"); }
+}
+
 say(issues ? `\n${issues} issue(s) — fix the → lines above, then re-run the doctor.` : "\nAll clear — open a claude session in any project and say: \"fire up the crew\".");
 // Must come BEFORE the exit — process.exit() here truncated the report entirely.
 if (JSON_MODE) console.log(JSON.stringify({ ...REPORT, issueCount: issues }));

package/bin/duty.mjs

@@ -245,6 +245,14 @@ if (cmd === "up") {
   const env = (() => {
     const e = { RELAY_URL: hub, RUNNER_RULES: RULES, CREW_KICKOFF: KICKOFF,
                 RUNNER_DUTY_NUDGES: "1",
+                // A parked seat waits for `trantor up`. That is right for a CODE seat — burning a
+                // plan re-sending the same contract helps nobody (#6270). It is wrong for DUTY,
+                // which is the seat every other seat's liveness runs through: on 2026-09-09 it
+                // parked on a quota read and sat holding 48 messages for 21.9 hours while the
+                // crew finished a night's work nobody gated. Duty is the one seat under a launchd
+                // keepalive, so it does not need to sit there — it can exit and let the supervisor
+                // bring it back clean, which also re-reads auth. 15 minutes, then hand over.
+                RUNNER_PARK_MAX_MS: "900000",
                 RUNNER_TITLE: "Trantor Duty Agent", RUNNER_ABOUT: ABOUT,
                 // launchd starts jobs with a MINIMAL Path — the resurrected seat could not find
                 // `claude` and every turn died exit 127 "missing-cli" (found live 2026-08-31,
@@ -360,6 +368,31 @@ if (cmd === "down") {
   process.exit(0);
 }
 
+/**
+ * Is duty actually moving mail? Read from the runner's own on-disk queue rather than trusting the
+ * process table. `pending-<agent>-<project>.json` is written on every failed delivery and deleted
+ * when the queue drains, so its existence means messages are held and its oldest entry says for how
+ * long. STALL_HOURS is deliberately well past the runner's own 15-minute retry ceiling: anything
+ * older than that is not a retry in progress, it is a parked seat nobody restarted.
+ */
+const STALL_HOURS = 1;
+function dutyHealth() {
+  const f = join(BUS, `pending-${AGENT}-trantor-duty.json`);
+  try {
+    const j = JSON.parse(readFileSync(f, "utf8"));
+    const wake = Array.isArray(j.wake) ? j.wake : [];
+    const bcast = Array.isArray(j.bcast) ? j.bcast : [];
+    const held = wake.length + bcast.length;
+    if (!held) return { held: 0, stalled: false, oldestHours: "0.0" };
+    const stamps = [...wake, ...bcast].map(m => m?.ts).filter(Number.isFinite);
+    const oldest = stamps.length ? Math.min(...stamps) : j.ts;
+    const hours = (Date.now() - oldest) / 3.6e6;
+    return { held, stalled: hours >= STALL_HOURS, oldestHours: hours.toFixed(1) };
+  } catch {
+    return { held: 0, stalled: false, oldestHours: "0.0" };   // no queue file = nothing held
+  }
+}
+
 // status
 {
   const pid = alivePid();
@@ -370,7 +403,41 @@ if (cmd === "down") {
   console.log("  whether a seat is still alive, and clears away dead runners. It never writes code");
   console.log("  and never edits your project files.  Stop it with: trantor duty down");
   console.log("");
-  console.log(pid ? `RUNNING (pid ${pid}) as ${SESSION}` : "NOT running");
+  // A pid is not health. This line used to read `pid ? "RUNNING" : "NOT running"`, and on 2026-09-09
+  // it said RUNNING for a seat whose last successful turn was 21.8 hours earlier and which was
+  // holding 48 undelivered messages, the oldest 21.9 hours old — the runner had parked itself
+  // waiting on a quota reset and only `trantor up` un-parks it. Nothing noticed, because the one
+  // command whose job is to answer "is duty working" was answering "does a process exist".
+  //
+  // The irony worth keeping: ten lines below, this same function already refuses to assume the hub
+  // feed is wired, on the grounds that "a running seat the hub isn't feeding looks identical to a
+  // working one from the outside". That rigour was applied to the hub and not to the seat itself.
+  //
+  // The queue is the honest signal because it survives the process: the runner persists it to
+  // pending-<agent>-<project>.json on every failed delivery, so a backlog with an old head means
+  // messages are not moving no matter what the process table says.
+  const health = dutyHealth();
+  if (!pid) {
+    console.log("NOT running");
+    // A backlog matters MORE when the seat is down, not less: those messages have nobody to deliver
+    // them and no retry ladder running. Reporting it only in the pid branch was the first version
+    // of this fix, and it hid exactly the case that needs saying out loud.
+    if (health.held) {
+      console.log(`  \x1b[31mand ${health.held} undelivered message(s) are held on disk, oldest ${health.oldestHours}h old\x1b[0m`);
+      console.log(`  → nothing will deliver them until the seat is back: trantor duty up`);
+    } else {
+      console.log("  queue empty — nothing is waiting");
+    }
+  }
+  else if (health.stalled) {
+    console.log(`\x1b[31mSTALLED\x1b[0m (pid ${pid}) as ${SESSION} — the process is up but mail is not moving`);
+    console.log(`  holding ${health.held} undelivered message(s), oldest ${health.oldestHours}h old`);
+    console.log(`  → the runner parks on quota/api failure and only a restart un-parks it: trantor duty up`);
+  } else if (health.held) {
+    console.log(`RUNNING (pid ${pid}) as ${SESSION} — draining ${health.held} queued message(s), oldest ${health.oldestHours}h old`);
+  } else {
+    console.log(`RUNNING (pid ${pid}) as ${SESSION} — queue empty`);
+  }
   console.log(existsSync(DUTY_PLIST)
     ? `keepalive: installed (${DUTY_LABEL}${process.platform === "darwin" ? (dutyLoaded() ? ", loaded" : ", not loaded in this session") : ""}) — launchd relaunches the seat after a crash or reboot`
     : "keepalive: NOT installed — a crash or reboot leaves the seat down (trantor duty up installs it)");

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, resolveHandoffSurface } from "../hooks/lib/handoff.mjs";
+import { spawnBaton, handoffMode, resolveHandoffSurface, attachState, resolveSeat, resolveHandoffCard } from "../hooks/lib/handoff.mjs";
 import { handoffDir } from "../lib/project.mjs";
 
 const baton = process.argv.includes("--baton");
@@ -63,6 +63,12 @@ if (latest) {
 // carries the same interface the hooks-side records have: transcript_path ("" — the summary IS
 // the model's own words), mode (attended|unattended, #5648).
 const rec = { id: `${name}-${stamp}`, project, projectName: name, machine: hostname(), trigger: baton ? "manual-baton" : "manual-skill", stamp: Number(stamp) || 0, summary: summary.trim() || "(empty)", transcript_path: "", mode: handoffMode(name), gitStatus: git, consumed: false, states: [{ state: "written", ts: Number(stamp) || 0, by: baton ? "manual-baton" : "manual-skill" }] };
+// The structured working state rides beside the prose (TDD §4.5), dark behind
+// TRANTOR_STATE_HANDOFF. The manual path gets it for the same reason the hook path does: this
+// record is what the successor loads, and `summary` here IS the model's own handoff — the richest
+// STATE block there is.
+const seat = resolveSeat(name);
+attachState(rec, { project: name, seat, card: resolveHandoffCard({ projectName: name, seat }), worktree: project });
 const file = join(dir, `${rec.id}.json`);
 writeFileSync(file, JSON.stringify(rec, null, 2));
 console.log(`handoff saved: ${file}`);

package/hooks/lib/handoff.mjs

@@ -18,7 +18,13 @@ import { fileURLToPath } from "node:url";
 import { deriveSubagentManifest } from "../../lib/subagent-manifest.mjs";
 import { signedPost } from "./api.mjs";
 import { loadAutonomy, resolveAutonomy } from "../../lib/autonomy.mjs";
-import { resolveProject, orchSessionsPath } from "../../lib/project.mjs";
+import { resolveProject, orchSessionsPath, hostId } from "../../lib/project.mjs";
+// Trantor State (TDD §4.5). Dark behind TRANTOR_STATE_HANDOFF: these are imported unconditionally
+// because they are pure modules with no side effects at load, and a lazy import would make
+// attachState async on a path that is deliberately synchronous.
+import { statePath, readState } from "../../lib/state/store.mjs";
+import { stateError } from "../../lib/state/schema.mjs";
+import { deriveState } from "../../lib/state/derive.mjs";
 
 // Writer and reader MUST resolve the same directory — see lib/project.mjs busDir(). This used to
 // honour only RELAY_DATA_DIR while the reader honoured neither override.
@@ -448,6 +454,109 @@ export function capSummary(text, cap = 4096) {
   return head + elide + tail;
 }
 
+// ---------------------------------------------------------------------------------------------
+// Trantor State — the structured field on the record (TDD §4.5). `summary` keeps being written
+// exactly as it is today; `state` rides beside it, validated on write and NEVER capped. That is
+// the whole fix for #6528: capSummary's mid-string elision ate the STATE section of the prose, and
+// the structured field cannot lose a member because the lossy operation is not applied to it.
+// ---------------------------------------------------------------------------------------------
+
+/** Dark by default. The prose path is untouched either way; this flag only decides whether the
+ *  structured field is built and rendered (TDD §4.5, "Fallback"). */
+export function stateHandoffEnabled(env = process.env) {
+  return ["1", "true", "on", "yes"].includes(String(env.TRANTOR_STATE_HANDOFF || "").toLowerCase());
+}
+
+/** The bus id of the seat writing this handoff — the same resolution sessionstart.mjs uses, so a
+ *  sidecar written under the runner's seat name is the one this path reads back. */
+export function resolveSeat(projectName, env = process.env) {
+  return env.RELAY_SESSION || (env.RELAY_AGENT ? `${env.RELAY_AGENT}:${projectName}` : `${hostId()}:${projectName}`);
+}
+
+/**
+ * Which card this handoff belongs to. `TRANTOR_CARD` wins — the crew runner knows the answer for
+ * certain and a lookup cannot beat being told. Otherwise ask the hub for this seat's newest open
+ * card, on the same 2s best-effort budget as the verify-gates fetch: a hub that is down costs the
+ * handoff a card number, never the handoff.
+ */
+export function resolveHandoffCard({ projectName, seat, env = process.env } = {}) {
+  const told = Number(env.TRANTOR_CARD);
+  if (Number.isInteger(told) && told > 0) return told;
+  try {
+    const out = execSync(`curl -s --max-time 2 ${JSON.stringify(relayUrl() + "/tasks?project=" + encodeURIComponent(projectName))}`, { encoding: "utf8", timeout: 2500 });
+    const tasks = JSON.parse(out).tasks || [];
+    const mine = tasks
+      .filter(t => t && Number.isInteger(t.id) && t.assignee === seat && ["doing", "testing"].includes(t.status))
+      .sort((a, b) => (a.status === b.status ? (b.updated || b.ts || 0) - (a.updated || a.ts || 0) : a.status === "doing" ? -1 : 1));
+    return mine.length ? mine[0].id : 0;
+  } catch { return 0; }
+}
+
+/**
+ * Attach the structured working state to a handoff record, from two sources in order:
+ *   1. the sidecar, when one exists (Phase 2a and after) — read, migrated, validated;
+ *   2. derived from git + the model's own STATE block, when none does (every Phase-1 handoff).
+ *
+ * Invalid or underivable state attaches `null` and logs. It NEVER blocks a handoff: a session at
+ * the context wall losing its baton because a state object would not validate is a far worse
+ * failure than a successor reading prose, which is exactly what it read before this field existed.
+ * @returns {object|null} the attached state
+ */
+export function attachState(rec, { project, seat, card, worktree, env = process.env } = {}) {
+  if (!stateHandoffEnabled(env)) return null;
+  try {
+    const name = project || rec?.projectName || "";
+    const who = seat || resolveSeat(name, env);
+    const no = Number.isInteger(card) ? card : 0;
+    const cwd = worktree || rec?.project || "";
+
+    let state = null;
+    const sidecar = statePath(who, no, name);
+    if (sidecar && existsSync(sidecar)) {
+      const r = readState(who, no, { project: name, cwd, recover: false });
+      if (!r.ok) throw new Error(`sidecar rejected: ${r.code} at ${r.at} — ${r.message}`);
+      state = r.state;
+    } else {
+      state = deriveState({ project: name, seat: who, card: no, worktree: cwd, handoffText: rec?.summary || "" });
+    }
+
+    const why = state ? stateError(state) : "no state could be derived";
+    if (why) throw new Error(why);
+    rec.state = state;
+    return state;
+  } catch (e) {
+    process.stderr.write(`[trantor] handoff state skipped: ${e?.message || e}\n`);
+    rec.state = null;
+    return null;
+  }
+}
+
+/** The state as the successor reads it: one compact block, bounded by the schema's own caps, with
+ *  the absence of credit stated rather than implied. */
+export function renderStateBlock(state) {
+  const line = (items) => items.map(i => `${i.id} ${i.text}${i.paths?.length ? ` [${i.paths.join(", ")}]` : ""}`).join("; ");
+  const rows = [];
+  if (state?.task) rows.push(`task: ${state.task}`);
+  for (const [list, label] of [["done", "done"], ["in_flight", "in flight"], ["next", "next"], ["blockers", "blockers"]]) {
+    const items = state?.[list] || [];
+    if (!items.length) continue;
+    const more = list === "done" && state.done_count ? ` (+${state.done_count} compacted)` : "";
+    rows.push(`${label} (${items.length}${more}): ${line(items)}`);
+  }
+  const files = state?.files || {};
+  const paths = Object.keys(files);
+  const verified = paths.filter(p => files[p].verified === true);
+  if (paths.length) rows.push(`files: ${paths.length} touched, ${verified.length} verified${verified.length ? ` — ${verified.join(", ")}` : ""}`);
+  const verify = Object.entries(state?.verify || {});
+  if (verify.length) rows.push(`verify: ${verify.map(([k, v]) => `${k}=${v}`).join(" ")}`);
+  if (!rows.length) return "";   // nothing to render is not a block with a warning in it
+  if (!verified.length) {
+    rows.push("NO PATH IS VERIFIED HERE — no gate ran at the handoff. Nothing in this block is evidence: re-earn it before you move anything to done.");
+  }
+  if (state.notes) rows.push(`notes: ${state.notes}`);
+  return rows.join("\n");
+}
+
 // How fresh a model-authored handoff must be before an automatic digest DEFERS to it: 15 minutes.
 // Older than that, the state it describes has likely moved on — compose fresh.
 const FRESH_HANDOFF_SEC = 15 * 60;
@@ -564,6 +673,11 @@ export function writeHandoff({ projectDir, sessionId, transcript, trigger, summa
     // The §5 machine's ledger: every transition appends here via appendHandoffState.
     states: [{ state: "written", ts: Number(stamp) || 0, by: sessionId || "" }],
   };
+  // The structured field (TDD §4.5), dark behind TRANTOR_STATE_HANDOFF. It is attached AFTER the
+  // record is built because it reads `summary` — the model's own STATE block is one of its two
+  // sources — and BEFORE the write, so the field lands in the same file the successor loads.
+  const seat = resolveSeat(projectName);
+  attachState(record, { project: projectName, seat, card: resolveHandoffCard({ projectName, seat }), worktree: projectDir });
   const file = join(HANDOFF_DIR, `${record.id}.json`);
   writeFileSync(file, JSON.stringify(record, null, 2));
   supersedeOlderHandoffs(projectName, record.id);

package/hooks/sessionstart.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 import { resolveProject, hostId, resolveHubInfo, knownProjects, nonSeatReason, 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 { 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";
@@ -569,6 +570,15 @@ try {
       }
       additionalContext += `\n`;
     }
+    // The structured working state (TDD §4.5), AFTER the recap instruction and above the prose: it
+    // is bounded by the schema's own caps, so unlike the summary it cannot have lost a member to an
+    // elision (#6528). A record without one — every handoff until the flag is on — renders nothing
+    // and the successor sees exactly today's prose handoff.
+    const stateBlock = renderStateBlock(handoff.state);
+    if (stateBlock) {
+      additionalContext += `## Working state (structured, card #${sanitize(String(handoff.state.card || 0))}, turn ${sanitize(String(handoff.state.cursor?.turn ?? 0))})\n`;
+      additionalContext += `${sanitize(stateBlock)}\n\n`;
+    }
     additionalContext += `## Handoff summary\n${sanitize(capHandoffSummary(handoff))}\n`;
     if (handoff.gitStatus) additionalContext += `\n## Git working-tree at handoff\n\`\`\`\n${sanitize(handoff.gitStatus)}\n\`\`\`\n`;
     // Sub-agent manifest: LIVE-primary, snapshot-as-fallback. The prior session may have had