trantor 0.18.49 → 0.18.51

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.
@@ -247,7 +253,13 @@ export function lastRowMidTurn(transcriptPath) {
       const c = r?.message?.content;
       if (r.type === "assistant") {
         const blocks = Array.isArray(c) ? c : [];
-        if (blocks.some(b => b?.type === "tool_use")) return true;   // a result is still owed
+        const calls = blocks.filter(b => b?.type === "tool_use");
+        // #6668: a session parked in a LONE relay_wait is at its boundary. The wait is not work
+        // in flight — everything the turn did is already on disk, and the tool returns only when
+        // the bus speaks. Reading it as mid-turn armed the baton for the 17-minute boundary wait
+        // on a turn that never ends on its own; the pre-kill idle gate's deadline is what ends it.
+        if (calls.length && calls.every(isRelayWaitCall)) return false;
+        if (calls.length) return true;                               // a result is still owed
         return false;                                                // text-only → turn said its piece
       }
       // user row: #6528 follow-up — a trailing user row of ANY kind means in flight. A
@@ -263,6 +275,42 @@ export function lastRowMidTurn(transcriptPath) {
 export function turnInFlight(transcriptPath) {
   return subagentsActive(transcriptPath) || lastRowMidTurn(transcriptPath);
 }
+// The relay MCP's wait tool, by any server prefix (mcp__plugin_trantor_relay__relay_wait,
+// mcp__trantor__relay_wait, a bare relay_wait in a fixture).
+function isRelayWaitCall(block) {
+  return /(^|__)relay_wait$/.test(String(block?.name || ""));
+}
+
+// ---- does the transcript's session still have a process? (#6668) ------------------------------
+// Claude Code registers every live session in ~/.claude/sessions/<pid>.json ({pid, sessionId,
+// cwd, ...}) and removes the file at exit. The 09-07 12:35 chain armed on a transcript whose
+// session had exited at 12:16: the transcript's last row was a tool_result ("Connection closed"),
+// so the boundary gate read it as mid-turn and waited on a turn that no process would ever end.
+// A session with no live process IS at its boundary — its record can be written now.
+//   "live"    an entry names this session and its pid answers kill -0
+//   "dead"    the registry is in use (some other session is live) and none of its live entries
+//             name this session
+//   "unknown" no registry, or nothing in it is alive — say nothing, the boundary gate decides
+// The "dead" verdict needs another LIVE entry on purpose: a Claude Code too old to keep the
+// registry must not turn every mid-turn handoff into an immediate write.
+export function sessionProcessState(sessionId, { home = homedir() } = {}) {
+  if (!sessionId) return "unknown";
+  let files;
+  try { files = readdirSync(join(home, ".claude", "sessions")).filter(f => f.endsWith(".json")); } catch { return "unknown"; }
+  let anyLive = false;
+  for (const f of files) {
+    let entry;
+    try { entry = JSON.parse(readFileSync(join(home, ".claude", "sessions", f), "utf8")); } catch { continue; }
+    const pid = Number(entry?.pid) || Number(basename(f, ".json")) || 0;
+    if (!(pid > 0) || !pidAlive(pid)) continue;
+    anyLive = true;
+    if (String(entry?.sessionId || "") === sessionId) return "live";
+  }
+  return anyLive ? "dead" : "unknown";
+}
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; }
+}
 
 // ---- whole-session summary --------------------------------------------------
 function collectTurns(transcriptPath) {
@@ -406,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;
@@ -522,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

package/lib/duty-nudges.mjs

@@ -32,17 +32,15 @@ export function dutyEscalations(messages) {
 export function readDutyNudgeState(path) {
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    return parsed?.nudged instanceof Object && !Array.isArray(parsed.nudged)
-      ? parsed
-      : { version: 1, nudged: {} };
+    if (!(parsed?.nudged instanceof Object) || Array.isArray(parsed.nudged)) throw new Error("invalid nudged state");
+    if (!(parsed.planned instanceof Object) || Array.isArray(parsed.planned)) parsed.planned = {};
+    return parsed;
   } catch {
-    return { version: 1, nudged: {} };
+    return { version: 1, nudged: {}, planned: {} };
   }
 }
 
-export function planDutyNudges(messages, statePath) {
-  const state = readDutyNudgeState(statePath);
-  const items = dutyEscalations(messages).filter(item => !state.nudged[item.id]);
+function buildPlan(items, owner = "") {
   const targets = [];
   for (const item of items) {
     let target = targets.find(candidate => candidate.recipient === item.recipient);
@@ -52,7 +50,37 @@ export function planDutyNudges(messages, statePath) {
     }
     if (!target.ids.includes(item.id)) target.ids.push(item.id);
   }
-  return { items, targets };
+  return { items, targets, owner };
+}
+
+export function planDutyNudges(messages, statePath) {
+  const state = readDutyNudgeState(statePath);
+  const items = dutyEscalations(messages).filter(item => !state.nudged[item.id] && !state.planned[item.id]);
+  return buildPlan(items);
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export async function claimDutyNudges({ messages, statePath, owner, pid = process.pid, now = Date.now() }) {
+  let plan = buildPlan([], owner);
+  await withStateLock(statePath, state => {
+    for (const [id, claim] of Object.entries(state.planned)) {
+      if (now - Number(claim?.plannedAt || 0) > 30 * 60 * 1000 || !processAlive(Number(claim?.pid || 0))) {
+        delete state.planned[id];
+      }
+    }
+    const items = dutyEscalations(messages).filter(item => !state.nudged[item.id] && !state.planned[item.id]);
+    plan = buildPlan(items, owner);
+    for (const item of items) {
+      state.planned[item.id] = {
+        owner, pid, recipient: item.recipient, project: item.project, plannedAt: now,
+      };
+    }
+  });
+  return plan;
 }
 
 export function dutyNudgeDirective(plan) {
@@ -93,7 +121,8 @@ export function observedDutyNudgeIds(transcriptDir, sinceMs) {
         for (const use of uses) {
           const input = use.input || {};
           const text = String(input.message || input.content || "");
-          if (!text.startsWith("Trantor delivery nudge from the duty seat:")) continue;
+          if (!text.startsWith("Trantor delivery nudge from the duty seat:")
+            || !text.endsWith("This nudge carries no message content; the signed bus messages are the source of truth.")) continue;
           for (const id of idsIn(text)) ids.add(id);
         }
       }
@@ -106,7 +135,7 @@ function writeDutyNudgeState(path, state) {
   const entries = Object.entries(state.nudged)
     .sort((a, b) => Number(b[1]?.nudgedAt || 0) - Number(a[1]?.nudgedAt || 0))
     .slice(0, 5000);
-  const next = { version: 1, nudged: Object.fromEntries(entries) };
+  const next = { version: 1, nudged: Object.fromEntries(entries), planned: state.planned || {} };
   const temporary = `${path}.${process.pid}.tmp`;
   writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
   renameSync(temporary, path);
@@ -136,6 +165,7 @@ export async function recordDutyNudges({ plan, observedIds, statePath, now = Dat
   await withStateLock(statePath, state => {
     for (const item of nudged) {
       state.nudged[item.id] = { recipient: item.recipient, project: item.project, nudgedAt: now };
+      delete state.planned[item.id];
     }
   });
   return nudged;
@@ -148,5 +178,13 @@ export async function auditDutyNudges({ plan, observedIds, statePath, reportFail
     ids: target.ids.filter(id => !observedIds.has(id)),
   })).filter(target => target.ids.length);
   for (const target of missing) await reportFailure(target);
+  if (missing.length) {
+    const missingIds = new Set(missing.flatMap(target => target.ids));
+    await withStateLock(statePath, state => {
+      for (const id of missingIds) {
+        if (state.planned[id]?.owner === plan.owner) delete state.planned[id];
+      }
+    });
+  }
   return { missing, nudged };
 }

package/lib/state/apply.mjs

@@ -0,0 +1,170 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: ctx carries harness facts from the driver and set() merges model-supplied values; both are decoded here at the boundary rather than trusted. */
+// Trantor State — apply (TDD §4.2, stages 4-5). Validate, then apply to a CLONE, then the runtime
+// pass. Pure: `ctx` carries the clock and the harness facts, so this function is a function of its
+// arguments and nothing else.
+//
+// One apply point per turn is the whole crash-safety argument (§4.4): a turn killed mid-flight has
+// never partially applied a patch, because the patch is applied to a clone that is only returned
+// when every op passed.
+import { CAPS, LISTS, COMPACTING_LISTS, RUNTIME_EXT_KEYS, cloneState } from "./schema.mjs";
+import { validateTurn } from "./validate.mjs";
+
+/** Deep-merge one level, the `set` semantics of §3.2: null deletes an optional key. */
+function setField(state, field, value) {
+  const [root, sub] = String(field).split(".");
+  if (sub === undefined) {
+    if (value === null && root === "ext") { state.ext = {}; return; }
+    state[root] = value;
+    return;
+  }
+  if (value === null) { delete state[root][sub]; return; }
+  const cur = state[root][sub];
+  const mergeable = typeof cur === "object" && cur !== null && !Array.isArray(cur)
+    && typeof value === "object" && value !== null && !Array.isArray(value);
+  state[root][sub] = mergeable ? { ...cur, ...value } : value;
+}
+
+/** Keep `notes` under CAPS.NOTES by evicting whole lines from the FRONT — the tail is the recent
+ *  half, and a mid-string elision is #6528, the failure this whole schema exists to prevent. */
+function capNotes(notes) {
+  if (Buffer.byteLength(notes, "utf8") <= CAPS.NOTES) return notes;
+  const lines = notes.split("\n");
+  while (lines.length > 1 && Buffer.byteLength(lines.join("\n"), "utf8") > CAPS.NOTES) lines.shift();
+  let out = lines.join("\n");
+  while (out.length && Buffer.byteLength(out, "utf8") > CAPS.NOTES) out = out.slice(1);
+  return out;
+}
+
+/**
+ * The five-stage pipeline. `turn` is the TurnResult `{ patch, action }` — §4.8's driver snippet
+ * calls this slot `patch`, which is the same object under a shorter name.
+ *
+ * ctx: { now, by, verify, files, gate_attempted, gate }
+ *   - `verify` and `files` are harness facts from a gate that actually ran, never testimony.
+ *   - `gate_attempted` splits NEEDS_GATE from UNVERIFIED_DONE (§4.8).
+ *   - `gate` is the memo record runGate returned, written to ext._gate here so it lands through
+ *     the single apply point rather than as a side effect somewhere else.
+ *
+ * @returns {{ ok: true, state: object, promoted: object[] }
+ *          | { ok: false, code: string, at: string, message: string }}
+ */
+export function applyTurn(state, turn, ctx = {}) {
+  const v = validateTurn(state, turn, ctx);
+  if (!v.ok) return v;
+
+  // ---- stage 4: apply, in order, on a structural clone ----
+  const next = cloneState(state);
+  for (const op of v.ops) {
+    if (op.set) { setField(next, op.set.field, op.set.value); continue; }
+    if (op.add) { next[op.add.list].push(op.add.item); continue; }
+    if (op.remove) {
+      next[op.remove.list] = next[op.remove.list].filter(i => i.id !== op.remove.id);
+      continue;
+    }
+    const { id, from, to } = op.move;
+    const at = next[from].findIndex(i => i.id === id);
+    const [item] = next[from].splice(at, 1);
+    next[to].push(item);
+  }
+
+  // ---- stage 5: the runtime pass. Not model-visible, not model-writable. ----
+
+  // `verify` is REWRITTEN wholesale, never merged: it describes the gate that ran THIS turn, or
+  // nothing. That is what makes "evidence at the current rev" enforceable without a rev stamp on
+  // every field (§4.2).
+  next.verify = ctx.verify && typeof ctx.verify === "object" ? { ...ctx.verify } : {};
+
+  // Harness file facts: tier 1 sets `touched` from git, the gate sets `verified` + `hash`, and
+  // tier 1 EXPIRES a credit whose bytes have moved (R12). Setting evidence is the gate's
+  // privilege; expiring it belongs to the only thing that runs every turn.
+  for (const [path, fact] of Object.entries(ctx.files || {})) {
+    const cur = next.files[path] || { touched: false, verified: false };
+    const merged = { ...cur };
+    if (fact.touched !== undefined) merged.touched = fact.touched;
+    if (fact.verified !== undefined) merged.verified = fact.verified;
+    if (fact.blast_radius !== undefined) merged.blast_radius = fact.blast_radius;
+    if (fact.hash !== undefined) merged.hash = fact.hash;
+    if (merged.verified === false) delete merged.hash;
+    next.files[path] = merged;
+  }
+
+  if (ctx.gate && typeof ctx.gate === "object") next.ext._gate = { ...ctx.gate };
+  if (ctx.promoted !== undefined) next.ext._promoted = ctx.promoted;
+
+  // ---- compaction: history compacts, working lists never reach here (they were rejected) ----
+  for (const list of COMPACTING_LISTS) {
+    if (next[list].length > CAPS.LIST) {
+      const overflow = next[list].length - CAPS.LIST;
+      next[list] = next[list].slice(overflow);
+      if (list === "done") next.done_count += overflow;
+    }
+  }
+  next.done_count = Math.max(next.done_count, 0);
+  const paths = Object.keys(next.files);
+  if (paths.length > CAPS.FILES) {
+    // Drop the least interesting first: untouched and uncredited paths carry no evidence.
+    const rank = (p) => (next.files[p].verified ? 2 : next.files[p].touched ? 1 : 0);
+    const doomed = paths.sort((a, b) => rank(a) - rank(b)).slice(0, paths.length - CAPS.FILES);
+    for (const p of doomed) delete next.files[p];
+    next.files_count += doomed.length;
+  }
+
+  // ---- cap enforcement on content ----
+  next.task = next.task.slice(0, CAPS.TASK);
+  next.notes = capNotes(next.notes);
+  const extKeys = Object.keys(next.ext).filter(k => !RUNTIME_EXT_KEYS.includes(k));
+  for (const k of extKeys.slice(CAPS.EXT_KEYS)) delete next.ext[k];
+  let extBytes = Buffer.byteLength(JSON.stringify(
+    Object.fromEntries(Object.entries(next.ext).filter(([k]) => !RUNTIME_EXT_KEYS.includes(k))),
+  ), "utf8");
+  for (const k of extKeys.slice(0, CAPS.EXT_KEYS).reverse()) {
+    if (extBytes <= CAPS.EXT_BYTES) break;
+    extBytes -= Buffer.byteLength(JSON.stringify({ [k]: next.ext[k] }), "utf8");
+    delete next.ext[k];
+  }
+
+  next.cursor = {
+    turn: state.cursor.turn + 1,
+    ts: Number.isInteger(ctx.now) ? ctx.now : state.cursor.ts,
+    by: typeof ctx.by === "string" ? ctx.by : state.cursor.by,
+  };
+  next.rev = state.rev + 1;
+
+  return { ok: true, state: next, promoted: promotionPlan(state, next) };
+}
+
+/**
+ * The delta the board is allowed to see (TDD §4.7): what shipped, what is blocking, what the
+ * evidence says. `in_flight`/`next` are scratch and promote nothing — that churn is #6669's
+ * lesson. The promoter (P3) composes these into at most one card note per turn.
+ * @returns {{ kind: string, text: string }[]}
+ */
+export function promotionPlan(before, after) {
+  const out = [];
+  const wasDone = new Set(before.done.map(i => i.id));
+  for (const item of after.done) {
+    if (wasDone.has(item.id)) continue;
+    const ev = item.paths?.length ? ` (${item.paths.join(", ")})` : "";
+    out.push({ kind: "done", text: `${item.text}${ev}` });
+  }
+  const wasBlocked = new Map(before.blockers.map(i => [i.id, i]));
+  for (const item of after.blockers) {
+    if (!wasBlocked.has(item.id)) out.push({ kind: "blocker_added", text: item.text });
+  }
+  const nowBlocked = new Set(after.blockers.map(i => i.id));
+  for (const item of before.blockers) {
+    if (!nowBlocked.has(item.id)) out.push({ kind: "blocker_cleared", text: item.text });
+  }
+  for (const field of ["built", "tested", "observed"]) {
+    if (after.verify[field] === true && before.verify[field] !== true) {
+      const cmd = after.verify.cmd ? ` — ${after.verify.cmd}` : "";
+      out.push({ kind: "verify", text: `${field}${cmd}` });
+    }
+  }
+  return out;
+}
+
+/** Every id currently in the state, for the "arrays change only by id" property. */
+export function allIds(state) {
+  return LISTS.flatMap(l => state[l].map(i => i.id));
+}