mirror-mind 0.33.4 → 0.34.0

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."];

package/ts/src/frontDoor/routing.ts

@@ -373,10 +373,11 @@ const TS_CONVERSATION_LOGGER_SUBCOMMANDS = new Set([
   // CV21.DS2.US8: the Stop hook's reply, deterministic like user-prompt.
   "stop",
   "discard-current",
-  // US10 slice F, group 2 (need slice E): diagnose, dry-run repair, Codex import.
+  // US10 slice F, group 2 (need slice E): diagnose and dry-run repair. (The
+  // Codex import routed here too, until CV21.DS4.TS5 retired it with the
+  // v0.32.1 Codex wrapper.)
   "diagnose-journeys",
   "repair-journeys",
-  "backfill-codex-session",
 ]);
 
 // CV22.DS7.US10 slice F. These reach Python's `end_conversation`, which runs

package/ts/src/frontDoor/runtimeRoute.ts

@@ -26,6 +26,7 @@ import {
   diagnoseRuntime,
   hookFailureFindings,
   hookNodeFindings,
+  pluginWiringFindings,
   probeModelPins,
   renderRuntimeDiagnosis,
   rootStateFindings,
@@ -301,12 +302,19 @@ export async function runRuntimeReadRoute(
   if (subcommand === "diagnose") {
     // The install's own tree, so its worktree findings are Mirror's and never
     // the cwd project's (CR138).
+    const install = io.install ?? detectThisInstall();
     const report = buildRuntimeStatus({
       mirrorHome: optionValue(args, "--mirror-home"),
       env,
       version,
-      install: io.install ?? detectThisInstall(),
+      install,
     });
+    const installRoot =
+      install.kind === "clone"
+        ? install.repository
+        : install.kind === "package"
+          ? install.root
+          : null;
     const findings = [
       ...diagnoseRuntime(report, inspectGitWorktree(report.git.repository)),
       ...rootStateFindings(homesRoot(env)),
@@ -324,6 +332,10 @@ export async function runRuntimeReadRoute(
           return false;
         }
       }),
+      // CV21.DS4.TS6: the plugin wiring. Codex's versioned cache goes stale
+      // after an npm update; Claude Code's link can dangle. Absence is not
+      // drift, so an unwired machine stays green.
+      ...pluginWiringFindings(installRoot, env),
       // No catalog provider until DS8: inconclusive, which is also the
       // oracle's answer when it cannot reach OpenRouter.
       ...(await probeModelPins(null, "")),

package/ts/src/guards/claudePlugin.ts

@@ -1,5 +1,6 @@
-// Generate the canonical Mirror Mind Claude plugin (manifest + skills), and the
-// Claude Code copies of Pi-sourced skills.
+// Generate the canonical Mirror Mind Claude plugin (manifest + skills), the
+// Codex marketplace that names it (CV21.DS4.US1), and the Claude Code copies of
+// Pi-sourced skills.
 //
 // The Node port of `src/memory/plugins/claude.py` and its wrapper
 // `scripts/build_claude_plugin.py` (CV22.DS10.TS5, slice B).
@@ -43,6 +44,12 @@ export const SKILLS_SOURCE_DIR = ".claude/skills";
 export const PLUGIN_DIR = "plugins/mirror-mind";
 export const SKILL_FILENAME = "SKILL.md";
 
+/**
+ * Where Codex reads a marketplace from, under the marketplace root, which for
+ * the shipped package is the package root (CV21.DS4.US1; DS12.TS2 static 5).
+ */
+export const MARKETPLACE_PATH = ".agents/plugins/marketplace.json";
+
 /** A file the generator owns, addressed relative to the repo root. */
 export interface GeneratedFile {
   readonly relativePath: string;
@@ -142,6 +149,35 @@ export function manifestJson(version: string): string {
   return `${JSON.stringify(buildManifest(version), null, 2)}\n`;
 }
 
+/**
+ * The Codex marketplace the package ships (CV21.DS4.US1).
+ *
+ * `codex plugin marketplace add <package root>` reads it, and
+ * `codex plugin add mirror-mind@mirror-mind` copies the plugin it names into
+ * Codex's cache, at the version the plugin manifest carries: the marketplace
+ * itself has none. One local source, the plugin directory, relative to the
+ * root. Generated beside the manifest so the plugin's name lives in one
+ * constant and `--check` guards both files.
+ */
+export function buildMarketplace(): Record<string, unknown> {
+  return {
+    name: PLUGIN_NAME,
+    owner: { name: PLUGIN_AUTHOR },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: { source: "local", path: `./${PLUGIN_DIR}` },
+        description: PLUGIN_DESCRIPTION,
+      },
+    ],
+  };
+}
+
+/** The marketplace as deterministic JSON text. */
+export function marketplaceJson(): string {
+  return `${JSON.stringify(buildMarketplace(), null, 2)}\n`;
+}
+
 /**
  * The skill markdown file, matching `skill.md` case-insensitively.
  *
@@ -232,6 +268,7 @@ export function planGeneratedFiles(repoRoot: string): GeneratedFile[] {
       relativePath: join(PLUGIN_DIR, ".claude-plugin", "plugin.json"),
       content: manifestJson(version),
     },
+    { relativePath: MARKETPLACE_PATH, content: marketplaceJson() },
     ...claudeCopies.values(),
     ...[...pluginSkills].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, file]) => file),
   ];

package/ts/src/guards/packContents.ts

@@ -28,7 +28,6 @@ export const ALLOWED_PREFIXES: readonly string[] = [
   ".claude/hooks/",
   ".gemini/hooks/",
   "plugins/mirror-mind/",
-  "scripts/codex-hooks/",
 ];
 
 export const ALLOWED_FILES: readonly string[] = [
@@ -37,7 +36,9 @@ export const ALLOWED_FILES: readonly string[] = [
   "LICENSE",
   "AGENTS.md",
   "ts/README.md",
-  "scripts/codex-mirror.sh",
+  // CV21.DS4.US1: the Codex marketplace, read from the package root. The
+  // `.agents/skills/` symlinks beside it are the checkout's and stay out.
+  ".agents/plugins/marketplace.json",
 ];
 
 /** Files that must be in every tarball: the entries and one of each runtime's wiring. */
@@ -57,8 +58,7 @@ export const REQUIRED_FILES: readonly string[] = [
   ".claude/hooks/session-start.sh",
   ".gemini/hooks/session-start.sh",
   "plugins/mirror-mind/hooks/hooks.json",
-  "scripts/codex-hooks/session-start.sh",
-  "scripts/codex-mirror.sh",
+  ".agents/plugins/marketplace.json",
 ];
 
 /** Prefixes that must have at least one file: content the program reads at runtime. */