@cohortapp/agent-sdk 2.11.14 → 2.12.0

package/lib/session/handoffs.mjs

@@ -0,0 +1,295 @@
+/**
+ * lib/session/handoffs.mjs — the cadence → main-session handoff ledger
+ * (design §3.4).
+ *
+ * When the main session is the live front door, an escalate/guarded cadence
+ * tick is not spawned as a `claude --print` sub-session; the consumer writes
+ * `state/session/handoffs/<tickId>.json` and marks the tick processed with
+ * `decision:"handed-to-session"`. The session's feed tails this directory,
+ * works the rendered prompt, and acks with `maestro session ack <tickId>`,
+ * which moves the file to `handoffs/done/`. The consumer's sweep expires any
+ * handoff past `deadlineAt` (default 30 min) so it can re-enqueue the tick on
+ * the legacy lane — a wedged session cannot starve a cadence.
+ *
+ * Durable writes go through lib/fs-atomic (tmp + fsync + rename). The clock
+ * and the fs are injectable; every function returns `{ok}` / data and never
+ * throws past its boundary.
+ *
+ * @module lib/session/handoffs
+ */
+
+import { join, basename } from "node:path";
+import * as nodeFs from "node:fs";
+import { writeJsonAtomic as writeJsonAtomicDefault } from "../fs-atomic.mjs";
+
+/** A handoff not acked within this window is expired and re-enqueued. */
+export const DEFAULT_HANDOFF_DEADLINE_MS = 30 * 60_000;
+/** done/ records and rendered prompts older than this are pruned. */
+export const DEFAULT_HANDOFF_RETENTION_MS = 7 * 24 * 60 * 60_000;
+/** Handoff directory (relative to the agent root). */
+export const HANDOFFS_RELATIVE = "state/session/handoffs";
+
+// A tick id is a bus event id (`evt-<iso>-<hex>`) or a test literal. It is a
+// path segment, so anything that could climb out of the directory is refused.
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+function safeId(id) {
+  const s = String(id || "").trim();
+  return SAFE_ID.test(s) && !s.includes("..") ? s : null;
+}
+
+function iso(ms) { return new Date(ms).toISOString(); }
+function nowOf(o) { return typeof o.now === "number" ? o.now : Date.now(); }
+
+/**
+ * Resolve the handoff paths under an agent root.
+ * @param {string} agentRoot
+ * @returns {{dir:string, done:string, prompts:string}}
+ */
+export function handoffPaths(agentRoot) {
+  const dir = join(agentRoot, HANDOFFS_RELATIVE);
+  return { dir, done: join(dir, "done"), prompts: join(dir, "prompts") };
+}
+
+/**
+ * Write a handoff. Idempotent: an existing file for the tick is left as-is
+ * and reported (`existing:true`).
+ *
+ * @param {string} agentRoot
+ * @param {{tickId:string, cadence:string, mode?:string, promptPath?:string, metadata?:object, deadlineAt?:string}} handoff
+ * @param {{now?:number, deadlineMs?:number, fs?:object, writeJson?:Function}} [deps]
+ * @returns {{ok:true, path:string, existing?:boolean, handoff:object}|{ok:false, error:string}}
+ */
+export function writeHandoff(agentRoot, handoff, deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const writeJson = deps.writeJson || writeJsonAtomicDefault;
+  if (!handoff || typeof handoff !== "object") return { ok: false, error: "handoff object required" };
+  const tickId = safeId(handoff.tickId);
+  if (!tickId) return { ok: false, error: "tickId required" };
+  const cadence = String(handoff.cadence || "").trim();
+  if (!cadence) return { ok: false, error: "cadence required" };
+  const now = nowOf(deps);
+  const deadlineMs = Number.isFinite(deps.deadlineMs) && deps.deadlineMs > 0 ? deps.deadlineMs : DEFAULT_HANDOFF_DEADLINE_MS;
+  const paths = handoffPaths(agentRoot);
+  const path = join(paths.dir, `${tickId}.json`);
+  try {
+    if (fs.existsSync(path)) {
+      let existing = null;
+      try { existing = JSON.parse(fs.readFileSync(path, "utf-8")); } catch { existing = null; /* unreadable — still not ours to clobber */ }
+      return { ok: true, path, existing: true, handoff: existing };
+    }
+    const record = {
+      tickId,
+      cadence,
+      mode: handoff.mode || "escalate",
+      promptPath: handoff.promptPath || null,
+      enqueuedAt: handoff.enqueuedAt || iso(now),
+      deadlineAt: handoff.deadlineAt || iso(now + deadlineMs),
+      metadata: handoff.metadata && typeof handoff.metadata === "object" ? handoff.metadata : {},
+      status: "open",
+    };
+    fs.mkdirSync(paths.dir, { recursive: true });
+    writeJson(path, record);
+    return { ok: true, path, handoff: record };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+function readJson(fs, path) {
+  try { const v = JSON.parse(fs.readFileSync(path, "utf-8")); return v && typeof v === "object" ? v : null; }
+  catch { return null; /* corrupt or vanished — skipped, never fatal */ }
+}
+
+/**
+ * Open handoffs, oldest first. Corrupt files are skipped.
+ * @param {string} agentRoot
+ * @param {{fs?:object}} [deps]
+ * @returns {object[]} each record carries `path`
+ */
+export function listHandoffs(agentRoot, deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const { dir } = handoffPaths(agentRoot);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return []; /* no handoffs yet */ }
+  const out = [];
+  for (const n of names) {
+    if (!n.endsWith(".json")) continue;
+    const path = join(dir, n);
+    const rec = readJson(fs, path);
+    if (!rec || !rec.tickId) continue;
+    out.push({ ...rec, path });
+  }
+  out.sort((a, b) => String(a.enqueuedAt || "").localeCompare(String(b.enqueuedAt || "")) || a.tickId.localeCompare(b.tickId));
+  return out;
+}
+
+/**
+ * One open handoff by tick id, or null.
+ * @param {string} agentRoot
+ * @param {string} tickId
+ * @param {{fs?:object}} [deps]
+ * @returns {object|null}
+ */
+export function readHandoff(agentRoot, tickId, deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const id = safeId(tickId);
+  if (!id) return null;
+  const path = join(handoffPaths(agentRoot).dir, `${id}.json`);
+  const rec = readJson(fs, path);
+  return rec ? { ...rec, path } : null;
+}
+
+/** Move an open handoff into done/ with a terminal status. */
+function retire(agentRoot, rec, patch, deps) {
+  const fs = deps.fs || nodeFs;
+  const writeJson = deps.writeJson || writeJsonAtomicDefault;
+  const paths = handoffPaths(agentRoot);
+  const src = join(paths.dir, `${rec.tickId}.json`);
+  const dst = join(paths.done, `${rec.tickId}.json`);
+  fs.mkdirSync(paths.done, { recursive: true });
+  const { path: _p, ...clean } = rec;
+  void _p;
+  writeJson(dst, { ...clean, ...patch });
+  try { fs.unlinkSync(src); } catch { /* already gone — the done/ record is what matters */ }
+  return dst;
+}
+
+/**
+ * Ack a handoff: the session finished (or consciously declined) the work.
+ * Moves the record to done/ with `status:"acked"`. Idempotent.
+ *
+ * @param {string} agentRoot
+ * @param {string} tickId
+ * @param {{resultPath?:string, note?:string, now?:number, fs?:object, writeJson?:Function}} [o]
+ * @returns {{ok:true, path:string, already?:boolean}|{ok:false, error:string}}
+ */
+export function ackHandoff(agentRoot, tickId, o = {}) {
+  const fs = o.fs || nodeFs;
+  const id = safeId(tickId);
+  if (!id) return { ok: false, error: "invalid tickId" };
+  const paths = handoffPaths(agentRoot);
+  try {
+    const rec = readHandoff(agentRoot, id, { fs });
+    if (!rec) {
+      const donePath = join(paths.done, `${id}.json`);
+      if (fs.existsSync(donePath)) return { ok: true, path: donePath, already: true };
+      return { ok: false, error: "not-found" };
+    }
+    const path = retire(agentRoot, rec, {
+      status: "acked",
+      ackedAt: iso(nowOf(o)),
+      resultPath: o.resultPath || null,
+      ...(o.note ? { note: String(o.note) } : {}),
+    }, o);
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Expire every open handoff past its deadline (or, for a record without one,
+ * past enqueuedAt + default). Each is moved to done/ with `status:"expired"`
+ * and returned so the caller can re-enqueue the tick with
+ * `metadata.handoffTimedOut=true`.
+ *
+ * ORDER MATTERS. `onExpire(record)` — the caller's re-enqueue — runs BEFORE
+ * the record is retired; a hook that throws or returns `false` leaves the
+ * handoff open (reported under `failed`) so the next sweep tries again. The
+ * tick is only ever gone from the ledger once it is back on the bus.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, deadlineMs?:number, fs?:object, writeJson?:Function, onExpire?:(rec:object)=>boolean|void}} [o]
+ * @returns {{expired:object[], failed:{tickId:string, error:string}[], scanned:number}}
+ */
+export function expireHandoffs(agentRoot, o = {}) {
+  const now = nowOf(o);
+  const deadlineMs = Number.isFinite(o.deadlineMs) && o.deadlineMs > 0 ? o.deadlineMs : DEFAULT_HANDOFF_DEADLINE_MS;
+  const onExpire = typeof o.onExpire === "function" ? o.onExpire : null;
+  const open = listHandoffs(agentRoot, o);
+  const expired = [];
+  const failed = [];
+  for (const rec of open) {
+    let deadline = Date.parse(rec.deadlineAt || "");
+    if (!Number.isFinite(deadline)) {
+      const enq = Date.parse(rec.enqueuedAt || "");
+      deadline = Number.isFinite(enq) ? enq + deadlineMs : now; // undated → expire now
+    }
+    if (now < deadline) continue;
+    const { path: _p, ...clean } = rec;
+    void _p;
+    if (onExpire) {
+      let ok = false;
+      let error = "onExpire returned false";
+      try { ok = onExpire(clean) !== false; } catch (err) { ok = false; error = err && err.message ? err.message : String(err); }
+      if (!ok) { failed.push({ tickId: rec.tickId, error }); continue; }
+    }
+    try {
+      retire(agentRoot, rec, { status: "expired", expiredAt: iso(now) }, o);
+      expired.push(clean);
+    } catch { /* leave it for the next sweep; a failed move is not a lost tick */ }
+  }
+  return { expired, failed, scanned: open.length };
+}
+
+/**
+ * Ledger hygiene. Removes done/ records whose terminal time (ackedAt /
+ * expiredAt, else enqueuedAt, else mtime) is older than `retentionMs`
+ * (default 7 d), and rendered prompts under prompts/ older than the window
+ * that no OPEN handoff references. Never touches an open handoff or its
+ * prompt. Best-effort; returns what it removed.
+ *
+ * @param {string} agentRoot
+ * @param {{now?:number, retentionMs?:number, fs?:object}} [o]
+ * @returns {{removed:{done:string[], prompts:string[]}}}
+ */
+export function pruneHandoffs(agentRoot, o = {}) {
+  const fs = o.fs || nodeFs;
+  const now = nowOf(o);
+  const retentionMs = Number.isFinite(o.retentionMs) && o.retentionMs > 0 ? o.retentionMs : DEFAULT_HANDOFF_RETENTION_MS;
+  const cutoff = now - retentionMs;
+  const paths = handoffPaths(agentRoot);
+  const removed = { done: [], prompts: [] };
+  const mtimeOf = (p) => { try { return fs.statSync(p).mtimeMs; } catch { return null; } };
+  const referenced = new Set(listHandoffs(agentRoot, { fs }).map((h) => h.promptPath && basename(String(h.promptPath))).filter(Boolean));
+  const dropPrompt = (n) => {
+    if (!n || referenced.has(n) || removed.prompts.includes(n)) return;
+    try { fs.unlinkSync(join(paths.prompts, n)); removed.prompts.push(n); } catch { /* absent or raced away — fine */ }
+  };
+  // done/ — by terminal timestamp, mtime for a record that cannot be read.
+  // A pruned record takes its rendered prompt with it.
+  let names = [];
+  try { names = fs.readdirSync(paths.done); } catch { names = []; }
+  for (const n of names) {
+    if (!n.endsWith(".json")) continue;
+    const path = join(paths.done, n);
+    const rec = readJson(fs, path);
+    let at = rec ? Date.parse(rec.ackedAt || rec.expiredAt || rec.enqueuedAt || "") : NaN;
+    if (!Number.isFinite(at)) at = mtimeOf(path);
+    if (at == null || at >= cutoff) continue;
+    try { fs.unlinkSync(path); removed.done.push(n); } catch { continue; /* raced away — fine */ }
+    if (rec && rec.promptPath) dropPrompt(basename(String(rec.promptPath)));
+  }
+  // prompts/ — old orphans no open handoff still points at.
+  try { names = fs.readdirSync(paths.prompts); } catch { names = []; }
+  for (const n of names) {
+    if (referenced.has(n) || removed.prompts.includes(n)) continue;
+    const at = mtimeOf(join(paths.prompts, n));
+    if (at == null || at >= cutoff) continue;
+    dropPrompt(n);
+  }
+  return { removed };
+}
+
+export default {
+  DEFAULT_HANDOFF_DEADLINE_MS,
+  DEFAULT_HANDOFF_RETENTION_MS,
+  HANDOFFS_RELATIVE,
+  handoffPaths,
+  writeHandoff,
+  listHandoffs,
+  readHandoff,
+  ackHandoff,
+  expireHandoffs,
+  pruneHandoffs,
+};

package/lib/session/handoffs.test.mjs

@@ -0,0 +1,183 @@
+/**
+ * handoffs.test.mjs — the cadence → session handoff ledger (design §3.4).
+ *
+ * `state/session/handoffs/<tickId>.json` is written by the cadence consumer
+ * when a live session takes an escalate/guarded tick, acked by
+ * `maestro session ack <tickId>` (moved to `done/`), and expired by the
+ * consumer's sweep once past `deadlineAt`. Clock injected everywhere.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync, utimesSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  DEFAULT_HANDOFF_DEADLINE_MS,
+  handoffPaths,
+  writeHandoff,
+  listHandoffs,
+  readHandoff,
+  ackHandoff,
+  expireHandoffs,
+  pruneHandoffs,
+  DEFAULT_HANDOFF_RETENTION_MS,
+} from "./handoffs.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00.000Z");
+
+function root() { return mkdtempSync(join(tmpdir(), "maestro-handoffs-")); }
+function rm(dir) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ } }
+
+test("writeHandoff: lands <tickId>.json with enqueuedAt + deadlineAt (30 min default), idempotent", () => {
+  const dir = root();
+  try {
+    const r = writeHandoff(dir, { tickId: "evt-1", cadence: "goal-steward", mode: "escalate", promptPath: "/p/goal.md" }, { now: T0 });
+    assert.equal(r.ok, true);
+    assert.equal(r.path, join(handoffPaths(dir).dir, "evt-1.json"));
+    const on = JSON.parse(readFileSync(r.path, "utf-8"));
+    assert.equal(on.tickId, "evt-1");
+    assert.equal(on.cadence, "goal-steward");
+    assert.equal(on.mode, "escalate");
+    assert.equal(on.promptPath, "/p/goal.md");
+    assert.equal(on.enqueuedAt, new Date(T0).toISOString());
+    assert.equal(on.deadlineAt, new Date(T0 + DEFAULT_HANDOFF_DEADLINE_MS).toISOString());
+    // Second write for the same tick is a no-op that reports the existing file.
+    const again = writeHandoff(dir, { tickId: "evt-1", cadence: "goal-steward", mode: "escalate", promptPath: "/p/other.md" }, { now: T0 + 5 });
+    assert.equal(again.ok, true);
+    assert.equal(again.existing, true);
+    assert.equal(JSON.parse(readFileSync(r.path, "utf-8")).promptPath, "/p/goal.md");
+  } finally { rm(dir); }
+});
+
+test("writeHandoff: refuses a handoff without a tickId/cadence — returns {ok:false}, never throws", () => {
+  const dir = root();
+  try {
+    assert.equal(writeHandoff(dir, { cadence: "x" }).ok, false);
+    assert.equal(writeHandoff(dir, { tickId: "evt-9" }).ok, false);
+    assert.equal(writeHandoff(dir, null).ok, false);
+    // Path-traversal-shaped ids never escape the directory.
+    assert.equal(writeHandoff(dir, { tickId: "../../etc", cadence: "x", promptPath: "/p" }).ok, false);
+  } finally { rm(dir); }
+});
+
+test("listHandoffs / readHandoff: open handoffs sorted by enqueuedAt; corrupt files skipped; done/ excluded", () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-b", cadence: "b", mode: "escalate", promptPath: "/b" }, { now: T0 + 1000 });
+    writeHandoff(dir, { tickId: "evt-a", cadence: "a", mode: "guarded", promptPath: "/a" }, { now: T0 });
+    writeFileSync(join(handoffPaths(dir).dir, "junk.json"), "{nope");
+    mkdirSync(handoffPaths(dir).done, { recursive: true });
+    writeFileSync(join(handoffPaths(dir).done, "evt-z.json"), JSON.stringify({ tickId: "evt-z" }));
+    const open = listHandoffs(dir);
+    assert.deepEqual(open.map((h) => h.tickId), ["evt-a", "evt-b"]);
+    assert.equal(readHandoff(dir, "evt-a").cadence, "a");
+    assert.equal(readHandoff(dir, "evt-nope"), null);
+    assert.deepEqual(listHandoffs(join(dir, "does-not-exist")), []);
+  } finally { rm(dir); }
+});
+
+test("ackHandoff: moves the handoff to done/ with ackedAt + result; idempotent; unknown → not-found", () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-1", cadence: "c", mode: "escalate", promptPath: "/p" }, { now: T0 });
+    const r = ackHandoff(dir, "evt-1", { resultPath: "/tmp/out.md", now: T0 + 60_000 });
+    assert.equal(r.ok, true);
+    assert.equal(existsSync(join(handoffPaths(dir).dir, "evt-1.json")), false);
+    const done = JSON.parse(readFileSync(join(handoffPaths(dir).done, "evt-1.json"), "utf-8"));
+    assert.equal(done.status, "acked");
+    assert.equal(done.ackedAt, new Date(T0 + 60_000).toISOString());
+    assert.equal(done.resultPath, "/tmp/out.md");
+    assert.deepEqual(listHandoffs(dir), []);
+    const again = ackHandoff(dir, "evt-1", { now: T0 + 70_000 });
+    assert.equal(again.ok, true);
+    assert.equal(again.already, true);
+    const missing = ackHandoff(dir, "evt-404", { now: T0 });
+    assert.equal(missing.ok, false);
+    assert.equal(missing.error, "not-found");
+    assert.equal(ackHandoff(dir, "../x", { now: T0 }).ok, false);
+  } finally { rm(dir); }
+});
+
+test("expireHandoffs: past-deadline handoffs are moved to done/ as expired and returned; fresh ones stay", () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-old", cadence: "goal-steward", mode: "escalate", promptPath: "/p", metadata: { reason: "x" } }, { now: T0 });
+    writeHandoff(dir, { tickId: "evt-new", cadence: "inbox-processor", mode: "guarded", promptPath: "/q" }, { now: T0 + 20 * 60_000 });
+    const r = expireHandoffs(dir, { now: T0 + DEFAULT_HANDOFF_DEADLINE_MS + 1 });
+    assert.equal(r.scanned, 2);
+    assert.deepEqual(r.expired.map((h) => h.tickId), ["evt-old"]);
+    assert.equal(r.expired[0].cadence, "goal-steward");
+    assert.deepEqual(r.expired[0].metadata, { reason: "x" });
+    assert.deepEqual(listHandoffs(dir).map((h) => h.tickId), ["evt-new"]);
+    const done = JSON.parse(readFileSync(join(handoffPaths(dir).done, "evt-old.json"), "utf-8"));
+    assert.equal(done.status, "expired");
+    assert.equal(done.expiredAt, new Date(T0 + DEFAULT_HANDOFF_DEADLINE_MS + 1).toISOString());
+    // A handoff with no deadlineAt (legacy shape) falls back to enqueuedAt + default.
+    writeFileSync(join(handoffPaths(dir).dir, "evt-legacy.json"), JSON.stringify({ tickId: "evt-legacy", cadence: "c", enqueuedAt: new Date(T0).toISOString() }));
+    const r2 = expireHandoffs(dir, { now: T0 + DEFAULT_HANDOFF_DEADLINE_MS + 1 });
+    assert.deepEqual(r2.expired.map((h) => h.tickId), ["evt-legacy"]);
+    // Nothing to do on a missing directory.
+    assert.deepEqual(expireHandoffs(join(dir, "nope"), { now: T0 }), { expired: [], failed: [], scanned: 0 });
+  } finally { rm(dir); }
+});
+
+test("expireHandoffs: onExpire runs BEFORE the record is retired — a false/throwing hook leaves the handoff open for the next sweep", () => {
+  const dir = root();
+  try {
+    writeHandoff(dir, { tickId: "evt-old", cadence: "goal-steward", mode: "escalate", promptPath: "/p" }, { now: T0 });
+    const late = T0 + DEFAULT_HANDOFF_DEADLINE_MS + 1;
+    const seen = [];
+    const r1 = expireHandoffs(dir, { now: late, onExpire: (h) => { seen.push(h.tickId); throw new Error("bus unwritable"); } });
+    assert.deepEqual(seen, ["evt-old"]);
+    assert.deepEqual(r1.expired, [], "not retired: the re-enqueue did not happen");
+    assert.deepEqual(r1.failed.map((f) => f.tickId), ["evt-old"]);
+    assert.deepEqual(listHandoffs(dir).map((h) => h.tickId), ["evt-old"], "still open");
+    assert.equal(existsSync(join(handoffPaths(dir).done, "evt-old.json")), false);
+    const r2 = expireHandoffs(dir, { now: late, onExpire: () => false });
+    assert.deepEqual(r2.expired, []);
+    assert.deepEqual(listHandoffs(dir).map((h) => h.tickId), ["evt-old"]);
+    // The hook succeeds → retired as before.
+    const r3 = expireHandoffs(dir, { now: late, onExpire: () => true });
+    assert.deepEqual(r3.expired.map((h) => h.tickId), ["evt-old"]);
+    assert.deepEqual(listHandoffs(dir), []);
+    assert.equal(JSON.parse(readFileSync(join(handoffPaths(dir).done, "evt-old.json"), "utf-8")).status, "expired");
+  } finally { rm(dir); }
+});
+
+test("pruneHandoffs: done/ records and rendered prompts past retention are removed; open handoffs and their prompts are never touched", () => {
+  const dir = root();
+  try {
+    const paths = handoffPaths(dir);
+    mkdirSync(paths.prompts, { recursive: true });
+    // An old acked handoff + its prompt.
+    writeFileSync(join(paths.prompts, "evt-old.md"), "# old");
+    writeHandoff(dir, { tickId: "evt-old", cadence: "a", promptPath: join(paths.prompts, "evt-old.md") }, { now: T0 });
+    ackHandoff(dir, "evt-old", { now: T0 + 1000 });
+    // A recent acked handoff.
+    writeFileSync(join(paths.prompts, "evt-recent.md"), "# recent");
+    writeHandoff(dir, { tickId: "evt-recent", cadence: "b", promptPath: join(paths.prompts, "evt-recent.md") }, { now: T0 + DEFAULT_HANDOFF_RETENTION_MS - 60_000 });
+    ackHandoff(dir, "evt-recent", { now: T0 + DEFAULT_HANDOFF_RETENTION_MS - 60_000 });
+    // An OPEN handoff whose prompt is old on disk (never pruned while open).
+    writeFileSync(join(paths.prompts, "evt-open.md"), "# open");
+    utimesSync(join(paths.prompts, "evt-open.md"), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS));
+    writeHandoff(dir, { tickId: "evt-open", cadence: "c", promptPath: join(paths.prompts, "evt-open.md") }, { now: T0 });
+    // An orphan prompt nobody references, old.
+    writeFileSync(join(paths.prompts, "evt-orphan.md"), "# orphan");
+    utimesSync(join(paths.prompts, "evt-orphan.md"), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS));
+    // A corrupt done record with an old mtime.
+    writeFileSync(join(paths.done, "junk.json"), "{not json");
+    utimesSync(join(paths.done, "junk.json"), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS), new Date(T0 - 10 * DEFAULT_HANDOFF_RETENTION_MS));
+
+    const r = pruneHandoffs(dir, { now: T0 + DEFAULT_HANDOFF_RETENTION_MS + 5000 });
+    assert.deepEqual(r.removed.done.sort(), ["evt-old.json", "junk.json"]);
+    assert.deepEqual(r.removed.prompts.sort(), ["evt-old.md", "evt-orphan.md"]);
+    assert.deepEqual(readdirSync(paths.done).sort(), ["evt-recent.json"]);
+    assert.deepEqual(readdirSync(paths.prompts).sort(), ["evt-open.md", "evt-recent.md"]);
+    assert.deepEqual(listHandoffs(dir).map((h) => h.tickId), ["evt-open"]);
+    // Idempotent and safe on a missing ledger.
+    assert.deepEqual(pruneHandoffs(dir, { now: T0 + DEFAULT_HANDOFF_RETENTION_MS + 5000 }).removed, { done: [], prompts: [] });
+    assert.deepEqual(pruneHandoffs(join(dir, "nope"), { now: T0 }).removed, { done: [], prompts: [] });
+  } finally { rm(dir); }
+});