@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/scripts/daemon/cadence-handlers.test.mjs

@@ -1,837 +0,0 @@
-/**
- * cadence-handlers.test.mjs — skill-curator guard phase-2 consolidation gating.
- * Run: node --test scripts/daemon/cadence-handlers.test.mjs
- *
- * The guard spawns the LLM consolidation worker DETACHED only when DUE: enabled
- * + candidate count ≥ minSkills + ≥ intervalDays since the last run (tracked in
- * state/learning/consolidation.json). We inject a FAKE spawner (no detached
- * child, no LLM) and assert the interval gate + the candidate-count gate + that
- * lastConsolidationAt advances so the next tick doesn't re-spawn.
- *
- * The phase-1 deterministic transitions and the always-`inline` decision are
- * preserved (the guard never escalates).
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { guardSkillCurator, maybeSpawnConsolidation, CADENCE_REGISTRY,
-  handleNightlyBackup,
-  handleNightlyCostReconcile, handleFleetCostDigest, handleOrgCostSync, guardDynamicJobs,
-  guardMessagingInbound, guardDirectoryHygiene, guardBrandSteward } from "./cadence-handlers.mjs";
-import { writeSkill } from "../../lib/learning/skill-writer.mjs";
-import { createJob, parseWhen } from "../../lib/scheduling/dynamic-jobs.mjs";
-
-function tmpRoot() {
-  return mkdtempSync(join(tmpdir(), "maestro-curator-guard-"));
-}
-const stateFile = (root) => join(root, "state", "learning", "consolidation.json");
-const DAY = 86400_000;
-
-/** Seed N active (live) skills for the curator candidate count. */
-function seedSkills(root, n) {
-  for (let i = 0; i < n; i++) {
-    writeSkill({ agentRoot: root, name: `Skill ${i}`, description: "d", body: `body ${i}`, nowIso: new Date().toISOString(), trusted: true });
-  }
-}
-
-test("quarterly-self-assessment guard escalates ONLY in a quarter-start month (0.14)", async () => {
-  const def = CADENCE_REGISTRY["quarterly-self-assessment"];
-  assert.equal(def.mode, "guarded", "wired as a guarded cadence, not always-escalate");
-  assert.equal(typeof def.guard, "function", "has a guard fn");
-  // Jan/Apr/Jul/Oct = quarter starts → escalate; other months → inline (no spawn).
-  for (const m of [0, 3, 6, 9]) {
-    assert.equal((await def.guard({ now: new Date(2026, m, 1) })).decision, "escalate", `month ${m + 1} escalates`);
-  }
-  for (const m of [1, 2, 4, 5, 7, 8, 10, 11]) {
-    assert.equal((await def.guard({ now: new Date(2026, m, 1) })).decision, "inline", `month ${m + 1} stays inline`);
-  }
-});
-
-test("not due below minSkills: spawner not called", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 3);
-  let calls = 0;
-  const r = await maybeSpawnConsolidation(root, { now: Date.now(), spawnFn: () => { calls++; return true; } });
-  assert.equal(calls, 0, "no spawn below threshold");
-  assert.equal(r.spawned, false);
-  assert.equal(r.reason, "below-threshold");
-  assert.ok(!existsSync(stateFile(root)), "no state written when not due");
-});
-
-test("due on first run (no prior state) once at/above minSkills: spawner called + state advanced", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 5);
-  const now = Date.parse("2026-06-10T00:00:00Z");
-  let captured = null;
-  const r = await maybeSpawnConsolidation(root, { now, spawnFn: (ar) => { captured = ar; return true; } });
-  assert.equal(r.spawned, true, "spawned on first due run");
-  assert.equal(captured, root, "spawner handed the agent root");
-  assert.ok(existsSync(stateFile(root)), "consolidation.json written");
-  const saved = JSON.parse(readFileSync(stateFile(root), "utf8"));
-  assert.equal(Date.parse(saved.lastConsolidationAt), now, "lastConsolidationAt set to now");
-});
-
-test("interval gate: within intervalDays of the last run → NOT due (no spawn)", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 6);
-  const last = Date.parse("2026-06-01T00:00:00Z");
-  mkdirSync(join(root, "state", "learning"), { recursive: true });
-  writeFileSync(stateFile(root), JSON.stringify({ lastConsolidationAt: new Date(last).toISOString() }));
-
-  // 10 days later, intervalDays default 14 → still inside the window.
-  let calls = 0;
-  const r = await maybeSpawnConsolidation(root, { now: last + 10 * DAY, spawnFn: () => { calls++; return true; } });
-  assert.equal(calls, 0, "no spawn within the interval");
-  assert.equal(r.reason, "not-due");
-  // State unchanged.
-  assert.equal(Date.parse(JSON.parse(readFileSync(stateFile(root), "utf8")).lastConsolidationAt), last);
-});
-
-test("interval gate: past intervalDays → due again (spawn + state advances)", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 6);
-  const last = Date.parse("2026-06-01T00:00:00Z");
-  mkdirSync(join(root, "state", "learning"), { recursive: true });
-  writeFileSync(stateFile(root), JSON.stringify({ lastConsolidationAt: new Date(last).toISOString() }));
-
-  const now = last + 15 * DAY; // > 14d default
-  let calls = 0;
-  const r = await maybeSpawnConsolidation(root, { now, spawnFn: () => { calls++; return true; } });
-  assert.equal(calls, 1, "spawned once past the interval");
-  assert.equal(r.spawned, true);
-  assert.equal(Date.parse(JSON.parse(readFileSync(stateFile(root), "utf8")).lastConsolidationAt), now, "state advanced");
-});
-
-test("disabled via config: never spawns", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 8);
-  mkdirSync(join(root, "config"), { recursive: true });
-  writeFileSync(join(root, "config", "learning.yaml"), "consolidation:\n  enabled: false\n");
-  let calls = 0;
-  const r = await maybeSpawnConsolidation(root, { now: Date.now(), spawnFn: () => { calls++; return true; } });
-  assert.equal(calls, 0, "disabled → no spawn");
-  assert.equal(r.reason, "disabled");
-});
-
-test("custom minSkills/intervalDays from config are honoured", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 4);
-  mkdirSync(join(root, "config"), { recursive: true });
-  // Lower the floor to 3 and interval to 7 days.
-  writeFileSync(join(root, "config", "learning.yaml"), "consolidation:\n  minSkills: 3\n  intervalDays: 7\n");
-  let calls = 0;
-  const r = await maybeSpawnConsolidation(root, { now: Date.now(), spawnFn: () => { calls++; return true; } });
-  assert.equal(calls, 1, "4 candidates ≥ custom floor 3 → spawned");
-  assert.equal(r.spawned, true);
-});
-
-test("guardSkillCurator: always returns inline; reports consolidation outcome; never escalates", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 5);
-  let spawned = false;
-  const res = await guardSkillCurator(
-    { agentRoot: root, log: () => {} },
-    { consolidation: { now: Date.parse("2026-06-10T00:00:00Z"), spawnFn: () => { spawned = true; return true; } } },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline", "guard never escalates");
-  assert.equal(spawned, true, "consolidation worker spawned when due");
-  assert.equal(res.consolidation, "spawned");
-});
-
-test("guardSkillCurator: below threshold → inline, consolidation reason below-threshold, no spawn", async () => {
-  const root = tmpRoot();
-  seedSkills(root, 2);
-  let spawned = false;
-  const res = await guardSkillCurator(
-    { agentRoot: root, log: () => {} },
-    { consolidation: { now: Date.now(), spawnFn: () => { spawned = true; return true; } } },
-  );
-  assert.equal(res.decision, "inline");
-  assert.equal(spawned, false);
-  assert.equal(res.consolidation, "below-threshold");
-});
-
-test("guardSkillCurator: fully fail-open (bad agentRoot still returns inline)", async () => {
-  const res = await guardSkillCurator({ agentRoot: "/nonexistent/path/xyz", log: () => {} }, {});
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-});
-
-// ---------------------------------------------------------------------------
-// Economics / scheduling cadence handlers (WS-economics)
-// ---------------------------------------------------------------------------
-
-const ev = (cadence) => ({ event: { cadence }, agentRoot: tmpRoot(), log: () => {} });
-
-test("CADENCE_REGISTRY wires the economics/scheduling cadences with the right mode", () => {
-  assert.equal(CADENCE_REGISTRY["nightly-cost-reconcile"].mode, "inline");
-  assert.equal(typeof CADENCE_REGISTRY["nightly-cost-reconcile"].handler, "function");
-  assert.equal(CADENCE_REGISTRY["fleet-cost-digest"].mode, "inline");
-  assert.equal(typeof CADENCE_REGISTRY["fleet-cost-digest"].handler, "function");
-  assert.equal(CADENCE_REGISTRY["org-cost-sync"].mode, "inline");
-  assert.equal(typeof CADENCE_REGISTRY["org-cost-sync"].handler, "function");
-  assert.equal(CADENCE_REGISTRY["dynamic-jobs"].mode, "guarded");
-  assert.equal(typeof CADENCE_REGISTRY["dynamic-jobs"].guard, "function");
-  // dynamic-jobs can escalate → must carry a prompt for the consumer's spawn.
-  assert.ok(CADENCE_REGISTRY["dynamic-jobs"].prompt);
-});
-
-// ---------------------------------------------------------------------------
-// nightly-backup (DR) — the whole point is that a failed run is never silent
-// ---------------------------------------------------------------------------
-
-test("CADENCE_REGISTRY wires nightly-backup as an inline handler", () => {
-  assert.equal(CADENCE_REGISTRY["nightly-backup"].mode, "inline");
-  assert.equal(typeof CADENCE_REGISTRY["nightly-backup"].handler, "function");
-  // Inline cadences must NOT carry a prompt — a prompt would let the consumer
-  // spawn a Claude session for a tar job.
-  assert.ok(!CADENCE_REGISTRY["nightly-backup"].prompt);
-});
-
-test("nightly-backup: a clean run is ok and reports no warnings", async () => {
-  const res = await handleNightlyBackup(ev("nightly-backup"), {
-    runImpl: async () => ({ code: 0, stdout: "[info] backup complete (tier=offsite).\n", stderr: "" }),
-  });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.cadence, "nightly-backup");
-  assert.equal(res.warnings, 0);
-});
-
-test("nightly-backup: a non-zero exit is REPORTED, not swallowed", async () => {
-  const logs = [];
-  const res = await handleNightlyBackup(
-    { event: { cadence: "nightly-backup" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push([lvl, m]) },
-    { runImpl: async () => ({ code: 1, stdout: "", stderr: "[error] REFUSING: no .maestro/backup-config.yaml\n" }) }
-  );
-  assert.equal(res.ok, false);
-  assert.match(res.error, /exited 1/);
-  assert.ok(logs.some(([lvl, m]) => lvl === "error" && /REFUSING/.test(m)), "the refusal must reach the daemon log");
-});
-
-test("nightly-backup: a degraded-but-successful run surfaces its warnings in the daemon log", async () => {
-  const logs = [];
-  const res = await handleNightlyBackup(
-    { event: { cadence: "nightly-backup" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push([lvl, m]) },
-    {
-      runImpl: async () => ({
-        code: 0,
-        stdout:
-          "[info] plan: tier=local\n" +
-          "[warn] offsite is NOT configured — these restore points do not survive losing this machine.\n" +
-          "[warn] include path DROPPED by the credential deny-list: .env (matched .env)\n",
-        stderr: "",
-      }),
-    }
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.warnings, 2);
-  assert.ok(logs.some(([, m]) => /offsite is NOT configured/.test(m)));
-  assert.ok(logs.some(([, m]) => /credential deny-list/.test(m)));
-  assert.ok(!logs.some(([, m]) => /\[info\]/.test(m)), "info noise stays in the backup log, not the daemon log");
-});
-
-test("nightly-backup: a throwing runner degrades to ok:false, never an unhandled rejection", async () => {
-  const res = await handleNightlyBackup(ev("nightly-backup"), {
-    runImpl: async () => { throw new Error("spawn ENOENT"); },
-  });
-  assert.equal(res.ok, false);
-  assert.match(res.error, /spawn ENOENT/);
-});
-
-test("nightly-cost-reconcile: inline, surfaces driftPct, passes NO fetchImpl (fails open)", async () => {
-  let sawFetch = "unset";
-  const fake = async (o) => {
-    sawFetch = o.fetchImpl; // handler must not synthesize a fetchImpl
-    return { day: "2026-06-10", localUSD: 1.0, providerUSD: null, driftPct: null, flagged: false, thresholdPct: 10 };
-  };
-  const res = await handleNightlyCostReconcile(ev("nightly-cost-reconcile"), { reconcileImpl: fake });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.cadence, "nightly-cost-reconcile");
-  assert.equal(res.driftPct, null);
-  assert.equal(res.flagged, false);
-  assert.equal(sawFetch, undefined, "handler passes undefined fetchImpl → reconcile fails open");
-});
-
-test("nightly-cost-reconcile: drift > 10% sets flagged + logs a warning", async () => {
-  const logs = [];
-  const fake = async () => ({ day: "2026-06-10", localUSD: 1.0, providerUSD: 2.0, driftPct: 50, flagged: true, thresholdPct: 10 });
-  const res = await handleNightlyCostReconcile(
-    { event: { cadence: "nightly-cost-reconcile" }, agentRoot: tmpRoot(), log: (lvl, msg) => logs.push([lvl, msg]) },
-    { reconcileImpl: fake },
-  );
-  assert.equal(res.decision, "inline");
-  assert.equal(res.flagged, true);
-  assert.equal(res.driftPct, 50);
-  assert.ok(logs.some(([lvl, msg]) => lvl === "warn" && /drift 50%/.test(msg)), "flagged drift logs a warning");
-});
-
-test("nightly-cost-reconcile: fail-open (lib throw → ok:false, decision inline, never throws)", async () => {
-  const res = await handleNightlyCostReconcile(ev("nightly-cost-reconcile"), {
-    reconcileImpl: async () => { throw new Error("admin api down"); },
-  });
-  assert.equal(res.ok, false);
-  assert.equal(res.decision, "inline");
-  assert.match(res.error, /admin api down/);
-});
-
-test("fleet-cost-digest: inline, returns the digest summary", async () => {
-  const digest = {
-    day: "2026-06-10", totalUSD: 12.5, sessions: 7,
-    cacheReadRatio: 0.72, cacheReadKpiOk: true, source: "local", topSpenders: [], byModel: {}, byAgent: {}, notes: [],
-  };
-  const res = await handleFleetCostDigest(ev("fleet-cost-digest"), { digestImpl: async () => digest });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.totalUSD, 12.5);
-  assert.equal(res.source, "local");
-  assert.match(res.summary, /Fleet LLM spend 2026-06-10 \(local\): \$12\.5 over 7 session/);
-});
-
-test("fleet-cost-digest: cache-read KPI miss logs a warning; fail-open on throw", async () => {
-  const logs = [];
-  const lowKpi = { day: "2026-06-10", totalUSD: 1, sessions: 1, cacheReadRatio: 0.2, cacheReadKpiOk: false, source: "local" };
-  const res = await handleFleetCostDigest(
-    { event: { cadence: "fleet-cost-digest" }, agentRoot: tmpRoot(), log: (lvl, msg) => logs.push([lvl, msg]) },
-    { digestImpl: async () => lowKpi },
-  );
-  assert.equal(res.decision, "inline");
-  assert.ok(logs.some(([lvl]) => lvl === "warn"), "low cache-read KPI warns");
-
-  const failed = await handleFleetCostDigest(ev("fleet-cost-digest"), { digestImpl: async () => { throw new Error("boom"); } });
-  assert.equal(failed.ok, false);
-  assert.equal(failed.decision, "inline");
-  assert.match(failed.error, /boom/);
-});
-
-test("org-cost-sync: inline; no-op/fail-open when org disabled (enabled:false)", async () => {
-  const res = await handleOrgCostSync(ev("org-cost-sync"), {
-    reportImpl: async () => ({ enabled: false, rowsRead: 3, reported: 0, failed: 0, localUSD: 1.5, batches: [] }),
-  });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.enabled, false);
-  assert.equal(res.rowsRead, 3);
-  assert.equal(res.reported, 0);
-  assert.equal(res.localUSD, 1.5);
-});
-
-test("org-cost-sync: reports rows when enabled; fail-open on throw", async () => {
-  const res = await handleOrgCostSync(ev("org-cost-sync"), {
-    reportImpl: async () => ({ enabled: true, rowsRead: 5, reported: 5, failed: 0, localUSD: 4.2, batches: [{ count: 5, ok: true }] }),
-  });
-  assert.equal(res.enabled, true);
-  assert.equal(res.reported, 5);
-
-  const failed = await handleOrgCostSync(ev("org-cost-sync"), { reportImpl: async () => { throw new Error("net"); } });
-  assert.equal(failed.ok, false);
-  assert.equal(failed.decision, "inline");
-  assert.match(failed.error, /net/);
-});
-
-test("dynamic-jobs guard: INLINE when no job is due (real dueJobs over tmp state)", async () => {
-  const root = tmpRoot();
-  // A job whose fire window is 2 hours out → not due now.
-  const now = Date.parse("2026-06-10T09:00:00Z");
-  createJob({ agentRoot: root, when: parseWhen("in 2 hours", { now, tz: "UTC" }), action: "reminder", payload: { text: "later" }, now });
-  const res = await guardDynamicJobs({ event: { cadence: "dynamic-jobs" }, agentRoot: root }, { now });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline", "no due job → inline");
-  assert.equal(res.due, 0);
-});
-
-test("dynamic-jobs guard: ESCALATES with the due jobs when one fires", async () => {
-  const root = tmpRoot();
-  const now = Date.parse("2026-06-10T09:00:00Z");
-  // One-off due 1 minute ago (within TTL) → fires now.
-  createJob({ agentRoot: root, when: { at: now - 60_000, tz: "UTC" }, action: "reminder", payload: { text: "ping Layla" }, now });
-  const res = await guardDynamicJobs({ event: { cadence: "dynamic-jobs" }, agentRoot: root }, { now });
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "escalate", "a due job escalates so the consumer spawns a session");
-  assert.equal(res.due, 1);
-  assert.ok(Array.isArray(res.jobs) && res.jobs.length === 1, "due jobs carried in the result");
-  assert.equal(res.jobs[0].payload.text, "ping Layla");
-});
-
-test("dynamic-jobs guard: escalates only when due (injected dueJobs proves the gate)", async () => {
-  // Empty → inline.
-  const none = await guardDynamicJobs({ event: { cadence: "dynamic-jobs" }, agentRoot: "/tmp/x" }, { dueJobsImpl: () => [] });
-  assert.equal(none.decision, "inline");
-  assert.equal(none.due, 0);
-  // Non-empty → escalate, jobs forwarded.
-  const some = await guardDynamicJobs(
-    { event: { cadence: "dynamic-jobs" }, agentRoot: "/tmp/x" },
-    { dueJobsImpl: () => [{ id: "job-1", action: "reminder" }, { id: "job-2", action: "channel-summary" }] },
-  );
-  assert.equal(some.decision, "escalate");
-  assert.equal(some.due, 2);
-});
-
-test("dynamic-jobs guard: fail-open (dueJobs throws → inline, never throws)", async () => {
-  const res = await guardDynamicJobs({ event: { cadence: "dynamic-jobs" }, agentRoot: "/tmp/x" }, {
-    dueJobsImpl: () => { throw new Error("store corrupt"); },
-  });
-  assert.equal(res.ok, false);
-  assert.equal(res.decision, "inline");
-  assert.match(res.error, /store corrupt/);
-});
-
-test("monitoring-alerts cadence is registered inline and fires alerts to a sink", async () => {
-  const def = CADENCE_REGISTRY["monitoring-alerts"];
-  assert.equal(def.mode, "inline");
-  assert.equal(typeof def.handler, "function");
-
-  // Inject a guard-fail spike snapshot + a capturing sink; a quiet ledger/presence.
-  const delivered = [];
-  const res = await def.handler(
-    { event: { cadence: "monitoring-alerts" }, agentRoot: "/tmp/none", log: () => {} },
-    {
-      snapshot: { "guard.fail": 999, "send.blocked": 999 },
-      ledger: { spentUSD: 0, sessions: 0, byModel: {} },
-      presence: [],
-      health: { daemonDown: false, ts: Date.now() },
-      cfg: {},
-      now: Date.now(),
-      sink: async (a) => { delivered.push(a); },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.ok(res.alerts >= 1, "a guard-fail spike fired at least one alert");
-  assert.ok(delivered.length >= 1, "alerts were delivered to the sink");
-});
-
-test("monitoring-alerts is quiet when nothing is wrong", async () => {
-  const def = CADENCE_REGISTRY["monitoring-alerts"];
-  const delivered = [];
-  const res = await def.handler(
-    { event: { cadence: "monitoring-alerts" }, agentRoot: "/tmp/none", log: () => {} },
-    {
-      snapshot: {}, ledger: { spentUSD: 0, sessions: 0, byModel: {} }, presence: [],
-      health: { daemonDown: false, ts: Date.now() }, cfg: {}, now: Date.now(),
-      sink: async (a) => { delivered.push(a); },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.alerts, 0);
-  assert.equal(delivered.length, 0);
-});
-
-// ---------------------------------------------------------------------------
-// messaging-inbound guard (SP10)
-// ---------------------------------------------------------------------------
-
-test("CADENCE_REGISTRY wires messaging-inbound as guarded with a prompt (can escalate)", () => {
-  const def = CADENCE_REGISTRY["messaging-inbound"];
-  assert.equal(def.mode, "guarded");
-  assert.equal(typeof def.guard, "function");
-  assert.ok(def.prompt, "carries a trigger prompt for the escalate path");
-});
-
-test("messaging-inbound: pulls new directed items and routes them into the inbox (inline by default)", async () => {
-  const root = tmpRoot();
-  const written = [];
-  const ev1 = { channel: "cohort", message_id: "m1", channel_id: "C", text: "@me ping", from: { id: "agent-2" } };
-  const ev2 = { channel: "cohort", message_id: "m2", channel_id: "C", text: "call invite", from: { id: "agent-3" } };
-
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t", agentId: "me" } } },
-      // Fresh root → no inbound cursor. Seed from the push-channel head so the
-      // pull starts at "now" (not genesis). The stub stands in for
-      // lib/org/push.readCursor.
-      pushHeadImpl: () => 5,
-      pullImpl: async () => ({ events: [ev1, ev2], nextCursor: 12 }),
-      toInboxImpl: (e) => ({ id: e.message_id, service: "cohort", content: e.text }),
-      writeImpl: (service, item) => written.push({ service, item }),
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline", "reactive daemon owns dispatch → inline routing by default");
-  assert.equal(res.routed, 2);
-  assert.equal(written.length, 2);
-  assert.equal(written[0].service, "cohort", "items land under state/inbox/cohort/");
-  // Cursor persisted atomically after writing.
-  const cursorFile = join(root, "state", "messaging", "inbound-cursor.json");
-  assert.ok(existsSync(cursorFile));
-  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 12);
-});
-
-test("messaging-inbound: FIRST RUN seeds the inbound cursor from the push-channel head (no backlog replay)", async () => {
-  const root = tmpRoot();
-  let pulledCursor = null;
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-      // The push channel has advanced to seq 4200. A fresh install must start
-      // there, NOT at 0 (which would replay the whole org ledger).
-      pushHeadImpl: () => 4200,
-      pullImpl: async ({ cursor }) => { pulledCursor = cursor; return { events: [], nextCursor: cursor }; },
-      toInboxImpl: () => ({}),
-      writeImpl: () => { throw new Error("should not write an item"); },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(pulledCursor, 4200, "the pull started at the push head, not at genesis");
-  const cursorFile = join(root, "state", "messaging", "inbound-cursor.json");
-  assert.ok(existsSync(cursorFile), "the seeded head is persisted so a crash cannot fall back to genesis");
-  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 4200);
-});
-
-test("messaging-inbound: FIRST RUN with no push head yet HOLDS the tick (never replays from genesis)", async () => {
-  const root = tmpRoot();
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-      pushHeadImpl: () => null, // push channel has not established a head yet
-      pullImpl: async () => { throw new Error("must not pull before a head exists"); },
-      toInboxImpl: () => ({}),
-      writeImpl: () => { throw new Error("must not write"); },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.routed, 0);
-  assert.match(res.reason, /awaiting push-channel head/);
-  assert.ok(!existsSync(join(root, "state", "messaging", "inbound-cursor.json")), "no cursor seeded while we wait for a head");
-});
-
-test("messaging-inbound: no new directed items → inline, routed 0, cursor unchanged", async () => {
-  const root = tmpRoot();
-  // A cursor already exists (not a first run), so seeding is skipped and the pull
-  // starts from the persisted seq. Nothing new → the cursor must not move.
-  const cursorFile = join(root, "state", "messaging", "inbound-cursor.json");
-  mkdirSync(join(root, "state", "messaging"), { recursive: true });
-  writeFileSync(cursorFile, JSON.stringify({ cursor: 9, updatedAt: "2026-01-01T00:00:00Z" }));
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-      pullImpl: async ({ cursor }) => { assert.equal(cursor, 9, "pull starts from the persisted cursor"); return { events: [], nextCursor: cursor }; },
-      toInboxImpl: () => ({}),
-      writeImpl: () => { throw new Error("should not write"); },
-    },
-  );
-  assert.equal(res.decision, "inline");
-  assert.equal(res.routed, 0);
-  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 9, "cursor unchanged when nothing advanced");
-});
-
-test("messaging-inbound: org not configured → inline no-op (fail-open)", async () => {
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: {}, pullImpl: async () => { throw new Error("should not pull"); } },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.equal(res.routed, 0);
-  assert.match(res.reason, /not configured/);
-});
-
-test("messaging-inbound: MESSAGING_INBOUND_ESCALATE=1 escalates when items arrive", async () => {
-  const prev = process.env.MESSAGING_INBOUND_ESCALATE;
-  process.env.MESSAGING_INBOUND_ESCALATE = "1";
-  try {
-    const res = await guardMessagingInbound(
-      { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: () => {} },
-      {
-        cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-        pushHeadImpl: () => 1,
-        pullImpl: async () => ({ events: [{ message_id: "m1", text: "@me" }], nextCursor: 1 }),
-        toInboxImpl: (e) => ({ id: e.message_id }),
-        writeImpl: () => {},
-      },
-    );
-    assert.equal(res.decision, "escalate");
-    assert.equal(res.routed, 1);
-  } finally {
-    if (prev === undefined) delete process.env.MESSAGING_INBOUND_ESCALATE;
-    else process.env.MESSAGING_INBOUND_ESCALATE = prev;
-  }
-});
-
-test("messaging-inbound: fully fail-open (pull throws → inline, never throws)", async () => {
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-      pushHeadImpl: () => 3,
-      pullImpl: async () => { throw new Error("network down"); },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "inline");
-  assert.match(res.error, /network down/);
-});
-
-// ---------------------------------------------------------------------------
-// directory-hygiene (2026-07) — guarded, propose-only
-// ---------------------------------------------------------------------------
-
-const ORG_CFG = { org: { cohort: { enabled: true, base: "https://org.example", token: "t", orgId: "acme" } } };
-
-test("directory-hygiene: pending captures/duplicates → escalate with the counts", async () => {
-  const seen = [];
-  const res = await guardDirectoryHygiene(
-    { event: { cadence: "directory-hygiene" }, agentRoot: tmpRoot(), log: () => {} },
-    {
-      cfg: ORG_CFG,
-      callImpl: async (method, params) => {
-        seen.push({ method, params });
-        if (method === "directory.listCaptures") return { ok: true, result: { captures: [{ id: "c1" }, { id: "c2" }] } };
-        if (method === "directory.listMerges") return { ok: true, result: { candidates: [{ id: "m1" }] } };
-        throw new Error(`unexpected ${method}`);
-      },
-    },
-  );
-  assert.equal(res.ok, true);
-  assert.equal(res.decision, "escalate");
-  assert.equal(res.captures, 2);
-  assert.equal(res.duplicates, 1);
-  assert.equal(res.pending, 3);
-  // The guard is READ-ONLY: only the two queue reads, both filtered to PENDING.
-  assert.deepEqual(seen.map((c) => c.method).sort(), ["directory.listCaptures", "directory.listMerges"]);
-  for (const c of seen) assert.equal(c.params.status, "PENDING");
-});
-
-test("directory-hygiene: clear queues → inline, no spawn", async () => {
-  const res = await guardDirectoryHygiene(
-    { event: { cadence: "directory-hygiene" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: ORG_CFG, callImpl: async () => ({ ok: true, result: { captures: [], candidates: [] } }) },
-  );
-  assert.equal(res.decision, "inline");
-  assert.equal(res.captures, 0);
-  assert.equal(res.duplicates, 0);
-  assert.match(res.reason, /clear/);
-});
-
-test("directory-hygiene: org unconfigured → inline no-op; a throwing call stays inline (fail-open)", async () => {
-  const off = await guardDirectoryHygiene(
-    { event: { cadence: "directory-hygiene" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: {}, callImpl: async () => { throw new Error("should not call"); } },
-  );
-  assert.equal(off.ok, true);
-  assert.equal(off.decision, "inline");
-  assert.match(off.reason, /not configured/);
-
-  const boom = await guardDirectoryHygiene(
-    { event: { cadence: "directory-hygiene" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: ORG_CFG, callImpl: async () => { throw new Error("network down"); } },
-  );
-  assert.equal(boom.ok, true, "a guard must never throw or DLQ the tick");
-  assert.equal(boom.decision, "inline");
-  assert.match(boom.error, /network down/);
-});
-
-test("directory-hygiene is registered guarded, propose-only in its scoped allowlist", () => {
-  const def = CADENCE_REGISTRY["directory-hygiene"];
-  assert.equal(def.mode, "guarded");
-  assert.equal(typeof def.guard, "function");
-  assert.equal(def.prompt, "schedules/triggers/directory-hygiene.md");
-  // The human-gated verbs must be absent, so even MAESTRO_SCOPED_PERMISSIONS=1
-  // sessions physically cannot reach for them.
-  for (const banned of [
-    "directory_resolve_capture", "directory_execute_merge", "directory_revert_merge",
-    "directory_set_awareness", "directory_archive_person", "directory_archive_org",
-  ]) {
-    assert.ok(!def.allowedTools.includes(banned), `${banned} must not be reachable`);
-  }
-  assert.ok(def.allowedTools.includes("directory_propose_capture"));
-  assert.ok(def.allowedTools.includes("directory_propose_merge"));
-});
-
-// ---------------------------------------------------------------------------
-// brand-steward (2026-07) — guarded on a real foundation save
-// ---------------------------------------------------------------------------
-
-test("brand-steward: a branding version.saved event → escalate; cursor persisted", async () => {
-  const root = tmpRoot();
-  const res = await guardBrandSteward(
-    { event: { cadence: "brand-steward" }, agentRoot: root, log: () => {} },
-    {
-      cfg: ORG_CFG,
-      readImpl: async (path) => {
-        assert.match(path, /^events\?cursor=0&limit=200/);
-        return {
-          ok: true,
-          payload: {
-            events: [
-              { seq: 41, family: "messaging", kind: "message.sent" },
-              { seq: 42, family: "branding", kind: "version.saved" },
-            ],
-          },
-        };
-      },
-    },
-  );
-  assert.equal(res.decision, "escalate");
-  assert.equal(res.saves, 1, "only the branding save counts");
-  assert.equal(res.latestKind, "version.saved");
-  const cursorFile = join(root, "state", "org", "brand-steward-cursor.json");
-  assert.ok(existsSync(cursorFile));
-  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 42, "cursor advances past the whole window");
-});
-
-test("brand-steward: unrelated events only → inline, cursor still advances", async () => {
-  const root = tmpRoot();
-  const res = await guardBrandSteward(
-    { event: { cadence: "brand-steward" }, agentRoot: root, log: () => {} },
-    {
-      cfg: ORG_CFG,
-      readImpl: async () => ({ ok: true, payload: { events: [{ seq: 7, family: "books", kind: "invoice.sent" }] } }),
-    },
-  );
-  assert.equal(res.decision, "inline");
-  assert.equal(res.saves, 0);
-  assert.equal(JSON.parse(readFileSync(join(root, "state", "org", "brand-steward-cursor.json"), "utf8")).cursor, 7);
-});
-
-test("brand-steward: empty window leaves the cursor alone; unconfigured/throwing stays inline", async () => {
-  const root = tmpRoot();
-  const empty = await guardBrandSteward(
-    { event: { cadence: "brand-steward" }, agentRoot: root, log: () => {} },
-    { cfg: ORG_CFG, readImpl: async () => ({ ok: true, payload: { events: [] } }) },
-  );
-  assert.equal(empty.decision, "inline");
-  assert.ok(!existsSync(join(root, "state", "org", "brand-steward-cursor.json")), "no cursor write when nothing advanced");
-
-  const off = await guardBrandSteward(
-    { event: { cadence: "brand-steward" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: {}, readImpl: async () => { throw new Error("should not read"); } },
-  );
-  assert.equal(off.decision, "inline");
-  assert.match(off.reason, /not configured/);
-
-  const boom = await guardBrandSteward(
-    { event: { cadence: "brand-steward" }, agentRoot: tmpRoot(), log: () => {} },
-    { cfg: ORG_CFG, readImpl: async () => { throw new Error("network down"); } },
-  );
-  assert.equal(boom.ok, true, "a guard must never throw or DLQ the tick");
-  assert.equal(boom.decision, "inline");
-  assert.match(boom.error, /network down/);
-});
-
-test("brand-steward is registered guarded and cannot reach the admin foundation writers", () => {
-  const def = CADENCE_REGISTRY["brand-steward"];
-  assert.equal(def.mode, "guarded");
-  assert.equal(typeof def.guard, "function");
-  assert.equal(def.prompt, "schedules/triggers/brand-steward.md");
-  for (const banned of ["branding_save_foundation", "design_save_foundation", "design_restore_foundation"]) {
-    assert.ok(!def.allowedTools.includes(banned), `${banned} must not be reachable`);
-  }
-  assert.ok(def.allowedTools.includes("design_propose_change"), "proposing IS the lane");
-});
-
-// ---------------------------------------------------------------------------
-// messaging-inbound is WIDE (JOINT 3) — the LIVE default, not an injected stub
-// ---------------------------------------------------------------------------
-
-/**
- * The regression this pins: `guardMessagingInbound` used to default to
- * `lib/org/messaging.pullInbound`, whose events URL hardcodes
- * `family=messaging,calling`. Board, calendar, escalation, approval, decision,
- * files and handoff events were read off the wire and discarded, so a task
- * assigned to this agent reached NOBODY — hq stands down for a live daemon
- * (4d762d30) and the daemon was structurally deaf to the family.
- *
- * No `pullImpl` here ON PURPOSE: the point is which reader the REAL default
- * resolves to. Only the network is faked.
- */
-test("messaging-inbound (JOINT 3): the DEFAULT reader is wide — no family filter, and a board assignment arrives", async () => {
-  const root = tmpRoot();
-  const urls = [];
-  const written = [];
-  const ME = "member-me";
-
-  const json = (body) => ({
-    ok: true,
-    status: 200,
-    headers: { get: () => "application/json" },
-    text: async () => JSON.stringify(body),
-    json: async () => body,
-  });
-
-  const fetchImpl = async (url, init) => {
-    const u = String(url);
-    urls.push(`${(init && init.method) || "GET"} ${u}`);
-    if (u.includes("/events?")) {
-      return json({
-        events: [
-          {
-            seq: 501, family: "board", kind: "item.assigned", entity_id: "task-9",
-            actor: "member-boss", at: "2026-08-11T09:00:00Z",
-            // REDACTED BY DESIGN: no mention list, no recipient list.
-            payload: { actor: "member-boss", assignee: ME, assignedBy: "member-boss" },
-          },
-        ],
-        nextCursor: 501,
-      });
-    }
-    if (u.includes("board.context")) {
-      return json({ ok: true, result: { tasks: [{ id: "task-9", title: "Ship the transport joint", assigneeId: ME, col: "todo" }] } });
-    }
-    if (u.includes("messaging.channels")) return json({ ok: true, result: { channels: [] } });
-    return json({ ok: true, result: {} });
-  };
-
-  const res = await guardMessagingInbound(
-    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
-    {
-      cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
-      agentId: ME,
-      pushHeadImpl: () => 1, // fresh root: seed past genesis so the ledger read runs
-      fetchImpl,
-      toInboxImpl: (e) => ({ id: e.id, service: "cohort", kind: e.kind, content: e.text }),
-      writeImpl: (service, item) => written.push({ service, item }),
-    },
-  );
-
-  const eventsUrl = urls.find((u) => u.includes("/events?"));
-  assert.ok(eventsUrl, "the ledger was read");
-  assert.ok(
-    !/family=/.test(eventsUrl),
-    `the events read must NOT pin a family — got ${eventsUrl}`,
-  );
-  assert.equal(res.wide, true, "the wide reader is the default, not an opt-in");
-  assert.equal(res.routed, 1, "a board assignment reaches the inbox pipeline");
-  assert.equal(written[0].item.kind, "task_assigned", "and carries the routing hint the classifier needs");
-  assert.equal(res.stats.bySurface.task_assigned, 1);
-});
-
-test("messaging-inbound (JOINT 3): MESSAGING_INBOUND_WIDE=0 falls back to the narrow reader — and SAYS SO", async () => {
-  const prev = process.env.MESSAGING_INBOUND_WIDE;
-  process.env.MESSAGING_INBOUND_WIDE = "0";
-  const logs = [];
-  try {
-    const res = await guardMessagingInbound(
-      { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push(`${lvl}:${m}`) },
-      {
-        cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
-        agentId: "member-me",
-        pushHeadImpl: () => 1, // fresh root: seed past genesis so the read runs
-        // The narrow reader pins family=messaging,calling on its URL; assert the
-        // degradation is announced rather than inferred from an empty inbox.
-        fetchImpl: async () => ({ ok: true, status: 200, headers: { get: () => "application/json" }, text: async () => JSON.stringify({ events: [], nextCursor: 0 }), json: async () => ({ events: [], nextCursor: 0 }) }),
-      },
-    );
-    assert.equal(res.wide, false);
-    assert.ok(
-      logs.some((l) => l.startsWith("warn:") && /WILL NOT arrive/.test(l)),
-      `a silent narrowing is the bug; got ${JSON.stringify(logs)}`,
-    );
-  } finally {
-    if (prev === undefined) delete process.env.MESSAGING_INBOUND_WIDE;
-    else process.env.MESSAGING_INBOUND_WIDE = prev;
-  }
-});