mirror-mind 0.33.3 → 0.34.0

package/ts/src/conversation/deferredCloseTail.ts

@@ -0,0 +1,154 @@
+// The deferred close tail (CV21.DS4.TS2).
+//
+// A session's close tail is two things: the state writes (`ended_at`, the
+// runtime session inactive, the transcript backfill) and the LLM work
+// (extraction, then title/summary/tags). Some runtimes give a SessionEnd hook
+// less time than one model call: Codex runs it synchronously under a 1 s
+// default (DS12.TS2 L2; DS2's live `/hooks` table), Grok under 1.5 s
+// (DS12.TS4). Pi and Gemini CLI already close without extraction at exit and
+// let the next session start extract (`session-end-pi`). On a runtime that
+// bounds the hook, the shared Claude-family `session-end` does the same, and a
+// little more: it also skips the metadata finalization, and flags the
+// conversation so the next start's maintenance finishes it.
+//
+// The flag lives in `conversations.metadata` beside `extracted`,
+// `extraction_status`, and `extraction_quarantined`: same table, same
+// `json_extract` predicate, no migration. It is written and cleared through
+// the two helpers here and nowhere else, read-modify-write on the blob, and
+// cleared by deleting the key: the sibling predicates read `IS 1`/`IS NOT 1`,
+// and a `false` left behind is noise every later reader has to think about.
+//
+// The maintenance step runs AFTER `extractPending`, so a conversation's stored
+// summary is kept by `finalizeMetadataOnClose` ("summary already exists")
+// rather than generated twice, and takes only conversations already extracted
+// or ineligible for extraction: one still waiting on the extraction budget is
+// left, flag intact, so finalization never precedes its extraction. It is
+// bounded like its siblings (`RETITLE_LIMIT`, the extraction budget), FIFO by
+// `ended_at`, and carries the rest over. Two runtimes started at once both run
+// maintenance with no lock and can both pick the same conversation; that race
+// is `extractPending`'s and `retitlePending`'s today, and is not solved here.
+
+import { metadataDict } from "#conversation/closeTail.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+
+// The policy that decides which runtimes defer the tail lives in
+// `runtimePolicy.ts` (`sessionEndRunsLlmTail`), beside its sibling for sessions
+// that outlive the TUI (US4).
+
+export const CLOSE_TAIL_PENDING_KEY = "close_tail_pending";
+
+/** The sibling budgets: extraction 10 per run, retitle 5. Finalization is up to three calls. */
+export const DEFERRED_CLOSE_TAIL_LIMIT = 5;
+
+function readMetadata(
+  db: WritableDatabase,
+  conversationId: string,
+): Record<string, unknown> | null {
+  const row = db.prepare("SELECT metadata FROM conversations WHERE id = ?").get(conversationId);
+  if (!row) return null;
+  return metadataDict(typeof row.metadata === "string" ? row.metadata : null);
+}
+
+function writeMetadata(
+  db: WritableDatabase,
+  conversationId: string,
+  metadata: Record<string, unknown>,
+): void {
+  db.prepare("UPDATE conversations SET metadata = ? WHERE id = ?").run(
+    pythonJsonDumps(metadata),
+    conversationId,
+  );
+}
+
+/** Flag the conversation as owing its finalization. A missing conversation is left alone. */
+export function markCloseTailPending(db: WritableDatabase, conversationId: string): void {
+  const metadata = readMetadata(db, conversationId);
+  if (metadata === null) return;
+  metadata[CLOSE_TAIL_PENDING_KEY] = true;
+  writeMetadata(db, conversationId, metadata);
+}
+
+/** Clear the flag by deleting the key, never by writing `false`. */
+export function clearCloseTailPending(db: WritableDatabase, conversationId: string): void {
+  const metadata = readMetadata(db, conversationId);
+  if (metadata === null || !(CLOSE_TAIL_PENDING_KEY in metadata)) return;
+  delete metadata[CLOSE_TAIL_PENDING_KEY];
+  writeMetadata(db, conversationId, metadata);
+}
+
+export function isCloseTailPending(db: WritableDatabase, conversationId: string): boolean {
+  return readMetadata(db, conversationId)?.[CLOSE_TAIL_PENDING_KEY] === true;
+}
+
+const PENDING_WHERE = `
+  WHERE c.ended_at IS NOT NULL
+    AND json_extract(c.metadata, '$.${CLOSE_TAIL_PENDING_KEY}') IS 1
+`;
+
+/**
+ * Already extracted, or not eligible for extraction (the orchestration's own
+ * gate: a journey and four messages), so finalization follows extraction and
+ * never precedes it.
+ */
+const READY_WHERE = `
+    AND (json_extract(c.metadata, '$.extracted') IS 1
+         OR c.journey IS NULL
+         OR (SELECT COUNT(*) FROM messages m WHERE m.conversation_id = c.id) < 4)
+`;
+
+export interface DeferredCloseTail {
+  id: string;
+  endedAt: string;
+}
+
+/** Flagged conversations ready to finalize, oldest-ended first, bounded. */
+export function selectDeferredCloseTails(
+  db: WritableDatabase,
+  limit: number | null,
+): DeferredCloseTail[] {
+  const base = `SELECT c.id, c.ended_at FROM conversations c${PENDING_WHERE}${READY_WHERE}ORDER BY c.ended_at ASC`;
+  const rows = limit === null ? db.prepare(base).all() : db.prepare(`${base} LIMIT ?`).all(limit);
+  return rows.map((row) => ({ id: String(row.id), endedAt: String(row.ended_at) }));
+}
+
+/** Every flagged conversation, ready or not, and the oldest: what `runtime diagnose` reads. */
+export function countDeferredCloseTails(db: WritableDatabase): {
+  count: number;
+  oldestEndedAt: string | null;
+} {
+  const row = db
+    .prepare(`SELECT COUNT(*) AS n, MIN(c.ended_at) AS oldest FROM conversations c${PENDING_WHERE}`)
+    .get();
+  const count = Number(row?.n ?? 0);
+  return { count, oldestEndedAt: count > 0 && row?.oldest ? String(row.oldest) : null };
+}
+
+export interface FinishDeferredCloseTailsDeps {
+  /** The close-time finalization (title, summary, tags). Throwing is isolated. */
+  finalizeCloseTail: (db: WritableDatabase, conversationId: string) => Promise<void> | void;
+  limit?: number;
+}
+
+/**
+ * The maintenance step: finalize each ready, flagged conversation and clear
+ * its flag. A finalization that throws leaves its flag for the next run and
+ * does not stop the loop. Returns how many were finished.
+ */
+export async function finishDeferredCloseTails(
+  db: WritableDatabase,
+  deps: FinishDeferredCloseTailsDeps,
+): Promise<number> {
+  const limit = deps.limit ?? DEFERRED_CLOSE_TAIL_LIMIT;
+  let count = 0;
+  for (const tail of selectDeferredCloseTails(db, limit)) {
+    try {
+      await deps.finalizeCloseTail(db, tail.id);
+    } catch {
+      continue;
+    }
+    clearCloseTailPending(db, tail.id);
+    count += 1;
+  }
+  return count;
+}

package/ts/src/conversation/logger.ts

@@ -12,6 +12,8 @@
 
 import { closeSync, existsSync, mkdirSync, openSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { isCommandTurn } from "#conversation/commandTurn.ts";
+import { markCloseTailPending } from "#conversation/deferredCloseTail.ts";
 import {
   lastAssistantMessageOf,
   parseHookPayloadObject,
@@ -20,6 +22,7 @@ import {
   subagentTypeOf,
   turnIdOf,
 } from "#conversation/hookPayload.ts";
+import { sessionEndRunsLlmTail } from "#conversation/runtimePolicy.ts";
 import { backfillAssistantMessages } from "#conversation/transcriptBackfill.ts";
 import { type WritableDatabase, withTransaction } from "#db/database.ts";
 import { mirrorForm } from "#mirror/mirrorForm.ts";
@@ -146,7 +149,12 @@ export function getOrCreateSessionConversation(
     const boundId =
       bound && typeof bound.conversation_id === "string" ? bound.conversation_id : null;
     if (boundId) {
-      const existing = db.prepare("SELECT id FROM conversations WHERE id = ?").get(boundId);
+      // Live: exists and not ended. A closed conversation is not reopened by a
+      // prompt (CV21.DS4.US4): a `codex resume` after the idle close starts a new
+      // one on the same thread id rather than appending to an extracted one.
+      const existing = db
+        .prepare("SELECT id FROM conversations WHERE id = ? AND ended_at IS NULL")
+        .get(boundId);
       if (existing) return boundId;
     }
 
@@ -318,17 +326,39 @@ function startConversation(
  * finalization in a `finally`. Duplicating that contract in a second async
  * close path would let the two drift on exactly the property that must not.
  */
+export interface CloseTailOptions {
+  extract: boolean;
+  /**
+   * Run the close-time metadata finalization (title, summary, tags). Off, there
+   * is no LLM work at all: the conversation is flagged as owing it, immediately
+   * before `ended_at` so the window against a still-running async Stop logger's
+   * metadata write is microseconds, and the next session start's maintenance
+   * finishes it (CV21.DS4.TS2, `deferredCloseTail.ts`). Default on.
+   */
+  finalize?: boolean;
+  /**
+   * Runs after the state writes and before any LLM work: where `endSession`
+   * deactivates the session and `handleSessionEndHook` backfills the
+   * transcript, which the close bounds and extraction should see.
+   */
+  beforeTail?: () => void;
+}
+
 export async function endConversation(
   db: WritableDatabase,
   conversationId: string,
-  options: { extract: boolean },
+  options: CloseTailOptions,
   deps: LoggerDeps,
   hooks: CloseHooks = {},
 ): Promise<void> {
+  const finalize = options.finalize ?? true;
+  if (!finalize) markCloseTailPending(db, conversationId);
   db.prepare("UPDATE conversations SET ended_at = ? WHERE id = ?").run(
     deps.nowIso(),
     conversationId,
   );
+  options.beforeTail?.();
+  if (!finalize) return;
   try {
     if (options.extract) await hooks.runExtraction?.(db, conversationId);
   } finally {
@@ -383,19 +413,43 @@ export async function switchConversation(
   return newConversationId;
 }
 
-/** Python `end_session`: close the bound conversation and deactivate. */
+/**
+ * Python `end_session`: close the bound conversation and deactivate.
+ *
+ * The session is deactivated BEFORE the tail, not after (CV21.DS4.TS2). A tail
+ * cut by the runtime's bound (Codex 1 s, Grok 1.5 s, Gemini CLI 30 s) or a
+ * background hook that dies used to leave the session `active = 1`: the row
+ * `guessRuntimeSessionId` reads as "the session", which is how another
+ * runtime's agent wrote into a Codex conversation (DS12.TS2 L9).
+ */
 export async function endSession(
   db: WritableDatabase,
   sessionId: string,
-  options: { extract: boolean },
+  options: CloseTailOptions,
   deps: LoggerDeps,
   hooks: CloseHooks = {},
-): Promise<void> {
+): Promise<boolean> {
   const runtimeSession = getRuntimeSession(db, sessionId);
   const conversationId = runtimeSession?.conversationId ?? null;
-  if (!conversationId) return;
-  await endConversation(db, conversationId, { extract: options.extract }, deps, hooks);
-  upsertRuntimeSession(db, sessionId, { active: false, closedAt: deps.nowIso() }, deps.nowIso());
+  if (!conversationId) return false;
+  // A closed conversation is not closed twice (CV21.DS4.US4): Codex 0.163.0 fires
+  // SessionEnd when its daemon reaps the detached thread, and maintenance may have
+  // closed the idle conversation first. The session is deactivated; ended_at and
+  // the tail are left as they are.
+  const alreadyEnded = db
+    .prepare("SELECT 1 FROM conversations WHERE id = ? AND ended_at IS NOT NULL")
+    .get(conversationId);
+  if (alreadyEnded) {
+    upsertRuntimeSession(db, sessionId, { active: false, closedAt: deps.nowIso() }, deps.nowIso());
+    options.beforeTail?.();
+    return true;
+  }
+  const deactivate = () => {
+    upsertRuntimeSession(db, sessionId, { active: false, closedAt: deps.nowIso() }, deps.nowIso());
+    options.beforeTail?.();
+  };
+  await endConversation(db, conversationId, { ...options, beforeTail: deactivate }, deps, hooks);
+  return true;
 }
 
 /**
@@ -479,7 +533,7 @@ export type UserPromptHookOutcome =
         | "malformed_payload"
         | "missing_session"
         | "missing_prompt"
-        | "slash_command"
+        | "command_turn"
         | "bare_mirror_form";
     }
   | { action: "logged"; sessionId: string }
@@ -564,7 +618,8 @@ function recordSkippedTurn(
  * Grok session whose first turn was a Mirror turn used to be labelled
  * `claude_code` and bound to someone else's session (DS12.TS4 L7, TS2 L9).
  * And a Mirror turn is a conversation turn: its question is logged without
- * the form, where every other slash command stays a command.
+ * the form, where every other skill invocation, in `/` or in Codex's `$`
+ * (CV21.DS4.TS3), stays a command.
  */
 export function handleUserPromptHook(
   db: WritableDatabase,
@@ -594,11 +649,12 @@ export function handleUserPromptHook(
         return { action: "skipped", reason: "bare_mirror_form" };
       }
       content = mirror.query;
-    } else if (prompt.startsWith("/")) {
-      // Slash commands never enter conversation history, and neither does
-      // their reply: the turn is recorded so the Stop hook knows why.
+    } else if (isCommandTurn(prompt)) {
+      // A skill invocation, in `/` or in Codex's `$` (CV21.DS4.TS3), never
+      // enters conversation history, and neither does its reply: the turn is
+      // recorded so the Stop hook knows why.
       recordSkippedTurn(db, sessionId, turnIdOf(payload), deps);
-      return { action: "skipped", reason: "slash_command" };
+      return { action: "skipped", reason: "command_turn" };
     }
 
     logUserMessage(
@@ -785,7 +841,13 @@ export function handleStopHook(
 export async function handleSessionEndHook(
   db: WritableDatabase,
   rawPayload: string,
-  options: { mirrorHome: string; claudeProjectDir: string | null; homeDir: string },
+  options: {
+    mirrorHome: string;
+    claudeProjectDir: string | null;
+    homeDir: string;
+    /** The runtime the hook detected: the fallback when the session row has no label. */
+    interface?: string;
+  },
   deps: LoggerDeps,
   hooks: CloseHooks = {},
 ): Promise<SessionEndHookOutcome> {
@@ -794,19 +856,41 @@ export async function handleSessionEndHook(
     if (!payload) return { action: "skipped", reason: "malformed_payload" };
 
     const sessionId = payloadString(payload, "session_id");
-    if (sessionId) await endSession(db, sessionId, { extract: true }, deps, hooks);
-
     const transcriptPath = resolveTranscriptPath(
       payloadString(payload, "transcript_path"),
       sessionId,
       options.claudeProjectDir,
       options.homeDir,
     );
-    const backfilled = transcriptPath !== null && existsSync(transcriptPath);
-    if (backfilled) backfillAssistantMessages(db, transcriptPath, deps);
+    let backfilled = false;
+    // After the close, which bounds the backfill window, and before the tail,
+    // which should see what the backfill adds (CV21.DS4.TS2).
+    const backfill = () => {
+      backfilled = transcriptPath !== null && existsSync(transcriptPath);
+      if (backfilled && transcriptPath !== null)
+        backfillAssistantMessages(db, transcriptPath, deps);
+    };
+
+    if (sessionId) {
+      // The label US8 stamps on every prompt; the hook's own detection only when
+      // the row carries none; today's behavior when neither names a runtime.
+      const label = getRuntimeSession(db, sessionId)?.interface || options.interface || null;
+      const finalize = sessionEndRunsLlmTail(label);
+      const closed = await endSession(
+        db,
+        sessionId,
+        { extract: finalize, finalize, beforeTail: backfill },
+        deps,
+        hooks,
+      );
+      // A session with no bound conversation closes nothing; the backfill still runs.
+      if (!closed) backfill();
+    } else {
+      backfill();
+    }
 
     if (sessionId) return { action: "ended", sessionId, transcriptPath, backfilled };
-    if (backfilled) return { action: "backfilled", transcriptPath };
+    if (backfilled && transcriptPath !== null) return { action: "backfilled", transcriptPath };
     return { action: "skipped", reason: "nothing_to_do" };
   } catch (error) {
     return { action: "failed", error: error instanceof Error ? error.message : String(error) };

package/ts/src/conversation/loggerCli.ts

@@ -15,7 +15,6 @@
 // needs the dated zip backup from the runtime (CV22.DS7.TS1) and refuses, like
 // Python, when it is not available.
 
-import { backfillCodexSession } from "#conversation/backfill.ts";
 import { diagnoseJourneyAssociations, renderJourneyFindings } from "#conversation/journeyRepair.ts";
 import {
   discardCurrentConversation,
@@ -64,7 +63,6 @@ export const CONVERSATION_LOGGER_SUBCOMMANDS = [
   "session-maintenance",
   "diagnose-journeys",
   "repair-journeys",
-  "backfill-codex-session",
 ] as const;
 
 /** The subcommands whose Python path runs `end_conversation`'s LLM close tail. */
@@ -189,7 +187,10 @@ export async function runConversationLoggerCommand(
       }
     }
 
-    case "session-end":
+    case "session-end": {
+      // `--interface`, as `stop` takes it: the hook's own detection, used only
+      // when the session row carries no label (CV21.DS4.TS2).
+      const interfaceName = extractOption(args.slice(1), "--interface").value ?? undefined;
       await handleSessionEndHook(
         db,
         context.stdin ?? "",
@@ -197,11 +198,13 @@ export async function runConversationLoggerCommand(
           mirrorHome: home,
           claudeProjectDir: runtime.claudeProjectDir,
           homeDir: runtime.homeDir,
+          interface: interfaceName,
         },
         deps,
         await runtime.closeHooks(),
       );
       return ok([]);
+    }
 
     case "log-user":
     case "log-assistant": {
@@ -300,21 +303,6 @@ export async function runConversationLoggerCommand(
       return ok(lines);
     }
 
-    case "backfill-codex-session": {
-      if (args.length < 2) return ok([]);
-      const path = args[1] as string;
-      const count = backfillCodexSession(
-        db,
-        { jsonlPath: path, interface: interfaceOption(args, "codex") },
-        deps,
-      );
-      return ok([
-        count
-          ? `Backfilled 1 Codex session from ${path}`
-          : `No new Codex session backfilled from ${path}`,
-      ]);
-    }
-
     default:
       return ok([]);
   }

package/ts/src/conversation/loggerRuntime.ts

@@ -7,7 +7,7 @@
 // that cross the LLM close tail -- the replay providers and the maintenance
 // dependencies built on them.
 //
-// The providers are loaded lazily. `diagnose-journeys`, `backfill-codex-session`,
+// The providers are loaded lazily. `diagnose-journeys`
 // or `session-start --fast` must never fail because a replay fixture is not
 // configured, and `switch` or `session-end` must fail loudly (and fall back
 // to Python at the routing layer) when it is not: "unconfigured installs keep
@@ -29,6 +29,7 @@ import {
   resolveExtractionMaxAttempts,
   resolveExtractionModel,
   resolveMaintenanceMaxExtractions,
+  resolveStaleOrphanMinutes,
   resolveSummarizeEnabled,
   resolveTwoPassEnabled,
 } from "#providers/config.ts";
@@ -242,6 +243,9 @@ export function createLoggerRuntime(options: LoggerRuntimeOptions): LoggerRuntim
             source: "startup_maintenance",
           }),
         runExtraction,
+        // CV21.DS4.TS2: the finalization a bounded runtime's SessionEnd deferred.
+        finalizeCloseTail: (database, conversationId) =>
+          hooks.finalizeMetadata(database, conversationId),
         // CR121: only the sessions newer than this home; its birth is read from
         // the ledger once per maintenance run, and an unknown birth is an error.
         backfillPiSessions: (database) =>
@@ -251,6 +255,7 @@ export function createLoggerRuntime(options: LoggerRuntimeOptions): LoggerRuntim
             deps,
           ),
         extractionLimit: resolveMaintenanceMaxExtractions({ env }),
+        staleOrphanMinutes: resolveStaleOrphanMinutes({ env }),
         monotonic: options.monotonic,
         now: deps.nowIso,
       };

package/ts/src/conversation/runtimePolicy.ts

@@ -0,0 +1,50 @@
+// What a runtime's session lifecycle lets Mirror do at its edges, by the label
+// US8 stamps on the session row (`claude_code`, `codex`, `grok_build`). One home
+// for the two policies the close path reads (CV21.DS4.TS2, US4).
+
+/**
+ * Whether a runtime's SessionEnd hook has the time to run the LLM tail at exit
+ * (CV21.DS4.TS2). Measured bounds, with the evidence:
+ *
+ *   claude_code  the plugin registers the hook `async`; Claude Code runs it in
+ *                the background after exit, unbounded by the user's wait.
+ *   codex        synchronous ("running async SessionEnd hook synchronously",
+ *                DS12.TS2 L2), 1 s for a handler with no `timeout` (DS2's live
+ *                `/hooks` table, 2026-10-13, Codex 0.162.1).
+ *   grok_build   1.5 s for a handler with no `timeout` (DS12.TS4, Grok 1.0.52).
+ *                DS10 re-measures it and may flip this entry.
+ *
+ * Any other label, and no label, keeps today's behavior: the tail runs.
+ */
+export function sessionEndRunsLlmTail(interfaceName: string | null | undefined): boolean {
+  switch (interfaceName) {
+    case "codex":
+    case "grok_build":
+      return false;
+    default:
+      return true;
+  }
+}
+
+/**
+ * Whether a runtime's session outlives its TUI, so that `active = 1` on the
+ * session row means RESUMABLE rather than attended (CV21.DS4.US4).
+ *
+ *   codex        0.163.0: `/quit` and Ctrl-D print "Disconnected from this task.
+ *                Any running work continues. To reconnect, run: codex resume
+ *                <id>". The thread persists in the shared app-server daemon, and
+ *                SessionEnd does not fire at TUI exit: Codex's own log shows no
+ *                hook started after the last turn, and a probe hook pair recorded
+ *                nothing on either quit path (US4's probe, 2026-10-17). On 0.162.1,
+ *                four days earlier, `/quit` ended the session and SessionEnd fired
+ *                (DS2). The session is still re-measured by the next story that
+ *                depends on it.
+ *
+ * For such a runtime, an open conversation idle past the orphan threshold is an
+ * orphan even while its session is active, and the close deactivates the session
+ * (`closeStaleOrphans`). Every other runtime's session ends with its TUI, and an
+ * active session there means a person who may still be typing.
+ */
+export function sessionOutlivesTui(interfaceName: string | null | undefined): boolean {
+  return interfaceName === "codex";
+}

package/ts/src/conversation/sessionComposites.ts

@@ -16,6 +16,7 @@
 // report still fails. Freezing real timings would have faked the evidence
 // instead of isolating it.
 
+import { finishDeferredCloseTails } from "#conversation/deferredCloseTail.ts";
 import {
   countCarriedOverConversations,
   countConversationsWithExtractionStatus,
@@ -23,6 +24,7 @@ import {
   extractPending,
 } from "#conversation/extractionDriver.ts";
 import { setMute } from "#conversation/logger.ts";
+import { sessionOutlivesTui } from "#conversation/runtimePolicy.ts";
 import type { WritableDatabase } from "#db/database.ts";
 import { GLOBAL_STICKY_DEFAULTS_SESSION_ID } from "#mirror/runtimeSession.ts";
 import { deactivateOperatingMode } from "#mode/operatingMode.ts";
@@ -40,6 +42,12 @@ export interface MaintenanceDeps {
   retitleConversation: (db: WritableDatabase, conversationId: string) => Promise<boolean> | boolean;
   /** The DS5 orchestration behind replay with its accounting, as the driver injects it. */
   runExtraction: (db: WritableDatabase, conversationId: string) => Promise<void> | void;
+  /**
+   * The close-time finalization (title, summary, tags) for a conversation a
+   * bounded runtime's SessionEnd closed without it (CV21.DS4.TS2). Optional
+   * only for callers written before the step existed; the front door wires it.
+   */
+  finalizeCloseTail?: (db: WritableDatabase, conversationId: string) => Promise<void> | void;
   /**
    * `backfillPiSessions` (slice E) bound to its resolved sessions directory.
    * Injected rather than resolved here so the composite never reads the
@@ -48,6 +56,8 @@ export interface MaintenanceDeps {
   backfillPiSessions: (db: WritableDatabase) => Promise<number> | number;
   /** Python's `MEMORY_MAINTENANCE_MAX_EXTRACTIONS` (AI-05); defaults to the released budget. */
   extractionLimit?: number;
+  /** `MIRROR_STALE_ORPHAN_MINUTES` (CV21.DS4.US4); defaults to the 30-minute threshold. */
+  staleOrphanMinutes?: number;
   /** Monotonic seconds, injected so report timings are pinnable. */
   monotonic?: () => number;
   now?: () => string;
@@ -64,14 +74,38 @@ export function resetSessionOrientation(db: WritableDatabase, now: () => string
   );
 }
 
-/** Conversation ids bound to an active runtime session. */
-function activeConversationIds(db: WritableDatabase): Set<string> {
+/**
+ * Conversation ids bound to an ATTENDED active runtime session: one whose
+ * runtime ends the session with its TUI, so `active = 1` means a person may
+ * still be typing. A runtime whose session outlives the TUI (Codex 0.163.0,
+ * `runtimePolicy.ts`) is left out: there `active` means resumable, and an idle
+ * conversation is an orphan like any other (CV21.DS4.US4).
+ */
+function attendedConversationIds(db: WritableDatabase): Set<string> {
   const rows = db
     .prepare(
-      "SELECT conversation_id FROM runtime_sessions WHERE active = 1 AND conversation_id IS NOT NULL",
+      "SELECT conversation_id, interface FROM runtime_sessions WHERE active = 1 AND conversation_id IS NOT NULL",
     )
     .all() as Record<string, unknown>[];
-  return new Set(rows.map((row) => String(row.conversation_id)));
+  return new Set(
+    rows
+      .filter(
+        (row) => !sessionOutlivesTui(typeof row.interface === "string" ? row.interface : null),
+      )
+      .map((row) => String(row.conversation_id)),
+  );
+}
+
+/**
+ * The runtime sessions still active on a conversation just closed as an orphan:
+ * marked inactive with `closed_at`, so `guessRuntimeSessionId` stops reading
+ * them as "the session" (DS12.TS2 L9's class), and a later prompt on the same
+ * id binds a new conversation.
+ */
+function deactivateSessionsOf(db: WritableDatabase, conversationId: string, now: string): void {
+  db.prepare(
+    "UPDATE runtime_sessions SET active = 0, closed_at = ?, updated_at = ? WHERE conversation_id = ? AND active = 1",
+  ).run(now, now, conversationId);
 }
 
 /** Python's `get_open_conversations_idle_since`. */
@@ -91,7 +125,10 @@ function openConversationsIdleSince(db: WritableDatabase, threshold: string): st
 
 /**
  * Python's `close_stale_orphans`: end open conversations idle longer than the
- * threshold, skipping any still bound to an active runtime session.
+ * threshold, skipping any still bound to an attended active runtime session
+ * (`attendedConversationIds`). Since CV21.DS4.US4 a session on a runtime that
+ * outlives its TUI does not protect its conversation, and the close
+ * deactivates every session the orphan was bound to.
  *
  * The count increments even when closing raises: `ended_at` is written before
  * the tail, so the orphan IS closed and an extraction failure must not stop the
@@ -109,15 +146,16 @@ export async function closeStaleOrphans(
   const now = deps.now ?? nowIso;
   const threshold = new Date(Date.parse(now()) - thresholdMinutes * 60_000).toISOString();
 
-  const active = activeConversationIds(db);
+  const attended = attendedConversationIds(db);
   let count = 0;
   for (const conversationId of openConversationsIdleSince(db, threshold)) {
-    if (active.has(conversationId)) continue;
+    if (attended.has(conversationId)) continue;
     try {
       await deps.closeConversation(db, conversationId);
     } catch {
       // The orphan is closed regardless; a failed tail must not stop the loop.
     }
+    deactivateSessionsOf(db, conversationId, now());
     count += 1;
   }
   return count;
@@ -142,6 +180,8 @@ export async function retitlePendingConversations(
         `SELECT c.id
            FROM conversations c
           WHERE c.ended_at IS NOT NULL
+            -- Owed its deferred finalization, which titles it later this run (CV21.DS4.US4).
+            AND (c.metadata IS NULL OR json_extract(c.metadata, '$.close_tail_pending') IS NOT 1)
             AND EXISTS (SELECT 1 FROM messages m WHERE m.conversation_id = c.id AND m.role = 'user')
             AND EXISTS (SELECT 1 FROM messages m WHERE m.conversation_id = c.id AND m.role = 'assistant')
           ORDER BY c.ended_at DESC, c.started_at DESC
@@ -203,7 +243,7 @@ export async function sessionMaintenance(
       closeStaleOrphans(db, {
         closeConversation: deps.closeConversation,
         now: deps.now,
-        thresholdMinutes: STALE_ORPHAN_THRESHOLD_MINUTES,
+        thresholdMinutes: deps.staleOrphanMinutes ?? STALE_ORPHAN_THRESHOLD_MINUTES,
       }),
     ),
     await timedStep("Backfilled Pi sessions", monotonic, () => deps.backfillPiSessions(db)),
@@ -213,6 +253,12 @@ export async function sessionMaintenance(
     await timedStep("Extracted pending conversations", monotonic, () =>
       extractPending(db, { runExtraction: deps.runExtraction, limit: deps.extractionLimit }),
     ),
+    // After extraction, so a stored summary is kept rather than generated twice.
+    await timedStep("Finished deferred close tails", monotonic, () =>
+      deps.finalizeCloseTail
+        ? finishDeferredCloseTails(db, { finalizeCloseTail: deps.finalizeCloseTail })
+        : 0,
+    ),
   ];
 
   const parts = ["Conversation maintenance complete."];