sentinelayer-cli 0.22.0 → 0.24.0

package/src/commands/session.js

@@ -33,6 +33,12 @@ import {
   unregisterAgent,
 } from "../session/agent-registry.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
+import {
+  getDaemonStatus,
+  removeDaemonPidRecord,
+  spawnDetachedSentiDaemon,
+  writeDaemonPidRecord,
+} from "../session/daemon-spawn.js";
 import { listRuntimeRuns } from "../session/runtime-bridge.js";
 import {
   listFileLocks,
@@ -55,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,
@@ -781,6 +790,42 @@ function sentiAutostartDisabled() {
   return String(process.env.SENTINELAYER_SKIP_SENTI_AUTOSTART || "").trim() === "1";
 }
 
+export function formatSentiDaemonStatusLine(sentiDaemon = {}, { cliCommand = "sl", sessionId = "" } = {}) {
+  if (sentiDaemon.spawned) {
+    return {
+      tone: "green",
+      text: `Senti: managing this session (daemon pid ${sentiDaemon.pid}, detached — survives this terminal). Log: ${sentiDaemon.logPath}`,
+    };
+  }
+  if (sentiDaemon.reason === "already_running") {
+    return {
+      tone: "green",
+      text: `Senti: already managing this session (daemon pid ${sentiDaemon.pid}).`,
+    };
+  }
+  if (sentiDaemon.reason === "disabled" || sentiDaemon.reason === "opt_out") {
+    return {
+      tone: "gray",
+      text: `Senti daemon skipped (${sentiDaemon.reason === "opt_out" ? "--no-daemon" : "SENTINELAYER_SKIP_SENTI_AUTOSTART=1"}); session is unmanaged. Start manually: ${cliCommand} session daemon ${sessionId}`,
+    };
+  }
+  return {
+    tone: "yellow",
+    text: `! Senti daemon not started (${sentiDaemon.reason || "unknown"}); session is unmanaged. Start manually: ${cliCommand} session daemon ${sessionId}`,
+  };
+}
+
+function printSentiDaemonStatusLine(sentiDaemon, context) {
+  const line = formatSentiDaemonStatusLine(sentiDaemon, context);
+  if (line.tone === "green") {
+    console.log(pc.green(line.text));
+  } else if (line.tone === "yellow") {
+    console.log(pc.yellow(line.text));
+  } else {
+    console.log(pc.gray(line.text));
+  }
+}
+
 function buildResumeContext(candidate, { reuseWindowSeconds = 3600 } = {}) {
   if (!candidate) return null;
   const source = normalizeString(candidate._source) || "unknown";
@@ -1201,7 +1246,7 @@ async function ensureLocalSessionForRemoteCommand(
   return { materialized: true, refreshed: false, session: created };
 }
 
-async function ensureWorkspaceSession({
+export async function ensureWorkspaceSession({
   targetPath,
   ttlSeconds = DEFAULT_TTL_SECONDS,
   template = null,
@@ -2178,7 +2223,7 @@ export function registerSessionCommand(program) {
   session
     .command("start")
     .description(
-      "Start (or resume) a persistent session. By default reuses the most recent active session for this workspace; pass --force-new to always mint a fresh id.",
+      "Start (or resume) a managed session. Reuses this workspace's most recent active session when it was active within the last hour (--force-new always mints a fresh id), then spawns the detached Senti daemon that manages it — agent greetings, mention routing, recaps, checkpoints — surviving this terminal. Pass --no-daemon for an unmanaged session.",
     )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--title <title>", "Human-readable label (shown in web sidebar + transcript)")
@@ -2194,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",
@@ -2208,6 +2257,10 @@ export function registerSessionCommand(program) {
       "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
       "3600",
     )
+    .option(
+      "--no-daemon",
+      "Do not spawn the detached Senti daemon (session will be unmanaged: no greetings, recaps, or checkpoints)",
+    )
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -2233,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;
@@ -2290,19 +2343,40 @@ export function registerSessionCommand(program) {
         }).catch(() => {});
       }
 
-      // Auto-start the Senti orchestrator daemon. Without this, every
-      // session ran with `Senti actions: 1` (just the welcome alert)
-      // because nothing kicked the daemon ticking — agents joining
-      // never got greeted, mentions never routed, recaps never fired.
-      // Best-effort + non-blocking: the daemon registers itself in an
-      // in-memory map keyed by (sessionId, targetPath) and tolerates
-      // being started for an already-active session (returns the
-      // existing handle). If the daemon fails to start (unauth env,
-      // missing model proxy), the session keeps working — Senti just
-      // stays quiet, same as before this change.
-      if (!sentiAutostartDisabled()) {
-        void startSenti(created.sessionId, { targetPath }).catch(() => {});
+      // Make the session managed by default: spawn the Senti daemon as a
+      // DETACHED process so greetings, mention routing, recaps, and
+      // checkpoints keep running after this CLI command (and terminal)
+      // exits. The old in-process `startSenti` died the moment this
+      // action returned, so every session was effectively unmanaged.
+      // Deduped via the session's pid file; best-effort and never blocks
+      // session creation.
+      let sentiDaemon = { spawned: false, pid: null, reason: "skipped", logPath: "" };
+      if (sentiAutostartDisabled()) {
+        sentiDaemon.reason = "disabled";
+      } else if (options.daemon === false) {
+        sentiDaemon.reason = "opt_out";
+      } else {
+        sentiDaemon = await spawnDetachedSentiDaemon({
+          sessionId: created.sessionId,
+          targetPath,
+        });
       }
+      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));
@@ -2324,6 +2398,7 @@ export function registerSessionCommand(program) {
         }
         console.log("");
         console.log(`Dashboard: ${dashboardUrl}`);
+        printSentiDaemonStatusLine(sentiDaemon, { cliCommand, sessionId: created.sessionId });
         return;
       }
 
@@ -2349,6 +2424,13 @@ export function registerSessionCommand(program) {
       console.log(
         `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`,
       );
+      console.log(pc.gray(`Dashboard: ${dashboardUrl}`));
+      printSentiDaemonStatusLine(sentiDaemon, { cliCommand, sessionId: created.sessionId });
+      console.log(
+        pc.gray(
+          `Agents join with: ${cliCommand} session join ${created.sessionId} --agent <name>`,
+        ),
+      );
       if (remoteSync.status === "auth_required") {
         console.log(
           pc.yellow(
@@ -2361,7 +2443,9 @@ export function registerSessionCommand(program) {
       if (!resumed) {
         console.log(
           pc.gray(
-            `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
+            (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.`,
           ),
         );
       }
@@ -3411,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")
@@ -3458,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.",
@@ -3513,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.");
@@ -3634,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 {
@@ -3642,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";
@@ -3664,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") {
@@ -3694,8 +3954,11 @@ export function registerSessionCommand(program) {
 
   session
     .command("daemon [sessionId]")
-    .description("Run the Senti session daemon: hydrate events, emit recaps, and generate checkpoints")
+    .description(
+      "Run the Senti daemon that manages a session: greet joining agents, route mentions, emit recaps, and generate durable checkpoints. `session start` spawns this automatically as a detached background process — run it manually only for foreground monitoring or after --no-daemon. Records its pid in the session dir (senti-daemon.json) and exits when the session expires.",
+    )
     .option("--session <id>", "Session id to monitor")
+    .option("--force", "Take over even if senti-daemon.json reports another live daemon for this session")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--tick-interval <seconds>", "Seconds between health ticks (default 30)", "30")
     .option("--stale-agent-seconds <seconds>", "Seconds before an inactive agent is flagged stale (default 90)", "90")
@@ -3723,6 +3986,18 @@ export function registerSessionCommand(program) {
         "tick-interval",
         30,
       );
+      // One manager per session: refuse to double-run unless --force.
+      // A stale pid file (reboot, hard kill) reads as not-running and is
+      // safely overwritten.
+      if (!options.once) {
+        const existingDaemon = await getDaemonStatus(normalizedSessionId, { targetPath });
+        if (existingDaemon.running && existingDaemon.pid !== process.pid && !options.force) {
+          throw new Error(
+            `A Senti daemon is already managing session ${normalizedSessionId} (pid ${existingDaemon.pid}). Use --force to take over.`,
+          );
+        }
+        await writeDaemonPidRecord(normalizedSessionId, { targetPath, tickIntervalMs });
+      }
       const daemon = await startSenti(normalizedSessionId, {
         targetPath,
         autoStart: false,
@@ -3824,10 +4099,28 @@ export function registerSessionCommand(program) {
           } else {
             console.log(pc.gray(`tick ${payload.summary.generatedAt}: recap=${payload.summary.recap.reason || payload.summary.recap.mode || "ok"} checkpoint=${payload.summary.checkpoint.reason || payload.summary.checkpoint.checkpointId || "ok"}`));
           }
+          // A daemon must not outlive its session: stop cleanly once the
+          // session expires or its local cache disappears.
+          const liveSession = await getSession(normalizedSessionId, { targetPath }).catch(() => null);
+          const expiresAtMs = Date.parse(liveSession?.expiresAt || "");
+          if (
+            !liveSession ||
+            liveSession.status !== "active" ||
+            (Number.isFinite(expiresAtMs) && expiresAtMs <= Date.now())
+          ) {
+            if (!emitJson) {
+              console.log(pc.gray("senti daemon: session expired or closed; stopping."));
+            }
+            break;
+          }
         }
       } finally {
         process.removeListener("SIGINT", stop);
         process.removeListener("SIGTERM", stop);
+        await removeDaemonPidRecord(normalizedSessionId, {
+          targetPath,
+          onlyForPid: process.pid,
+        }).catch(() => {});
         const stopped = await daemon.stop("signal");
         if (emitJson) {
           console.log(

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