@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/lib/session-router.test.mjs

@@ -0,0 +1,295 @@
+/**
+ * session-router.test.mjs — node:test coverage for the session router.
+ *
+ * No real subprocess spawns, no real disk writes outside os.tmpdir().
+ * Each test creates its own registry path under tmpdir and cleans up.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { routingKey, createRouter } from "./session-router.mjs";
+
+function tmpRegistryPath(suffix = "") {
+  const name = `session-router-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${suffix}.json`;
+  return join(tmpdir(), name);
+}
+
+async function safeUnlink(path) {
+  try {
+    await fsp.unlink(path);
+  } catch {
+    /* ignore */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 1. routingKey — one assertion per row of memo §4.2.
+// ---------------------------------------------------------------------------
+
+test("routingKey — slack threaded message", () => {
+  const k = routingKey({
+    source: "slack",
+    channel: "C0123ABC",
+    thread_ts: "1777283277.000100",
+  });
+  assert.equal(k, "slack:C0123ABC:1777283277.000100");
+});
+
+test("routingKey — slack DM (no thread)", () => {
+  const k = routingKey({
+    source: "slack",
+    channel: "D099N1JGKRQ",
+  });
+  assert.equal(k, "slack:D099N1JGKRQ");
+});
+
+test("routingKey — slack channel non-DM (no thread)", () => {
+  const k = routingKey({
+    source: "slack",
+    channel: "C0123ABC",
+    ts: "1777283277.000200",
+  });
+  assert.equal(k, "slack:C0123ABC:1777283277.000200");
+});
+
+test("routingKey — gmail", () => {
+  const k = routingKey({ source: "gmail", thread_id: "1818abc" });
+  assert.equal(k, "gmail:1818abc");
+});
+
+test("routingKey — calendar", () => {
+  const k = routingKey({ source: "calendar", event_id: "evt_42" });
+  assert.equal(k, "calendar:evt_42");
+});
+
+test("routingKey — internal queue item", () => {
+  const k = routingKey({ source: "internal", id: "ar-20260427-001" });
+  assert.equal(k, "internal:ar-20260427-001");
+});
+
+test("routingKey — backlog with topic_slug", () => {
+  const k = routingKey({
+    source: "backlog",
+    topic_slug: "session-router-step2",
+    id: "as-20260427-x",
+  });
+  assert.equal(k, "backlog:session-router-step2");
+});
+
+test("routingKey — backlog without topic_slug falls back to internal:<id>", () => {
+  const k = routingKey({ source: "backlog", id: "as-20260427-fallback" });
+  assert.equal(k, "internal:as-20260427-fallback");
+});
+
+// ---------------------------------------------------------------------------
+// 2. route() — missing key returns EPHEMERAL.
+// ---------------------------------------------------------------------------
+
+test("route — missing key returns EPHEMERAL", async (t) => {
+  const path = tmpRegistryPath("-missing");
+  t.after(() => safeUnlink(path));
+  const router = await createRouter({ registryPath: path });
+  const decision = router.route("slack:CNEVERSEEN:0");
+  assert.deepEqual(decision, { decision: "EPHEMERAL", resumeId: null });
+});
+
+// ---------------------------------------------------------------------------
+// 3. route() — past-TTL entry returns EPHEMERAL_REPLACE.
+// ---------------------------------------------------------------------------
+
+test("route — past-TTL entry returns EPHEMERAL_REPLACE", async (t) => {
+  const path = tmpRegistryPath("-ttl");
+  t.after(() => safeUnlink(path));
+  let clock = 1_000_000_000_000;
+  const router = await createRouter({
+    registryPath: path,
+    ttlSeconds: 60,
+    now: () => clock,
+  });
+  await router.touch("slack:DAAA:1", { claudeSessionId: "cli-1", model: "sonnet" });
+  // Advance clock past TTL.
+  clock += 61 * 1000;
+  const decision = router.route("slack:DAAA:1");
+  assert.equal(decision.decision, "EPHEMERAL_REPLACE");
+  assert.equal(decision.resumeId, null);
+});
+
+// ---------------------------------------------------------------------------
+// 4. route() — live, fresh, exit_code 0 returns RESUME with the stored id.
+// ---------------------------------------------------------------------------
+
+test("route — live fresh entry returns RESUME with stored claude_session_id", async (t) => {
+  const path = tmpRegistryPath("-resume");
+  t.after(() => safeUnlink(path));
+  let clock = 2_000_000_000_000;
+  const router = await createRouter({
+    registryPath: path,
+    ttlSeconds: 600,
+    now: () => clock,
+  });
+  await router.touch("slack:DRESUME:1", {
+    claudeSessionId: "cli-resume-xyz",
+    model: "sonnet",
+  });
+  clock += 30_000; // 30s — well within TTL.
+  const decision = router.route("slack:DRESUME:1");
+  assert.equal(decision.decision, "RESUME");
+  assert.equal(decision.resumeId, "cli-resume-xyz");
+});
+
+// ---------------------------------------------------------------------------
+// 5. route() — non-zero last_exit_code returns EPHEMERAL_REPLACE.
+// ---------------------------------------------------------------------------
+
+test("route — non-zero last_exit_code returns EPHEMERAL_REPLACE", async (t) => {
+  const path = tmpRegistryPath("-exitcode");
+  t.after(() => safeUnlink(path));
+  let clock = 3_000_000_000_000;
+  const router = await createRouter({
+    registryPath: path,
+    ttlSeconds: 600,
+    now: () => clock,
+  });
+  await router.touch("slack:DEXIT:1", {
+    claudeSessionId: "cli-exit",
+    model: "sonnet",
+  });
+  await router.recordExit("slack:DEXIT:1", 1);
+  clock += 5_000;
+  const decision = router.route("slack:DEXIT:1");
+  assert.equal(decision.decision, "EPHEMERAL_REPLACE");
+  assert.equal(decision.resumeId, null);
+});
+
+// ---------------------------------------------------------------------------
+// 6. touch() — LRU cap enforced; oldest entry evicted on overflow.
+// ---------------------------------------------------------------------------
+
+test("touch — LRU cap evicts oldest when at capacity", async (t) => {
+  const path = tmpRegistryPath("-lru");
+  t.after(() => safeUnlink(path));
+  let clock = 4_000_000_000_000;
+  const router = await createRouter({
+    registryPath: path,
+    ttlSeconds: 3600,
+    maxLiveSessions: 3,
+    now: () => clock,
+  });
+  for (let i = 1; i <= 3; i++) {
+    await router.touch(`slack:DLRU${i}`, {
+      claudeSessionId: `cli-${i}`,
+      model: "sonnet",
+    });
+    clock += 1000;
+  }
+  // At cap. Add a fourth.
+  await router.touch("slack:DLRU4", {
+    claudeSessionId: "cli-4",
+    model: "sonnet",
+  });
+  const snap = router._readForTests();
+  assert.equal(snap.lru.length, 3, "lru should still hold 3 keys");
+  assert.ok(!("slack:DLRU1" in snap.sessions), "oldest (DLRU1) evicted");
+  assert.ok("slack:DLRU2" in snap.sessions);
+  assert.ok("slack:DLRU3" in snap.sessions);
+  assert.ok("slack:DLRU4" in snap.sessions);
+});
+
+// ---------------------------------------------------------------------------
+// 7. recordExit() — non-zero code flips status to "killed".
+// ---------------------------------------------------------------------------
+
+test("recordExit — non-zero code flips status to killed", async (t) => {
+  const path = tmpRegistryPath("-killed");
+  t.after(() => safeUnlink(path));
+  const router = await createRouter({ registryPath: path });
+  await router.touch("slack:DKILL:1", {
+    claudeSessionId: "cli-kill",
+    model: "sonnet",
+  });
+  await router.recordExit("slack:DKILL:1", 137);
+  const snap = router._readForTests();
+  assert.equal(snap.sessions["slack:DKILL:1"].status, "killed");
+  assert.equal(snap.sessions["slack:DKILL:1"].last_exit_code, 137);
+});
+
+// ---------------------------------------------------------------------------
+// 8. evictExpired() — removes only stale entries, returns count.
+// ---------------------------------------------------------------------------
+
+test("evictExpired — removes only stale entries and returns count", async (t) => {
+  const path = tmpRegistryPath("-evict");
+  t.after(() => safeUnlink(path));
+  let clock = 5_000_000_000_000;
+  const router = await createRouter({
+    registryPath: path,
+    ttlSeconds: 60,
+    now: () => clock,
+  });
+  await router.touch("slack:DEVICT:OLD", {
+    claudeSessionId: "cli-old",
+    model: "sonnet",
+  });
+  // Advance past TTL.
+  clock += 120_000;
+  await router.touch("slack:DEVICT:NEW", {
+    claudeSessionId: "cli-new",
+    model: "sonnet",
+  });
+  // Now: OLD is stale (last_used_at = clock - 120s, ttl = 60s),
+  //      NEW is fresh.
+  const evicted = await router.evictExpired();
+  assert.equal(evicted, 1, "one entry should have been evicted");
+  const snap = router._readForTests();
+  assert.ok(!("slack:DEVICT:OLD" in snap.sessions));
+  assert.ok("slack:DEVICT:NEW" in snap.sessions);
+});
+
+// ---------------------------------------------------------------------------
+// 9. Registry round-trip — touch two keys, re-create router, state restored.
+// ---------------------------------------------------------------------------
+
+test("registry round-trip — second router instance reads persisted state", async (t) => {
+  const path = tmpRegistryPath("-roundtrip");
+  t.after(() => safeUnlink(path));
+  let clock = 6_000_000_000_000;
+
+  const r1 = await createRouter({
+    registryPath: path,
+    ttlSeconds: 3600,
+    now: () => clock,
+  });
+  await r1.touch("gmail:thread-A", {
+    claudeSessionId: "cli-A",
+    model: "sonnet",
+  });
+  clock += 1000;
+  await r1.touch("gmail:thread-B", {
+    claudeSessionId: "cli-B",
+    model: "opus",
+  });
+
+  // Fresh router instance against the same path.
+  const r2 = await createRouter({
+    registryPath: path,
+    ttlSeconds: 3600,
+    now: () => clock,
+  });
+  const snap = r2._readForTests();
+  assert.equal(Object.keys(snap.sessions).length, 2);
+  assert.equal(snap.sessions["gmail:thread-A"].claude_session_id, "cli-A");
+  assert.equal(snap.sessions["gmail:thread-B"].claude_session_id, "cli-B");
+  assert.equal(snap.sessions["gmail:thread-B"].model, "opus");
+  // Both keys present in the LRU array.
+  assert.ok(snap.lru.includes("gmail:thread-A"));
+  assert.ok(snap.lru.includes("gmail:thread-B"));
+
+  // route() should return RESUME for the persisted entry.
+  const dec = r2.route("gmail:thread-A");
+  assert.equal(dec.decision, "RESUME");
+  assert.equal(dec.resumeId, "cli-A");
+});

package/scripts/daemon/maestro-daemon.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+// =============================================================================
+// Maestro Daemon — Reactive event-driven message processor
+// =============================================================================
+//
+// Generic entry point that loads agent identity from config/agent.json and
+// delegates to the core daemon logic. This file is agent-name-agnostic.
+//
+// Lifecycle:
+//   1. Honour .emergency-stop BEFORE doing anything (don't acquire singleton
+//      lock, don't start consumer, don't import the core daemon). Stops the
+//      launchd restart treadmill cold.
+//   2. Acquire the daemon singleton lock so only one instance runs.
+//   3. Start the cadence consumer (state/cadence-bus/ drain loop).
+//   4. Import the core daemon (agent-daemon.mjs canonical, with fallbacks
+//      to a legacy <firstName>-daemon.mjs for back-compat).
+//
+// Run: node scripts/daemon/maestro-daemon.mjs
+// Install: launchd plist with KeepAlive.SuccessfulExit: false (clean exits
+// during emergency-stop should NOT trigger restart; non-zero exits should).
+// =============================================================================
+
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { installUnhandledHandlers } from "../../lib/util/unhandled.mjs";
+import { readPeers, readIdentity } from "../../lib/org/registry.mjs";
+import { bump as bumpCounter } from "../../lib/diagnostics/counters.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_DIR || resolve(__dirname, "../..");
+
+process.env.AGENT_DIR = AGENT_DIR;
+process.env.AGENT_ROOT = AGENT_DIR;
+
+// Never die silently (P0-6): a stray unhandled rejection / uncaught exception is
+// logged + counted, not a silent process death. Rejections keep the daemon
+// running; an uncaught exception logs+flushes then lets launchd restart us.
+installUnhandledHandlers({
+  bump: (name, attrs) => { try { bumpCounter(name, { ...attrs, agentRoot: AGENT_DIR }); } catch { /* never throw from the handler */ } },
+  onEvent: (e) => console.error(`[DAEMON] ${e.kind}: ${e.error && e.error.message}`),
+});
+
+// ---------------------------------------------------------------------------
+// 1. Emergency-stop gate
+// ---------------------------------------------------------------------------
+// If the operator dropped .emergency-stop, we exit cleanly (code 0). With
+// KeepAlive.SuccessfulExit:false this means launchd will NOT restart us
+// until the flag is lifted + the plist is reloaded by resume-operations.sh.
+// Older plists with plain KeepAlive:true will still restart, so we hold
+// the process for 30s before exiting to give launchd's ThrottleInterval
+// something to throttle.
+if (existsSync(join(AGENT_DIR, ".emergency-stop"))) {
+  console.error("[DAEMON] .emergency-stop flag present — refusing to start.");
+  console.error("[DAEMON] Lift with: scripts/resume-operations.sh");
+  await new Promise((r) => setTimeout(r, 30_000));
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// 2. Singleton guard
+// ---------------------------------------------------------------------------
+try {
+  const { acquireLock } = await import("../../lib/singleton.js");
+  if (!acquireLock("daemon")) {
+    console.log("[DAEMON] Already running — exiting");
+    process.exit(0);
+  }
+} catch { /* singleton lib missing — proceed without lock */ }
+
+// ---------------------------------------------------------------------------
+// 3. Cadence consumer (cadence bus drain loop)
+// ---------------------------------------------------------------------------
+// Start alongside the reactive event loop. This is the single persistent
+// owner of cadence housekeeping — launchd plists enqueue cadence ticks
+// onto state/cadence-bus/ and the consumer drains them here, either
+// handling them inline or escalating to a sub-session when warranted.
+// Failure to start the consumer must NOT take the reactive daemon down.
+try {
+  const { startConsumer } = await import("./cadence-consumer.mjs");
+  const consumer = startConsumer({ agentRoot: AGENT_DIR });
+  const shutdown = async (sig) => {
+    try { await consumer.stop(); } catch { /* ignore */ }
+    console.log(`[DAEMON] cadence consumer stopped (${sig})`);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+} catch (err) {
+  console.error(`[DAEMON] cadence consumer failed to start: ${err.message}`);
+  // Reactive daemon continues. Doctor / healthcheck will surface this.
+}
+
+// ---------------------------------------------------------------------------
+// 3b. Channel bus (1.12.0+; generic platform loop in 1.15.0/WS2)
+// ---------------------------------------------------------------------------
+// WS2: instead of a hardcoded voice+whatsapp block, we iterate the
+// self-registered PLATFORMS (lib/channels/contract.mjs definePlatform) and
+// start every platform whose gate file exists under the agent dir. Each
+// channel's onInbound writes a byte-compatible inbox item via
+// `writeInboxItem(service, eventToInboxItem(ev))` so new channels flow
+// through the unchanged poll()/classify/dispatch path. Failures here MUST
+// NOT take the reactive daemon down.
+try {
+  const channelsModule = resolve(__dirname, "../../lib/channels/index.mjs");
+  if (existsSync(channelsModule)) {
+    const { listPlatforms, eventToInboxItem } = await import(`file://${channelsModule}`);
+    const { writeInboxItem } = await import(`file://${resolve(__dirname, "../poller/utils.mjs")}`);
+    // Single-owner rule (H2): the shared SoT for which platforms the daemon must
+    // NOT start (they have a dedicated launchd owner — e.g. slack-socket).
+    const { isDaemonManagedPlatform } = await import(`file://${resolve(__dirname, "../../lib/channels/contract.mjs")}`);
+
+    // Importing the adapters runs their definePlatform() side-effects. Each is
+    // optional (dynamic deps); a failed import just means that platform isn't
+    // available and is skipped.
+    for (const mod of ["./slack/adapter.mjs", "./telegram/adapter.mjs", "./whatsapp/adapter-baileys.mjs", "./orgmail/adapter.mjs"]) {
+      try { await import(`file://${resolve(__dirname, "../../lib/channels", mod)}`); }
+      catch (err) { console.warn(`[DAEMON] channel-bus: ${mod} not loadable — ${err.message}`); }
+    }
+
+    const makeOnInbound = (service) => (ev) => {
+      try {
+        writeInboxItem(service, eventToInboxItem(ev));
+      } catch (err) {
+        console.warn(`[DAEMON] channel-bus inbox write failed (${service}): ${err.message}`);
+      }
+    };
+
+    // Register started adapters with the typing registry so the dispatcher can
+    // drive a "typing…" heartbeat on the originating channel during a session.
+    let registerTypingAdapter = null;
+    try {
+      ({ registerTypingAdapter } = await import(`file://${resolve(__dirname, "./typing-registry.mjs")}`));
+    } catch { /* typing is optional */ }
+
+    // SINGLE-OWNER RULE (H2): some platforms have a DEDICATED launchd process
+    // that owns their real-time connection — the daemon must NOT also start
+    // them here, or the channel is ingested twice (every DM answered twice).
+    // Slack's owner is `ai.maestro.<agent>-slack-socket` (generate-plists.sh),
+    // which runs scripts/poller/slack-socket-mode.mjs and reads config/slack.yaml
+    // itself for reactions/cc. This generic loop is only for daemon-owned
+    // channels (telegram / whatsapp / voice) that have NO dedicated plist.
+    // The exclusion SoT is lib/channels/contract.mjs (isDaemonManagedPlatform).
+    for (const platform of listPlatforms()) {
+      if (!isDaemonManagedPlatform(platform.name)) {
+        console.log(`[DAEMON] channel-bus: ${platform.name} skipped — owned by its dedicated launchd process (single-owner rule)`);
+        continue;
+      }
+      const gatePath = join(AGENT_DIR, platform.gateFile);
+      if (!existsSync(gatePath)) continue;
+      try {
+        // Peer registry → bot-loop guard (P0-5): pass this agent's own id + the
+        // set of peer-agent ids so BaseAdapter._isOwnOrPeer won't auto-reply to a
+        // sibling agent in a shared channel (reply-storm prevention). Best-effort:
+        // ids are matched per-platform where known; a no-match is simply not guarded.
+        const peers = readPeers(AGENT_DIR) || [];
+        const self = readIdentity(AGENT_DIR) || {};
+        const peerAgentIds = new Set(
+          peers.flatMap((p) => [p.slackId, p.telegramId, p.id, p.whatsapp, p.handle].filter(Boolean)),
+        );
+        const ownId = self.slackId || self.id || self.repoSlug || "";
+        const channel = platform.factory({ agentRoot: AGENT_DIR, ownId, peerAgentIds });
+        if (registerTypingAdapter) { try { registerTypingAdapter(platform.name, channel); } catch { /* */ } }
+        // start() returns once the underlying transport is constructed (socket
+        // built / long-poll launched) — not when fully authenticated — so we
+        // don't block the daemon boot on it.
+        Promise.resolve(channel.start({ onInbound: makeOnInbound(platform.name) }))
+          .catch((err) => console.warn(`[DAEMON] channel-bus: ${platform.name}.start() failed — ${err.message}`));
+        console.log(`[DAEMON] channel-bus: ${platform.name} channel started (gate: ${platform.gateFile})`);
+      } catch (err) {
+        console.warn(`[DAEMON] channel-bus: ${platform.name} channel skipped — ${err.message}`);
+      }
+    }
+  }
+} catch (err) {
+  console.warn(`[DAEMON] channel-bus initialization failed: ${err.message}`);
+}
+
+// ---------------------------------------------------------------------------
+// 3b'. Org mesh runtime membership (org-connect)
+// ---------------------------------------------------------------------------
+// Make this agent actually JOIN the Cohort org mesh at runtime: register at
+// boot, presence-beat (~30s), and act on the server's directives — the kill
+// switch ("halt" → .emergency-stop + stop), policy-stale refetch, directory
+// resync, token rotation. A no-op when the org integration is disabled, and
+// fully fail-open (org down ⇒ the daemon runs standalone). Failure here MUST NOT
+// take the reactive daemon down.
+try {
+  // Org enrollment lives in config/org.yaml (written by `maestro setup` /
+  // lib/setup/sections/org.mjs, read by lib/org/client.mjs) — NOT
+  // config/collective.yaml. Use the canonical org-config loader so an
+  // enrolled agent's mesh actually connects.
+  const { connectOrgMesh } = await import("../../lib/org/mesh.mjs");
+  const { loadOrgConfig } = await import("../../lib/org/client.mjs");
+  const cfg = loadOrgConfig(AGENT_DIR);
+  const orgMesh = await connectOrgMesh({ agentRoot: AGENT_DIR, cfg });
+  if (orgMesh && orgMesh.isEnabled) console.log("[DAEMON] org-mesh connected");
+  const stopMesh = (sig) => {
+    try { orgMesh.stop(); } catch { /* ignore */ }
+    if (orgMesh && orgMesh.isEnabled) console.log(`[DAEMON] org-mesh stopped (${sig})`);
+  };
+  process.on("SIGTERM", () => stopMesh("SIGTERM"));
+  process.on("SIGINT", () => stopMesh("SIGINT"));
+} catch (err) {
+  console.warn(`[DAEMON] org-mesh init failed (running standalone): ${err.message}`);
+}
+
+// ---------------------------------------------------------------------------
+// 3c. Model router config validation (1.12.0+, advisory)
+// ---------------------------------------------------------------------------
+// If config/model-routing.yaml is active, validate it loads cleanly at
+// daemon startup so a typo doesn't silently break every spawn. We don't
+// reject startup on failure — dispatcher's resolver also catches this
+// and falls back to the Anthropic CLI default.
+try {
+  if (existsSync(join(AGENT_DIR, "config/model-routing.yaml"))) {
+    const routerModule = resolve(__dirname, "../../lib/model-router.mjs");
+    if (existsSync(routerModule)) {
+      const { loadRoutingConfig, listBackends } = await import(`file://${routerModule}`);
+      const cfg = loadRoutingConfig(AGENT_DIR);
+      if (cfg) {
+        const backends = listBackends({ config: cfg });
+        console.log(`[DAEMON] model-router active (${backends.length} backend(s): ${backends.join(", ")})`);
+      } else {
+        console.warn("[DAEMON] model-router config present but loader returned null");
+      }
+    }
+  }
+} catch (err) {
+  console.warn(`[DAEMON] model-router validation failed (spawn will fall back to default): ${err.message}`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Core daemon import
+// ---------------------------------------------------------------------------
+// Resolve the core daemon module. Try, in order:
+//   1. ./agent-daemon.mjs   — canonical filename (1.9.4+)
+//   2. ./<firstName>-daemon.mjs — legacy per-agent rename (pre-1.9.4)
+//   3. The first scripts/daemon/*-daemon.mjs that isn't this file (catches any
+//      other legacy-named core daemon still on disk in an old agent repo)
+function resolveCoreDaemon() {
+  const localCandidates = [
+    resolve(__dirname, "agent-daemon.mjs"),
+  ];
+
+  try {
+    const agentJson = join(AGENT_DIR, "config", "agent.json");
+    if (existsSync(agentJson)) {
+      const { firstName } = JSON.parse(readFileSync(agentJson, "utf-8"));
+      if (firstName && typeof firstName === "string") {
+        const lower = firstName.toLowerCase();
+        localCandidates.push(resolve(__dirname, `${lower}-daemon.mjs`));
+      }
+    }
+  } catch { /* identity unavailable — fall through */ }
+
+  for (const p of localCandidates) if (existsSync(p)) return p;
+
+  // Final fallback: scan the directory for *-daemon.mjs (excluding self).
+  try {
+    for (const name of readdirSync(__dirname)) {
+      if (name === "maestro-daemon.mjs") continue;
+      if (name.endsWith("-daemon.mjs")) return resolve(__dirname, name);
+    }
+  } catch { /* */ }
+
+  return null;
+}
+
+const coreDaemon = resolveCoreDaemon();
+if (!coreDaemon) {
+  console.error("[DAEMON] could not locate a core daemon module under scripts/daemon/. Expected agent-daemon.mjs (canonical) or a legacy <firstName>-daemon.mjs.");
+  process.exit(78);
+}
+// Import and run the daemon (handles its own .env loading).
+await import(coreDaemon);