sentinelayer-cli 0.8.0 → 0.8.2

package/src/session/daemon.js

@@ -1,7 +1,20 @@
 import path from "node:path";
 import process from "node:process";
+import fsp from "node:fs/promises";
 
+import { invokeViaProxy } from "../ai/proxy.js";
 import { createAgentEvent } from "../events/schema.js";
+import {
+  buildDocumentsFromBlackboardEntries,
+  buildLocalHybridIndex,
+  buildSharedMemoryCorpus,
+  queryLocalHybridIndex,
+} from "../memory/retrieval.js";
+import {
+  endSession as endTelemetrySession,
+  recordLlmUsage,
+  startSession as startTelemetrySession,
+} from "../telemetry/session-tracker.js";
 import {
   detectStaleAgents,
   heartbeatAgent,
@@ -9,18 +22,36 @@ import {
   registerAgent,
   unregisterAgent,
 } from "./agent-registry.js";
+import {
+  DEFAULT_FILE_LOCK_TTL_SECONDS,
+  lockFile,
+  unlockFile,
+} from "./file-locks.js";
 import { resolveSessionPaths } from "./paths.js";
+import {
+  DEFAULT_RECAP_INACTIVITY_MS,
+  DEFAULT_RECAP_INTERVAL_MS,
+  emitPeriodicRecap,
+} from "./recap.js";
 import { stopRuntimeRunsForSession } from "./runtime-bridge.js";
+import { pollHumanMessages } from "./sync.js";
 import { getSession, renewSession } from "./store.js";
 import { appendToStream, readStream, tailStream } from "./stream.js";
+import { handleTaskDirective } from "./tasks.js";
 
 const DAEMON_TICK_INTERVAL_MS = 30_000;
-const HELP_REQUEST_TIMEOUT_MS = 30_000;
+const HELP_REQUEST_TIMEOUT_MS = 1_200;
+const HELP_MODEL_TIMEOUT_MS = 3_000;
+const HELP_CONTEXT_EVENT_TAIL = 50;
+const HELP_CONTEXT_RESULT_LIMIT = 6;
+const HELP_BLACKBOARD_ENTRY_LIMIT = 40;
 const FILE_CONFLICT_WINDOW_MS = 60_000;
 const RENEWAL_WINDOW_MS = 60 * 60 * 1000;
 const RENEWAL_THRESHOLD_EVENTS = 10;
 const RENEWAL_LEAD_MS = 60 * 60 * 1000;
 const DEFAULT_STALE_AGENT_SECONDS = 90;
+const DEFAULT_RECAP_INTERVAL_MS_OVERRIDE = DEFAULT_RECAP_INTERVAL_MS;
+const DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE = DEFAULT_RECAP_INACTIVITY_MS;
 
 const SENTI_MODEL = "gpt-5.4-mini";
 const SENTI_IDENTITY = Object.freeze({
@@ -136,7 +167,11 @@ function createSentiState({
   staleAgentSeconds,
   helpRequestTimeoutMs,
   tickIntervalMs,
+  recapIntervalMs,
+  recapInactivityMs,
   helpResponder,
+  llmInvoker,
+  telemetrySessionId,
 }) {
   return {
     daemonKey,
@@ -147,7 +182,11 @@ function createSentiState({
     staleAgentSeconds,
     helpRequestTimeoutMs,
     tickIntervalMs,
+    recapIntervalMs,
+    recapInactivityMs,
     helpResponder,
+    llmInvoker,
+    telemetrySessionId,
     running: true,
     tickTimer: null,
     helpAbortController: new AbortController(),
@@ -157,6 +196,9 @@ function createSentiState({
     conflictAlertAt: new Map(),
     lastTickAt: null,
     lastTickSummary: null,
+    recapEmitter: null,
+    humanMessageCursor: null,
+    humanMessagePollInFlight: false,
   };
 }
 
@@ -188,6 +230,105 @@ async function hasHelpResponseFromPeer(
   });
 }
 
+function normalizeUsageNumber(value) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return 0;
+  }
+  return normalized;
+}
+
+function buildStreamContextDocuments(events = []) {
+  return (events || [])
+    .map((event, index) => {
+      const payload = event && typeof event.payload === "object" ? event.payload : {};
+      const text = [
+        normalizeString(event.event),
+        normalizeString(event.agent?.id || event.agentId),
+        normalizeString(payload.message),
+        normalizeString(payload.response),
+        normalizeString(payload.alert),
+        normalizeString(payload.reason),
+        normalizeString(payload.file),
+      ]
+        .filter(Boolean)
+        .join(" ")
+        .trim();
+      if (!text) {
+        return null;
+      }
+      return {
+        documentId: `stream:${index + 1}:${normalizeIsoTimestamp(event.ts, new Date().toISOString())}`,
+        sourceType: "session-stream",
+        sourcePath: "",
+        severity: "P3",
+        updatedAt: normalizeIsoTimestamp(event.ts, new Date().toISOString()),
+        text,
+        metadata: {
+          category: "session-stream",
+          event: normalizeString(event.event),
+          agentId: normalizeString(event.agent?.id || event.agentId),
+        },
+      };
+    })
+    .filter(Boolean);
+}
+
+async function loadLatestBlackboardEntries(targetPath, { limit = HELP_BLACKBOARD_ENTRY_LIMIT } = {}) {
+  const memoryDirectory = path.join(targetPath, ".sentinelayer", "memory");
+  let entries = [];
+  try {
+    entries = await fsp.readdir(memoryDirectory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.startsWith("blackboard-") && entry.name.endsWith(".json"))
+    .map((entry) => entry.name)
+    .sort((left, right) => right.localeCompare(left));
+  for (const fileName of files) {
+    const filePath = path.join(memoryDirectory, fileName);
+    try {
+      const payload = JSON.parse(await fsp.readFile(filePath, "utf-8"));
+      if (!Array.isArray(payload.entries)) {
+        continue;
+      }
+      return payload.entries.slice(-Math.max(1, Math.floor(Number(limit) || HELP_BLACKBOARD_ENTRY_LIMIT)));
+    } catch {
+      // Ignore malformed artifacts and continue searching older files.
+    }
+  }
+  return [];
+}
+
+function buildFallbackHelpResponse({ requestMessage = "", synopsis = "context unavailable", contextHints = [] } = {}) {
+  const topHints = contextHints.slice(0, 2).join(" | ");
+  if (topHints) {
+    return `I saw your help_request ("${requestMessage}"). Quick context: ${synopsis}. Top hints: ${topHints}. Share the failing file or stack frame and I can route next steps.`;
+  }
+  return `I saw your help_request ("${requestMessage}"). Quick context: ${synopsis}. Share the failing file or stack frame and I can route next steps.`;
+}
+
+async function runWithTimeout(promise, timeoutMs, timeoutMessage) {
+  let timeoutHandle = null;
+  try {
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        reject(new Error(timeoutMessage));
+      }, timeoutMs);
+      if (typeof timeoutHandle.unref === "function") {
+        timeoutHandle.unref();
+      }
+    });
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
 async function buildHelpResponseMessage(
   daemonState,
   requestEvent,
@@ -195,6 +336,11 @@ async function buildHelpResponseMessage(
     targetPath = process.cwd(),
   } = {}
 ) {
+  const requestMessage =
+    normalizeString(requestEvent?.payload?.message) ||
+    normalizeString(requestEvent?.payload?.request) ||
+    "help request received";
+
   if (typeof daemonState.helpResponder === "function") {
     const custom = await daemonState.helpResponder({
       daemonState,
@@ -203,19 +349,170 @@ async function buildHelpResponseMessage(
     });
     const normalizedCustom = normalizeString(custom);
     if (normalizedCustom) {
-      return normalizedCustom;
+      return {
+        message: normalizedCustom,
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0,
+          costUsd: 0,
+          model: daemonState.model,
+          provider: "custom-responder",
+          latencyMs: 0,
+        },
+        fallbackPath: false,
+        fallbackReason: "",
+        contextSignals: {
+          documentCount: 0,
+          memoryHits: 0,
+          blackboardEntries: 0,
+          recentEvents: 0,
+        },
+      };
     }
   }
 
-  const session = await getSession(daemonState.sessionId, {
-    targetPath,
-  });
+  const session = await getSession(daemonState.sessionId, { targetPath });
   const synopsis = session ? formatCodebaseSynopsis(session) : "codebase context unavailable";
-  const requestMessage =
-    normalizeString(requestEvent?.payload?.message) ||
-    normalizeString(requestEvent?.payload?.request) ||
-    "help request received";
-  return `I saw your help_request ("${requestMessage}"). Quick context: ${synopsis}. Share the failing file or stack frame and I can route next steps.`;
+  const outputRoot = path.join(targetPath, ".sentinelayer");
+
+  const [recentEvents, blackboardEntries, sharedMemory] = await Promise.all([
+    readStream(daemonState.sessionId, {
+      targetPath,
+      tail: HELP_CONTEXT_EVENT_TAIL,
+    }).catch(() => []),
+    loadLatestBlackboardEntries(targetPath, {
+      limit: HELP_BLACKBOARD_ENTRY_LIMIT,
+    }),
+    buildSharedMemoryCorpus({
+      outputRoot,
+      targetPath,
+      ingest: session?.codebaseContext || {},
+      maxAuditRuns: 2,
+    }).catch(() => ({
+      documents: [],
+      sourceCounts: {},
+    })),
+  ]);
+
+  const documents = [
+    ...(sharedMemory.documents || []),
+    ...buildStreamContextDocuments(recentEvents),
+    ...buildDocumentsFromBlackboardEntries(blackboardEntries),
+  ];
+  const localIndex = buildLocalHybridIndex(documents);
+  const memoryQuery = queryLocalHybridIndex(localIndex, {
+    query: requestMessage,
+    limit: HELP_CONTEXT_RESULT_LIMIT,
+    minScore: 0.05,
+  });
+  const memoryHits = memoryQuery.results || [];
+  const contextHints = memoryHits
+    .slice(0, HELP_CONTEXT_RESULT_LIMIT)
+    .map((result) => {
+      const source = normalizeString(result.sourceType) || "memory";
+      const snippet = normalizeString(result.snippet || "").replace(/\s+/g, " ").trim();
+      if (!snippet) {
+        return "";
+      }
+      return `${source}: ${snippet}`;
+    })
+    .filter(Boolean);
+
+  const systemPrompt = [
+    "You are Senti, SentinelLayer's session daemon.",
+    "Answer the requesting agent with concise, actionable engineering guidance.",
+    "Prioritize concrete next steps and reference available context snippets.",
+    "Never invent repository files or runtime behavior.",
+  ].join(" ");
+  const userPrompt = [
+    `Agent request: ${requestMessage}`,
+    `Codebase synopsis: ${synopsis}`,
+    "Context snippets:",
+    contextHints.length > 0 ? contextHints.map((line, index) => `${index + 1}. ${line}`).join("\n") : "none",
+    "Respond in 2-4 short sentences.",
+  ].join("\n");
+
+  const startedAt = Date.now();
+  let llmText = "";
+  let fallbackPath = false;
+  let fallbackReason = "";
+  let usage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    costUsd: 0,
+    model: daemonState.model,
+    provider: "local-fallback",
+    latencyMs: 0,
+  };
+
+  const llmTimeoutMs = Math.max(
+    80,
+    Math.min(
+      HELP_MODEL_TIMEOUT_MS,
+      normalizePositiveInteger(daemonState.helpRequestTimeoutMs, HELP_REQUEST_TIMEOUT_MS) * 2
+    )
+  );
+
+  try {
+    const llmResult = await runWithTimeout(
+      Promise.resolve(
+        daemonState.llmInvoker({
+          model: daemonState.model,
+          systemPrompt,
+          prompt: userPrompt,
+          maxTokens: 320,
+          temperature: 0.1,
+        })
+      ),
+      llmTimeoutMs,
+      "Senti model response timeout."
+    );
+    llmText = normalizeString(llmResult?.text);
+    usage = {
+      inputTokens: normalizeUsageNumber(llmResult?.usage?.inputTokens),
+      outputTokens: normalizeUsageNumber(llmResult?.usage?.outputTokens),
+      costUsd: normalizeUsageNumber(llmResult?.usage?.costUsd),
+      model: normalizeString(llmResult?.usage?.model) || daemonState.model,
+      provider: normalizeString(llmResult?.usage?.provider) || "sentinelayer",
+      latencyMs: normalizeUsageNumber(llmResult?.usage?.latencyMs),
+    };
+    if (!llmText) {
+      fallbackPath = true;
+      fallbackReason = "Senti model returned an empty response.";
+    }
+  } catch (error) {
+    fallbackPath = true;
+    fallbackReason = normalizeString(error?.message || error) || "Senti model invocation failed.";
+  }
+
+  if (!usage.latencyMs) {
+    usage.latencyMs = Math.max(1, Date.now() - startedAt);
+  }
+  recordLlmUsage({
+    sessionId: daemonState.telemetrySessionId,
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    costUsd: usage.costUsd,
+  });
+
+  const message = llmText ||
+    buildFallbackHelpResponse({
+      requestMessage,
+      synopsis,
+      contextHints,
+    });
+  return {
+    message,
+    usage,
+    fallbackPath,
+    fallbackReason,
+    contextSignals: {
+      documentCount: documents.length,
+      memoryHits: memoryHits.length,
+      blackboardEntries: blackboardEntries.length,
+      recentEvents: recentEvents.length,
+    },
+  };
 }
 
 async function maybeRespondToHelpRequest(
@@ -238,23 +535,47 @@ async function maybeRespondToHelpRequest(
   if (hasPeerResponse) {
     return null;
   }
-  const responseMessage = await buildHelpResponseMessage(daemonState, requestEvent, {
+  const response = await buildHelpResponseMessage(daemonState, requestEvent, {
     targetPath,
   });
-  return emitSentiEvent(
+  const nowIso = new Date().toISOString();
+  const responseEvent = await emitSentiEvent(
     daemonState.sessionId,
     "help_response",
     {
       requestId,
       targetAgentId: normalizeString(requestEvent.agent?.id) || null,
-      response: responseMessage,
+      response: response.message,
+      sourceEvent: "help_request",
+      contextSignals: response.contextSignals,
+    },
+    {
+      targetPath,
+      nowIso,
+    }
+  );
+  await emitSentiEvent(
+    daemonState.sessionId,
+    "model_span",
+    {
       sourceEvent: "help_request",
+      requestId,
+      model: response.usage.model || daemonState.model,
+      provider: response.usage.provider || "sentinelayer",
+      inputTokens: response.usage.inputTokens,
+      outputTokens: response.usage.outputTokens,
+      costUsd: response.usage.costUsd,
+      latencyMs: response.usage.latencyMs,
+      fallbackPath: Boolean(response.fallbackPath),
+      fallbackReason: response.fallbackReason || null,
+      contextSignals: response.contextSignals,
     },
     {
       targetPath,
-      nowIso: new Date().toISOString(),
+      nowIso,
     }
   );
+  return responseEvent;
 }
 
 function queueHelpResponse(daemonState, requestEvent) {
@@ -309,6 +630,176 @@ async function runHelpWatcher(daemonState) {
   }
 }
 
+function splitFileAndIntent(raw = "") {
+  const normalized = normalizeString(raw);
+  if (!normalized) {
+    return {
+      filePath: "",
+      intent: "",
+    };
+  }
+  const separatorMatch = /\s(?:—|–|-)\s/.exec(normalized);
+  if (!separatorMatch) {
+    return {
+      filePath: normalizeString(normalized),
+      intent: "",
+    };
+  }
+  const separatorIndex = Number(separatorMatch.index || 0);
+  return {
+    filePath: normalizeString(normalized.slice(0, separatorIndex)),
+    intent: normalizeString(normalized.slice(separatorIndex + separatorMatch[0].length)),
+  };
+}
+
+function parseSessionDirective(event = {}) {
+  if (normalizeString(event.event) !== "session_message") {
+    return null;
+  }
+  const message = normalizeString(event.payload?.message);
+  if (!message) {
+    return null;
+  }
+  const directive = /^(lock|unlock)\s*:\s*(.+)$/i.exec(message);
+  if (!directive) {
+    return null;
+  }
+  const action = normalizeString(directive[1]).toLowerCase();
+  const body = normalizeString(directive[2]);
+  const parsed = splitFileAndIntent(body);
+  if (!parsed.filePath) {
+    return null;
+  }
+  return {
+    action,
+    filePath: parsed.filePath,
+    intent: parsed.intent,
+  };
+}
+
+async function maybeHandleSessionDirective(daemonState, event) {
+  const agentId = normalizeString(event.agent?.id);
+  if (!agentId || agentId === SENTI_IDENTITY.id) {
+    return null;
+  }
+  const nowIso = normalizeIsoTimestamp(event.ts, new Date().toISOString());
+  const fileDirective = parseSessionDirective(event);
+  if (fileDirective) {
+    if (fileDirective.action === "lock") {
+      const result = await lockFile(
+        daemonState.sessionId,
+        agentId,
+        fileDirective.filePath,
+        {
+          intent: fileDirective.intent,
+          ttlSeconds: DEFAULT_FILE_LOCK_TTL_SECONDS,
+          targetPath: daemonState.targetPath,
+          nowIso,
+        }
+      );
+      if (!result.locked) {
+        await emitSentiEvent(
+          daemonState.sessionId,
+          "daemon_alert",
+          {
+            alert: "file_lock_denied",
+            file: result.file || fileDirective.filePath,
+            requestedBy: agentId,
+            heldBy: result.heldBy || null,
+            since: result.since || null,
+            suggestion: `${fileDirective.filePath} is locked by ${result.heldBy || "another agent"} (${result.since || "recently"}). Coordinate before editing.`,
+          },
+          {
+            targetPath: daemonState.targetPath,
+            nowIso,
+          }
+        );
+      }
+      return result;
+    }
+    if (fileDirective.action === "unlock") {
+      const result = await unlockFile(
+        daemonState.sessionId,
+        agentId,
+        fileDirective.filePath,
+        {
+          reason: "session_message_unlock",
+          targetPath: daemonState.targetPath,
+          nowIso,
+        }
+      );
+      if (!result.unlocked && result.reason === "held_by_other_agent") {
+        await emitSentiEvent(
+          daemonState.sessionId,
+          "daemon_alert",
+          {
+            alert: "file_unlock_denied",
+            file: result.file || fileDirective.filePath,
+            requestedBy: agentId,
+            heldBy: result.heldBy || null,
+            since: result.since || null,
+            suggestion: `${fileDirective.filePath} is locked by ${result.heldBy || "another agent"}. Only the lock holder can release it.`,
+          },
+          {
+            targetPath: daemonState.targetPath,
+            nowIso,
+          }
+        );
+      }
+      return result;
+    }
+  }
+
+  try {
+    return await handleTaskDirective(daemonState.sessionId, event, {
+      targetPath: daemonState.targetPath,
+      nowIso,
+    });
+  } catch (error) {
+    await emitSentiEvent(
+      daemonState.sessionId,
+      "daemon_alert",
+      {
+        alert: "task_directive_error",
+        requestedBy: agentId,
+        reason: normalizeString(error?.message) || "Task directive failed.",
+        message: normalizeString(event.payload?.message) || null,
+      },
+      {
+        targetPath: daemonState.targetPath,
+        nowIso,
+      }
+    );
+    return null;
+  }
+}
+
+async function runSessionDirectiveWatcher(daemonState) {
+  const signal = daemonState.helpAbortController.signal;
+  try {
+    for await (const event of tailStream(daemonState.sessionId, {
+      targetPath: daemonState.targetPath,
+      signal,
+      since: daemonState.startedAt,
+      replayTail: 0,
+      pollMs: 100,
+    })) {
+      if (!daemonState.running) {
+        return;
+      }
+      if (normalizeString(event.event) !== "session_message") {
+        continue;
+      }
+      await maybeHandleSessionDirective(daemonState, event);
+    }
+  } catch (error) {
+    if (error && typeof error === "object" && error.name === "AbortError") {
+      return;
+    }
+    throw error;
+  }
+}
+
 function buildConflictSignature(agentA, agentB, filePath) {
   const pair = [normalizeString(agentA), normalizeString(agentB)].filter(Boolean).sort().join("|");
   return `${pair}::${normalizeString(filePath).replace(/\\/g, "/")}`;
@@ -327,6 +818,12 @@ function createHealthSummaryBase(nowIso, session, agents) {
     staleAgents: [],
     conflictAlerts: [],
     renewed: null,
+    humanMessages: {
+      relayed: 0,
+      dropped: 0,
+      cursor: null,
+      reason: "",
+    },
   };
 }
 
@@ -490,6 +987,66 @@ async function maybeRenewActiveSession(
   };
 }
 
+async function pollAndRelayHumanMessages(
+  daemonState,
+  summary,
+  nowIso = new Date().toISOString()
+) {
+  if (daemonState.humanMessagePollInFlight) {
+    summary.humanMessages.reason = "poll_in_flight";
+    return;
+  }
+
+  daemonState.humanMessagePollInFlight = true;
+  try {
+    const polled = await pollHumanMessages(daemonState.sessionId, {
+      targetPath: daemonState.targetPath,
+      since: daemonState.humanMessageCursor,
+    });
+    if (!polled.ok) {
+      summary.humanMessages.reason = normalizeString(polled.reason) || "poll_failed";
+      summary.humanMessages.cursor = daemonState.humanMessageCursor;
+      return;
+    }
+
+    const relayedEvents = [];
+    for (const event of polled.events || []) {
+      const persisted = await appendToStream(daemonState.sessionId, event, {
+        targetPath: daemonState.targetPath,
+      });
+      relayedEvents.push(persisted);
+    }
+    daemonState.humanMessageCursor = normalizeString(polled.cursor) || daemonState.humanMessageCursor;
+
+    summary.humanMessages.relayed = relayedEvents.length;
+    summary.humanMessages.dropped = Array.isArray(polled.dropped) ? polled.dropped.length : 0;
+    summary.humanMessages.cursor = daemonState.humanMessageCursor;
+    summary.humanMessages.reason = "";
+
+    if (relayedEvents.length > 0) {
+      await emitSentiEvent(
+        daemonState.sessionId,
+        "daemon_alert",
+        {
+          alert: "human_directive_received",
+          relayedCount: relayedEvents.length,
+          droppedCount: summary.humanMessages.dropped,
+        },
+        {
+          targetPath: daemonState.targetPath,
+          nowIso,
+        }
+      );
+    }
+  } catch (error) {
+    summary.humanMessages.reason =
+      normalizeString(error?.message) || "poll_relay_failed";
+    summary.humanMessages.cursor = daemonState.humanMessageCursor;
+  } finally {
+    daemonState.humanMessagePollInFlight = false;
+  }
+}
+
 export async function runSentiHealthTick(
   sessionId,
   {
@@ -522,7 +1079,11 @@ export async function runSentiHealthTick(
       staleAgentSeconds,
       helpRequestTimeoutMs: HELP_REQUEST_TIMEOUT_MS,
       tickIntervalMs: DAEMON_TICK_INTERVAL_MS,
+      recapIntervalMs: DEFAULT_RECAP_INTERVAL_MS_OVERRIDE,
+      recapInactivityMs: DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE,
       helpResponder: null,
+      llmInvoker: invokeViaProxy,
+      telemetrySessionId: null,
     });
   const normalizedNow = normalizeIsoTimestamp(nowIso, new Date().toISOString());
   const activeAgents = await listAgents(normalizedSessionId, {
@@ -542,6 +1103,7 @@ export async function runSentiHealthTick(
   await emitStaleAndRecoveryAlerts(resolvedDaemonState, summary, staleAgents, normalizedNow);
   await emitConflictAlerts(resolvedDaemonState, summary, filteredAgents, normalizedNow);
   await maybeRenewActiveSession(resolvedDaemonState, summary, session, normalizedNow);
+  await pollAndRelayHumanMessages(resolvedDaemonState, summary, normalizedNow);
   return summary;
 }
 
@@ -554,7 +1116,10 @@ export async function startSenti(
     tickIntervalMs = DAEMON_TICK_INTERVAL_MS,
     staleAgentSeconds = DEFAULT_STALE_AGENT_SECONDS,
     helpRequestTimeoutMs = HELP_REQUEST_TIMEOUT_MS,
+    recapIntervalMs = DEFAULT_RECAP_INTERVAL_MS_OVERRIDE,
+    recapInactivityMs = DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE,
     helpResponder = null,
+    llmInvoker = invokeViaProxy,
   } = {}
 ) {
   const normalizedSessionId = normalizeString(sessionId);
@@ -584,7 +1149,16 @@ export async function startSenti(
     staleAgentSeconds,
     DEFAULT_STALE_AGENT_SECONDS
   );
+  const normalizedRecapIntervalMs = normalizePositiveInteger(
+    recapIntervalMs,
+    DEFAULT_RECAP_INTERVAL_MS_OVERRIDE
+  );
+  const normalizedRecapInactivityMs = normalizePositiveInteger(
+    recapInactivityMs,
+    DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE
+  );
   const nowIso = new Date().toISOString();
+  const telemetrySession = startTelemetrySession(`session daemon ${normalizedSessionId}`);
   const daemonState = createSentiState({
     daemonKey,
     sessionId: normalizedSessionId,
@@ -594,7 +1168,11 @@ export async function startSenti(
     staleAgentSeconds: normalizedStaleSeconds,
     helpRequestTimeoutMs: normalizedHelpTimeoutMs,
     tickIntervalMs: normalizedTickIntervalMs,
+    recapIntervalMs: normalizedRecapIntervalMs,
+    recapInactivityMs: normalizedRecapInactivityMs,
     helpResponder,
+    llmInvoker: typeof llmInvoker === "function" ? llmInvoker : invokeViaProxy,
+    telemetrySessionId: telemetrySession?.id || null,
   });
 
   await upsertSentiAgent(normalizedSessionId, {
@@ -661,6 +1239,10 @@ export async function startSenti(
       clearTimeout(timer);
     }
     daemonState.pendingHelpTimers.clear();
+    if (daemonState.recapEmitter && daemonState.recapEmitter.isRunning()) {
+      daemonState.recapEmitter.stop("daemon_stop");
+      daemonState.recapEmitter = null;
+    }
 
     let runtimeStopSummary = null;
     try {
@@ -700,6 +1282,9 @@ export async function startSenti(
       }
     );
     ACTIVE_SENTI_DAEMONS.delete(daemonKey);
+    if (daemonState.telemetrySessionId) {
+      endTelemetrySession({ sessionId: daemonState.telemetrySessionId });
+    }
     return {
       stopped: true,
       daemonKey,
@@ -729,6 +1314,8 @@ export async function startSenti(
       lastTickAt: daemonState.lastTickAt,
       staleAlertedAgents: [...daemonState.staleAlertedAgents],
       pendingHelpRequests: daemonState.pendingHelpTimers.size,
+      recapRunning: Boolean(daemonState.recapEmitter?.isRunning?.()),
+      humanMessageCursor: daemonState.humanMessageCursor,
     }),
   };
 
@@ -736,6 +1323,12 @@ export async function startSenti(
   ACTIVE_SENTI_DAEMONS.set(daemonKey, daemonState);
 
   void runHelpWatcher(daemonState).catch(() => {});
+  void runSessionDirectiveWatcher(daemonState).catch(() => {});
+  daemonState.recapEmitter = emitPeriodicRecap(normalizedSessionId, {
+    targetPath: normalizedTargetPath,
+    intervalMs: daemonState.recapIntervalMs,
+    inactivityMs: daemonState.recapInactivityMs,
+  });
 
   if (autoStart) {
     await runTick(nowIso);
@@ -790,6 +1383,8 @@ export function getSentiDaemon(
 export {
   ACTIVE_SENTI_DAEMONS,
   DAEMON_TICK_INTERVAL_MS,
+  DEFAULT_RECAP_INACTIVITY_MS_OVERRIDE,
+  DEFAULT_RECAP_INTERVAL_MS_OVERRIDE,
   DEFAULT_STALE_AGENT_SECONDS,
   FILE_CONFLICT_WINDOW_MS,
   HELP_REQUEST_TIMEOUT_MS,