mirror-mind 0.33.4 → 0.35.0

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,59 @@
+// 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.
+ *
+ *   antigravity  1.4.2: agy exposes no SessionEnd hook at all (its contracts
+ *                are SessionStart, PreTool, PostTool, PreInvocation,
+ *                PostInvocation, Stop; CV21.DS7.TS2 probe). Stop fires at each
+ *                turn's end, never at session end, so nothing closes the
+ *                conversation at TUI exit — the same situation as Codex, reached
+ *                by a different absence. The agy Stop handler logs each turn and
+ *                leaves the conversation open (CV21.DS7.TS3); the orphan close
+ *                is what ends it, and the next SessionStart sweeps 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" || interfaceName === "antigravity";
+}

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/docs/docsLint.ts

@@ -49,6 +49,14 @@ const FIXTURE_DIR_NAME = "fixtures";
 // itself has no `index.md`, by design. Not a broken link.
 const TEMPLATE_DIR_MARKER = "/roadmap/templates/";
 
+// Generated byte copies of a root document, each held equal to its source by
+// a guard (`claudePlugin.ts`: the plugin's `rules/AGENTS.md` is `AGENTS.md`'s
+// bytes, CV21.DS7.US1). Their links are the source's links, authored at the
+// repo root, so they resolve there -- a root-relative `REFERENCE.md` can never
+// exist under `rules/`, and skipping the file would hide a link the source
+// itself cannot resolve.
+const ROOT_COPIES = new Set(["plugins/mirror-mind/rules/AGENTS.md"]);
+
 export interface BrokenLink {
   readonly sourceFile: string;
   readonly line: number;
@@ -115,6 +123,11 @@ function isTemplatePlaceholder(sourceFile: string, targetPath: string): boolean
   return toPosix(sourceFile).includes(TEMPLATE_DIR_MARKER) && targetPath === "index.md";
 }
 
+/** The directory a file's relative links resolve from: its own, or the root for a root copy. */
+function linkBase(sourceFile: string, repoRoot: string): string {
+  return ROOT_COPIES.has(toPosix(relative(repoRoot, sourceFile))) ? repoRoot : dirname(sourceFile);
+}
+
 /** True for a `fixtures` directory nested under a `test`/`tests` one. */
 function isTestFixturePath(path: string): boolean {
   const parts = toPosix(path).split("/");
@@ -185,7 +198,7 @@ export function checkFile(sourceFile: string, repoRoot: string): BrokenLink[] {
     const anchorPart = hashIndex === -1 ? "" : link.slice(hashIndex + 1);
     if (isTemplatePlaceholder(sourceFile, pathPart)) continue;
 
-    const target = normalize(join(dirname(sourceFile), pathPart));
+    const target = normalize(join(linkBase(sourceFile, repoRoot), pathPart));
     if (!existsSync(target)) {
       problems.push({
         sourceFile: relSource,

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/frontDoor/stdinSource.ts

@@ -10,8 +10,8 @@
 // A one-shot handoff rather than an argument because the hooks run the front
 // door in-process (`runFrontDoor`), through the same `main(argv)` every other
 // caller uses, and a payload does not belong in argv: argv is what `ps`
-// shows, and what the Gemini hooks already put a prompt into is the exception
-// this seam avoids repeating.
+// shows, and what the Gemini CLI hooks (retired by CV21.DS8.US1) put a prompt
+// into is the exception this seam avoids repeating.
 
 import { readFileSync } from "node:fs";
 

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,100 @@ 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 agy-native layer (CV21.DS7.US1) -------------------------------------
+//
+// Antigravity treats a directory as a NATIVE plugin only when a root
+// `plugin.json` marks it (or `.antigravity-plugin/`/`.gemini-plugin/`).
+// Without the marker, `agy plugin install` converts the Claude surfaces as an
+// extension and OVERWRITES a shipped root `hooks.json` with Claude's — the
+// probe on agy 1.4.2 showed both behaviors (evidence in the US1 story
+// package). With the marker, validation passes, our root `hooks.json`
+// survives staging, `mcpServers: 1 processed`, and the 25 skills ride along.
+//
+// The layer is four generated files at agy's documented paths: the marker,
+// the hooks skeleton (TS2 adds injection, TS3 adds logging), the MCP map
+// (DERIVED from the manifest's entry — one locator, every carrier), and
+// `rules/AGENTS.md` (agy merges `rules/` into the active rule set; the guard
+// comparing committed to generated bytes is the sync with `AGENTS.md`).
+
+/** The native-plugin marker. Claude Code and Codex read `.claude-plugin/`. */
+export function buildAgyPluginMarker(): Record<string, unknown> {
+  return { name: PLUGIN_NAME, description: PLUGIN_DESCRIPTION };
+}
+
+export function agyPluginMarkerJson(): string {
+  return `${JSON.stringify(buildAgyPluginMarker(), null, 2)}\n`;
+}
+
+/**
+ * The named hook with its handlers (CV21.DS7.TS2). Commands are relative:
+ * agy sets a handler's cwd to the directory holding `hooks.json`, and the
+ * wrappers live beside it in `agy/` (generated agy-form; the pre-invocation
+ * wrapper gates on stdin before Node is ever resolved, because
+ * `PreInvocation` fires before every model call and blocks the agent loop).
+ * Timeouts are explicit and small: the fast path is shell-instant, the slow
+ * path is one `mirror load`, and a hang here freezes the agent — which a
+ * user reads as "Antigravity broke", not "Mirror hung". `Stop` is TS3's.
+ */
+export function buildAgyHooks(): Record<string, unknown> {
+  return {
+    [PLUGIN_NAME]: {
+      enabled: true,
+      SessionStart: [{ type: "command", command: "agy/session-start.sh", timeout: 60 }],
+      PreInvocation: [{ type: "command", command: "agy/pre-invocation.sh", timeout: 15 }],
+      // CV21.DS7.TS3: Stop fires at each turn's end (agy has no SessionEnd);
+      // the handler reads the transcript and logs the turn as antigravity.
+      Stop: [{ type: "command", command: "agy/stop.sh", timeout: 30 }],
+    },
+  };
+}
+
+export function agyHooksJson(): string {
+  return `${JSON.stringify(buildAgyHooks(), null, 2)}\n`;
+}
+
+/** agy's `mcp_config.json`: the same `mcpServers` map the manifest carries. */
+export function buildAgyMcpConfig(): Record<string, unknown> {
+  return {
+    mcpServers: {
+      [PLUGIN_NAME]: { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] },
+    },
+  };
+}
+
+export function agyMcpConfigJson(): string {
+  return `${JSON.stringify(buildAgyMcpConfig(), null, 2)}\n`;
+}
+
 /**
  * The skill markdown file, matching `skill.md` case-insensitively.
  *
@@ -232,6 +333,16 @@ export function planGeneratedFiles(repoRoot: string): GeneratedFile[] {
       relativePath: join(PLUGIN_DIR, ".claude-plugin", "plugin.json"),
       content: manifestJson(version),
     },
+    { relativePath: MARKETPLACE_PATH, content: marketplaceJson() },
+    // The agy-native layer (CV21.DS7.US1).
+    { relativePath: join(PLUGIN_DIR, "plugin.json"), content: agyPluginMarkerJson() },
+    { relativePath: join(PLUGIN_DIR, "hooks.json"), content: agyHooksJson() },
+    { relativePath: join(PLUGIN_DIR, "mcp_config.json"), content: agyMcpConfigJson() },
+    {
+      relativePath: join(PLUGIN_DIR, "rules", "AGENTS.md"),
+      content: readFileSync(join(repoRoot, "AGENTS.md"), "utf8"),
+      source: "AGENTS.md",
+    },
     ...claudeCopies.values(),
     ...[...pluginSkills].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, file]) => file),
   ];

package/ts/src/guards/packContents.ts

@@ -26,9 +26,7 @@ export const ALLOWED_PREFIXES: readonly string[] = [
   ".pi/extensions/",
   ".pi/skills/",
   ".claude/hooks/",
-  ".gemini/hooks/",
   "plugins/mirror-mind/",
-  "scripts/codex-hooks/",
 ];
 
 export const ALLOWED_FILES: readonly string[] = [
@@ -37,7 +35,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. */
@@ -55,10 +55,11 @@ export const REQUIRED_FILES: readonly string[] = [
   ".pi/extensions/mirror-logger.ts",
   ".pi/skills/mm-mirror/SKILL.md",
   ".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",
+  // CV21.DS7.US1: the agy-native layer's hooks file. A tarball cannot ship
+  // the skills without the layer Antigravity runs them beside.
+  "plugins/mirror-mind/hooks.json",
+  ".agents/plugins/marketplace.json",
 ];
 
 /** Prefixes that must have at least one file: content the program reads at runtime. */

package/ts/src/guards/piSourcedSkills.ts

@@ -1,7 +1,7 @@
 // Skills with one body in every runtime (CR102).
 //
 // Most Mirror skills have two authored bodies. `.pi/skills/` serves Pi, and
-// through the `.agents/skills/` links Codex and Gemini CLI too. `.claude/skills/`
+// through the `.agents/skills/` links Codex too. `.claude/skills/`
 // serves Claude Code, and `claudePlugin.ts` copies it into the plugin. CR071
 // kept the two apart on purpose: Usage sections, example language, and in
 // `mm-soul` and `mm-mirror` whole lines that are true for one runtime only.

package/ts/src/guards/retiredSurfaces.ts

@@ -460,6 +460,42 @@ export const RETIRED: readonly RetiredSurface[] = [
     // exploration's record is `docs/project/exploration/es-004-*.md`.
     exemptions: {},
   },
+  {
+    surfaceId: "codex-wrapper",
+    story: "CV21.DS4.TS5",
+    // The v0.32.1 Codex wiring: a wrapper script around the `codex` command,
+    // its two generated hooks, the `codex:*` hook family, and the JSONL
+    // backfill the wrapper drove at exit. Retired once US4 measured Codex at
+    // L4 through the shipped plugin, live: the plugin's Claude-family hooks
+    // log Codex turns as they happen, so nothing re-imports the transcript.
+    // The backfill's only caller was the wrapper's session-end hook, and the
+    // plugin's SessionEnd closes the session without reading it -- the
+    // condition DS4 set for keeping it was not met.
+    absentPaths: [
+      "scripts/codex-mirror.sh",
+      "scripts/codex-hooks/",
+      "ts/src/hooks/codex.ts",
+      "scripts/smoke_codex.sh",
+      "ts/test/fixtures/backfill/codex/",
+    ],
+    // File and route names, never vocabulary: "codex" is a living word (the
+    // plugin serves Codex; `runtimeDetection.ts` labels its payloads).
+    forbiddenPatterns: [
+      "codex-mirror\\.sh",
+      "codex-hooks",
+      "codex:session-(start|end)",
+      "backfill-codex-session",
+      "backfill_codex_session",
+      "backfillCodexSession",
+      "smoke_codex",
+    ],
+    exemptions: {
+      "docs/getting-started.md":
+        "the un-wiring guidance: a user who started codex through the retired wrapper needs its name to undo that wiring",
+      "ts/src/conversation/backfill.ts":
+        "the header names the retired importer to say where it went, beside the Pi importer that stays",
+    },
+  },
   {
     // Not a deleted surface: a retired IDIOM. A URL's pathname is not a
     // filesystem path -- it percent-encodes `Código` and `John Doe`, and on
@@ -478,6 +514,37 @@ export const RETIRED: readonly RetiredSurface[] = [
     residueScope: ["ts/src/", "ts/scripts/"],
     exemptions: {},
   },
+  {
+    surfaceId: "gemini-cli",
+    story: "CV21.DS8.US1",
+    // The Gemini CLI integration: four generated wrappers under `.gemini/hooks`,
+    // the `gemini:*` hook family behind them, the two `mirror init` steps, and
+    // the Gemini smoke. Retired once DS7.US4 measured Antigravity at L4 on agy
+    // 1.4.2 -- a Gemini CLI user loses nothing by moving. `.gemini/` is an
+    // absent path and not merely an unallowed one because `mirror init` told
+    // users to write absolute paths into that directory into their
+    // `~/.gemini/settings.json`: a standing instruction to execute whatever a
+    // later release might ship there. This row is what keeps that from
+    // happening.
+    absentPaths: [".gemini/", "ts/src/hooks/gemini.ts", "scripts/smoke_gemini_cli.sh"],
+    // File and route names, never vocabulary: "gemini" is a living word (the
+    // extraction and consult models, Antigravity's own `~/.gemini/` home, the
+    // `gemini_cli` label on conversations already logged). The row landed in
+    // two steps: US1 carried the names only code and CI used, and
+    // CV21.DS8.US2 added the doc-facing ones when it cleared the runtime-facing
+    // docs, so no exemption was ever staged. Not `.gemini/settings.json` and
+    // not `~/.gemini`: that directory is Antigravity's home too, and the
+    // cutoff note names the file a Gemini CLI user edits.
+    forbiddenPatterns: [
+      "smoke_gemini_cli",
+      "geminiHooksSettings",
+      "hooks/gemini\\.ts",
+      "\\.gemini/hooks",
+      "gemini:(session-start|session-end|log-user|log-assistant)",
+      "gemini skills link",
+    ],
+    exemptions: {},
+  },
 ];
 
 export interface SurfaceProblem {