mirror-mind 0.33.4 → 0.35.0

package/ts/src/conversation/backfill.ts

@@ -1,20 +1,17 @@
 // Session backfills from runtime-written JSONL (CV22.DS7.US10 slice E).
 //
-// Ports `backfill_pi_sessions` and `backfill_codex_session` from
-// `src/memory/cli/conversation_logger.py`. Both import a closed session the
-// live hooks never saw, through the atomic seam in `sessionImport.ts`, and
-// both are graded against `ts/test/goldens/backfill.golden.json`.
+// Ports `backfill_pi_sessions` from `src/memory/cli/conversation_logger.py`:
+// it imports closed sessions the live hooks never saw, through the atomic
+// seam in `sessionImport.ts`, and is graded against
+// `ts/test/goldens/backfill.golden.json`. (The Codex importer,
+// `backfill_codex_session`, was ported beside it and retired with the
+// v0.32.1 Codex wrapper by CV21.DS4.TS5: its only caller was the wrapper's
+// session-end hook, and the plugin logs Codex turns live.)
 //
-// The two are deliberately NOT unified beyond that seam, because Python's
-// asymmetries are the contract:
-//   * Pi titles through `set_provisional_title` (whitespace collapse plus
-//     `title_source`/`title_status` provenance in metadata); Codex titles
-//     through `_generate_title` and a bare column write with no provenance.
-//   * Pi tolerates a corrupt or structurally invalid file by skipping THAT
-//     file and continuing the walk; Codex gives up on its single file.
-//   * Pi parses every timestamp form (millisecond epoch, string, absent);
-//     Codex stores the raw `timestamp` value and lets the model reject a
-//     missing one.
+// Pi titles through `set_provisional_title` (whitespace collapse plus
+// `title_source`/`title_status` provenance in metadata), tolerates a corrupt
+// or structurally invalid file by skipping THAT file and continuing the
+// walk, and parses every timestamp form (millisecond epoch, string, absent).
 //
 // Nothing here touches a provider or the clock directly: `now` is injected
 // through `LoggerDeps`, which is what makes "no timestamp -> now" pinnable.
@@ -24,12 +21,11 @@
 // home meant the person's whole Pi history, copied and spent on before the
 // first prompt. The floor is explicit (`notBefore`), never defaulted, and
 // the rule fails closed: there is no value that means "everything" except
-// the epoch, which says so. The Codex importer is untouched: it imports the
-// one session the wrapper names, not a history.
+// the epoch, which says so.
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
-import { generateTitle, type LoggerDeps, setProvisionalTitle } from "#conversation/logger.ts";
+import { type LoggerDeps, setProvisionalTitle } from "#conversation/logger.ts";
 import { type ImportedMessage, importClosedConversation } from "#conversation/sessionImport.ts";
 import type { WritableDatabase } from "#db/database.ts";
 import { expandHome } from "#util/paths.ts";
@@ -76,13 +72,6 @@ function getFrom(container: unknown, key: string): unknown {
   return getOr(container, key, undefined);
 }
 
-/** Python truthiness for JSON values: empty containers are falsy too. */
-function pythonTruthy(value: unknown): boolean {
-  if (Array.isArray(value)) return value.length > 0;
-  if (isRecord(value)) return Object.keys(value).length > 0;
-  return Boolean(value);
-}
-
 /** Python `_parse_pi_content`: a string as-is, text blocks joined by `\n`, else `""`. */
 export function parsePiContent(content: unknown): string {
   if (typeof content === "string") return content;
@@ -280,108 +269,3 @@ export function backfillPiSessions(
   }
   return count;
 }
-
-interface CodexParse {
-  sessionId: string | null;
-  messages: { role: string; content: unknown; createdAt: unknown }[];
-}
-
-/**
- * Parse a Codex session file. Throws on the first line that is not valid
- * JSON or not the expected shape; Python's single `try` turns that into
- * "return 0". Values are collected raw: Python validates them only when the
- * import constructs its models.
- */
-function parseCodexSessionFile(path: string): CodexParse {
-  const parsed: CodexParse = { sessionId: null, messages: [] };
-  for (const line of readFileSync(path, "utf8").split(/\r?\n|\r/)) {
-    if (!line.trim()) continue;
-    const entry: unknown = JSON.parse(line);
-    const entryType = getFrom(entry, "type");
-    const payload = getOr(entry, "payload", {});
-    if (entryType === "session_meta") {
-      // Codex writes a UUID string; a non-string id is treated as absent
-      // (the same simplification the hook payloads make).
-      const id = getFrom(payload, "id");
-      parsed.sessionId = typeof id === "string" ? id : null;
-    } else if (entryType === "event_msg") {
-      const payloadType = getFrom(payload, "type");
-      if (payloadType === "user_message" || payloadType === "agent_message") {
-        const content = getOr(payload, "message", "");
-        // Python: `if content:` -- any truthy value is kept and validated later.
-        if (pythonTruthy(content)) {
-          parsed.messages.push({
-            role: payloadType === "user_message" ? "user" : "assistant",
-            content,
-            createdAt: getFrom(entry, "timestamp"),
-          });
-        }
-      }
-    }
-  }
-  return parsed;
-}
-
-export interface CodexBackfillOptions {
-  jsonlPath: string;
-  interface?: string;
-}
-
-/**
- * Python `backfill_codex_session`: import one Codex session file as a closed
- * conversation titled through `_generate_title`. Returns 1 on import, else 0.
- *
- * Throws when a kept event has a non-string `message` or `timestamp`: Python's
- * `Message(...)` model rejects those inside the import transaction, so the
- * database is left untouched and the caller sees the failure.
- */
-export function backfillCodexSession(
-  db: WritableDatabase,
-  options: CodexBackfillOptions,
-  deps: LoggerDeps,
-): number {
-  const jsonlPath = expandHome(options.jsonlPath);
-  if (!existsSync(jsonlPath) || !statSync(jsonlPath).isFile()) return 0;
-
-  let parsed: CodexParse;
-  try {
-    parsed = parseCodexSessionFile(jsonlPath);
-  } catch {
-    return 0;
-  }
-  if (!parsed.sessionId || parsed.messages.length === 0) return 0;
-  if (db.prepare("SELECT 1 FROM runtime_sessions WHERE session_id = ?").get(parsed.sessionId)) {
-    return 0;
-  }
-
-  const messages: ImportedMessage[] = parsed.messages.map((message) => {
-    if (typeof message.content !== "string") {
-      throw new TypeError("Codex event message must be a string");
-    }
-    if (typeof message.createdAt !== "string") {
-      throw new TypeError("Codex event timestamp must be a string");
-    }
-    return { role: message.role, content: message.content, createdAt: message.createdAt };
-  });
-
-  const conversationId = importClosedConversation(
-    db,
-    parsed.sessionId,
-    {
-      interface: options.interface ?? "codex",
-      messages,
-      endedAt: (messages.at(-1) as ImportedMessage).createdAt,
-    },
-    deps,
-  );
-  if (conversationId === null) return 0;
-
-  const firstUser = messages.find((message) => message.role === "user");
-  if (firstUser) {
-    db.prepare("UPDATE conversations SET title = ? WHERE id = ?").run(
-      generateTitle(firstUser.content),
-      conversationId,
-    );
-  }
-  return 1;
-}

package/ts/src/conversation/commandTurn.ts

@@ -0,0 +1,42 @@
+// A command turn: a prompt that opens with a skill invocation, in any runtime's
+// sigil (CV21.DS4.TS3).
+//
+// The prompt hook skips a command turn and records it, so the Stop hook skips
+// its reply too (`command_turn`, CV21.DS2.US8): a skill's rendering -- a
+// journey table, help text -- is not conversation, and extraction reading it
+// as if the person said it is noise. What you say to the mirror is remembered;
+// a skill you invoke is not. The one exception is the Mirror skill's explicit
+// form, whose question IS the conversation turn (`mirrorForm.ts`); the prompt
+// hook checks that form first, and a test holds every Mirror form to be a
+// command turn, so the exception always sits inside this rule.
+//
+// The two sides are deliberately asymmetric:
+//
+//   `/`  skips ANYTHING. Every runtime uses `/` for its own built-ins as well as
+//        for skills (`/hooks`, `/mcp`, `/compact`), so a prompt opening with it
+//        is a command whatever follows. This is the rule US8 inherited.
+//   `$`  skips only a SKILL NAME. `$` is Codex's skill sigil and nothing else
+//        (`$mirror-mind:mm:journeys` through the plugin, DS12.TS2 L10;
+//        `$mm-journeys` through a skills link), and `$5 a month` is English.
+//        The name is lowercase segments -- letters, digits, hyphens, and
+//        underscores after the first letter, since Codex discovers
+//        `~/.codex/skills/<dir>` by directory name -- with an optional
+//        plugin-name prefix joined by `:`, ending at whitespace or the end of
+//        the prompt, the boundary `mirrorForm` draws. A comma is not a boundary
+//        and a leading space is not a prompt start, as ` /help` is not a
+//        command today.
+//
+// One rule for every runtime: a Claude Code user who types `$mm-journeys`,
+// which Claude Code does not understand, is still invoking a skill, and that
+// turn is not conversation either. The rule has one home for every hook that
+// runs in our process (the Claude-family logger, agy's Stop); the Pi
+// extension, a separate process in Pi's file, keeps its own `/` check.
+
+const SKILL_SEGMENT = "[a-z][a-z0-9_-]*";
+const DOLLAR_SKILL_FORM = new RegExp(`^\\$${SKILL_SEGMENT}(?::${SKILL_SEGMENT})*(?=\\s|$)`);
+
+/** Whether the prompt opens with a skill invocation in any runtime's sigil. */
+export function isCommandTurn(prompt: string): boolean {
+  if (prompt.startsWith("/")) return true;
+  return DOLLAR_SKILL_FORM.test(prompt);
+}

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 already closes without extraction at exit and
+// lets 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) 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([]);
   }