sentinelayer-cli 0.22.0 → 0.24.0

package/src/session/daemon-spawn.js

@@ -0,0 +1,192 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { resolveSessionPaths } from "./paths.js";
+
+const PID_FILE_NAME = "senti-daemon.json";
+const LOG_FILE_NAME = "senti-daemon.log";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function sentiDaemonDisabled(env = process.env) {
+  return (
+    normalizeString(env.SENTINELAYER_SKIP_SENTI_AUTOSTART) === "1" ||
+    normalizeString(env.SENTINELAYER_SKIP_SENTI_DAEMON) === "1"
+  );
+}
+
+export function resolveDaemonPidPath(sessionId, { targetPath = process.cwd() } = {}) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  return path.join(paths.sessionDir, PID_FILE_NAME);
+}
+
+export function resolveDaemonLogPath(sessionId, { targetPath = process.cwd() } = {}) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  return path.join(paths.sessionDir, LOG_FILE_NAME);
+}
+
+export function isProcessAlive(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error?.code === "EPERM";
+  }
+}
+
+export async function readDaemonPidRecord(sessionId, { targetPath = process.cwd() } = {}) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(pidPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeDaemonPidRecord(
+  sessionId,
+  { targetPath = process.cwd(), pid = process.pid, tickIntervalMs = 30000 } = {}
+) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  const record = {
+    pid: Number(pid),
+    sessionId: normalizeString(sessionId),
+    targetPath: path.resolve(String(targetPath || ".")),
+    tickIntervalMs: Number(tickIntervalMs) || 30000,
+    startedAt: new Date().toISOString(),
+  };
+  await fsp.mkdir(path.dirname(pidPath), { recursive: true });
+  await fsp.writeFile(pidPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+  return record;
+}
+
+export async function removeDaemonPidRecord(
+  sessionId,
+  { targetPath = process.cwd(), onlyForPid = null } = {}
+) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  if (onlyForPid != null) {
+    const existing = await readDaemonPidRecord(sessionId, { targetPath });
+    if (existing && Number(existing.pid) !== Number(onlyForPid)) {
+      return false;
+    }
+  }
+  try {
+    await fsp.unlink(pidPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a detached Senti daemon is currently managing the session.
+ * Stale pid files (machine reboot, hard kill on Windows) are reported as
+ * not running so the caller can safely respawn over them.
+ */
+export async function getDaemonStatus(sessionId, { targetPath = process.cwd() } = {}) {
+  const record = await readDaemonPidRecord(sessionId, { targetPath });
+  if (!record) {
+    return { running: false, pid: null, stale: false, record: null };
+  }
+  const alive = isProcessAlive(record.pid);
+  return {
+    running: alive,
+    pid: alive ? Number(record.pid) : null,
+    stale: !alive,
+    record,
+  };
+}
+
+export function resolveCliEntryPath() {
+  const entry = normalizeString(process.argv[1]);
+  return entry ? path.resolve(entry) : "";
+}
+
+/**
+ * Spawn `sl session daemon <id>` as a detached background process so the
+ * session stays managed (greetings, recaps, checkpoints, mention routing)
+ * after the creating terminal exits. Deduped via the session's pid file;
+ * output goes to senti-daemon.log in the session directory.
+ *
+ * Never throws: returns { spawned, pid, reason, logPath } so callers can
+ * report status without ever failing session creation.
+ */
+export async function spawnDetachedSentiDaemon({
+  sessionId,
+  targetPath = process.cwd(),
+  cliPath = "",
+  env = process.env,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { spawned: false, pid: null, reason: "missing_session_id", logPath: "" };
+  }
+  if (sentiDaemonDisabled(env)) {
+    return { spawned: false, pid: null, reason: "disabled", logPath: "" };
+  }
+
+  const status = await getDaemonStatus(normalizedSessionId, { targetPath });
+  if (status.running) {
+    return {
+      spawned: false,
+      pid: status.pid,
+      reason: "already_running",
+      logPath: resolveDaemonLogPath(normalizedSessionId, { targetPath }),
+    };
+  }
+
+  const entryPath = normalizeString(cliPath) || resolveCliEntryPath();
+  if (!entryPath) {
+    return { spawned: false, pid: null, reason: "cli_entry_unresolved", logPath: "" };
+  }
+
+  const logPath = resolveDaemonLogPath(normalizedSessionId, { targetPath });
+  let logFd = null;
+  try {
+    await fsp.mkdir(path.dirname(logPath), { recursive: true });
+    logFd = fs.openSync(logPath, "a");
+    const child = spawn(
+      process.execPath,
+      [entryPath, "session", "daemon", normalizedSessionId, "--path", path.resolve(String(targetPath || "."))],
+      {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        windowsHide: true,
+        env,
+      }
+    );
+    child.unref();
+    return { spawned: true, pid: child.pid ?? null, reason: "spawned", logPath };
+  } catch (error) {
+    return {
+      spawned: false,
+      pid: null,
+      reason: `spawn_failed: ${normalizeString(error?.message) || "unknown"}`,
+      logPath,
+    };
+  } finally {
+    if (logFd != null) {
+      try {
+        fs.closeSync(logFd);
+      } catch {
+        // fd already closed
+      }
+    }
+  }
+}

package/src/session/first-message.js

@@ -0,0 +1,99 @@
+import { createAgentEvent } from "../events/schema.js";
+import { appendToStream } from "./stream.js";
+
+export const FIRST_MESSAGE_AGENT = Object.freeze({
+  id: "senti",
+  model: "senti",
+  persona: "Senti",
+  shortName: "Senti",
+  color: "magenta",
+  avatar: "S",
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+/**
+ * The deterministic "first Senti message" pinned to every new session —
+ * the approved Carter draft combining the GPT/Codex lanes and the Claude
+ * lane. Model-aware (each agent uses the path that fits its runtime),
+ * command-accurate, low-power. `<AGENT_ID>` stays a placeholder each agent
+ * substitutes; the session id is filled in.
+ */
+export function buildFirstSentiMessage({ sessionId } = {}) {
+  const sid = normalizeString(sessionId) || "<SID>";
+  return [
+    `👋 Welcome to this Senti coding room (session ${sid}). The transcript IS the deliverable evidence. Don't go dark, don't make top-level noise. Loop: read → ACK → claim → prove → stay reachable, until ORCH/human accepts handoff. The whole loop is LOW-POWER by design — it should barely touch your API budget.`,
+    "",
+    "IDENTITY — your name = lane + model (api-01-gpt-5.5, ui-01-gpt-5.5, verify-01-opus-4.8).",
+    "",
+    "MANDATORY FIRST COMMANDS, in order:",
+    `1) sl --help && sl session --help   (trust local help over memory)`,
+    `2) sl session join ${sid} --agent <AGENT_ID> --model <MODEL> --role <role>`,
+    `3) sl ai identity provision --execute ; sl ai identity list`,
+    `4) sl session pins ${sid} --json`,
+    `5) sl session read ${sid} --remote --agent <AGENT_ID> --tail 60   (records your view receipt)`,
+    `6) sl session react ${sid} ack --target-sequence <THIS_SEQ> --agent <AGENT_ID>`,
+    `7) sl session reply ${sid} <THIS_SEQ> "ACK <AGENT_ID> role=<role> model=<model> locks=none first_action=<one concrete action>" --agent <AGENT_ID>`,
+    "",
+    "STAY REACHABLE — two honest paths, use YOURS (always pass --agent <AGENT_ID> so the room knows who's listening):",
+    `- Persistent process (Codex/GPT): keep ONE listener alive + a 60s watchdog that restarts it if the pid dies (cursor catch-up replays anything missed):`,
+    `  sl session listen --session ${sid} --agent <AGENT_ID> --active-interval 30 --active-window 300 --interval 60 --presence-interval 60 --model <MODEL> --display-name <AGENT_ID>`,
+    `- No socket (Claude Code): you are NOT continuously connected — you re-arm a wake each turn. 30-270s while actively waiting, 20-30min idle when quiet. Treat time-critical things as POSTED messages you catch next tick, never assumed instant.`,
+    `CADENCE both converge to: ~30s active; after 5min quiet → 60s; after another 5 → 90s; +30s every 5min to a floor. Wake IMMEDIATELY on: new human/ORCH msg, a direct reply/@mention, a lock conflict, a deploy/gate notice.`,
+    "",
+    "REACTIONS — lowest-noise action that tells the truth (one line each):",
+    `- ack — "seen + accountable." Silent ack is enough for FYI, another lane's lock, an assignment you'll act on. No comment needed.`,
+    `- working_on — ONLY when actually taking scope: sl session action ${sid} working_on --target-sequence <SEQ> --agent <AGENT_ID> --note "<action>; ETA <t>"`,
+    `- reply — a real answer/decision/blocker/evidence/done. Reply UNDER the message you're answering.`,
+    `- like — agreement, no text useful.   dislike — materially wrong/unsafe; ALWAYS pair with a correction reply.   disregard — supersede your OWN mistaken action.   view — receipt only, not an ACK.`,
+    "",
+    "THREADING (this is the social-media-for-AI part — keep it clean):",
+    `- Reply UNDER the message you're answering. Do NOT start a new top-level post for a reply.`,
+    `- Adding to your OWN comment? Don't post a sibling — NEST it (unlimited depth, like IG):`,
+    `  sl session action ${sid} reply --target-action-id <YOUR_ACTION_UUID> --agent <AGENT_ID> --note "UPDATE: <one compact line>"`,
+    `  (find UUIDs: sl session read ${sid} --remote --agent <AGENT_ID> --tail 20 --json)`,
+    `- DO start a new top-level post when the topic is genuinely UNRELATED, or for: a phase decision, a room-wide blocker, deploy/gate evidence, a handoff, or a recap. Unrelated → new post is correct. Related → nest.`,
+    "",
+    `LOCKS before edits: sl session locks ${sid} --json → sl session lock ${sid} <files...> --agent <AGENT_ID> --intent "<why>" → unlock when done. Never touch another lane's lock.`,
+    "",
+    `PROVE, DON'T RECALL: "done" carries evidence: command=<exact> outcome=<key output> artifact=<PR/link>. If a check can't run, say why + the substitute. Never paste secrets; post privileged actions as evidence: cmd+outcome.`,
+    "",
+    `TICKET TRAIL (if the project has a board/Jira) — one ticket = one PR, lean like senti: on PR open → move the ticket to In-review + comment the PR link; on merge+green → Done; on gate-fail → Blocked + the finding. One update per transition, not every step. The PR body carries the ticket id.`,
+    "",
+    "LESSONS + GOALS (keep these explicit so a fresh turn is productive immediately):",
+    `- LESSONS: after ANY human correction, append trigger / mistake / prevention-rule to the project lessons file (tasks/lessons.md or LESSONS.md).`,
+    `- GOAL note: objective, stop_conditions, credentials_allowed, validation, last_seen_sequence, resume_command. Default idle goal: monitor, ACK actionable events, keep your cursor current — quietly.`,
+    "",
+    "EXIT only after ORCH/human accepts handoff in-thread.",
+  ].join("\n");
+}
+
+/**
+ * Post the first-Senti-message as the opening event of a freshly created
+ * session. Best-effort + non-blocking — a failure never fails session
+ * creation. Returns { posted, reason }.
+ */
+export async function postFirstSentiMessage({ sessionId, targetPath = process.cwd() } = {}) {
+  const sid = normalizeString(sessionId);
+  if (!sid) {
+    return { posted: false, reason: "missing_session_id" };
+  }
+  const event = createAgentEvent({
+    event: "session_message",
+    agent: FIRST_MESSAGE_AGENT,
+    sessionId: sid,
+    payload: {
+      message: buildFirstSentiMessage({ sessionId: sid }),
+      channel: "session",
+      firstMessage: true,
+    },
+  });
+  try {
+    await appendToStream(sid, event, { targetPath, awaitRemoteSync: true });
+    return { posted: true, reason: "posted" };
+  } catch (error) {
+    return { posted: false, reason: normalizeString(error?.message) || "append_failed" };
+  }
+}

package/src/session/listeners.js

@@ -0,0 +1,126 @@
+import { pollSessionEventsBefore } from "./sync.js";
+
+const LISTENER_EVENT_TYPES = new Set([
+  "session_listener_started",
+  "session_listener_heartbeat",
+  "session_listener_stopped",
+]);
+
+// A heartbeat older than this (and not explicitly stopped) means the
+// listener likely died without a clean stop — show it as stale, not live.
+const DEFAULT_STALE_AFTER_MS = 180_000;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function eventEpochMs(event) {
+  const raw = normalizeString(event?.ts) || normalizeString(event?.timestamp);
+  const parsed = Date.parse(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function positiveInt(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/**
+ * Reduce a stream of session_listener_* events into one row per agent: who is
+ * listening, at what cadence, and whether they're currently active or idle.
+ * Pure + testable — the command layer just fetches events and renders this.
+ */
+export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfterMs = DEFAULT_STALE_AFTER_MS } = {}) {
+  const latestByAgent = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    const type = normalizeString(event?.event);
+    if (!LISTENER_EVENT_TYPES.has(type)) continue;
+    const agentId = normalizeString(event?.agent?.id) || normalizeString(readRecord(event?.payload).listenerId);
+    if (!agentId) continue;
+    const epoch = eventEpochMs(event) ?? 0;
+    const existing = latestByAgent.get(agentId);
+    if (!existing || epoch >= existing.epoch) {
+      latestByAgent.set(agentId, { event, type, epoch });
+    }
+  }
+
+  const rows = [];
+  for (const [agentId, { event, type, epoch }] of latestByAgent) {
+    const payload = readRecord(event.payload);
+    const ageMs = epoch ? Math.max(0, nowMs - epoch) : null;
+    const stopped = type === "session_listener_stopped";
+    const active = Boolean(payload.active);
+    const idleIntervalSeconds = positiveInt(payload.idleIntervalSeconds);
+    const activeIntervalSeconds = positiveInt(payload.activeIntervalSeconds);
+    const nextPollSeconds = positiveInt(payload.nextPollMs)
+      ? Math.round(positiveInt(payload.nextPollMs) / 1000)
+      : null;
+    // The effective cadence right now: active window uses the fast interval,
+    // otherwise the idle interval; fall back to the reported next poll.
+    const cadenceSeconds = active
+      ? activeIntervalSeconds || nextPollSeconds
+      : idleIntervalSeconds || nextPollSeconds;
+    let status;
+    if (stopped) status = "stopped";
+    else if (ageMs !== null && ageMs > staleAfterMs) status = "stale";
+    else status = active ? "active" : "idle";
+
+    rows.push({
+      agentId,
+      displayName: normalizeString(event.agent?.displayName) || agentId,
+      model: normalizeString(event.agent?.model),
+      status,
+      active,
+      cadenceSeconds: cadenceSeconds ?? null,
+      idleIntervalSeconds,
+      activeIntervalSeconds,
+      nextPollSeconds,
+      lastSeenAt: epoch ? new Date(epoch).toISOString() : null,
+      lastSeenAgoSeconds: ageMs !== null ? Math.round(ageMs / 1000) : null,
+      lastHumanActivityAt: normalizeString(payload.lastHumanActivityAt) || null,
+    });
+  }
+
+  // Live listeners first, then by most-recently-seen.
+  const statusRank = { active: 0, idle: 1, stale: 2, stopped: 3 };
+  rows.sort((a, b) => {
+    const r = (statusRank[a.status] ?? 9) - (statusRank[b.status] ?? 9);
+    if (r !== 0) return r;
+    return (b.lastSeenAt || "").localeCompare(a.lastSeenAt || "");
+  });
+  return rows;
+}
+
+/**
+ * Fetch recent session events from the API and summarize the listeners.
+ * `limit` controls how far back we look for heartbeats.
+ */
+export async function fetchSessionListeners(
+  sessionId,
+  { targetPath = process.cwd(), limit = 200, nowMs = Date.now, poll = pollSessionEventsBefore } = {}
+) {
+  const result = await poll(sessionId, { targetPath, limit });
+  if (!result?.ok) {
+    return { ok: false, reason: normalizeString(result?.reason) || "fetch_failed", listeners: [] };
+  }
+  const listeners = summarizeListeners(result.events || [], { nowMs: nowMs() });
+  return { ok: true, sessionId: normalizeString(sessionId), listeners };
+}
+
+export function formatListenerLine(row) {
+  const cadence = row.cadenceSeconds ? `${row.cadenceSeconds}s` : "—";
+  const seen = row.lastSeenAgoSeconds === null ? "never" : `${row.lastSeenAgoSeconds}s ago`;
+  const statusLabel =
+    row.status === "active"
+      ? "● active"
+      : row.status === "idle"
+        ? "○ idle"
+        : row.status === "stale"
+          ? "◌ stale"
+          : "× stopped";
+  return `${statusLabel.padEnd(10)} ${row.agentId.padEnd(24)} cadence=${cadence.padEnd(6)} last_seen=${seen}`;
+}

package/src/session/project-bootstrap.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+
+import { ensureWorkspaceSession } from "../commands/session.js";
+import { createAgentEvent } from "../events/schema.js";
+import { spawnDetachedSentiDaemon } from "./daemon-spawn.js";
+import { setupSessionGuides } from "./setup-guides.js";
+import { appendToStream } from "./stream.js";
+import { syncSessionMetadataToApi } from "./sync.js";
+import { buildDashboardUrl } from "./templates.js";
+
+export const PROJECT_BOOTSTRAP_AGENT = Object.freeze({
+  id: "project-bootstrap",
+  persona: "Project Bootstrap",
+  shortName: "Bootstrap",
+  color: "green",
+  avatar: "P",
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function buildProjectSessionWelcomeMessage({ projectName, sessionId } = {}) {
+  const name = normalizeString(projectName) || "this project";
+  return [
+    `🏗️ Project session for "${name}" is live (created by \`create-sentinelayer\`).`,
+    "",
+    "This is the project's shared coordination room. Agents working on this codebase should:",
+    `- Join before starting work: \`sl session join ${sessionId} --agent <your-agent-name>\``,
+    `- Post status updates as you work: \`sl session say ${sessionId} "<update>" --agent <your-agent-name>\``,
+    "- Audit runs (`sentinel audit`) post per-persona progress here automatically, so swarm agents can see each other's findings without losing context.",
+  ].join("\n");
+}
+
+/**
+ * Create the project's senti session as part of `create-sentinelayer` init:
+ * a fresh workspace session rooted at the new project directory, with
+ * coordination guides written into AGENTS.md / CLAUDE.md and a welcome
+ * message announcing the room to joining agents.
+ *
+ * Local-first: session creation always succeeds offline; dashboard metadata
+ * sync and the welcome-message relay are best-effort and never throw.
+ *
+ * Pass `skipGuides: true` when the caller writes coding-agent config files
+ * after this call (guide upsert would otherwise create AGENTS.md/CLAUDE.md
+ * first and make the config scaffold skip itself) — then call
+ * `setupSessionGuides` once those files exist.
+ */
+export async function bootstrapProjectSession({
+  projectDir,
+  projectName,
+  ttlSeconds,
+  skipGuides = false,
+} = {}) {
+  const targetPath = path.resolve(normalizeString(projectDir) || ".");
+  const title = normalizeString(projectName) || path.basename(targetPath);
+
+  const ensured = await ensureWorkspaceSession({
+    targetPath,
+    title,
+    resume: false,
+    forceNew: true,
+    ...(Number.isFinite(Number(ttlSeconds)) && Number(ttlSeconds) > 0
+      ? { ttlSeconds: Math.floor(Number(ttlSeconds)) }
+      : {}),
+  });
+  const created = ensured.created;
+  const sessionId = created.sessionId;
+
+  // Best-effort dashboard visibility — session creation stays local-first.
+  await syncSessionMetadataToApi(sessionId, {
+    targetPath,
+    sessionId,
+    status: created.status,
+    createdAt: created.createdAt,
+    expiresAt: created.expiresAt,
+    title: ensured.title || title,
+    template: created.template,
+    codebaseContext: created.codebaseContext,
+  }).catch(() => {});
+
+  const guides = skipGuides ? null : await setupSessionGuides(sessionId, { targetPath });
+
+  const welcomeEvent = createAgentEvent({
+    event: "session_message",
+    agent: PROJECT_BOOTSTRAP_AGENT,
+    sessionId,
+    payload: {
+      message: buildProjectSessionWelcomeMessage({ projectName: title, sessionId }),
+      channel: "session",
+    },
+  });
+  let welcomePosted = true;
+  try {
+    await appendToStream(sessionId, welcomeEvent, { targetPath, awaitRemoteSync: true });
+  } catch {
+    welcomePosted = false;
+  }
+
+  // Project rooms are managed by default too: the detached Senti daemon
+  // greets joining agents and keeps recaps/checkpoints flowing. Honors
+  // SENTINELAYER_SKIP_SENTI_AUTOSTART / SENTINELAYER_SKIP_SENTI_DAEMON
+  // and never fails the bootstrap.
+  const daemon = await spawnDetachedSentiDaemon({ sessionId, targetPath });
+
+  return {
+    sessionId,
+    title: ensured.title || title,
+    targetPath,
+    dashboardUrl: buildDashboardUrl(sessionId),
+    guides,
+    welcomePosted,
+    daemon,
+  };
+}

package/src/session/wake/listen-wake.js

@@ -0,0 +1,144 @@
+import { createResolveTarget } from "./resolve-target.js";
+import claudeWakeAdapter from "./claude.js";
+import codexWakeAdapter from "./codex.js";
+
+const BUILTIN_ADAPTERS = {
+  claude: claudeWakeAdapter,
+  codex: codexWakeAdapter,
+};
+
+// Receipt-confirmation defaults (Carter's idea: a wake isn't done until the
+// agent actually acks/views the message). Conservative so reconcile never
+// spam-resumes a slow-but-awake agent.
+const DEFAULT_CONFIRM_WINDOW_MS = 90_000;
+const DEFAULT_MAX_WAKE_ATTEMPTS = 3;
+const RECEIPT_ACTION_TYPES = new Set(["ack", "view", "reply", "working_on", "like"]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function eventSequence(event) {
+  const raw = event?.sequenceId ?? event?.sequence_id ?? event?.payload?.sequenceId;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/**
+ * Wire the built wake bus (resolve-target routing + a host adapter) into the
+ * live `sl session listen` poll so an addressed message INSTANTLY resumes the
+ * host — the auto-wake cutover — and CONFIRMS the wake via read receipts.
+ *
+ * Returns { trigger, reconcile, pendingCount } or null when disabled:
+ *  - trigger(event): route + resume the host on an addressed message, and (if
+ *    the message has a durable sequence) record a pending wake to confirm.
+ *  - reconcile({ fetchActions, nowMs }): for each pending wake, fetch the
+ *    message's actions; if THIS agent acked/viewed/replied → confirmed (woke).
+ *    Else past the confirm window, re-resume (up to maxAttempts) — the agent
+ *    didn't wake. Past maxAttempts → dead-letter. Never throws.
+ */
+export function createListenerHostWake({
+  host,
+  resumeSessionId,
+  agentId,
+  sessionId,
+  adapters = BUILTIN_ADAPTERS,
+  confirmWindowMs = DEFAULT_CONFIRM_WINDOW_MS,
+  maxAttempts = DEFAULT_MAX_WAKE_ATTEMPTS,
+} = {}) {
+  const hostName = normalizeString(host).toLowerCase();
+  const resumeId = normalizeString(resumeSessionId);
+  const selfId = normalizeString(agentId);
+  const sid = normalizeString(sessionId);
+  const adapter = adapters[hostName];
+  if (!adapter || typeof adapter.wake !== "function") return null;
+  if (!resumeId || !selfId || !sid) return null;
+
+  const resolveTarget = createResolveTarget({
+    agentId: selfId,
+    host: hostName,
+    sessionId: resumeId,
+  });
+
+  // Serialize resumes: each spawns a host process; never two at once.
+  let queue = Promise.resolve();
+  // seq -> { target, attempts, lastWakeAt }
+  const pending = new Map();
+
+  function resume(target) {
+    queue = queue.then(async () => {
+      try {
+        const result = await adapter.wake(target);
+        return {
+          woken: Boolean(result?.ok),
+          ok: Boolean(result?.ok),
+          reason: result?.ok ? "resumed" : normalizeString(result?.reason) || "wake_failed",
+          host: hostName,
+        };
+      } catch (error) {
+        return { woken: false, ok: false, reason: normalizeString(error?.message) || "wake_error", host: hostName };
+      }
+    });
+    return queue;
+  }
+
+  function trigger(event) {
+    const target = resolveTarget(event);
+    if (!target) return Promise.resolve({ woken: false, reason: "not_routed" });
+    const seq = eventSequence(event);
+    // Record a pending wake to confirm. lastWakeAt is stamped on the first
+    // reconcile (callers own the clock) so the confirm window starts then.
+    if (seq !== null && !pending.has(seq)) {
+      pending.set(seq, { target, attempts: 1, lastWakeAt: Number.NaN });
+    }
+    return resume(target);
+  }
+
+  async function reconcile({ fetchActions, nowMs = 0 } = {}) {
+    const summary = { confirmed: 0, retried: 0, deadLettered: 0, stillPending: 0 };
+    if (typeof fetchActions !== "function" || pending.size === 0) {
+      summary.stillPending = pending.size;
+      return summary;
+    }
+    for (const [seq, entry] of [...pending.entries()]) {
+      if (!Number.isFinite(entry.lastWakeAt)) entry.lastWakeAt = nowMs;
+      let actions = [];
+      try {
+        const res = await fetchActions(seq);
+        actions = Array.isArray(res?.actions) ? res.actions : [];
+      } catch {
+        // transient fetch error — leave pending, try next reconcile
+        summary.stillPending += 1;
+        continue;
+      }
+      const acked = actions.some(
+        (a) =>
+          normalizeString(a?.actorId).toLowerCase() === selfId.toLowerCase() &&
+          RECEIPT_ACTION_TYPES.has(normalizeString(a?.actionType).toLowerCase()),
+      );
+      if (acked) {
+        pending.delete(seq);
+        summary.confirmed += 1;
+        continue;
+      }
+      if (nowMs - entry.lastWakeAt >= confirmWindowMs) {
+        if (entry.attempts < maxAttempts) {
+          entry.attempts += 1;
+          entry.lastWakeAt = nowMs;
+          void resume(entry.target);
+          summary.retried += 1;
+        } else {
+          pending.delete(seq);
+          summary.deadLettered += 1;
+        }
+      } else {
+        summary.stillPending += 1;
+      }
+    }
+    return summary;
+  }
+
+  return { trigger, reconcile, pendingCount: () => pending.size };
+}
+
+export { BUILTIN_ADAPTERS };