@remnic/core 9.3.726 → 9.3.727

package/src/chat/chat-http.ts

@@ -1,5 +1,5 @@
 /**
- * Chat HTTP handler (issue #1583 PR 3).
+ * Chat HTTP handler (issue #1583 PR 3; deferred items #1685 / #1687).
  *
  * Implements the HTTP backend for the admin console Chat pane:
  * - POST /engram/v1/chat/message — send a message, get a reply
@@ -9,41 +9,133 @@
  * Per-session isolation: every request verifies the session's principal
  * matches the caller (rule 42/47).
  *
+ * Deferred items wired here (issues #1685 / #1687):
+ *  - The HTTP message handler delegates to the shared `processChatMessage`
+ *    (Thread 18) so session/engine/transcript construction is identical to
+ *    the MCP surface, instead of re-implementing it.
+ *  - Concurrent identical POSTs are coalesced by an in-flight dedup keyed on
+ *    `memoryDir + chatSessionId + principal + message` so a double-submit
+ *    processes exactly once (issue #1687 Thread 18 / #1685). The memoryDir
+ *    scopes the key per store (AGENTS.md State Scoping); an absent principal
+ *    is encoded distinctly so it can never alias a real principal string.
+ *  - The SSE stream subscribes to live transcript appends and pushes new
+ *    entries to connected clients (issue #1685 item 2 / #1687 Thread 8).
+ *    Subscription is established before the transcript snapshot is read so no
+ *    concurrent append is missed (cursor Bugbot race fix); the burst drains
+ *    the buffer only after switching to live mode so no buffered entry is
+ *    dropped. The disconnect cleanup is registered immediately and guarded
+ *    by a `closed` flag so an early close cannot leak the heartbeat or write
+ *    to an ended response.
+ *
  * This module is imported by access-http.ts with thin route registration —
  * the god-file ratchet (#1520) tracks access-http.ts LOC.
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { createHash } from "node:crypto";
 
 import type { EngramAccessService } from "../access-service.js";
-import type { ChatConfig } from "./chat-types.js";
-import type { ChatTurnResult } from "./chat-types.js";
-import { ChatEngine } from "./chat-engine.js";
-import { isConfirmationMessage } from "./chat-engine.js";
-import { createProductionChatLlmAdapter } from "./chat-llm.js";
-import { createChatExecutor } from "./chat-executor.js";
+import type { ChatConfig, ChatTranscriptEntry, ChatTurnResult } from "./chat-types.js";
+import { processChatMessage } from "./chat-factory.js";
 import {
-  createChatSession,
   loadChatSession,
-  appendTranscriptEntry,
   sessionBelongsToPrincipal,
-  markPendingPlan,
-  markPlanResolved,
-  markPendingPromotion,
-  markPromotionResolved,
+  subscribeChatTranscript,
 } from "./chat-session.js";
 
 export interface ChatHttpHandlerOptions {
   service: EngramAccessService;
   config: ChatConfig | undefined;
   memoryDir: string;
+  /**
+   * Optional hook the host server supplies so the SSE handler can register
+   * its disconnect cleanup with the server's stop() set (cursor Medium
+   * review). Returns an unregister function the handler calls on normal
+   * client disconnect. When omitted, cleanup runs only on req 'close'.
+   */
+  registerSseCleanup?: (cleanup: () => void) => () => void;
 }
 
+// ---------------------------------------------------------------------------
+// In-flight request dedup (issue #1687 Thread 18 / #1685)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pending chat-message promises keyed by
+ * `memoryDir:chatSessionId:principal:messageHash`.  A concurrent identical
+ * POST joins the in-flight promise instead of re-processing (no second LLM
+ * call, no second transcript append).  Entries are always removed via
+ * `finally` so the map cannot leak across requests.
+ *
+ * The memoryDir is part of the key so two Remnic stores in one process
+ * cannot share a promise (AGENTS.md State Scoping).  Only requests targeting
+ * an existing `chatSessionId` are coalesced: when no session id is supplied
+ * each request legitimately mints its own session, so identical message
+ * bodies are genuinely distinct turns.
+ */
+const chatInFlight = new Map<string, Promise<ChatTurnResult>>();
+
+/**
+ * Encode the principal into a fingerprint component where an absent principal
+ * occupies a distinct namespace from any real principal string (control-byte
+ * prefix), so a no-principal request can never coalesce with a request whose
+ * principal is literally `"_"` (or any other string) and reuse its authorized
+ * promise (codex P2 review thread).
+ */
+function principalFingerprintComponent(principal: string | undefined): string {
+  return principal === undefined ? "\x00absent" : `\x01${principal}`;
+}
+
+function chatDedupFingerprint(memoryDir: string, chatSessionId: string, principal: string | undefined, message: string): string {
+  // sha256 keeps the key bounded for long messages; the principal component
+  // is distinct per principal (incl. absent) so two callers targeting the
+  // same session id can never share a result — the wrong principal still
+  // independently hits access_denied inside processChatMessage.
+  const messageHash = createHash("sha256").update(message, "utf8").digest("hex").slice(0, 32);
+  return `${memoryDir}:${chatSessionId}:${principalFingerprintComponent(principal)}:${messageHash}`;
+}
+
+/**
+ * Run `processChatMessage` with concurrent-identical-request coalescing.
+ * Distinct messages (or distinct sessions / principals / stores) never collide.
+ */
+function processChatMessageDedup(opts: {
+  service: EngramAccessService;
+  config: ChatConfig | undefined;
+  memoryDir: string;
+  message: string;
+  chatSessionId?: string;
+  principal?: string;
+}): Promise<ChatTurnResult> {
+  // No session id → no coalescing (each request creates its own session).
+  if (!opts.chatSessionId) {
+    return processChatMessage(opts);
+  }
+  const fp = chatDedupFingerprint(opts.memoryDir, opts.chatSessionId, opts.principal, opts.message);
+  const existing = chatInFlight.get(fp);
+  if (existing) return existing;
+  const pending = processChatMessage(opts).finally(() => {
+    chatInFlight.delete(fp);
+  });
+  chatInFlight.set(fp, pending);
+  return pending;
+}
+
+// ---------------------------------------------------------------------------
+// POST /engram/v1/chat/message
+// ---------------------------------------------------------------------------
+
 /**
  * Handle POST /engram/v1/chat/message.
  *
  * Body: `{ message: string, chatSessionId?: string }`
  * Response: `{ reply: string, chatSessionId: string, pendingPlan?: {...} }`
+ *
+ * Boundary checks (chat-disabled / missing message / no-LLM) run before
+ * delegation so each maps to a precise HTTP status without spinning up a
+ * session.  Session/engine work is delegated to `processChatMessage`
+ * (Thread 18), wrapped in {@link processChatMessageDedup} for double-submit
+ * protection.
  */
 export async function handleChatMessage(
   req: IncomingMessage,
@@ -63,8 +155,7 @@ export async function handleChatMessage(
     return;
   }
 
-  const llm = opts.service.fallbackLlmRef ?? opts.service.localLlmRef;
-  if (!llm) {
+  if (!opts.service.fallbackLlmRef && !opts.service.localLlmRef) {
     respondJson(res, 503, {
       error: "No LLM model is available. Configure a local or cloud model.",
       code: "no_llm",
@@ -72,74 +163,42 @@ export async function handleChatMessage(
     return;
   }
 
-  const adapter = createProductionChatLlmAdapter(llm as {
-    chatCompletion(
-      messages: Array<{ role: string; content: string }>,
-      options?: { model?: string; signal?: AbortSignal },
-    ): Promise<{ content: string } | null>;
-  });
+  const chatSessionId = typeof body.chatSessionId === "string" ? body.chatSessionId : undefined;
 
-  // Load or create session.
-  const requestedSessionId = typeof body.chatSessionId === "string" ? body.chatSessionId : undefined;
-  let session;
-  if (requestedSessionId) {
-    session = await loadChatSession(opts.memoryDir, requestedSessionId);
-    if (!session) {
+  let result: ChatTurnResult;
+  try {
+    result = await processChatMessageDedup({
+      service: opts.service,
+      config: opts.config,
+      memoryDir: opts.memoryDir,
+      message,
+      ...(chatSessionId ? { chatSessionId } : {}),
+      ...(principal ? { principal } : {}),
+    });
+  } catch (err) {
+    // processChatMessage throws tagged errors for the session/LLM/engine
+    // paths; map each back to its HTTP status.  Dedup coalescing means a
+    // concurrent duplicate shares the same rejection.  A 'chat_session_expired'
+    // means the session was swept by the TTL cleanup mid-turn (codex P2) —
+    // tell the client to start a fresh session (410 Gone).
+    const code = err instanceof Error ? err.message : String(err);
+    if (code === "chat_session_not_found") {
       respondJson(res, 404, { error: "chat_session_not_found", code: "chat_session_not_found" });
-      return;
-    }
-    if (!sessionBelongsToPrincipal(session, principal)) {
+    } else if (code === "access_denied") {
       respondJson(res, 403, { error: "access_denied", code: "access_denied" });
-      return;
+    } else if (code === "chat_session_expired") {
+      respondJson(res, 410, { error: "chat_session_expired", code: "chat_session_expired" });
+    } else if (code === "chat_disabled") {
+      respondJson(res, 404, { error: "chat_disabled", code: "chat_disabled" });
+    } else if (code === "no_llm_available" || code === "engine_unavailable") {
+      respondJson(res, 503, {
+        error: "No LLM model is available. Configure a local or cloud model.",
+        code: "no_llm",
+      });
+    } else {
+      respondJson(res, 500, { error: "internal_error", code: "internal_error" });
     }
-  } else {
-    session = await createChatSession(opts.memoryDir, { principal });
-  }
-
-  const executor = createChatExecutor({
-    service: opts.service,
-    principal,
-    ...(session.namespace ? { namespace: session.namespace } : {}),
-    ...(session.sessionKey ? { sessionKey: session.sessionKey } : {}),
-  });
-
-  const engine = new ChatEngine({
-    llm: adapter,
-    executor,
-    maxToolCallsPerTurn: opts.config.maxToolCallsPerTurn,
-    ...(opts.config.model ? { model: opts.config.model } : {}),
-    correctionAvailable: false,
-    scopeInspectAvailable: false,
-  });
-
-  await appendTranscriptEntry(opts.memoryDir, session.id, {
-    role: "user",
-    content: message,
-  });
-
-  // Snapshot pending state BEFORE the turn so we only persist a marker when
-  // state actually changed (Thread 15 — a normal turn must not clear an
-  // active pending plan/promotion from an earlier turn).
-  const priorPendingPlanId = session.pendingPlanId;
-  const priorPendingPromotionId = session.pendingPromotionId;
-
-  const result: ChatTurnResult = await engine.processMessage(message, session);
-
-  await appendTranscriptEntry(opts.memoryDir, session.id, {
-    role: "assistant",
-    content: result.reply,
-  });
-
-  // Persist pending-plan/promotion state (append-only markers). Only append
-  // when state actually changed.
-  if (result.pendingPlan?.planId) {
-    await markPendingPlan(opts.memoryDir, session.id, result.pendingPlan.planId);
-  } else if (session.pendingPromotionId && !priorPendingPromotionId) {
-    await markPendingPromotion(opts.memoryDir, session.id, session.pendingPromotionId);
-  } else if (priorPendingPlanId && !session.pendingPlanId && !result.error) {
-    await markPlanResolved(opts.memoryDir, session.id, priorPendingPlanId);
-  } else if (priorPendingPromotionId && !session.pendingPromotionId && !result.error) {
-    await markPromotionResolved(opts.memoryDir, session.id, priorPendingPromotionId);
+    return;
   }
 
   // Strip internal error details from the wire response (CodeQL — no stack
@@ -150,12 +209,30 @@ export async function handleChatMessage(
   respondJson(res, 200, wireResult);
 }
 
+// ---------------------------------------------------------------------------
+// GET /engram/v1/chat/events/:chatSessionId (SSE)
+// ---------------------------------------------------------------------------
+
 /**
  * Handle GET /engram/v1/chat/events/:chatSessionId.
  *
- * SSE stream.  Sends a heartbeat every 25s so proxies don't time out.
- * Currently streams the session transcript as an initial burst, then keeps
- * the connection open for future updates.
+ * SSE stream.  Sends the existing transcript as an initial burst, then keeps
+ * the connection open and **pushes new transcript entries live** as they are
+ * appended (issue #1685 item 2 / #1687 Thread 8) via the per-session pub/sub
+ * in `chat-session.ts`.  A heartbeat is emitted every 25 s so proxies do not
+ * time out.  A `retry:` directive asks reconnecting clients to wait 5 s, and
+ * because the initial burst always replays the full transcript (entries carry
+ * a strictly-monotonic `seq`), clients dedupe on reconnect — the stream is
+ * reconnect-safe.
+ *
+ * Race-free ordering (cursor Bugbot): the subscription is established BEFORE
+ * the transcript snapshot is read; entries appended concurrently during the
+ * snapshot read are buffered, then the buffer is drained AFTER switching to
+ * live mode (so an append landing between the drain and the mode switch is
+ * never dropped — cursor review). Every write goes through a `closed`-guarded
+ * helper so a disconnect during the burst cannot write to an ended response
+ * (cursor/kilo review). The disconnect cleanup is registered immediately and
+ * guarded by `closed` so an early close cannot leak the heartbeat.
  */
 export async function handleChatEventsSSE(
   req: IncomingMessage,
@@ -169,12 +246,74 @@ export async function handleChatEventsSSE(
     return;
   }
 
+  // Liveness flag + handle, both closed over by the disconnect cleanup. The
+  // cleanup is idempotent (guarded by `closed`) so a repeat close is harmless.
+  let heartbeat: NodeJS.Timeout | undefined;
+  let closed = false;
+  // Every SSE write goes through this helper so a closed connection is never
+  // written to (cursor Low review). Returns false when the write was skipped.
+  const writeSse = (chunk: string): boolean => {
+    if (closed) return false;
+    try {
+      res.write(chunk);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  // Subscribe BEFORE reading the transcript so a concurrent append between
+  // the snapshot read and subscription is never missed (cursor Bugbot race).
+  // During the initial burst entries are buffered; after the burst the
+  // listener switches to writing straight to the response. A `closed` check
+  // short-circuits pushes to a connection that is already gone.
+  const pending: ChatTranscriptEntry[] = [];
+  let bursting = true;
+  const unsubscribe = subscribeChatTranscript(opts.memoryDir, chatSessionId, (entry) => {
+    if (closed) return;
+    if (bursting) {
+      pending.push(entry);
+      return;
+    }
+    writeSse(`data: ${JSON.stringify(entry)}\n\n`);
+  });
+
+  // Register disconnect cleanup IMMEDIATELY so a close during loadChatSession
+  // or the burst still releases the subscription (cursor Bugbot). The flag
+  // gates every later write so the handler never touches an ended response
+  // (kilo review thread) and never sets up a heartbeat for a dead socket
+  // (cursor review thread).
+  const doCleanup = (): void => {
+    closed = true;
+    clearInterval(heartbeat);
+    unsubscribe();
+    try { res.end(); } catch { /* already ended */ }
+  };
+  // Register with the host server's stop() cleanup set (cursor Medium) so an
+  // HTTP shutdown forcibly releases the subscription + heartbeat even when a
+  // lingering client never emits 'close'. Unregistered again on normal close.
+  const unregisterServerCleanup = opts.registerSseCleanup?.(doCleanup) ?? ((): void => {});
+  req.on("close", () => {
+    doCleanup();
+    unregisterServerCleanup();
+  });
+
   const session = await loadChatSession(opts.memoryDir, chatSessionId);
+  // If the client disconnected during the load, cleanup already ran — bail
+  // out before touching the response (prevents "headers after end").
+  if (closed) return;
   if (!session) {
+    // No SSE stream is established — release the server stop() registration
+    // alongside the subscription so sseCleanupFns does not retain a stale
+    // callback for this JSON error response (cursor Medium: error-path leak).
+    unsubscribe();
+    unregisterServerCleanup();
     respondJson(res, 404, { error: "chat_session_not_found", code: "chat_session_not_found" });
     return;
   }
   if (!sessionBelongsToPrincipal(session, principal)) {
+    unsubscribe();
+    unregisterServerCleanup();
     respondJson(res, 403, { error: "access_denied", code: "access_denied" });
     return;
   }
@@ -186,26 +325,42 @@ export async function handleChatEventsSSE(
     connection: "keep-alive",
   });
 
-  // Send the transcript as an initial burst.
+  // Ask reconnecting clients to wait 5 s before retrying (reconnect-safe:
+  // the initial burst below replays the full transcript on rejoin).
+  writeSse("retry: 5000\n\n");
+
+  // Send the transcript snapshot as the initial burst, recording delivered
+  // seqs so buffered concurrent appends are not double-delivered.
+  const deliveredSeqs = new Set<number>();
   for (const entry of session.transcript) {
-    res.write(`data: ${JSON.stringify(entry)}\n\n`);
+    writeSse(`data: ${JSON.stringify(entry)}\n\n`);
+    deliveredSeqs.add(entry.seq);
   }
 
-  // Heartbeat. Unref'd so a lingering connection never blocks process
-  // exit (rule 47 — no shared mutable objects keep the loop alive).
-  const heartbeat = setInterval(() => {
-    try {
-      res.write(`data: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
-    } catch {
-      // Connection closed — clearInterval below.
+  // Switch to live push FIRST, THEN drain buffered appends. Ordering matters:
+  // if an append lands between the drain and the mode switch it would be
+  // buffered (bursting still true) and never re-drained (cursor Medium). With
+  // live mode on, appends during the drain write straight through and the
+  // buffer is emptied once.
+  bursting = false;
+  for (const entry of pending) {
+    if (!deliveredSeqs.has(entry.seq)) {
+      writeSse(`data: ${JSON.stringify(entry)}\n\n`);
     }
-  }, 25_000);
-  heartbeat.unref();
+  }
 
-  req.on("close", () => {
-    clearInterval(heartbeat);
-    try { res.end(); } catch { /* already ended */ }
-  });
+  // Heartbeat. Unref'd so a lingering connection never blocks process
+  // exit (rule 47 — no shared mutable objects keep the loop alive). Cleared
+  // by the close handler above when the client disconnects. Guard against
+  // arming after a disconnect during the burst/drain: the close handler
+  // already ran doCleanup (clearing any prior handle and unregistering the
+  // server callback), so an interval armed here would be untracked and never
+  // cleared — bail out instead (codex P2).
+  if (closed) return;
+  heartbeat = setInterval(() => {
+    writeSse(`data: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
+  }, 25_000);
+  heartbeat.unref?.();
 }
 
 // ---------------------------------------------------------------------------

package/src/chat/chat-session.ts

@@ -7,7 +7,8 @@
  * *about* memories does not create memories of the conversation itself.
  */
 
-import { mkdir, readFile, appendFile, readdir, stat, unlink } from "node:fs/promises";
+import { mkdir, readFile, appendFile, readdir, stat, unlink, open } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
@@ -40,6 +41,26 @@ export function chatSessionFile(memoryDir: string, chatSessionId: string): strin
   return join(chatSessionDir(memoryDir), `${chatSessionId}.jsonl`);
 }
 
+// ---------------------------------------------------------------------------
+// Monotonic transcript seq (issue #1687 review — strictly increasing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Last emitted transcript `seq`. Seeded from `Date.now()` on first use and
+ * incremented when two appends land in the same millisecond, so `seq` is
+ * strictly increasing within a process (review thread: `Date.now()` alone is
+ * not monotonic — same-ms entries would share a seq and break the SSE
+ * reconnect dedup-by-seq contract). Across process restarts `Date.now()` is
+ * already forward-moving, so no collision occurs in practice.
+ */
+let lastTranscriptSeq = 0;
+
+function nextTranscriptSeq(): number {
+  const now = Date.now();
+  lastTranscriptSeq = now > lastTranscriptSeq ? now : lastTranscriptSeq + 1;
+  return lastTranscriptSeq;
+}
+
 /**
  * Create a new chat session.  The session binds the caller's principal and
  * sessionKey at creation (rule 42); every tool call flows through
@@ -169,25 +190,130 @@ export async function loadChatSession(
 
 /**
  * Append a transcript entry to the session file (atomic append, rule 54).
+ *
+ * After the append resolves, in-process subscribers (open SSE connections —
+ * issue #1687) are notified synchronously so live clients receive the new
+ * entry without polling.  Listener errors are swallowed so a misbehaving
+ * subscriber can never break a transcript append (rule 54 — atomic + safe).
  */
 export async function appendTranscriptEntry(
   memoryDir: string,
   chatSessionId: string,
   entry: Omit<ChatTranscriptEntry, "seq" | "ts">,
 ): Promise<ChatTranscriptEntry> {
+  const filePath = chatSessionFile(memoryDir, chatSessionId);
   const full: ChatTranscriptEntry = {
     ...entry,
-    seq: Date.now(),
+    seq: nextTranscriptSeq(),
     ts: new Date().toISOString(),
   };
-  await appendFile(
-    chatSessionFile(memoryDir, chatSessionId),
-    JSON.stringify(full) + "\n",
-    "utf8",
-  );
+  // Atomic resurrection guard (codex P2): open with O_APPEND but WITHOUT
+  // O_CREAT so a session already unlinked by a concurrent TTL sweep fails at
+  // open-time (ENOENT) — there is no stat->appendFile TOCTOU. A headerless
+  // recreation would load with no principal binding and be treated as public
+  // by sessionBelongsToPrincipal. A concurrent unlink during the append is
+  // caught by the post-append re-stat below so the turn fails visibly rather
+  // than writing to an orphaned inode and returning 200.
+  let fh;
+  try {
+    fh = await open(filePath, fsConstants.O_APPEND | fsConstants.O_WRONLY);
+  } catch (err) {
+    // Only ENOENT (session unlinked by a concurrent TTL sweep) maps to
+    // chat_session_expired; real fs errors (EACCES, EMFILE, EISDIR, ...)
+    // are rethrown so the caller surfaces the actual failure (codex P2).
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("chat_session_expired");
+    }
+    throw err;
+  }
+  try {
+    await fh.appendFile(JSON.stringify(full) + "\n", "utf8");
+  } finally {
+    await fh.close();
+  }
+  // Post-append re-check (codex P2): if a concurrent TTL sweep unlinked the
+  // session between open() and here, the append landed on the orphaned inode
+  // and the directory no longer references it. Re-stat the PATH (not the fd)
+  // so the turn fails with chat_session_expired instead of returning 200 with
+  // a reply the client cannot resume. A later sweep unlinking an over-TTL
+  // session is a legitimate TTL action, not a silent loss.
+  try {
+    await stat(filePath);
+  } catch (err) {
+    // Only ENOENT (concurrent TTL unlink) is session expiry; other fs
+    // errors (EACCES, EMFILE, ENOTDIR, ...) are rethrown (codex/kilo P2).
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("chat_session_expired");
+    }
+    throw err;
+  }
+  notifyTranscriptListeners(memoryDir, chatSessionId, full);
   return full;
 }
 
+// ---------------------------------------------------------------------------
+// In-process transcript pub/sub (issue #1687 SSE push)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-session listener sets, keyed by `memoryDir + chatSessionId` so two
+ * memory stores sharing a legacy/imported session id cannot leak transcript
+ * entries to each other (AGENTS.md State Scoping — module-level singletons
+ * are scoped per store).  Kept module-level so appendTranscriptEntry can fan
+ * out new entries to open SSE connections regardless of which caller
+ * appended (HTTP, MCP, or CLI).  Empty sets are pruned so the map never
+ * grows unbounded (rule 47 — no leak).
+ */
+const transcriptListeners = new Map<string, Set<(entry: ChatTranscriptEntry) => void>>();
+
+function transcriptListenerKey(memoryDir: string, chatSessionId: string): string {
+  return `${memoryDir}\x00${chatSessionId}`;
+}
+
+function notifyTranscriptListeners(memoryDir: string, chatSessionId: string, entry: ChatTranscriptEntry): void {
+  const set = transcriptListeners.get(transcriptListenerKey(memoryDir, chatSessionId));
+  if (!set) return;
+  for (const fn of set) {
+    try {
+      fn(entry);
+    } catch {
+      // A listener must never break the append path (rule 54).
+    }
+  }
+}
+
+/**
+ * Subscribe to live transcript entries for a chat session in a given memory
+ * store.  Returns an unsubscribe function that removes the listener and
+ * prunes the session's set when it becomes empty.  Used by the SSE handler
+ * to push new user/assistant entries to connected clients (issue #1687).
+ *
+ * The `memoryDir` scopes the subscription to its store so a process hosting
+ * two Remnic services cannot cross-deliver transcript entries (AGENTS.md
+ * State Scoping).
+ */
+export function subscribeChatTranscript(
+  memoryDir: string,
+  chatSessionId: string,
+  listener: (entry: ChatTranscriptEntry) => void,
+): () => void {
+  const key = transcriptListenerKey(memoryDir, chatSessionId);
+  let set = transcriptListeners.get(key);
+  if (!set) {
+    set = new Set();
+    transcriptListeners.set(key, set);
+  }
+  set.add(listener);
+  return () => {
+    const current = transcriptListeners.get(key);
+    if (!current) return;
+    current.delete(listener);
+    if (current.size === 0) {
+      transcriptListeners.delete(key);
+    }
+  };
+}
+
 /**
  * Append a pending-plan marker so a later turn can confirm the plan
  * (append-only state — loadChatSession scans for the latest unresolved one).
@@ -271,6 +397,16 @@ export async function cleanupExpiredChatSessions(
       // boundary is inclusive; sub-millisecond APFS mtime skew is negligible
       // against an hour-scale threshold (rule 54 — deterministic cleanup).
       if (ttlHours <= 0 || ageHours >= ttlHours) {
+        // Re-check mtime immediately before unlinking so a turn appended
+        // mid-sweep (which refreshes mtime) is not deleted by the stale age
+        // decision captured above (codex P2). ttlHours <= 0 (expire-all)
+        // skips the re-check. The residual microsecond window is a
+        // legitimate sweep of an over-TTL file.
+        if (ttlHours > 0) {
+          const fresh = await stat(filePath);
+          const freshAge = (Date.now() - fresh.mtimeMs) / (1000 * 60 * 60);
+          if (freshAge < ttlHours) continue;
+        }
         await unlink(filePath);
         removed++;
       }

package/src/compat/codex-cli-fallback.ts

@@ -0,0 +1,23 @@
+/**
+ * Deprecated alias subpath `@remnic/core/codex-cli-fallback`.
+ *
+ * PR #1638 renamed `src/codex-cli-fallback.ts` -> `src/cli-fallback.ts` to
+ * graduate the host-prefixed name per CLAUDE.md rule 31 (generic @remnic/core
+ * modules must not carry a host prefix). This thin re-export keeps the old
+ * subpath resolving during the compat window so external consumers importing
+ * `@remnic/core/codex-cli-fallback` do not hit ERR_PACKAGE_PATH_NOT_EXPORTED.
+ * It forwards every export to the canonical module -- no logic is duplicated.
+ *
+ * Removal timeline: v10.0.0 (see issue #1643).
+ * Import from `@remnic/core/cli-fallback` instead.
+ */
+export * from "../cli-fallback.js";
+
+process.emitWarning(
+  "@remnic/core/codex-cli-fallback is a deprecated alias; import from @remnic/core/cli-fallback instead. Removed in v10.0.0 (issue #1643).",
+  {
+    type: "DeprecationWarning",
+    code: "REMNIC_DEP_CORE_SUBPATH_CODEX_CLI_FALLBACK",
+    detail: "PR #1638 renamed codex-cli-fallback.ts to cli-fallback.ts.",
+  },
+);