@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/session/handoffs.test.mjs

@@ -1,183 +0,0 @@
-/**
- * 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); }
-});

package/lib/session/identity.test.mjs

@@ -1,180 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { join, resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { spawnSync } from "node:child_process";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-import {
-  parseMainSession,
-  newMainSession,
-  loadMainSession,
-  saveMainSession,
-  agentFirstName,
-  muxSessionName,
-  mainSessionName,
-  launchMode,
-  recordLaunch,
-  rotationDecision,
-  rotateMainSession,
-  FAILURE_WINDOW_MS,
-  MAX_ROTATIONS_PER_HOUR,
-  BACKOFF_MS,
-} from "./identity.mjs";
-
-const T0 = Date.parse("2026-09-08T10:00:00Z");
-const UUID = "11111111-2222-4333-8444-555555555555";
-
-test("parseMainSession: valid record round-trips; junk → null", () => {
-  const rec = parseMainSession(JSON.stringify({ sessionId: UUID, createdAt: "2026-09-08T09:00:00Z", resumes: 2 }));
-  assert.deepEqual(rec, { sessionId: UUID, createdAt: "2026-09-08T09:00:00Z", resumes: 2, rotations: [] });
-  assert.equal(parseMainSession("{not json"), null);
-  assert.equal(parseMainSession(JSON.stringify({ sessionId: "not-a-uuid" })), null);
-  assert.equal(parseMainSession(JSON.stringify({ resumes: 1 })), null);
-  assert.equal(parseMainSession(null), null);
-});
-
-test("newMainSession: uses the injected uuid + clock, starts at zero resumes", () => {
-  const rec = newMainSession({ now: T0, uuid: () => UUID });
-  assert.deepEqual(rec, { sessionId: UUID, createdAt: "2026-09-08T10:00:00.000Z", resumes: 0, rotations: [] });
-});
-
-test("loadMainSession / saveMainSession go through injected fs and the atomic writer", () => {
-  const disk = {};
-  const deps = {
-    readFileSync: (p) => { if (!(p in disk)) { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; } return disk[p]; },
-    writeJsonAtomic: (p, obj) => { disk[p] = JSON.stringify(obj); },
-  };
-  assert.equal(loadMainSession("/agent", deps), null);
-  const rec = newMainSession({ now: T0, uuid: () => UUID });
-  const saved = saveMainSession("/agent", rec, deps);
-  assert.deepEqual(saved, { ok: true });
-  assert.ok(disk[join("/agent", "state", "session", "main-session.json")]);
-  assert.deepEqual(loadMainSession("/agent", deps), rec);
-});
-
-test("saveMainSession: a failing writer is a returned error, not a throw", () => {
-  const res = saveMainSession("/agent", newMainSession({ now: T0, uuid: () => UUID }), {
-    writeJsonAtomic: () => { throw new Error("EROFS"); },
-  });
-  assert.equal(res.ok, false);
-  assert.match(res.error, /EROFS/);
-});
-
-test("agentFirstName: lower-cased firstName from config/agent.json; agent.ts, then the dir name minus -ai, as generate-plists.sh does", () => {
-  const fs = (files) => ({ readFileSync: (p) => { if (!(p in files)) { const e = new Error(`ENOENT ${p}`); e.code = "ENOENT"; throw e; } return files[p]; } });
-  const J = join("/Users/o/ravi-ai", "config", "agent.json");
-  const T = join("/Users/o/ravi-ai", "config", "agent.ts");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"Olivia"}' })), "olivia");
-  // NOT slugged: the plist generator lower-cases only, and the label, the
-  // lock, the mux and the session name must agree on one derivation.
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"Jean Luc"}' })), "jean luc");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"José"}' })), "josé");
-  // Fallbacks in the generator's order: agent.ts inline literal, then the directory.
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [T]: "export const AGENT = { firstName: 'Priya', lastName: 'T' };\n" })), "priya");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [T]: "interface A { firstName: string; }\n" })), "ravi", "a type-only firstName is not a value");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"UNCONFIGURED"}' })), "ravi");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: "{" })), "ravi");
-  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({})), "ravi");
-  assert.equal(agentFirstName("/Users/o/sam", fs({})), "sam");
-  // Blank everywhere (no usable dir name either) → "agent".
-  assert.equal(agentFirstName("/", fs({ [join("/", "config", "agent.json")]: '{"firstName":"  "}' })), "agent");
-});
-
-test("agentFirstName agrees with generate-plists.sh's derivation, run verbatim from the script (cross-pin)", () => {
-  const script = readFileSync(resolve(__dirname, "..", "..", "scripts", "local-triggers", "generate-plists.sh"), "utf8");
-  const start = script.indexOf('AGENT_JSON="$AGENT_DIR/config/agent.json"');
-  const end = script.indexOf("AGENT_UPPER=");
-  assert.ok(start > 0 && end > start, "generate-plists.sh derivation block markers moved — update this cross-pin AND agentFirstName together");
-  const block = script.slice(start, end);
-  const shellFirst = (dir) => {
-    const r = spawnSync("/bin/bash", ["-c", `AGENT_DIR=${JSON.stringify(dir)}\n${block}\nprintf '%s' "$AGENT_FIRST"`], { encoding: "utf8", env: { PATH: "/usr/bin:/bin", LANG: "en_US.UTF-8", LC_ALL: "en_US.UTF-8" } });
-    assert.equal(r.status, 0, r.stderr);
-    return r.stdout;
-  };
-  const cases = [
-    ["ravi-ai", { json: { firstName: "Olivia" } }],
-    ["ravi-ai", { json: { firstName: "Jean Luc" } }],
-    ["ravi-ai", { json: { firstName: "José" } }],
-    ["ravi-ai", { json: { firstName: "UNCONFIGURED" } }],
-    ["ravi-ai", { ts: "export const AGENT = { firstName: 'Priya', lastName: 'T' };\n" }],
-    ["ravi-ai", { ts: "interface A { firstName: string; }\n" }],
-    ["sam-ai", {}],
-    ["kai", { json: {} }],
-    ["Ravi-ai", {}], // the generator does NOT lower-case the directory fallback
-  ];
-  for (const [dirName, fx] of cases) {
-    const base = mkdtempSync(join(tmpdir(), "maestro-first-"));
-    const dir = join(base, dirName);
-    mkdirSync(join(dir, "config"), { recursive: true });
-    if (fx.json) writeFileSync(join(dir, "config", "agent.json"), JSON.stringify(fx.json));
-    if (fx.ts) writeFileSync(join(dir, "config", "agent.ts"), fx.ts);
-    try {
-      assert.equal(agentFirstName(dir), shellFirst(dir), `${dirName} ${JSON.stringify(fx)}`);
-    } finally {
-      rmSync(base, { recursive: true, force: true });
-    }
-  }
-});
-
-test("muxSessionName / mainSessionName", () => {
-  assert.equal(muxSessionName("olivia"), "maestro-olivia");
-  assert.equal(mainSessionName("olivia"), "olivia-main");
-});
-
-test("launchMode: a never-launched id starts fresh; a launched id resumes; resume:false always starts fresh", () => {
-  const fresh = newMainSession({ now: T0, uuid: () => UUID });
-  assert.equal(launchMode(fresh, { resume: true }), "session-id");
-  const launched = recordLaunch(fresh, { now: T0 });
-  assert.equal(launched.resumes, 1);
-  assert.equal(launched.lastLaunchAt, "2026-09-08T10:00:00.000Z");
-  assert.equal(launchMode(launched, { resume: true }), "resume");
-  assert.equal(launchMode(launched, { resume: false }), "session-id");
-  // recordLaunch is pure — the input is untouched.
-  assert.equal(fresh.resumes, 0);
-});
-
-test("rotationDecision: non-zero exit inside the failure window on a resume → rotate", () => {
-  const rec = { sessionId: UUID, createdAt: "x", resumes: 2, rotations: [] };
-  const d = rotationDecision({ record: rec, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 5_000, now: T0 + 5_000 });
-  assert.equal(d.action, "rotate");
-});
-
-test("rotationDecision: a clean end, a long-lived session, or a fresh-id launch → relaunch (exit 75)", () => {
-  const rec = { sessionId: UUID, createdAt: "x", resumes: 2, rotations: [] };
-  const base = { record: rec, startedAt: T0, now: T0 + 5_000 };
-  assert.equal(rotationDecision({ ...base, mode: "resume", exitCode: 0, endedAt: T0 + 5_000 }).action, "relaunch");
-  assert.equal(rotationDecision({ ...base, mode: "resume", exitCode: 1, endedAt: T0 + FAILURE_WINDOW_MS + 1, now: T0 + FAILURE_WINDOW_MS + 1 }).action, "relaunch");
-  assert.equal(rotationDecision({ ...base, mode: "session-id", exitCode: 1, endedAt: T0 + 5_000 }).action, "relaunch");
-});
-
-test("rotationDecision: an unknown exit code inside the window counts as a failure (fail-safe toward rotation)", () => {
-  const rec = { sessionId: UUID, createdAt: "x", resumes: 1, rotations: [] };
-  const d = rotationDecision({ record: rec, mode: "resume", exitCode: null, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
-  assert.equal(d.action, "rotate");
-});
-
-test("rotationDecision: more than MAX_ROTATIONS_PER_HOUR in the last hour → backoff", () => {
-  const recent = Array.from({ length: MAX_ROTATIONS_PER_HOUR }, (_, i) => new Date(T0 - (i + 1) * 60_000).toISOString());
-  const rec = { sessionId: UUID, createdAt: "x", resumes: 1, rotations: recent };
-  const d = rotationDecision({ record: rec, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
-  assert.equal(d.action, "backoff");
-  assert.equal(d.sleepMs, BACKOFF_MS);
-  // Rotations older than an hour no longer count.
-  const old = recent.map((iso) => new Date(Date.parse(iso) - 3_600_000).toISOString());
-  const d2 = rotationDecision({ record: { ...rec, rotations: old }, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
-  assert.equal(d2.action, "rotate");
-});
-
-test("rotateMainSession: fresh id, zero resumes, rotation stamped and pruned to the last hour", () => {
-  const rec = { sessionId: UUID, createdAt: "x", resumes: 4, rotations: [new Date(T0 - 2 * 3_600_000).toISOString()] };
-  const next = rotateMainSession(rec, { now: T0, uuid: () => "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee" });
-  assert.equal(next.sessionId, "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee");
-  assert.equal(next.resumes, 0);
-  assert.deepEqual(next.rotations, ["2026-09-08T10:00:00.000Z"]);
-  assert.equal(next.rotatedFrom, UUID);
-  assert.equal(rec.resumes, 4);
-});

package/lib/session/inbox-claims.test.mjs

@@ -1,286 +0,0 @@
-/**
- * inbox-claims.test.mjs — session claims on inbox items + the assurance
- * reopen sweep (design §3.3).
- *
- * `maestro inbox claim <id>` parks the item at `.yaml.dispatched` (the same
- * durable-admission marker the daemon uses) and stamps `claimed_by: session`
- * into the YAML. A claim neither replied nor done within 20 min is reopened
- * (`.dispatched` → `.yaml`) by the daemon sweep; a `--until` deferral is
- * reopened once its time passes. Clock injected; real fs on a tmp root.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, utimesSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-
-import {
-  SESSION_CLAIM_STALE_MS,
-  sessionMarkerLines,
-  parseSessionMarkers,
-  stripSessionMarkers,
-  findInboxFile,
-  markSessionClaim,
-  markSessionDeferral,
-  markSessionReplied,
-  sweepSessionInbox,
-  sweepSessionInboxForDaemon,
-  DAEMON_ORPHAN_RECLAIM_MS,
-  REPLIED_RETIRE_MS,
-} from "./inbox-claims.mjs";
-
-const T0 = Date.parse("2026-09-08T10:00:00.000Z");
-const ITEM = `id: "cohort-abc123"
-service: "cohort"
-channel: "dm/olivia"
-channel_id: "ch_1"
-sender: "Olivia Chen"
-timestamp: "2026-09-08T09:59:00.000Z"
-subject: ""
-content: |
-  can you send me the deck?
-raw_ref: "cohort-abc123"
-`;
-
-function root() {
-  const dir = mkdtempSync(join(tmpdir(), "maestro-inbox-claims-"));
-  mkdirSync(join(dir, "state", "inbox", "cohort"), { recursive: true });
-  return dir;
-}
-function rm(dir) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ } }
-function plant(dir, name = "2026-09-08T09-59-00-000Z-cohort-abc123.yaml", body = ITEM) {
-  const p = join(dir, "state", "inbox", "cohort", name);
-  writeFileSync(p, body);
-  return p;
-}
-function ls(dir) { return readdirSync(join(dir, "state", "inbox", "cohort")).sort(); }
-
-test("markers: lines round-trip through parse and strip without touching the item", () => {
-  const lines = sessionMarkerLines({ claimedBy: "session", now: T0 });
-  const body = ITEM + lines;
-  assert.deepEqual(parseSessionMarkers(body), {
-    claimedBy: "session", claimedAt: new Date(T0).toISOString(), deferredUntil: null, deferredReason: null, repliedAt: null,
-  });
-  assert.equal(stripSessionMarkers(body), ITEM);
-  // Markers must be TOP-LEVEL keys: an indented look-alike inside a body block is ignored.
-  const forged = ITEM.replace("can you send me the deck?", "claimed_by: \"session\"\n  x");
-  assert.equal(parseSessionMarkers(forged).claimedBy, null);
-  assert.equal(stripSessionMarkers(forged), forged);
-  assert.deepEqual(parseSessionMarkers(""), { claimedBy: null, claimedAt: null, deferredUntil: null, deferredReason: null, repliedAt: null });
-});
-
-test("findInboxFile: locates an item by id in any state, reports the state; null when absent", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    const f = findInboxFile(dir, "cohort-abc123");
-    assert.equal(f.service, "cohort");
-    assert.equal(f.state, "new");
-    assert.ok(f.path.endsWith(".yaml"));
-    assert.equal(findInboxFile(dir, "nope"), null);
-    // A specific service narrows the search; a wrong one finds nothing.
-    assert.equal(findInboxFile(dir, "cohort-abc123", { service: "slack" }), null);
-    plant(dir, "2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched");
-    rmSync(f.path);
-    assert.equal(findInboxFile(dir, "cohort-abc123").state, "claimed");
-  } finally { rm(dir); }
-});
-
-test("markSessionClaim: renames to .dispatched and stamps claimed_by/claimed_at; not claimable twice", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    const r = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
-    assert.equal(r.ok, true);
-    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched"]);
-    const body = readFileSync(r.path, "utf-8");
-    const m = parseSessionMarkers(body);
-    assert.equal(m.claimedBy, "session");
-    assert.equal(m.claimedAt, new Date(T0).toISOString());
-    assert.ok(body.startsWith(ITEM), "the item body is untouched above the markers");
-    const again = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 + 1 });
-    assert.equal(again.ok, false);
-    assert.equal(again.error, "not-claimable");
-  } finally { rm(dir); }
-});
-
-test("markSessionDeferral: parks the item as .deferred with deferred_until/reason (from new or claimed)", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
-    const r = markSessionDeferral(dir, "cohort", { id: "cohort-abc123" }, { until: T0 + 30 * 60_000, reason: "waiting on finance", now: T0 });
-    assert.equal(r.ok, true);
-    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.deferred"]);
-    const m = parseSessionMarkers(readFileSync(r.path, "utf-8"));
-    assert.equal(m.deferredUntil, new Date(T0 + 30 * 60_000).toISOString());
-    assert.equal(m.deferredReason, "waiting on finance");
-    // The claim marker is replaced, not stacked.
-    assert.equal(m.claimedBy, null);
-    assert.equal(markSessionDeferral(dir, "cohort", { id: "ghost" }, { until: T0, now: T0 }).ok, false);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: a session claim older than 20 min is reopened to .yaml with markers stripped; fresh stays", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
-    // A daemon-dispatched (no marker) .dispatched file is NOT the sweep's to reopen.
-    plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
-
-    const fresh = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS - 1 });
-    assert.deepEqual(fresh.reopened, []);
-    assert.equal(fresh.scanned >= 2, true);
-
-    const r = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
-    assert.deepEqual(r.reopened.map((x) => [x.id, x.service, x.reason]), [["cohort-abc123", "cohort", "claim-stale"]]);
-    assert.deepEqual(ls(dir), [
-      "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched",
-      "2026-09-08T09-59-00-000Z-cohort-abc123.yaml",
-    ]);
-    assert.equal(readFileSync(join(dir, "state/inbox/cohort/2026-09-08T09-59-00-000Z-cohort-abc123.yaml"), "utf-8"), ITEM);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: a deferral whose time has passed is reopened; a future one stays; unmarked .deferred untouched", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    markSessionDeferral(dir, "cohort", { id: "cohort-abc123" }, { until: T0 + 10_000, reason: "later", now: T0 });
-    // Legacy daemon deferral (thread-lock park) carries no marker — promoteDeferred owns it.
-    plant(dir, "2026-09-08T09-58-00-000Z-cohort-legacy.yaml.deferred", ITEM.replace(/cohort-abc123/g, "cohort-legacy"));
-    assert.deepEqual(sweepSessionInbox(dir, { now: T0 + 9_999 }).reopened, []);
-    const r = sweepSessionInbox(dir, { now: T0 + 10_000 });
-    assert.deepEqual(r.reopened.map((x) => [x.id, x.reason]), [["cohort-abc123", "deferral-due"]]);
-    assert.deepEqual(ls(dir), [
-      "2026-09-08T09-58-00-000Z-cohort-legacy.yaml.deferred",
-      "2026-09-08T09-59-00-000Z-cohort-abc123.yaml",
-    ]);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: a claim with an unparsable claimed_at falls back to the file mtime; missing inbox dir → nothing", () => {
-  const dir = root();
-  try {
-    const p = plant(dir, "2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched", ITEM + 'claimed_by: "session"\nclaimed_at: "garbage"\n');
-    const old = new Date(T0 - SESSION_CLAIM_STALE_MS - 1000);
-    utimesSync(p, old, old);
-    const r = sweepSessionInbox(dir, { now: T0 });
-    assert.deepEqual(r.reopened.map((x) => x.id), ["cohort-abc123"]);
-    assert.deepEqual(sweepSessionInbox(join(dir, "nope"), { now: T0 }), { reopened: [], scanned: 0 });
-  } finally { rm(dir); }
-});
-
-// ── review fixes ─────────────────────────────────────────────────────────────
-
-test("findInboxFile: an exact id wins over substring look-alikes; a truncated id that matches several is refused", () => {
-  const dir = root();
-  try {
-    for (const id of ["cohort-m1", "cohort-m10", "cohort-m11"]) {
-      plant(dir, `2026-09-08T09-59-00-000Z-${id}.yaml`, ITEM.replace(/cohort-abc123/g, id));
-    }
-    assert.ok(findInboxFile(dir, "cohort-m1").file.endsWith("-cohort-m1.yaml"));
-    assert.ok(findInboxFile(dir, "cohort-m10").file.endsWith("-cohort-m10.yaml"));
-    // "m1" is a substring of all three and the exact id of none → ambiguous, not a guess.
-    assert.equal(findInboxFile(dir, "m1"), null);
-    // A unique substring (a raw_ref fragment) still resolves.
-    assert.ok(findInboxFile(dir, "m11").file.endsWith("-cohort-m11.yaml"));
-  } finally { rm(dir); }
-});
-
-test("markSessionClaim: renames ONLY the claimed item — look-alike ids stay live", () => {
-  const dir = root();
-  try {
-    for (const id of ["cohort-m1", "cohort-m10", "cohort-m11"]) {
-      plant(dir, `2026-09-08T09-59-00-000Z-${id}.yaml`, ITEM.replace(/cohort-abc123/g, id));
-    }
-    const r = markSessionClaim(dir, "cohort", { id: "cohort-m1" }, { now: T0 });
-    assert.equal(r.ok, true);
-    assert.deepEqual(ls(dir), [
-      "2026-09-08T09-59-00-000Z-cohort-m1.yaml.dispatched",
-      "2026-09-08T09-59-00-000Z-cohort-m10.yaml",
-      "2026-09-08T09-59-00-000Z-cohort-m11.yaml",
-    ]);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: reopen never recreates the path — the reopened file is the SAME inode, and a vanished claim is not resurrected", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    const claim = markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
-    const ino = statSync(claim.path).ino;
-    const r = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
-    assert.equal(r.reopened.length, 1);
-    const live = join(dir, "state/inbox/cohort/2026-09-08T09-59-00-000Z-cohort-abc123.yaml");
-    assert.equal(statSync(live).ino, ino, "markers are stripped in place, not via tmp+rename over the claim path");
-    assert.equal(readFileSync(live, "utf-8"), ITEM);
-    // A claim that was finished (renamed away) between the readdir and the reopen is left alone.
-    const p2 = plant(dir, "2026-09-08T09-58-00-000Z-cohort-gone.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-gone") + sessionMarkerLines({ claimedBy: "session", now: T0 }));
-    rmSync(p2);
-    const r2 = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
-    assert.equal(r2.reopened.length, 0);
-    assert.equal(existsSync(join(dir, "state/inbox/cohort/2026-09-08T09-58-00-000Z-cohort-gone.yaml")), false);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: a claim that was REPLIED is not reopened at 20 min; it is retired to .processed once past the retire window", () => {
-  const dir = root();
-  try {
-    plant(dir);
-    markSessionClaim(dir, "cohort", { id: "cohort-abc123" }, { now: T0 });
-    const rep = markSessionReplied(dir, "cohort", { id: "cohort-abc123" }, { now: T0 + 60_000 });
-    assert.equal(rep.ok, true);
-    const m = parseSessionMarkers(readFileSync(rep.path, "utf-8"));
-    assert.equal(m.claimedBy, "session", "the claim marker survives the reply stamp");
-    assert.equal(m.repliedAt, new Date(T0 + 60_000).toISOString());
-
-    const at20 = sweepSessionInbox(dir, { now: T0 + SESSION_CLAIM_STALE_MS + 1 });
-    assert.deepEqual(at20.reopened, [], "a replied item must never be re-answered");
-    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.dispatched"]);
-
-    const late = sweepSessionInbox(dir, { now: T0 + 60_000 + REPLIED_RETIRE_MS + 1 });
-    assert.deepEqual(late.reopened.map((x) => [x.id, x.reason]), [["cohort-abc123", "replied-retired"]]);
-    assert.deepEqual(ls(dir), ["2026-09-08T09-59-00-000Z-cohort-abc123.yaml.processed"]);
-    // Replying to an item that is not in flight (new / processed) is refused, never a throw.
-    assert.equal(markSessionReplied(dir, "cohort", { id: "cohort-abc123" }, { now: T0 }).ok, false);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInbox: a daemon-owned .dispatched orphan is reopened for a LIVE session once past the daemon reclaim window; never while the session is not live", () => {
-  const dir = root();
-  try {
-    const p = plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
-    const old = new Date(T0 - DAEMON_ORPHAN_RECLAIM_MS - 1000);
-    utimesSync(p, old, old);
-    // Not live → the scanner's own reclaim owns it; the sweep does nothing.
-    assert.deepEqual(sweepSessionInbox(dir, { now: T0 }).reopened, []);
-    assert.deepEqual(sweepSessionInbox(dir, { now: T0, sessionLive: false }).reopened, []);
-    // Live but the file is still inside the window → in flight, untouched.
-    const fresh = plant(dir, "2026-09-08T09-58-30-000Z-cohort-daemon2.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon2"));
-    utimesSync(fresh, new Date(T0 - 1000), new Date(T0 - 1000));
-    const r = sweepSessionInbox(dir, { now: T0, sessionLive: true });
-    assert.deepEqual(r.reopened.map((x) => [x.id, x.reason]), [["cohort-daemon1", "daemon-orphan"]]);
-    assert.deepEqual(ls(dir), [
-      "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml",
-      "2026-09-08T09-58-30-000Z-cohort-daemon2.yaml.dispatched",
-    ]);
-  } finally { rm(dir); }
-});
-
-test("sweepSessionInboxForDaemon: reads liveness through the front-door reader; a throwing reader means not live (scanner keeps its reclaim)", () => {
-  const dir = root();
-  try {
-    const p = plant(dir, "2026-09-08T09-58-00-000Z-cohort-daemon1.yaml.dispatched", ITEM.replace(/cohort-abc123/g, "cohort-daemon1"));
-    const old = new Date(T0 - DAEMON_ORPHAN_RECLAIM_MS - 1000);
-    utimesSync(p, old, old);
-    const dead = sweepSessionInboxForDaemon(dir, { now: T0, readState: () => { throw new Error("boom"); } });
-    assert.equal(dead.sessionLive, false);
-    assert.deepEqual(dead.reopened, []);
-    const live = sweepSessionInboxForDaemon(dir, { now: T0, readState: () => ({ frontDoor: "session", sessionLive: true }) });
-    assert.equal(live.sessionLive, true);
-    assert.deepEqual(live.reopened.map((x) => x.reason), ["daemon-orphan"]);
-  } finally { rm(dir); }
-});