mirror-mind 0.33.4 → 0.34.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "mirror-mind",
+  "owner": {
+    "name": "Mirror Mind"
+  },
+  "plugins": [
+    {
+      "name": "mirror-mind",
+      "source": {
+        "source": "local",
+        "path": "./plugins/mirror-mind"
+      },
+      "description": "Mirror Mind — local-first memory and identity for agentic runtimes."
+    }
+  ]
+}

package/AGENTS.md

@@ -18,10 +18,10 @@ The mirror operates in four modes, chosen automatically based on context:
 Mirror, Builder, Explorer, and Soul.
 
 Each skill below is named three ways: `/mm-<skill>` in Pi and Gemini CLI,
-`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A Claude Code **plugin**
-install prefixes the plugin's name — `/mirror-mind:mm:<skill>` in the menu,
-`mirror-mind:mm-<skill>` as the skill's own name — and the forms below refer to
-the same skill.
+`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A **plugin** install
+prefixes the plugin's name — `/mirror-mind:mm:<skill>` in Claude Code's menu,
+`$mirror-mind:mm:<skill>` in Codex, `mirror-mind:mm-<skill>` as the skill's own
+name — and the forms below refer to the same skill.
 
 **Mirror Mode** — activate for: life decisions, feelings, business strategy,
 writing, mentoring, health, existential questions, sensemaking, psychological

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.34.0 — Codex Through the Canonical Plugin](v0.34.0.md) — minor release closing CV21.DS4: Codex runs Mirror through the canonical plugin, installed in two commands from a marketplace the package ships, measured live at L4 on Codex 0.163.0. The v0.32.1 wrapper wiring no longer ships; `runtime diagnose` and `runtime update` say when Codex's cached plugin copy is behind and name the re-add that brings it level. No migration.
 - [v0.33.4 — A Name Is a Key](v0.33.4.md) — patch release of three first-run corrections: two from a contributor's PR #43 and CR141, which its review opened. `init --help` created a home named `--help`, `init ../escaped` created one outside `.mirror-minds`, and `init "My User"` put a space into `MIRROR_USER`; a user name is now a kebab-case key like a journey slug or a persona id, refused otherwise with a name that would work and nothing created. `identity edit` on Windows opens Notepad when no editor is named. Existing homes untouched. No migration.
 - [v0.33.3 — Mirror Finds Itself Under Any Path](v0.33.3.md) — patch release of one Change Request, CR140, carried by a contributor's PR #42: Mirror read its own install path from `URL.pathname`, so a checkout or package under a path with a space or a non-ASCII character read as `Install: unknown`, the welcome card showed no update, and `runtime update` refused. The path is now a filesystem path, a guard keeps the idiom out, and an `unknown` install names the path it looked up from. On Windows, npm's global layout is recognized and npm runs with no shell, verified on Windows in CI for the two files they touch; there is still no Windows product. Affected installs update once by hand. No migration.
 - [v0.33.2 — Git Runs Where Mirror Lives](v0.33.2.md) — patch release of one Change Request, CR138: on a clone install, `runtime status`, `version`, and `diagnose` describe the install from any directory, and `diagnose` grades Mirror's own tree. Git now runs only in the install's own checkout, so a checkout someone else made can no longer run a `core.fsmonitor` command through these commands; `version --start PATH` is the one explicit exception. Package installs were never exposed. No migration.

package/docs/releases/v0.34.0.md

@@ -0,0 +1,142 @@
+---
+digest: >
+  v0.34.0 is a minor release closing CV21.DS4: Codex runs Mirror through the
+  canonical plugin, the same one Claude Code loads. The package ships a Codex
+  marketplace; two commands install the plugin, Codex asks once to trust its
+  hooks, and from then on every session carries the skills, the Operating
+  Instructions, per-turn Mirror Mode injection, the MCP server, and logging as
+  `codex` with every reply beside its prompt — measured live at L4 on Codex
+  0.163.0. The v0.32.1 wrapper wiring is removed: `scripts/codex-mirror.sh`,
+  its hooks, and the JSONL backfill no longer ship. Because Codex copies the
+  plugin into a versioned cache, `runtime diagnose` and `runtime update` now
+  say when that copy is behind and name the one command that brings it level.
+  No migration.
+---
+
+# v0.34.0 — Codex Through the Canonical Plugin
+
+**Date:** 2026-10-17
+
+## Highlights
+
+- **Codex installs Mirror as a plugin, from a marketplace the package ships**
+  (CV21.DS4.US1). Two commands — `codex plugin marketplace add "<pkg>"`, then
+  `codex plugin add mirror-mind@mirror-mind` — and Codex asks once, at the
+  next session, to trust the plugin's hooks. `mirror init` prints exactly
+  these steps when it finds `codex` on the PATH.
+- **Codex is at L4, measured live** (CV21.DS4.US4, on Codex 0.163.0): all 25
+  skills, the Operating Instructions as a developer message, Mirror Mode on
+  an ordinary turn and on `$mirror-mind:mm:mirror`, the 7 MCP tools behind
+  Codex's `tool_search`, and every prompt and reply logged as `codex`. Codex
+  detaches the TUI on `/quit` and fires SessionEnd only when its daemon reaps
+  the idle thread, so Mirror gained a safety net for sessions that outlive
+  their TUI: session maintenance closes them as orphans
+  (`MIRROR_STALE_ORPHAN_MINUTES`, default 30).
+- **A bounded SessionEnd no longer cuts extraction** (CV21.DS4.TS2). Codex
+  bounds the hook at 1 s; the close now runs no LLM work, and the next
+  session start finishes the deferred tail. Grok's 1.5 s bound rides the same
+  change.
+- **`$`-skill turns are command turns** (CV21.DS4.TS3), as `/`-commands are
+  on every other runtime, with Mirror's explicit form the one exception.
+- **The v0.32.1 Codex wiring is removed** (CV21.DS4.TS5). What no longer
+  exists: `scripts/codex-mirror.sh`, `scripts/codex-hooks/`, the
+  `codex:session-*` hook entries, and
+  `conversation-logger backfill-codex-session` — the plugin logs Codex turns
+  as they happen, so nothing re-imports the transcript at exit. A
+  retired-surfaces guard keeps the wiring from drifting back.
+- **An updated Mirror now reaches Codex's plugin cache — or says so**
+  (CV21.DS4.TS6). Codex copies the plugin into its cache at a version, so an
+  npm update changes the install but not the copy Codex runs. `runtime
+  diagnose` reports `codex_plugin_cache_behind` naming both versions and the
+  measured command — `codex plugin add mirror-mind@mirror-mind`; re-adding
+  refreshes the cache in place, no remove needed — and a successful `runtime
+  update` prints the same line. A dangling Claude Code skills link is
+  reported too (`claude_plugin_link_dangling`). Absence is not drift: an
+  unwired machine stays green.
+
+## Where We Started
+
+v0.33.0 proved one plugin works as it is on Claude Code, Codex, and Grok.
+But a Codex user still wired Mirror by hand: a skills link, an `AGENTS.md`
+link, and a wrapper script around every session that imported the transcript
+from JSONL at exit — v0.32.1's wiring, built when Codex had no hook system.
+Codex 0.157 added plugins; DS4 asked whether the canonical plugin could be
+the whole answer, and set a gate: the old wiring retires only once parity is
+shown live.
+
+## What Changed
+
+**The install is two commands.** The npm package root carries
+`.agents/plugins/marketplace.json`, one local plugin — the same
+`plugins/mirror-mind` Claude Code loads. Codex copies it into its cache at
+the plugin's version and runs its Claude-family hooks as they are; runtime
+detection reads Codex's `turn_id` and labels the session `codex`.
+
+**The gate was met, so the old path is gone.** US4 measured L4 twice, live,
+through the shipped plugin alone. TS5 then removed the wrapper, its generated
+hooks, the `codex:*` hook family, the JSONL backfill (its only caller was the
+wrapper's exit hook; the plugin's SessionEnd closes without reading it),
+their pack-contents guards, and their CI step. The docs name the marketplace
+install and nothing else.
+
+**The one stale copy is watched.** Claude Code reads the plugin through a
+link, in place; Codex runs a versioned copy. TS6 taught `runtime diagnose`
+and `runtime update`'s post-update hints to compare that copy against the
+installed version — the landed version, read from the just-updated tree —
+and to print the one command that works on Codex 0.163.0, which has no
+plugin-update verb: the re-add.
+
+## Upgrading
+
+```bash
+npm install -g mirror-mind@latest    # or: mirror runtime update
+```
+
+**If Codex runs the plugin already:** after this update (and any future one),
+bring the cache level once:
+
+```bash
+codex plugin add mirror-mind@mirror-mind
+```
+
+`mirror runtime diagnose` will tell you whenever this is needed.
+
+**If you wired Codex before the plugin** (a skills link, an `AGENTS.md` link,
+the wrapper script): install the plugin with the two commands above, then
+undo the old wiring — the exact steps are in Getting Started's Codex section.
+If you do nothing, everything still works, at the cost of doubled skills and
+double logging where the old wrapper still runs; an older installed package
+keeps its own wrapper copy, but this version ships none.
+
+No migration. Existing homes, sessions, and memories are untouched.
+
+## Conscious Exclusions
+
+- **Codex logging is no longer end-to-end tested**, by decision: the retired
+  wrapper smoke was the only artifact-level Codex check. Confidence now rests
+  on the shared Claude-family hook path (smoked), runtime-detection units,
+  and US4's live measurement.
+- **Mirror never runs `codex` itself.** The cache readers are read-only
+  filesystem checks; the person runs the printed command.
+- **Two named silences in the wiring checks:** a cache *ahead* of the install
+  (a deliberate downgrade gets no advice from the older tree), and a Claude
+  link that resolves to another install tree (healthy means the target
+  reads). Both are recorded as decisions with tests.
+- **CR142 is captured, not fixed:** the Claude plugin smoke's negative probe
+  fails on a machine with a globally installed `mirror-hook` — a smoke
+  isolation bug found during TS5's validation, pre-existing, filed under
+  RS010.
+
+## What We Learned
+
+The gate ordering did the work: retiring the old wiring only after L4 was
+measured live meant the removal was a deletion, not a bet. And the one real
+surprise of the arc — Codex sessions outlive their TUI — was caught by the
+live measurement, not by any test, which is why the measurement is part of
+the method.
+
+## Next Horizon
+
+DS4 closes with this release. CV21's remaining runtime stories — Antigravity
+through a native layer (DS7), Grok (DS10) — are pulled deliberately from the
+CV21 index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.4",
+  "version": "0.34.0",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,7 @@
     ".claude/hooks",
     ".gemini/hooks",
     "plugins/mirror-mind",
-    "scripts/codex-hooks",
-    "scripts/codex-mirror.sh",
+    ".agents/plugins",
     "AGENTS.md",
     "README.md",
     "LICENSE"

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.4",
+  "version": "0.34.0",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

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, the Gemini hook); 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 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;
+}