@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/scripts/daemon/goal-steward-cadence.test.mjs

@@ -0,0 +1,243 @@
+/**
+ * scripts/daemon/goal-steward-cadence.test.mjs — the wiring that makes the
+ * self-directed loop actually RUN.
+ *
+ * Before this, `lib/goals/loop.mjs` existed and nothing ever called it: no
+ * standard cadence, no registry entry, no plist. A loop nobody triggers is a
+ * design document. These tests pin the trigger down:
+ *
+ *   - `goal-steward` is a STANDARD cadence, so every agent gets a plist for it
+ *   - it is GUARDED, so an agent with no adopted mandate costs ~nothing
+ *   - it refreshes the mandate BEFORE measuring
+ *   - it defaults to observe-only, whatever the caller forgot to pass
+ *   - it escalates only when an open gap needs candidates it cannot produce
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { CADENCE_REGISTRY, getCadenceDef, guardGoalSteward } from "./cadence-handlers.mjs";
+import { STANDARD_CADENCES } from "../../lib/cadences.mjs";
+
+function makeRoot() {
+  const root = mkdtempSync(join(tmpdir(), "goal-cadence-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function cleanup(root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ } }
+
+/** Baseline seams: no network, no real loop. */
+function seams(over = {}) {
+  return {
+    refreshImpl: async () => ({ ok: true, source: "server", tier: "fresh" }),
+    runImpl: async () => ({ ok: true, measured: [], admitted: [], rejected: [], escalations: [], drift: [], decisions: [] }),
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+test("goal-steward is a STANDARD cadence, so every agent gets one", () => {
+  const c = STANDARD_CADENCES.find((x) => x.id === "goal-steward");
+  assert.ok(c, "the loop must have a trigger or it never runs");
+  assert.equal(c.scope, "standard");
+  assert.equal(c.mode, "guarded");
+  // Daily, on a calendar slot — not a hot interval.
+  assert.deepEqual(c.calendar, { hour: 7, minute: 15 });
+  assert.equal(c.prompt, "schedules/triggers/goal-steward.md");
+});
+
+test("the daemon can route the cadence it is about to be sent", () => {
+  const def = getCadenceDef("goal-steward");
+  assert.ok(def, "an unroutable cadence DLQs every tick");
+  assert.equal(def.mode, "guarded");
+  assert.equal(typeof def.guard, "function");
+  assert.equal(CADENCE_REGISTRY["goal-steward"].guard, guardGoalSteward);
+  // Scoped tool surface: reads + collaboration primitives, no shell.
+  const tools = CADENCE_REGISTRY["goal-steward"].allowedTools;
+  assert.ok(Array.isArray(tools) && tools.length > 0);
+  assert.ok(tools.includes("approval_request"), "gated work must be able to reach the approval path");
+  assert.ok(!tools.includes("Bash"), "the goal loop has no business running shell");
+});
+
+// ---------------------------------------------------------------------------
+// The guard
+// ---------------------------------------------------------------------------
+
+test("the mandate is refreshed BEFORE the loop measures anything", async () => {
+  const root = makeRoot();
+  try {
+    const order = [];
+    await guardGoalSteward({ event: { cadence: "goal-steward" }, agentRoot: root, log: () => {} }, seams({
+      refreshImpl: async () => { order.push("refresh"); return { ok: true }; },
+      runImpl: async () => { order.push("run"); return { ok: true, measured: [], admitted: [], decisions: [] }; },
+    }));
+    assert.deepEqual(order, ["refresh", "run"], "measuring against a stale mandate is worse than not measuring");
+  } finally { cleanup(root); }
+});
+
+test("enforcement defaults to OBSERVE when config/plan.yaml says nothing", async () => {
+  const root = makeRoot();
+  try {
+    let seen = null;
+    await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async (d) => { seen = d.enforcement; return { ok: true, measured: [], admitted: [], decisions: [] }; },
+    }));
+    assert.equal(seen, "observe", "a loop that starts by writing is how you lose a fleet");
+  } finally { cleanup(root); }
+});
+
+test("enforcement:active in config/plan.yaml turns the loop on", async () => {
+  const root = makeRoot();
+  try {
+    writeFileSync(join(root, "config", "plan.yaml"), "version: 1\nenforcement: active\nobligations: []\n", "utf-8");
+    let seen = null;
+    await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async (d) => { seen = d.enforcement; return { ok: true, measured: [], admitted: [], decisions: [] }; },
+    }));
+    assert.equal(seen, "active");
+  } finally { cleanup(root); }
+});
+
+test("any other enforcement value stays observe — fail-closed on the write path", async () => {
+  const root = makeRoot();
+  try {
+    writeFileSync(join(root, "config", "plan.yaml"), "enforcement: yes-please\n", "utf-8");
+    let seen = null;
+    await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async (d) => { seen = d.enforcement; return { ok: true, measured: [], admitted: [], decisions: [] }; },
+    }));
+    assert.equal(seen, "observe");
+  } finally { cleanup(root); }
+});
+
+test("no adopted mandate completes INLINE — an idle seat costs one cache read", async () => {
+  const root = makeRoot();
+  try {
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async () => ({ ok: false, skipped: "no mandate cache — this seat has never fetched an adopted mandate" }),
+    }));
+    assert.equal(r.ok, true, "a pre-adoption seat is not a bus failure");
+    assert.equal(r.decision, "inline");
+    assert.match(r.reason, /never fetched an adopted mandate/);
+  } finally { cleanup(root); }
+});
+
+test("a satisfied mandate completes inline and never spawns a session", async () => {
+  const root = makeRoot();
+  try {
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async () => ({
+        ok: true, measured: [{ objectiveKey: "pipeline", value: 4 }], admitted: [], rejected: [],
+        escalations: [], drift: [], decisions: [{ objectiveKey: "pipeline", action: "none" }],
+      }),
+    }));
+    assert.equal(r.decision, "inline");
+    assert.equal(r.measured, 1);
+    assert.equal(r.admitted, 0);
+  } finally { cleanup(root); }
+});
+
+test("a gap the deterministic planner SERVED completes inline — the work is already queued", async () => {
+  const root = makeRoot();
+  try {
+    writeFileSync(join(root, "config", "plan.yaml"), "enforcement: active\n", "utf-8");
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async () => ({
+        ok: true,
+        measured: [{ objectiveKey: "pipeline", value: 1 }],
+        admitted: [{ objectiveKey: "pipeline", title: "Book calls" }],
+        rejected: [], escalations: [], drift: [],
+        decisions: [{ objectiveKey: "pipeline", action: "create" }],
+      }),
+    }));
+    assert.equal(r.decision, "inline", "no model is needed when the work already exists");
+    assert.equal(r.admitted, 1);
+  } finally { cleanup(root); }
+});
+
+test("an UNSERVED open gap escalates to a planning session, naming the objectives", async () => {
+  const root = makeRoot();
+  try {
+    writeFileSync(join(root, "config", "plan.yaml"), "enforcement: active\n", "utf-8");
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async () => ({
+        ok: true,
+        measured: [{ objectiveKey: "pipeline", value: 1 }],
+        admitted: [], rejected: [], escalations: [], drift: [],
+        decisions: [{ objectiveKey: "pipeline", action: "create" }],
+      }),
+    }));
+    assert.equal(r.decision, "escalate");
+    assert.deepEqual(r.objectives, ["pipeline"]);
+  } finally { cleanup(root); }
+});
+
+test("OBSERVE-ONLY never escalates, even with an unserved gap", async () => {
+  const root = makeRoot();
+  try {
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: () => {} }, seams({
+      runImpl: async () => ({
+        ok: true, measured: [], admitted: [], rejected: [], escalations: [], drift: [],
+        decisions: [{ objectiveKey: "pipeline", action: "create" }],
+      }),
+    }));
+    assert.equal(r.decision, "inline", "the observe window must not spend money on planning sessions");
+  } finally { cleanup(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Failure containment
+// ---------------------------------------------------------------------------
+
+test("SERVER UNREACHABLE: a failed mandate refresh degrades to the cache, loudly", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: (l, m) => logs.push(`${l}:${m}`) }, seams({
+      refreshImpl: async () => ({ ok: false, reason: "call-threw:ECONNREFUSED" }),
+    }));
+    assert.equal(r.ok, true, "a partition must not stop the loop from running on cache");
+    assert.ok(logs.some((l) => /refresh failed/.test(l)));
+  } finally { cleanup(root); }
+});
+
+test("SERVER UNREACHABLE: a THROWING refresh is contained and logged", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: (l, m) => logs.push(`${l}:${m}`) }, seams({
+      refreshImpl: async () => { throw new Error("ECONNREFUSED"); },
+    }));
+    assert.equal(r.ok, true);
+    assert.ok(logs.some((l) => /refresh threw/.test(l)));
+  } finally { cleanup(root); }
+});
+
+test("a THROWING loop returns ok:false with the error — fail-open but never silent", async () => {
+  const root = makeRoot();
+  try {
+    const logs = [];
+    const r = await guardGoalSteward({ event: {}, agentRoot: root, log: (l, m) => logs.push(`${l}:${m}`) }, seams({
+      runImpl: async () => { throw new Error("loop exploded"); },
+    }));
+    assert.equal(r.ok, false);
+    assert.match(r.error, /loop exploded/);
+    assert.ok(logs.some((l) => l.startsWith("error:")), "the daemon keeps running, the failure is on the record");
+  } finally { cleanup(root); }
+});
+
+test("the guard never throws, whatever it is handed", async () => {
+  const r = await guardGoalSteward({ event: null, agentRoot: "/nonexistent-xyz", log: null }, seams({
+    runImpl: async () => null,
+  }));
+  assert.equal(typeof r.ok, "boolean");
+  assert.equal(r.cadence, "goal-steward");
+});

package/scripts/daemon/inbox-deferral.mjs

@@ -37,7 +37,36 @@
 import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const SERVICE_DIRS = ["slack", "gmail", "calendar", "internal", "sms", "whatsapp"];
+import { signalInbox } from "./inbox-wake.mjs";
+
+/**
+ * Fallback service list, used only when `state/inbox/` cannot be enumerated.
+ *
+ * It used to be the ONLY list, and it was written before the channel-bus and
+ * org services existed: `cohort`, `orgmail` and `telegram` were never in it. A
+ * deferred Cohort DM (the second message of any rapid-fire burst) therefore had
+ * NO promote path at all — `promoteDeferred` looked in six directories, none of
+ * which was `state/inbox/cohort/`, found nothing, and the message stayed
+ * `.deferred` forever. The list is now derived from disk (below) so a new
+ * service can never be silently un-promotable again.
+ */
+const FALLBACK_SERVICE_DIRS = ["slack", "gmail", "calendar", "internal", "sms", "whatsapp"];
+
+/**
+ * Every service inbox that exists on disk. Derived, not enumerated — the
+ * directories ARE the registry (the daemon creates one per configured service).
+ * @param {string} agentRoot
+ * @returns {string[]}
+ */
+function serviceDirs(agentRoot) {
+  try {
+    return readdirSync(join(agentRoot, "state", "inbox"), { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return FALLBACK_SERVICE_DIRS;
+  }
+}
 
 /**
  * Rename a live inbox file to its `.deferred` suffix so the scanner
@@ -142,7 +171,7 @@ export function promoteDeferred(channel, agentRoot) {
   const result = { promoted: 0, bundled: 0, service: null };
   if (!channel || !agentRoot) return result;
 
-  for (const service of SERVICE_DIRS) {
+  for (const service of serviceDirs(agentRoot)) {
     const inboxDir = join(agentRoot, "state", "inbox", service);
     if (!existsSync(inboxDir)) continue;
 
@@ -206,5 +235,19 @@ export function promoteDeferred(channel, agentRoot) {
     }
   }
 
+  // The promoted item is live on disk RIGHT NOW, and this runs on the
+  // dispatcher's session-close path — i.e. the moment a burst's next message
+  // becomes answerable. Without a nudge it waits for the daemon's next inbox
+  // sweep, which is the single largest term in the reply latency of a
+  // back-to-back conversation. Free and idempotent: a wake with no work costs
+  // one readdir (scripts/daemon/inbox-wake.mjs).
+  if (result.promoted > 0) {
+    try {
+      signalInbox("promote-deferred");
+    } catch {
+      /* the wake is an optimisation — never let it break the promote */
+    }
+  }
+
   return result;
 }

package/scripts/daemon/inbox-deferral.test.mjs

@@ -240,3 +240,59 @@ test("L7: latest-wins uses top-level timestamp, not a body `timestamp:` line", (
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+// --- service-dir discovery (the cohort/orgmail regression) -------------------
+
+/** Write a deferred item into ANY service dir (creating it). */
+function writeDeferredIn(root, service, name, { channel_id, timestamp, id }) {
+  mkdirSync(join(root, "state", "inbox", service), { recursive: true });
+  const body = [
+    `id: "${id}"`,
+    `service: "${service}"`,
+    `channel_id: "${channel_id}"`,
+    `timestamp: "${timestamp}"`,
+    `content: |`,
+    `  body`,
+    "",
+  ].join("\n");
+  writeFileSync(join(root, "state", "inbox", service, name), body);
+}
+
+test("promoteDeferred finds services the hardcoded list never knew about (cohort/orgmail)", () => {
+  const root = makeAgentRoot();
+  try {
+    writeDeferredIn(root, "cohort", "cohort-msg.yaml.deferred", {
+      channel_id: "ch_build",
+      timestamp: "2026-08-11T00:00:00Z",
+      id: "cohort-msg",
+    });
+    const r = promoteDeferred("ch_build", root);
+    assert.equal(r.promoted, 1, "a deferred Cohort message was previously un-promotable forever");
+    assert.equal(r.service, "cohort");
+    assert.deepEqual(readdirSync(join(root, "state", "inbox", "cohort")), ["cohort-msg.yaml"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("promoteDeferred signals the inbox wake so the promoted item is not stuck behind the poll", async () => {
+  const { waitForInboxWake, resetInboxWake } = await import("./inbox-wake.mjs");
+  const root = makeAgentRoot();
+  resetInboxWake();
+  try {
+    writeDeferredIn(root, "cohort", "burst-2.yaml.deferred", {
+      channel_id: "ch_dm",
+      timestamp: "2026-08-11T00:00:01Z",
+      id: "burst-2",
+    });
+    // scanMs is disabled so ONLY the in-process signal can settle this.
+    const waiting = waitForInboxWake({ agentRoot: root, timeoutMs: 3_000, scanMs: 600_000 });
+    setTimeout(() => promoteDeferred("ch_dm", root), 20);
+    const woke = await waiting;
+    assert.equal(woke.woke, true);
+    assert.equal(woke.service, "cohort");
+  } finally {
+    resetInboxWake();
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/scripts/daemon/inbox-wake.mjs

@@ -0,0 +1,282 @@
+/**
+ * scripts/daemon/inbox-wake.mjs — the daemon's "something landed" wake signal.
+ *
+ * ## The hop this removes
+ *
+ * The inbound ladder for a Cohort message is: hq commits → the messaging-inbound
+ * cadence pulls it → an inbox YAML file is written under
+ * `state/inbox/<service>/` → **the daemon notices on its next poll** → classify →
+ * dispatch. That last arrow was a flat `setInterval(poll, 60_000)`: a mean 30s
+ * and worst-case 60s of doing nothing while the work sat on disk, already
+ * fetched. With the push channel (`lib/org/push.mjs`) collapsing the two cadence
+ * hops above it from ~47s to ~1s, this became the single dominant term in the
+ * time-to-first-token budget.
+ *
+ * It is also the one hop that no amount of server-side work can fix, because
+ * nothing crosses the process boundary: the writer and the reader are two
+ * processes on the same box sharing a directory. So the fix belongs here.
+ *
+ * ## Design: a wake with a floor, not a watch you have to trust
+ *
+ * `waitForInboxWake()` resolves as soon as a live inbox item exists, and returns
+ * on `timeoutMs` otherwise — so the caller's loop shape is unchanged, only its
+ * sleep gets interrupted. Three independent sources feed it:
+ *
+ *   1. **fs.watch** on each service dir — near-zero latency, cross-process
+ *      (it sees the cadence consumer's write from another PID).
+ *   2. **a 1s rescan** — the FLOOR. fs.watch is genuinely unreliable in the
+ *      cases that matter here (a dir that does not exist yet, a network/synth
+ *      FS, watcher-limit exhaustion, macOS coalescing), and a missed wake is a
+ *      silently late agent — the exact failure class this pipeline keeps
+ *      producing. Correctness therefore does NOT depend on the watcher: with
+ *      every watcher dead this degrades to a 1s poll, not to 60s.
+ *   3. **{@link signalInbox}** — an in-process nudge for a writer in THIS
+ *      process (the dispatcher promoting a deferred item on session close),
+ *      which needs no filesystem round-trip at all.
+ *
+ * ## Why "a live item exists", not "an event fired"
+ *
+ * Every rename in these dirs raises watch events, including
+ * `x.yaml → x.yaml.processed` (which fires for BOTH names). Waking on raw events
+ * would spin the daemon every time it finished an item. The predicate is
+ * therefore a state check — "is there a file with no terminal suffix?" — which
+ * is false immediately after a drain and true only when there is genuine work.
+ * That makes a wake idempotent and a missed event harmless.
+ *
+ * Fail-open and LOUD: a watcher that cannot be created is logged once per
+ * directory and the scan floor carries the load.
+ *
+ * Node builtins only. ESM. Timers/fs injectable for tests.
+ *
+ * @module scripts/daemon/inbox-wake
+ */
+
+"use strict";
+
+import { existsSync, readdirSync, watch } from "node:fs";
+import { join } from "node:path";
+
+import { resolveAgentRoot } from "../../lib/agent-root.mjs";
+
+/** Suffixes the daemon's scanner skips — a file with one of these is not work. */
+const TERMINAL_SUFFIXES = [".processed", ".deferred", ".processed-bundled", ".claimed"];
+
+/** How often the wake rescans regardless of watch events (the floor). */
+export const DEFAULT_SCAN_MS = 1_000;
+
+/**
+ * Coalescing window after a watch event before the predicate is evaluated. A
+ * write + rename burst (the cadence writer does both) must produce ONE wake.
+ */
+export const DEFAULT_DEBOUNCE_MS = 60;
+
+/** The inbox services the daemon drains via a directory scan. */
+export const DEFAULT_SERVICES = Object.freeze([
+  "cohort",
+  "orgmail",
+  "telegram",
+  "whatsapp",
+  "slack",
+  "gmail",
+  "alex-gmail",
+  "calendar",
+  "voice",
+  "internal",
+  "sms",
+]);
+
+/** In-process listeners (see {@link signalInbox}). */
+const listeners = new Set();
+
+/** Directories we already reported an un-watchable error for (log once). */
+const watchWarned = new Set();
+
+/**
+ * Nudge every waiter in THIS process that inbox work may now exist. Used by the
+ * dispatcher's session-close path after promoting a deferred item — the work is
+ * already on disk, and waiting for a watch event or the 1s floor is pure delay.
+ *
+ * Safe to call at any time: a wake with no work costs one predicate evaluation.
+ *
+ * @param {string} [reason] free-form, surfaced to the waiter for logging
+ */
+export function signalInbox(reason = "signal") {
+  for (const fn of [...listeners]) {
+    try {
+      fn(reason);
+    } catch {
+      /* a waiter must never break the signaller */
+    }
+  }
+}
+
+/** Is `name` a live (un-drained) inbox item file? */
+export function isLiveItemName(name) {
+  if (!name || name.startsWith(".")) return false;
+  for (const s of TERMINAL_SUFFIXES) if (name.endsWith(s)) return false;
+  return true;
+}
+
+/**
+ * The wake predicate: the first service whose inbox dir holds a live item, or
+ * null. Cheap — a readdir of a handful of small directories.
+ *
+ * @param {object} o - { agentRoot?, services?, readdir? }
+ * @returns {string|null} the service name with work, else null
+ */
+export function findLiveInboxService(o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const services = o.services || DEFAULT_SERVICES;
+  const readdirFn = o.readdir || readdirSync;
+  for (const service of services) {
+    const dir = join(root, "state", "inbox", service);
+    let names;
+    try {
+      names = readdirFn(dir);
+    } catch {
+      continue; // dir absent (service not configured) — not an error
+    }
+    for (const name of names) if (isLiveItemName(name)) return service;
+  }
+  return null;
+}
+
+/**
+ * Park until inbox work exists, or `timeoutMs` elapses.
+ *
+ * @param {object} o - {
+ *   agentRoot?, services?, timeoutMs?, scanMs?, debounceMs?,
+ *   log?, watchImpl?, readdir?
+ * }
+ * @returns {Promise<{woke:boolean, reason:string, service:string|null, waitedMs:number}>}
+ */
+export async function waitForInboxWake(o = {}) {
+  const root = resolveAgentRoot(o.agentRoot);
+  const services = o.services || DEFAULT_SERVICES;
+  const timeoutMs = Number.isFinite(o.timeoutMs) ? o.timeoutMs : 60_000;
+  const scanMs = Number.isFinite(o.scanMs) ? o.scanMs : DEFAULT_SCAN_MS;
+  const debounceMs = Number.isFinite(o.debounceMs) ? o.debounceMs : DEFAULT_DEBOUNCE_MS;
+  const watchFn = o.watchImpl || watch;
+  const log =
+    o.log ||
+    ((msg) => {
+      try {
+        console.warn(`[inbox-wake] ${msg}`);
+      } catch {
+        /* never throw from logging */
+      }
+    });
+  const startedAt = Date.now();
+
+  // Work already waiting: never sleep on a full inbox.
+  const immediate = findLiveInboxService({ agentRoot: root, services, readdir: o.readdir });
+  if (immediate) {
+    return { woke: true, reason: "pending", service: immediate, waitedMs: 0 };
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let debounceTimer = null;
+    const watchers = [];
+    let scanTimer = null;
+    let timeoutTimer = null;
+    let listener = null;
+
+    function cleanup() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      if (scanTimer) clearInterval(scanTimer);
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (listener) listeners.delete(listener);
+      for (const w of watchers) {
+        try {
+          w.close();
+        } catch {
+          /* already closed */
+        }
+      }
+    }
+
+    function settle(reason, service) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({
+        woke: reason !== "timeout",
+        reason,
+        service: service || null,
+        waitedMs: Date.now() - startedAt,
+      });
+    }
+
+    /** Evaluate the predicate; settle only when there is REAL work. */
+    function check(reason) {
+      if (settled) return;
+      const service = findLiveInboxService({ agentRoot: root, services, readdir: o.readdir });
+      if (service) settle(reason, service);
+    }
+
+    function onEvent(reason) {
+      if (settled || debounceTimer) return;
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        check(reason);
+      }, debounceMs);
+      if (debounceTimer && typeof debounceTimer.unref === "function") debounceTimer.unref();
+    }
+
+    // 1. fs.watch per existing service dir — the fast path.
+    for (const service of services) {
+      const dir = join(root, "state", "inbox", service);
+      if (!existsSync(dir)) continue;
+      try {
+        const w = watchFn(dir, { persistent: false }, () => onEvent("watch"));
+        if (w && typeof w.on === "function") {
+          // A watcher error must degrade to the scan floor, never reject.
+          w.on("error", (err) => {
+            if (!watchWarned.has(dir)) {
+              watchWarned.add(dir);
+              log(`watch failed for ${dir} (${err && err.message}) — falling back to the ${scanMs}ms rescan`);
+            }
+          });
+        }
+        watchers.push(w);
+      } catch (err) {
+        if (!watchWarned.has(dir)) {
+          watchWarned.add(dir);
+          log(`cannot watch ${dir} (${err && err.message}) — falling back to the ${scanMs}ms rescan`);
+        }
+      }
+    }
+
+    // 2. the scan floor — correctness does not depend on the watchers.
+    scanTimer = setInterval(() => check("scan"), scanMs);
+    if (scanTimer && typeof scanTimer.unref === "function") scanTimer.unref();
+
+    // 3. in-process signal.
+    listener = (reason) => onEvent(reason || "signal");
+    listeners.add(listener);
+
+    // Deliberately NOT unref'd: this promise is the caller's sleep, and while it
+    // is pending the process still owes a poll. With every timer unref'd Node
+    // would consider the loop idle and exit mid-wait (or, under the test runner,
+    // report an unsettled promise). The watchers stay `persistent:false` and the
+    // scan/debounce timers stay unref'd so THIS is the only thing holding it.
+    timeoutTimer = setTimeout(() => settle("timeout", null), timeoutMs);
+  });
+}
+
+/** Drop in-process listener state (tests). */
+export function resetInboxWake() {
+  listeners.clear();
+  watchWarned.clear();
+}
+
+export default {
+  waitForInboxWake,
+  signalInbox,
+  findLiveInboxService,
+  isLiveItemName,
+  resetInboxWake,
+  DEFAULT_SERVICES,
+  DEFAULT_SCAN_MS,
+};