sentinelayer-cli 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/guide.js

@@ -4,6 +4,13 @@ import path from "node:path";
 
 import pc from "picocolors";
 
+import {
+  createMultiProviderApiClient,
+  resolveApiKey,
+  resolveModel,
+  resolveProvider,
+} from "../ai/client.js";
+import { enrichGuideTickets } from "../guide/enrich.js";
 import {
   defaultGuideExportFileName,
   generateBuildGuide,
@@ -12,6 +19,40 @@ import {
 } from "../guide/generator.js";
 import { renderTerminalMarkdown } from "../ui/markdown.js";
 
+// Optionally split each phase into per-PR tickets with an LLM. Best-effort:
+// any failure leaves the deterministic tickets untouched. Returns the number
+// of phases enriched (0 when disabled or unavailable).
+async function maybeEnrichGuide(guideDoc, options) {
+  if (!options || !options.enrich) return 0;
+  try {
+    const provider = resolveProvider({ provider: options.provider });
+    const model = resolveModel({ provider, model: options.model });
+    const apiKey = resolveApiKey({ provider, explicitApiKey: options.apiKey });
+    if (!apiKey) {
+      console.error(
+        pc.yellow(`! --enrich skipped: no API key for provider '${provider}'. Set the provider key or pass --api-key.`)
+      );
+      return 0;
+    }
+    const limits = {};
+    if (options.maxPhases) limits.maxPhases = Number(options.maxPhases);
+    if (options.maxPrsPerPhase) limits.maxTicketsPerPhase = Number(options.maxPrsPerPhase);
+    const { tickets, enrichedPhases } = await enrichGuideTickets({
+      guide: guideDoc,
+      client: createMultiProviderApiClient(),
+      provider,
+      model,
+      apiKey,
+      limits,
+    });
+    if (enrichedPhases > 0) guideDoc.tickets = tickets;
+    return enrichedPhases;
+  } catch (error) {
+    console.error(pc.yellow(`! --enrich failed, using deterministic tickets: ${error?.message || error}`));
+    return 0;
+  }
+}
+
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
   const globalFromCommand =
@@ -101,6 +142,12 @@ export function registerGuideCommand(program) {
     .option("--path <path>", "Target workspace path", ".")
     .option("--spec-file <path>", "Spec file path relative to --path")
     .option("--output-file <path>", "Output export file path relative to --path")
+    .option("--enrich", "Split each phase into per-PR tickets with an LLM (opt-in, capped)")
+    .option("--provider <provider>", "LLM provider for --enrich (openai|anthropic|google)")
+    .option("--model <model>", "LLM model for --enrich")
+    .option("--api-key <key>", "Explicit API key for --enrich (else from env)")
+    .option("--max-phases <n>", "Cap how many phases --enrich expands")
+    .option("--max-prs-per-phase <n>", "Cap PRs per phase for --enrich")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -116,6 +163,7 @@ export function registerGuideCommand(program) {
         projectPath: targetPath,
         specPath,
       });
+      const enrichedPhases = await maybeEnrichGuide(guideDoc, options);
       const exportBody = renderGuideExport({ format, guide: guideDoc });
 
       await fsp.mkdir(path.dirname(outputPath), { recursive: true });
@@ -128,6 +176,7 @@ export function registerGuideCommand(program) {
         specPath,
         outputPath,
         issueCount: guideDoc.tickets.length,
+        enrichedPhases,
       };
 
       if (shouldEmitJson(options, command)) {
@@ -139,6 +188,9 @@ export function registerGuideCommand(program) {
       console.log(pc.gray(`Format: ${format}`));
       console.log(pc.gray(`Output: ${outputPath}`));
       console.log(pc.gray(`Issues: ${guideDoc.tickets.length}`));
+      if (enrichedPhases > 0) {
+        console.log(pc.gray(`LLM-enriched phases: ${enrichedPhases}`));
+      }
     });
 
   guide

package/src/commands/session.js

@@ -61,6 +61,9 @@ import {
   refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
+import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
+import { postFirstSentiMessage } from "../session/first-message.js";
+import { createListenerHostWake } from "../session/wake/listen-wake.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import {
   addSessionEventIdentityKeys,
@@ -2236,6 +2239,10 @@ export function registerSessionCommand(program) {
       "--force-new",
       "Always create a new session even if a recent active one exists for this workspace",
     )
+    .option(
+      "--force",
+      "Alias of --force-new (both always mint a fresh session)",
+    )
     .option(
       "--resume",
       "Reuse the most recent active session for this workspace when one is inside the reuse window",
@@ -2279,7 +2286,7 @@ export function registerSessionCommand(program) {
         template,
         title: titleArg,
         resume: options.resume !== false,
-        forceNew: Boolean(options.forceNew),
+        forceNew: Boolean(options.forceNew || options.force),
         reuseWindowSeconds,
       });
       const created = ensured.created;
@@ -2356,6 +2363,21 @@ export function registerSessionCommand(program) {
       }
       payload.sentiDaemon = sentiDaemon;
 
+      // Pin the deterministic first-Senti-message as the opening event of a
+      // NEW room so every joining agent reads the operating protocol
+      // (identity, mandatory commands, reaction/threading/lock/evidence
+      // rules, cadence). Skipped on resume (already posted) and opt-outable
+      // via SENTINELAYER_SKIP_FIRST_MESSAGE=1. Best-effort, never blocks.
+      let firstMessage = { posted: false, reason: "skipped" };
+      const skipFirstMessage = String(process.env.SENTINELAYER_SKIP_FIRST_MESSAGE || "").trim() === "1";
+      if (!resumed && !skipFirstMessage) {
+        firstMessage = await postFirstSentiMessage({
+          sessionId: created.sessionId,
+          targetPath,
+        }).catch((error) => ({ posted: false, reason: normalizeString(error?.message) || "error" }));
+      }
+      payload.firstMessage = firstMessage;
+
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -2421,7 +2443,7 @@ export function registerSessionCommand(program) {
       if (!resumed) {
         console.log(
           pc.gray(
-            options.forceNew
+            (options.forceNew || options.force)
               ? `Tip: fresh session minted (--force-new honored). Subsequent \`${cliCommand} session start\` here within an hour will resume this new session.`
               : `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
           ),
@@ -3473,6 +3495,108 @@ export function registerSessionCommand(program) {
       return payload;
     });
 
+  session
+    .command("listeners <sessionId>")
+    .description(
+      "List who is actively listening to the session and at what poll cadence (active/idle/stale/stopped), derived from listener presence heartbeats. Mirrors the web roster.",
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--limit <n>", "Recent events to scan for heartbeats (default 200)", "200")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const limit = parsePositiveInteger(options.limit, "limit", 200);
+      const result = await fetchSessionListeners(normalizedSessionId, { targetPath, limit });
+      const listeners = Array.isArray(result.listeners) ? result.listeners : [];
+      const live = listeners.filter((row) => row.status === "active" || row.status === "idle").length;
+      const payload = {
+        command: "session listeners",
+        sessionId: normalizedSessionId,
+        ok: Boolean(result.ok),
+        reason: result.ok ? undefined : result.reason,
+        count: listeners.length,
+        liveCount: live,
+        listeners,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (!result.ok) {
+        console.log(pc.yellow(`Could not read listeners (${result.reason}).`));
+        return payload;
+      }
+      if (listeners.length === 0) {
+        console.log(pc.gray("No listeners detected (no recent presence heartbeats)."));
+        return payload;
+      }
+      console.log(pc.bold(`Listeners (${live} live / ${listeners.length} seen)`));
+      for (const row of listeners) {
+        const line = formatListenerLine(row);
+        if (row.status === "active") console.log(pc.green(`  ${line}`));
+        else if (row.status === "idle") console.log(pc.cyan(`  ${line}`));
+        else console.log(pc.gray(`  ${line}`));
+      }
+      return payload;
+    });
+
+  session
+    .command("stop-listener <sessionId>")
+    .description(
+      "Ask an agent's listener to stop (save energy). Posts a listener_stop directive the listener honors on its next poll, then exits cleanly. Targets one agent with --agent; omit it to stop every listener in the room.",
+    )
+    .option("--agent <id>", "Agent whose listener to stop (omit to stop all listeners in the room)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const targetAgent = normalizeString(options.agent);
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const event = createAgentEvent({
+        event: "listener_stop",
+        agent: { id: "session-control", model: "control", persona: "Session Control" },
+        sessionId: normalizedSessionId,
+        payload: {
+          // targetAgentId routes the directive to that agent's listener (an
+          // event recipient); omitting it broadcasts to every listener.
+          ...(targetAgent ? { targetAgentId: targetAgent } : { broadcast: true }),
+          reason: "operator_stop",
+        },
+      });
+      const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, { targetPath }).catch(
+        (error) => ({ synced: false, reason: normalizeString(error?.message) || "sync_failed" }),
+      );
+      await appendToStream(normalizedSessionId, event, { targetPath, syncRemote: false }).catch(() => {});
+      const payload = {
+        command: "session stop-listener",
+        sessionId: normalizedSessionId,
+        targetAgent: targetAgent || null,
+        scope: targetAgent ? "agent" : "all",
+        remoteSync: remoteSync || undefined,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      console.log(
+        pc.yellow(
+          targetAgent
+            ? `Listener stop requested for ${targetAgent}; it will exit on its next poll.`
+            : "Listener stop requested for ALL listeners in this room.",
+        ),
+      );
+      return payload;
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")
@@ -3520,6 +3644,14 @@ export function registerSessionCommand(program) {
       "--wake <command>",
       "Wake hook: run this shell command on each matched event (notify->resume bridge). Event JSON is piped to stdin; SL_WAKE_* env vars are set.",
     )
+    .option(
+      "--wake-host <name>",
+      "Auto-wake: resume this host (claude|codex) on each addressed message so listening IS waking. Requires --resume-session.",
+    )
+    .option(
+      "--resume-session <id>",
+      "Host session/rollout id to resume on wake (the claude/codex session id, not the Senti id). Pairs with --wake-host.",
+    )
     .option(
       "--coaching-interval <seconds>",
       "Seconds between in-session success reminders (ack, claim work, reply in-thread). Default 900; 0 disables.",
@@ -3575,6 +3707,25 @@ export function registerSessionCommand(program) {
         agentId,
         emit: emitWakeNotice,
       });
+      // Auto-wake cutover: when --wake-host + --resume-session are given, an
+      // addressed message INSTANTLY resumes the host (claude --resume / codex)
+      // via the built wake bus — turning `listen` into a true waker on the
+      // same poll. resolve-target routing inside ensures real-message-only,
+      // addressed-to-us, never-self.
+      const wakeHost = normalizeString(options.wakeHost);
+      const triggerHostWake = wakeHost
+        ? createListenerHostWake({
+            host: wakeHost,
+            resumeSessionId: options.resumeSession,
+            agentId,
+            sessionId: normalizedSessionId,
+          })
+        : null;
+      if (wakeHost && !triggerHostWake) {
+        throw new Error(
+          "--wake-host requires a valid host (claude|codex) and --resume-session <host-session-id>.",
+        );
+      }
       const requestedTransport = normalizeString(options.transport).toLowerCase() || "auto";
       if (!["auto", "stream", "poll"].includes(requestedTransport)) {
         throw new Error("--transport must be one of: auto, stream, poll.");
@@ -3696,6 +3847,20 @@ export function registerSessionCommand(program) {
             }
           },
           onEvent: async (event) => {
+            // Cut-listener: a `listener_stop` directive addressed to this
+            // agent (from the web "stop listening" control or
+            // `sl session stop-listener`) cleanly exits this listener to save
+            // energy. Untargeted (no targetAgentId) stops every listener.
+            if (normalizeString(event?.event) === "listener_stop") {
+              const target = normalizeString(event?.payload?.targetAgentId);
+              if (!target || target === agentId) {
+                if (emitFormat !== "ndjson") {
+                  console.log(pc.yellow(`Listener stop requested for ${agentId}; exiting.`));
+                }
+                ac.abort();
+                return;
+              }
+            }
             if (emitFormat === "ndjson") {
               console.log(JSON.stringify(event));
             } else {
@@ -3704,6 +3869,16 @@ export function registerSessionCommand(program) {
             // Fire the wake hook for any matched event (incl. ack/like) so the
             // host can resume its agent.
             wakeRunner.trigger(event);
+            // Auto-wake: instantly resume the host on an addressed message.
+            if (triggerHostWake) {
+              void Promise.resolve(triggerHostWake.trigger(event)).then((outcome) => {
+                if (outcome?.woken && emitFormat !== "ndjson") {
+                  console.log(pc.green(`auto-wake: resumed ${wakeHost} (${agentId})`));
+                } else if (outcome && !outcome.woken && outcome.reason !== "not_routed" && emitFormat !== "ndjson") {
+                  console.log(pc.yellow(`auto-wake: ${wakeHost} resume failed (${outcome.reason})`));
+                }
+              });
+            }
           },
           onError: async (result) => {
             const reason = normalizeString(result?.reason) || "poll_failed";
@@ -3726,6 +3901,29 @@ export function registerSessionCommand(program) {
             }
           },
           onLifecycle: async (lifecycle) => {
+            // Wake-confirmation runs on every heartbeat regardless of presence:
+            // re-resume agents that were woken but never acked within the
+            // window; confirm + retire the ones that did. (Carter's receipt
+            // idea — a wake isn't done until the agent actually reads it.)
+            if (triggerHostWake && normalizeString(lifecycle?.type) === "heartbeat") {
+              const outcome = await triggerHostWake
+                .reconcile({
+                  nowMs: Date.now(),
+                  fetchActions: (seq) =>
+                    listSessionMessageActions(normalizedSessionId, {
+                      targetPath,
+                      targetSequenceId: seq,
+                    }),
+                })
+                .catch(() => null);
+              if (outcome && (outcome.retried > 0 || outcome.deadLettered > 0) && emitFormat !== "ndjson") {
+                console.log(
+                  pc.yellow(
+                    `auto-wake reconcile: re-resumed ${outcome.retried}, gave up on ${outcome.deadLettered} (no ack).`,
+                  ),
+                );
+              }
+            }
             if (!publishPresence) return;
             const lifecycleType = normalizeString(lifecycle?.type);
             if (lifecycleType === "heartbeat") {

package/src/guide/enrich.js

@@ -0,0 +1,173 @@
+/**
+ * Optional LLM enrichment for the deterministic decomposition.
+ *
+ * The heuristic in generator.js produces one ticket per phase. This layer asks
+ * a model to split each phase into concrete, independently-mergeable per-PR
+ * tickets with sharper acceptance criteria. It is:
+ *  - opt-in (the caller passes a client),
+ *  - capped (bounded phases × tickets, so cost is bounded),
+ *  - fail-safe (any phase that errors or returns junk keeps its heuristic
+ *    ticket — enrichment never throws and never drops work).
+ */
+
+export const DEFAULT_ENRICH_LIMITS = Object.freeze({
+  maxPhases: 12,
+  maxTicketsPerPhase: 4,
+});
+
+function clampInt(value, fallback, min, max) {
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+export function buildEnrichPrompt(phase, maxTickets) {
+  const fields = phase?.fields || {};
+  const lines = [
+    `Phase: ${String(phase?.title || "").trim()}`,
+    fields.objective ? `Objective: ${fields.objective}` : "",
+    fields.files ? `Files: ${fields.files}` : "",
+    fields.tests ? `Tests: ${fields.tests}` : "",
+    Array.isArray(phase?.tasks) && phase.tasks.length
+      ? `Tasks:\n${phase.tasks.map((task) => `- ${task}`).join("\n")}`
+      : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return `You are splitting ONE software build phase into concrete, independently-mergeable pull requests.
+Return ONLY a JSON array (no prose, no markdown fences) of 1 to ${maxTickets} objects. Each object:
+{"title": "imperative summary, <= 80 chars", "summary": "one sentence", "acceptance_criteria": ["short testable bullet", "..."]}
+Rules: keep each PR small and shippable on its own; order them by dependency; 2-4 acceptance criteria each; no commentary.
+
+${lines}`;
+}
+
+/** Pull a JSON array out of a model response, tolerating code fences / prose. */
+export function extractJsonArray(text) {
+  const raw = String(text || "").trim();
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const body = (fenced ? fenced[1] : raw).trim();
+  const start = body.indexOf("[");
+  const end = body.lastIndexOf("]");
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const parsed = JSON.parse(body.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeSubTickets(parsed, maxTickets) {
+  if (!Array.isArray(parsed)) return null;
+  const out = [];
+  for (const item of parsed.slice(0, maxTickets)) {
+    const title = String(item?.title || "").trim();
+    if (!title) continue;
+    const summary = String(item?.summary || "").trim();
+    const acceptanceCriteria = Array.isArray(item?.acceptance_criteria)
+      ? item.acceptance_criteria
+          .map((value) => String(value || "").trim())
+          .filter(Boolean)
+          .slice(0, 6)
+      : [];
+    out.push({ title: title.slice(0, 120), summary, acceptanceCriteria });
+  }
+  return out.length ? out : null;
+}
+
+/** Enrich a single phase → array of {title, summary, acceptanceCriteria} or null. */
+export async function enrichPhase({ phase, client, provider, model, apiKey, env, maxTicketsPerPhase }) {
+  if (!client || typeof client.invoke !== "function") return null;
+  const cap = clampInt(maxTicketsPerPhase, DEFAULT_ENRICH_LIMITS.maxTicketsPerPhase, 1, 10);
+  try {
+    const result = await client.invoke({
+      provider,
+      model,
+      prompt: buildEnrichPrompt(phase, cap),
+      apiKey,
+      env,
+      stream: false,
+    });
+    return normalizeSubTickets(extractJsonArray(result?.text), cap);
+  } catch {
+    return null;
+  }
+}
+
+function subTicketDescription({ summary, acceptanceCriteria, dependencyLine }) {
+  const acBlock = acceptanceCriteria.length
+    ? acceptanceCriteria.map((item, index) => `${index + 1}. ${item}`).join("\n")
+    : "1. Phase outcomes are verified by deterministic checks.";
+  return [
+    `Dependencies: ${dependencyLine}`,
+    "",
+    summary ? `${summary}\n` : "",
+    "Acceptance criteria:",
+    acBlock,
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Produce an enriched ticket list from a generated guide. Each enriched phase
+ * expands into per-PR sub-tickets; phases beyond the cap, or that fail, keep
+ * their original heuristic ticket. Returns { tickets, enrichedPhases }.
+ */
+export async function enrichGuideTickets({ guide, client, provider, model, apiKey, env, limits } = {}) {
+  const phases = Array.isArray(guide?.phases) ? guide.phases : [];
+  const baseTickets = Array.isArray(guide?.tickets) ? guide.tickets : [];
+  const maxPhases = clampInt(limits?.maxPhases, DEFAULT_ENRICH_LIMITS.maxPhases, 1, 50);
+  const maxTicketsPerPhase = clampInt(
+    limits?.maxTicketsPerPhase,
+    DEFAULT_ENRICH_LIMITS.maxTicketsPerPhase,
+    1,
+    10,
+  );
+
+  const tickets = [];
+  let enrichedPhases = 0;
+
+  for (let index = 0; index < phases.length; index += 1) {
+    const phase = phases[index];
+    const baseTicket = baseTickets[index];
+    const subTickets =
+      index < maxPhases
+        ? await enrichPhase({ phase, client, provider, model, apiKey, env, maxTicketsPerPhase })
+        : null;
+
+    if (!subTickets) {
+      if (baseTicket) tickets.push(baseTicket);
+      continue;
+    }
+
+    enrichedPhases += 1;
+    const issueNumber = index + 1;
+    const phaseDeps = baseTicket?.dependencies || phase?.dependencies || [];
+    const baseLabels = baseTicket?.labels || ["sentinelayer", "build-guide", `phase-${issueNumber}`];
+
+    subTickets.forEach((sub, subIndex) => {
+      const dependencies =
+        subIndex === 0 ? phaseDeps : [tickets[tickets.length - 1].title];
+      const dependencyLine = dependencies.length > 0 ? dependencies.join(", ") : "none (entry phase)";
+      tickets.push({
+        id: `phase-${issueNumber}.${subIndex + 1}`,
+        phase_id: baseTicket?.phase_id || phase?.phaseId || "",
+        title: sub.title,
+        estimate_hours: baseTicket?.estimate_hours || { min: 4, max: 8 },
+        dependencies,
+        dependency_ids: subIndex === 0 ? baseTicket?.dependency_ids || [] : [],
+        labels: [...baseLabels, "pr"],
+        description: subTicketDescription({
+          summary: sub.summary,
+          acceptanceCriteria: sub.acceptanceCriteria,
+          dependencyLine,
+        }),
+      });
+    });
+  }
+
+  return { tickets, enrichedPhases };
+}

package/src/guide/generator.js

@@ -41,6 +41,29 @@ function parseNumberedLines(block) {
     .filter(Boolean);
 }
 
+// Labeled bullets the builder emits per phase (e.g. "- Objective: ...").
+// We capture these as structured fields so ticket bodies carry real content
+// instead of dropping every non-numbered line.
+const PHASE_FIELD_LABELS = new Map([
+  ["objective", "objective"],
+  ["dependencies", "dependencies"],
+  ["files", "files"],
+  ["commands", "commands"],
+  ["tests", "tests"],
+  ["rollback", "rollback"],
+  ["evidence", "evidence"],
+]);
+
+// "Phase 0 (P0) — Repo Bootstrap" -> "P0"; "Phase 2 ..." -> "P2".
+function parsePhaseHeadingId(title) {
+  const paren = String(title || "").match(/\(\s*([A-Za-z]+\d+)\s*\)/);
+  if (paren) {
+    return paren[1].toUpperCase();
+  }
+  const phaseNum = String(title || "").match(/^Phase\s+(\d+)\b/i);
+  return phaseNum ? `P${phaseNum[1]}` : "";
+}
+
 function parsePhasePlan(specMarkdown) {
   const phaseBlock = sectionBody(specMarkdown, "Phase Plan");
   if (!phaseBlock) {
@@ -58,16 +81,39 @@ function parsePhasePlan(specMarkdown) {
       if (current) {
         phases.push(current);
       }
+      const title = headingMatch[1].trim();
       current = {
-        title: headingMatch[1].trim(),
+        title,
+        phaseId: parsePhaseHeadingId(title),
         tasks: [],
+        fields: {},
       };
       continue;
     }
 
+    if (!current) {
+      continue;
+    }
+
     const taskMatch = line.match(/^\d+\.\s+(.+)$/);
-    if (taskMatch && current) {
+    if (taskMatch) {
       current.tasks.push(taskMatch[1].trim());
+      continue;
+    }
+
+    const bulletMatch = line.match(/^[-*]\s+(.+)$/);
+    if (bulletMatch) {
+      const body = bulletMatch[1].trim();
+      const labelMatch = body.match(/^([A-Za-z][A-Za-z ]*?):\s*(.*)$/);
+      if (labelMatch) {
+        const key = labelMatch[1].trim().toLowerCase();
+        if (PHASE_FIELD_LABELS.has(key)) {
+          current.fields[PHASE_FIELD_LABELS.get(key)] = labelMatch[2].trim();
+          continue;
+        }
+      }
+      // An unlabeled bullet is real work -> treat it as a task.
+      current.tasks.push(body);
     }
   }
 
@@ -78,6 +124,46 @@ function parsePhasePlan(specMarkdown) {
   return phases;
 }
 
+// Expand a dependency token into phase ids: "P0-P4" -> [P0..P4], "P0" -> [P0].
+function expandPhaseRange(token) {
+  const raw = String(token || "").trim();
+  if (!raw) {
+    return [];
+  }
+  const range = raw.match(/^([A-Za-z]+)(\d+)\s*[-–—]\s*([A-Za-z]+)?(\d+)$/);
+  if (range) {
+    const prefix = range[1].toUpperCase();
+    const start = Number(range[2]);
+    const end = Number(range[4]);
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start && end - start <= 50) {
+      const out = [];
+      for (let value = start; value <= end; value += 1) {
+        out.push(`${prefix}${value}`);
+      }
+      return out;
+    }
+  }
+  const single = raw.match(/^([A-Za-z]+\d+)$/);
+  return single ? [single[1].toUpperCase()] : [];
+}
+
+// Parse a declared "Dependencies" field into a list of phase ids.
+function parseDeclaredDependencies(value) {
+  const raw = String(value || "").trim();
+  if (!raw || /^none\b/i.test(raw)) {
+    return [];
+  }
+  const ids = [];
+  for (const part of raw.split(/[,;]/)) {
+    for (const id of expandPhaseRange(part)) {
+      if (!ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
 function parseProjectName(specMarkdown) {
   const match = String(specMarkdown || "").match(/^#\s*SPEC\s*-\s*(.+)$/im);
   return match ? match[1].trim() : "Project";
@@ -113,19 +199,58 @@ function estimateEffortHours({ phaseTitle, taskCount, riskSurfaceCount }) {
   };
 }
 
-function normalizeAcceptanceCriteria(specMarkdown, phaseTasks) {
+// Real, phase-specific acceptance criteria derived from the captured fields
+// (Tests/Evidence/Objective) and any tasks, instead of an empty placeholder.
+function derivePhaseAcceptance(specMarkdown, phase) {
   const globalCriteria = parseNumberedLines(sectionBody(specMarkdown, "Acceptance Criteria"));
   if (globalCriteria.length > 0) {
-    return globalCriteria.slice(0, 3);
+    return globalCriteria.slice(0, 5);
+  }
+  const fields = phase.fields || {};
+  const out = [];
+  if (fields.tests) {
+    out.push(`Tests pass: ${fields.tests}`);
+  }
+  if (fields.evidence) {
+    out.push(`Evidence captured: ${fields.evidence}`);
+  }
+  if (fields.objective) {
+    out.push(`Objective met: ${fields.objective}`);
   }
-  return phaseTasks.slice(0, 3).map((task) => `Validated completion: ${task}`);
+  for (const task of (phase.tasks || []).slice(0, 3)) {
+    out.push(`Completed: ${task}`);
+  }
+  if (out.length === 0) {
+    out.push("Phase outcomes are verified by deterministic checks.");
+  }
+  return out.slice(0, 5);
+}
+
+// Structured detail lines (objective/files/tests/...) for the ticket body.
+function renderPhaseDetailLines(phase) {
+  const fields = phase.fields || {};
+  const order = ["objective", "files", "commands", "tests", "rollback", "evidence"];
+  const labels = {
+    objective: "Objective",
+    files: "Files",
+    commands: "Commands",
+    tests: "Tests",
+    rollback: "Rollback",
+    evidence: "Evidence",
+  };
+  return order
+    .filter((key) => String(fields[key] || "").trim().length > 0)
+    .map((key) => `${labels[key]}: ${fields[key]}`);
 }
 
 function renderPhaseMarkdown(phase) {
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock =
+    detailLines.length > 0 ? `\n${detailLines.map((line) => `- ${line}`).join("\n")}` : "";
   const taskLines =
     phase.tasks.length > 0
       ? phase.tasks.map((task, index) => `${index + 1}. ${task}`).join("\n")
-      : "1. Define implementation tasks for this phase.";
+      : "1. Deliver the phase objective above with deterministic checks.";
   const acceptanceLines =
     phase.acceptanceCriteria.length > 0
       ? phase.acceptanceCriteria.map((item, index) => `${index + 1}. ${item}`).join("\n")
@@ -135,7 +260,7 @@ function renderPhaseMarkdown(phase) {
 
   return `### ${phase.title}
 - Estimated effort: ${phase.effort.label}
-- Dependencies: ${dependencyLine}
+- Dependencies: ${dependencyLine}${detailBlock}
 
 #### Implementation Tasks
 ${taskLines}
@@ -147,29 +272,38 @@ ${acceptanceLines}
 
 function buildTicket(phase, index) {
   const issueNumber = index + 1;
+  const phaseId = String(phase.phaseId || "").trim();
   const labels = ["sentinelayer", "build-guide", `phase-${issueNumber}`];
+  if (phaseId) {
+    labels.push(phaseId.toLowerCase());
+  }
   const dependencyLine =
     phase.dependencies.length > 0 ? phase.dependencies.join(", ") : "none (entry phase)";
   const acceptanceBlock = phase.acceptanceCriteria
     .map((item, criterionIndex) => `${criterionIndex + 1}. ${item}`)
     .join("\n");
   const taskBlock = phase.tasks.map((task, taskIndex) => `${taskIndex + 1}. ${task}`).join("\n");
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock = detailLines.length > 0 ? ["Details:", ...detailLines, ""] : [];
 
   return {
     id: `phase-${issueNumber}`,
+    phase_id: phaseId,
     title: phase.title,
     estimate_hours: {
       min: phase.effort.minHours,
       max: phase.effort.maxHours,
     },
     dependencies: phase.dependencies,
+    dependency_ids: phase.dependencyIds || [],
     labels,
     description: [
       `Dependencies: ${dependencyLine}`,
       `Estimated effort: ${phase.effort.label}`,
       "",
+      ...detailBlock,
       "Implementation tasks:",
-      taskBlock || "1. Define implementation tasks for this phase.",
+      taskBlock || "1. Deliver the phase objective above with deterministic checks.",
       "",
       "Acceptance criteria:",
       acceptanceBlock || "1. Phase outcomes are verified by deterministic checks.",
@@ -210,19 +344,42 @@ export function generateBuildGuide({
   const goal = parseGoal(source);
   const riskSurfaceCount = parseRiskSurfaceCount(source);
 
+  // Map declared phase ids (P0, P1, ...) to titles so a "Dependencies: P0-P1"
+  // line resolves to a real prerequisite graph instead of naive sequencing.
+  const idToTitle = new Map(
+    phases.filter((phase) => phase.phaseId).map((phase) => [phase.phaseId, phase.title])
+  );
+
   const resolvedPhases = phases.map((phase, index) => {
-    const dependencies = index > 0 ? [phases[index - 1].title] : [];
+    const declaredIds = parseDeclaredDependencies(phase.fields?.dependencies);
+    const knownIds = declaredIds.filter(
+      (id) => idToTitle.has(id) && idToTitle.get(id) !== phase.title
+    );
+    let dependencies;
+    if (knownIds.length > 0) {
+      // Honor the spec's declared dependency graph.
+      dependencies = knownIds.map((id) => idToTitle.get(id));
+    } else if (declaredIds.length === 0 && index > 0) {
+      // Nothing declared -> fall back to the previous phase only.
+      dependencies = [phases[index - 1].title];
+    } else {
+      // Declared "none", or deps that don't resolve -> entry phase.
+      dependencies = [];
+    }
     const effort = estimateEffortHours({
       phaseTitle: phase.title,
       taskCount: phase.tasks.length,
       riskSurfaceCount,
     });
-    const acceptanceCriteria = normalizeAcceptanceCriteria(source, phase.tasks);
+    const acceptanceCriteria = derivePhaseAcceptance(source, phase);
 
     return {
       title: phase.title,
+      phaseId: phase.phaseId,
       tasks: phase.tasks,
+      fields: phase.fields,
       dependencies,
+      dependencyIds: knownIds,
       effort,
       acceptanceCriteria,
     };

package/src/legacy-cli.js

@@ -2133,6 +2133,13 @@ Project: ${projectName}
 - [ ] Re-run gate and confirm clean status.
 - [ ] Merge only after quality gates are green.
 
+## Ticket Trail Contract (Per PR — lean, only if the project has a board/Jira)
+- [ ] One ticket = one PR; the PR body carries the ticket id.
+- [ ] On PR open: move the ticket to In-review + comment the PR link.
+- [ ] On merge + green: move the ticket to Done + comment "merged, gate green".
+- [ ] On gate fail: move the ticket to Blocked + the finding.
+- [ ] One update per transition — not every step (same discipline as senti).
+
 ## Command Roadmap (Local Terminal)
 - [ ] \`sentinel /omargate deep --path <repo>\`: local deep scan pipeline
 - [ ] \`sentinel /audit --path <repo>\`: security + quality audit summary
@@ -2219,6 +2226,13 @@ Execution mode:
 - Keep commits scoped and deterministic.
 - Stop only for blocking secrets/permission gaps.
 
+Ticket trail (lean, only if the project has a board/Jira — do this on every PR, not every step):
+- One ticket = one PR; put the ticket id in the PR body.
+- On PR open -> move the ticket to In-review and comment the PR link.
+- On merge + green -> move the ticket to Done and comment "merged, gate green".
+- On gate fail -> move the ticket to Blocked with the finding.
+- Post one short senti update per transition (same discipline as the ticket).
+
 Coding agent profile:
 - Selected agent: ${codingAgentProfile.name} (${codingAgentProfile.id})
 - Prompt target: ${codingAgentProfile.promptTarget}

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/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 };