@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/daemon/cadence-consumer-frontdoor.test.mjs

@@ -0,0 +1,393 @@
+/**
+ * cadence-consumer-frontdoor.test.mjs — the consumer with a live main session
+ * (design §3.4) and the F8/F9 cadence fixes.
+ *
+ *   - an escalate/guarded tick is HANDED to a live session (handoff file +
+ *     rendered prompt on disk + tick processed as "handed-to-session"), never
+ *     spawned; inline ticks keep running in the consumer
+ *   - a session that is not live → legacy spawn, unchanged
+ *   - a handoff past its deadline is re-enqueued with metadata.handoffTimedOut
+ *     and that tick is NOT handed off again (legacy spawn)
+ *   - per-cadence in-flight guard: a second tick for a cadence that already
+ *     has an open handoff / running sub-session is deferred, not spawned twice
+ *   - a deferred tick is re-keyed to the tail and tickOnce keeps scanning
+ *     past the deferral instead of breaking (head-of-line block)
+ *
+ * Every test drives tickOnce() by hand (pollMs is an hour) with an injected
+ * spawner, front-door state and clock. No real process is ever launched.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+
+import { enqueueTick, listInbox, busDepth, getBusPaths } from "../../lib/cadence-bus.mjs";
+import { listHandoffs, handoffPaths, writeHandoff, ackHandoff, DEFAULT_HANDOFF_DEADLINE_MS, DEFAULT_HANDOFF_RETENTION_MS } from "../../lib/session/handoffs.mjs";
+import { startConsumer as startConsumerRaw, renderCadencePromptBody } from "./cadence-consumer.mjs";
+import { withParallelism, countParallelism, PARALLELISM_DIRECTIVE } from "../../lib/prompts/parallelism.mjs";
+
+const ADMIT_ALL = { admit: () => ({ decision: "ADMIT", reason: "test", snapshot: {} }), defaultDeps: () => ({}) };
+const RATE_OK = { checkRateLimit: () => ({ allowed: true, retryAt: null }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} };
+const BUDGET_OK = { dailyStatus: () => ({ essentialOnly: false }) };
+const LIVE = () => ({ frontDoor: "session", sessionLive: true });
+const NOT_LIVE = () => ({ frontDoor: "session", sessionLive: false });
+
+function startConsumer(opts = {}) {
+  return startConsumerRaw({ governor: ADMIT_ALL, rateGuard: RATE_OK, budgetGuard: BUDGET_OK, pollMs: 3_600_000, heartbeatMs: 3_600_000, recoveryMs: 3_600_000, budgetEscalateMs: 0, ...opts });
+}
+async function makeAgentRoot() {
+  const p = join(tmpdir(), `cadence-frontdoor-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(p, { recursive: true });
+  writeFileSync(join(p, "config.json"), "{}");
+  mkdirSync(join(p, "config"), { recursive: true });
+  writeFileSync(join(p, "config", "agent.json"), JSON.stringify({ firstName: "Nova", lastName: "Reyes", name: "Nova Reyes" }));
+  return p;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+function plantPrompt(root, cadence, body = `# ${cadence} for {{agent.firstName}}`) {
+  const path = join(root, "schedules/triggers", `${cadence}.md`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body);
+  return path;
+}
+function processedEvents(root) {
+  const dir = getBusPaths(root).processed;
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const day of readdirSync(dir)) {
+    for (const f of readdirSync(join(dir, day))) {
+      if (f.endsWith(".json")) out.push(JSON.parse(readFileSync(join(dir, day, f), "utf-8")));
+    }
+  }
+  return out;
+}
+
+test("live session: an escalate tick is handed to the session — handoff + rendered prompt on disk, no spawn", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: LIVE,
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    const t = enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    const r = await consumer.tickOnce();
+    assert.equal(r.processed, 1);
+    assert.equal(spawns.length, 0, "must not spawn a sub-session while the session is live");
+    const open = listHandoffs(root);
+    assert.equal(open.length, 1);
+    assert.equal(open[0].tickId, t.id);
+    assert.equal(open[0].cadence, "daily-morning-brief");
+    assert.equal(open[0].mode, "escalate");
+    assert.ok(open[0].deadlineAt, "carries a deadline");
+    assert.ok(existsSync(open[0].promptPath), "the rendered prompt is on disk");
+    assert.equal(
+      readFileSync(open[0].promptPath, "utf-8"),
+      withParallelism("# daily-morning-brief for Nova"),
+      "identity tokens rendered, and the handed prompt is byte-identical to what a sub-session would have been given",
+    );
+    assert.equal(busDepth(root).inbox, 0);
+    assert.equal(busDepth(root).claimed, 0);
+    const done = processedEvents(root).find((e) => e.id === t.id);
+    assert.equal(done.result.decision, "handed-to-session");
+    assert.equal(consumer.getStats().handed_off, 1);
+    assert.equal(consumer.getStats().last_decision, "handed-to-session");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("live session: inline ticks still run in the consumer; not-live → legacy spawn", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  const spawns = [];
+  const live = { on: true };
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: () => ({ frontDoor: "session", sessionLive: live.on }),
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    enqueueTick({ cadence: "cadence-bus-heartbeat", source: "manual", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(consumer.getStats().inline, 1);
+    assert.deepEqual(listHandoffs(root), [], "inline never hands off");
+
+    live.on = false;
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(spawns.length, 1, "session not live → the legacy lane spawns");
+    assert.deepEqual(listHandoffs(root), []);
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("handoff timeout: a handoff past its deadline is re-enqueued with handoffTimedOut and then spawned, not handed off again", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  const spawns = [];
+  let now = Date.parse("2026-09-08T10:00:00.000Z");
+  const consumer = startConsumer({
+    agentRoot: root,
+    now: () => now,
+    frontDoorState: LIVE,
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    writeHandoff(root, { tickId: "evt-stuck", cadence: "daily-morning-brief", mode: "escalate", promptPath: "/x", metadata: { reason: "guard:escalate" } }, { now });
+    now += DEFAULT_HANDOFF_DEADLINE_MS + 1;
+    await consumer.tickOnce();
+    assert.equal(consumer.getStats().handoff_timeouts, 1);
+    assert.deepEqual(listHandoffs(root), [], "the stuck handoff is retired");
+    assert.equal(JSON.parse(readFileSync(join(handoffPaths(root).done, "evt-stuck.json"), "utf-8")).status, "expired");
+    // The re-enqueued tick ran on the legacy lane in that same tick (or the next).
+    if (spawns.length === 0) await consumer.tickOnce();
+    assert.equal(spawns.length, 1, "timed-out handoff → legacy spawn even though the session is live");
+    assert.equal(spawns[0].cadence, "daily-morning-brief");
+    const ev = processedEvents(root).find((e) => e.source === "handoff-timeout");
+    assert.equal(ev.metadata.handoffTimedOut, true);
+    assert.equal(ev.metadata.handoffTickId, "evt-stuck");
+    assert.equal(ev.result.decision, "escalated");
+    assert.deepEqual(listHandoffs(root), [], "never handed off a second time");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("per-cadence in-flight guard: a cadence with an open handoff is deferred (re-keyed), a different cadence proceeds", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  plantPrompt(root, "meeting-action-capture");
+  const consumer = startConsumer({ agentRoot: root, frontDoorState: LIVE, spawnSession: async () => ({ ok: true, exit_code: 0 }) });
+  try {
+    const a = enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(listHandoffs(root).length, 1);
+    await new Promise((r) => setTimeout(r, 2));
+    const a2 = enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await new Promise((r) => setTimeout(r, 2));
+    enqueueTick({ cadence: "meeting-action-capture", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    const open = listHandoffs(root);
+    assert.deepEqual(open.map((h) => h.cadence).sort(), ["daily-morning-brief", "meeting-action-capture"], "second cadence handed off; first not duplicated");
+    assert.equal(open.filter((h) => h.cadence === "daily-morning-brief").length, 1, "the same cadence is never in flight twice");
+    const inbox = listInbox(root);
+    assert.equal(inbox.length, 1, "the duplicate tick waits at the tail");
+    const waiting = JSON.parse(readFileSync(join(getBusPaths(root).inbox, `${inbox[0]}.json`), "utf-8"));
+    assert.equal(waiting.cadence, "daily-morning-brief");
+    assert.equal(waiting.metadata.originalId, a2.id);
+    assert.equal(waiting.metadata.deferrals, 1);
+    assert.notEqual(inbox[0], a2.id, "re-keyed, not requeued under its own id");
+    void a;
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("per-cadence in-flight guard: a running sub-session for a cadence blocks a second spawn of the same cadence", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  let release;
+  const gate = new Promise((r) => { release = r; });
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: NOT_LIVE,
+    spawnSession: async (o) => { spawns.push(o.cadence); await gate; return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    const first = consumer.tickOnce(); // holds the spawn open
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(spawns.length, 1);
+    await new Promise((r) => setTimeout(r, 2));
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(spawns.length, 1, "no second spawn while the first is running");
+    assert.equal(listInbox(root).length, 1, "the second tick is deferred to the tail");
+    release();
+    await first;
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("head-of-line: a circuit-open deferral is re-keyed to the tail and tickOnce keeps scanning to the next cadence", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  plantPrompt(root, "daily-morning-brief");
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: NOT_LIVE,
+    backoffSchedule: [0, 0, 0],
+    circuitThreshold: 1,
+    circuitDurationMs: 60_000,
+    maxAttempts: 1,
+    spawnSession: async (o) => {
+      spawns.push(o.cadence);
+      if (o.cadence === "weekly-strategic-memo") return { ok: false, exit_code: 1, error: "fail", duration_ms: 1 };
+      return { ok: true, exit_code: 0, duration_ms: 1 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await consumer.tickOnce(); // fails once → circuit opens for weekly-strategic-memo
+    assert.equal(consumer.getStats().spawn_failures, 1);
+
+    const held = enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await new Promise((r) => setTimeout(r, 2));
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    const r = await consumer.tickOnce();
+    // Before: the circuit skip broke the loop and daily-morning-brief waited a
+    // whole poll behind a tick that could not run. Now both are visited.
+    assert.equal(r.processed, 2, `both ticks visited in one tick (stats=${JSON.stringify(consumer.getStats())})`);
+    assert.deepEqual(spawns, ["weekly-strategic-memo", "daily-morning-brief"]);
+    assert.equal(consumer.getStats().skipped_circuit_open, 1);
+    const inbox = listInbox(root);
+    assert.equal(inbox.length, 1, "the held tick is back in the inbox, once");
+    assert.notEqual(inbox[0], held.id, "under a NEW id (tail), not its own");
+    const on = JSON.parse(readFileSync(join(getBusPaths(root).inbox, `${inbox[0]}.json`), "utf-8"));
+    assert.equal(on.metadata.originalId, held.id);
+    assert.equal(on.metadata.deferrals, 1);
+    // A further tick with ONLY the held cadence queued does not spin: one visit, one re-key, then it stops.
+    const r2 = await consumer.tickOnce();
+    assert.equal(r2.processed, 1);
+    assert.equal(listInbox(root).length, 1);
+    assert.equal(JSON.parse(readFileSync(join(getBusPaths(root).inbox, `${listInbox(root)[0]}.json`), "utf-8")).metadata.deferrals, 2);
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("a broken front-door reader fails open to the legacy lane", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: () => { throw new Error("boom"); },
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(spawns.length, 1);
+    assert.deepEqual(listHandoffs(root), []);
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("handoff timeout: when the re-enqueue fails the handoff stays OPEN and is retried by the next sweep — the cadence run is never lost", async () => {
+  if (process.getuid && process.getuid() === 0) return; // root ignores directory modes
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief");
+  let now = Date.parse("2026-09-08T10:00:00.000Z");
+  const consumer = startConsumer({ agentRoot: root, now: () => now, frontDoorState: LIVE, spawnSession: async () => ({ ok: true, exit_code: 0, duration_ms: 1 }) });
+  try {
+    writeHandoff(root, { tickId: "evt-stuck", cadence: "daily-morning-brief", mode: "escalate", promptPath: "/x" }, { now });
+    now += DEFAULT_HANDOFF_DEADLINE_MS + 1;
+    const inbox = getBusPaths(root).inbox;
+    chmodSync(inbox, 0o500); // the bus inbox is unwritable for a minute
+    try {
+      await consumer.tickOnce();
+      assert.deepEqual(listHandoffs(root).map((h) => h.tickId), ["evt-stuck"], "not retired while the tick could not be re-enqueued");
+      assert.equal(existsSync(join(handoffPaths(root).done, "evt-stuck.json")), false);
+      assert.equal(consumer.getStats().handoff_timeouts, 0);
+    } finally { chmodSync(inbox, 0o755); }
+    await consumer.tickOnce();
+    assert.deepEqual(listHandoffs(root), [], "retired once the re-enqueue succeeded");
+    assert.equal(consumer.getStats().handoff_timeouts, 1);
+    assert.equal(JSON.parse(readFileSync(join(handoffPaths(root).done, "evt-stuck.json"), "utf-8")).status, "expired");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("circuit/backoff skip: re-keyed to the tail but NOT counted as a retry or a deferral in the health stats", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: NOT_LIVE,
+    backoffSchedule: [0, 0, 0],
+    circuitThreshold: 1,
+    circuitDurationMs: 60_000,
+    maxAttempts: 1,
+    spawnSession: async () => ({ ok: false, exit_code: 1, error: "fail", duration_ms: 1 }),
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await consumer.tickOnce(); // opens the circuit
+    const before = consumer.getStats();
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    for (let i = 0; i < 5; i++) await consumer.tickOnce(); // five polls inside the circuit window
+    const after = consumer.getStats();
+    assert.equal(after.skipped_circuit_open, 5);
+    assert.equal(after.retries, before.retries, "a held-back cadence was never attempted — not a retry");
+    assert.equal(after.deferred, before.deferred, "nor a governance deferral");
+    assert.equal(listInbox(root).length, 1, "the held tick is still waiting, once");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("handoff ledger hygiene: the sweep prunes done/ records and prompts past retention, at most once an hour", async () => {
+  const root = await makeAgentRoot();
+  let now = Date.parse("2026-09-08T10:00:00.000Z");
+  const consumer = startConsumer({ agentRoot: root, now: () => now, frontDoorState: LIVE, spawnSession: async () => ({ ok: true, exit_code: 0 }) });
+  try {
+    const paths = handoffPaths(root);
+    mkdirSync(paths.prompts, { recursive: true });
+    writeFileSync(join(paths.prompts, "evt-done.md"), "# p");
+    writeHandoff(root, { tickId: "evt-done", cadence: "a", promptPath: join(paths.prompts, "evt-done.md") }, { now });
+    ackHandoff(root, "evt-done", { now });
+    now += DEFAULT_HANDOFF_RETENTION_MS + 1000;
+    await consumer.tickOnce();
+    assert.equal(existsSync(join(paths.done, "evt-done.json")), false, "pruned by the sweep");
+    assert.equal(existsSync(join(paths.prompts, "evt-done.md")), false);
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+// ── the parallelism directive on the escalate/guarded lane (WP-M7 mechanic 5) ──
+//
+// The spec puts the directive on "every escalate/guarded sub-session prompt".
+// Cadence trigger prompts never pass through `prompt-builder.mjs#buildPrompt`
+// — they are read straight off schedules/triggers/<name>.md — so this lane has
+// its own seam (`renderCadencePromptBody`) and needs its own pins. Without it
+// an `escalate` tick whose trigger asks for six independent audits spawns a
+// sub-session with no standing permission to fan out.
+
+test("escalate: the spawned sub-session prompt leads with the parallelism directive, exactly once", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief", "# daily-morning-brief for {{agent.firstName}}\n\nAudit six things.");
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: NOT_LIVE,
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(spawns.length, 1);
+    // The injected spawner is handed the promptPath, not the body — so assert
+    // on the seam the real spawner uses to turn that path into argv.
+    const body = renderCadencePromptBody(root, readFileSync(join(root, spawns[0].promptPath), "utf-8"));
+    assert.ok(body.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+    assert.equal(countParallelism(body), 1);
+    assert.ok(body.endsWith("# daily-morning-brief for Nova\n\nAudit six things."), "and the trigger body follows, tokens rendered");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("a trigger that already carries the directive is not given a second copy", () => {
+  const body = renderCadencePromptBody("/nonexistent-agent-root", withParallelism("# already-primed"));
+  assert.equal(countParallelism(body), 1, "idempotent — a repeated directive reads as emphasis and erodes the file-scope rule");
+  assert.equal(body, withParallelism("# already-primed"));
+});
+
+test("the handed-off prompt and the spawned prompt are the same bytes", async () => {
+  const root = await makeAgentRoot();
+  const raw = "# weekly-strategic-memo for {{agent.firstName}}";
+  plantPrompt(root, "weekly-strategic-memo", raw);
+  const consumer = startConsumer({ agentRoot: root, frontDoorState: LIVE, spawnSession: async () => ({ ok: true, exit_code: 0 }) });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    const open = listHandoffs(root);
+    assert.equal(open.length, 1);
+    const handed = readFileSync(open[0].promptPath, "utf-8");
+    assert.equal(handed, renderCadencePromptBody(root, raw), "one seam, two lanes");
+    assert.equal(countParallelism(handed), 1);
+    assert.ok(handed.startsWith(PARALLELISM_DIRECTIVE));
+  } finally { await consumer.stop(); await rmRoot(root); }
+});