@cohortapp/agent-sdk 2.3.0

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

@@ -0,0 +1,617 @@
+/**
+ * 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,
+  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);
+});
+
+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" } } },
+      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: no new directed items → inline, routed 0, cursor unchanged", 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" } } },
+      pullImpl: async ({ cursor }) => ({ events: [], nextCursor: cursor }),
+      toInboxImpl: () => ({}),
+      writeImpl: () => { throw new Error("should not write"); },
+    },
+  );
+  assert.equal(res.decision, "inline");
+  assert.equal(res.routed, 0);
+  assert.ok(!existsSync(join(root, "state", "messaging", "inbound-cursor.json")), "no cursor write 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" } } },
+        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" } } },
+      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");
+});