mirror-mind 0.33.4 → 0.34.0

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

package/ts/src/hooks/claude.ts

@@ -87,9 +87,21 @@ export async function claudeStop(stdin: string): Promise<number> {
   return 0;
 }
 
-/** `log-session-end.sh`: close the session, then take the silent backup. */
-export async function claudeSessionEnd(): Promise<number> {
-  await runFrontDoorQuietly("claude:session-end", ["conversation-logger", "session-end"]);
+/**
+ * `log-session-end.sh`: close the session, then take the silent backup.
+ *
+ * The runtime goes along as `--interface`, as Stop's does, for a session row
+ * with no label. On a runtime that bounds this hook (Codex 1 s, Grok 1.5 s)
+ * the close runs no LLM work and the next session start finishes the tail
+ * (CV21.DS4.TS2); both calls then fit inside the bound.
+ */
+export async function claudeSessionEnd(stdin: string): Promise<number> {
+  const runtime = detectHookRuntime(parseHookPayload(stdin).raw);
+  await runFrontDoorQuietly(
+    "claude:session-end",
+    ["conversation-logger", "session-end", "--interface", runtime],
+    { stdin },
+  );
   await runFrontDoorQuietly("claude:session-end", ["backup", "--silent"]);
   return 0;
 }
@@ -204,7 +216,7 @@ export async function claudeHook(name: string): Promise<number> {
     case "stop":
       return claudeStop(readStdin());
     case "session-end":
-      return claudeSessionEnd();
+      return claudeSessionEnd(readStdin());
     case "inject":
       return claudeInject(readStdin());
     default:

package/ts/src/hooks/gemini.ts

@@ -14,6 +14,7 @@
 // `GEMINI_SESSION_ID` still wins over the payload's `session_id`, because the
 // runtime sets it and the payload is the fallback.
 
+import { isCommandTurn } from "#conversation/commandTurn.ts";
 import { parseHookPayload } from "./payload.ts";
 import {
   operatingInstructionsFor,
@@ -37,7 +38,8 @@ export async function geminiLogUser(stdin: string): Promise<number> {
   const payload = parseHookPayload(stdin);
   const sessionId = sessionIdFrom(payload.sessionId);
 
-  if (payload.prompt.startsWith("/")) {
+  // The same rule as the Claude-family logger's (CV21.DS4.TS3): one home.
+  if (isCommandTurn(payload.prompt)) {
     process.stdout.write("{}\n");
     return 0;
   }

package/ts/src/hooks/main.ts

@@ -8,8 +8,10 @@
 //
 //     node ts/src/hooks/main.ts claude:inject
 //
-// Arguments after the name are the hook's own; only the Codex wrapper passes
-// any, since Codex has no hook payload to read (`codex.ts`).
+// Arguments after the name are the hook's own; every current hook reads its
+// payload from stdin and passes none. (The Codex wrapper's `codex:*` entries
+// were the exception, until CV21.DS4.TS5 retired them with the wrapper: the
+// plugin's Claude-family hooks are the Codex path now.)
 //
 // One entry rather than one file per hook because the generated wrappers then
 // differ only in the hook name and their depth, and `hooks.test.ts` asserts
@@ -34,7 +36,6 @@
 import { pathToFileURL } from "node:url";
 import { loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
 import { claudeHook } from "./claude.ts";
-import { codexSessionEnd, codexSessionStart } from "./codex.ts";
 import {
   geminiLogAssistant,
   geminiLogUser,
@@ -44,7 +45,7 @@ import {
 import { readStdin } from "./payload.ts";
 import { noteHookFailure } from "./runtime.ts";
 
-async function dispatch(name: string, args: readonly string[]): Promise<number> {
+async function dispatch(name: string): Promise<number> {
   const [runtime, hook] = name.split(":");
 
   switch (runtime) {
@@ -64,17 +65,6 @@ async function dispatch(name: string, args: readonly string[]): Promise<number>
           break;
       }
       break;
-    case "codex":
-      // Called by `scripts/codex-mirror.sh` through its generated wrappers.
-      switch (hook) {
-        case "session-start":
-          return codexSessionStart();
-        case "session-end":
-          return codexSessionEnd(args[0] ?? "", args[1] ?? "");
-        default:
-          break;
-      }
-      break;
     default:
       break;
   }
@@ -94,7 +84,7 @@ export async function runAsEntry(rawArgv = process.argv.slice(2)): Promise<numbe
   loadConfiguration({ entryPath: import.meta.filename });
   const name = rawArgv[0] ?? "";
   try {
-    return await dispatch(name, rawArgv.slice(1));
+    return await dispatch(name);
   } catch (error) {
     // The last line of defense. A hook that throws must still not break the
     // turn, and must still leave a trace that it happened.

package/ts/src/providers/config.ts

@@ -120,6 +120,17 @@ export function resolveMaintenanceMaxExtractions(options: ModelPinOptions = {}):
   return parsePythonInt(env.MEMORY_MAINTENANCE_MAX_EXTRACTIONS, 10);
 }
 
+/**
+ * `MIRROR_STALE_ORPHAN_MINUTES` (CV21.DS4.US4): how long an open conversation
+ * may sit idle before session maintenance closes it as an orphan. On a runtime
+ * whose session outlives the TUI (Codex 0.163.0) this is the close path, so an
+ * operator may shorten it; a route sets it to 0 to prove the close now.
+ */
+export function resolveStaleOrphanMinutes(options: ModelPinOptions = {}): number {
+  const env = options.env ?? process.env;
+  return parsePythonInt(env.MIRROR_STALE_ORPHAN_MINUTES, 30);
+}
+
 /** Python `int(os.getenv("MEMORY_EXTRACTION_MAX_ATTEMPTS", "3"))` (CV9.E2.S7). */
 export function resolveExtractionMaxAttempts(options: ModelPinOptions = {}): number {
   const env = options.env ?? process.env;

package/ts/src/runtime/diagnose.ts

@@ -31,7 +31,13 @@ import { identityKeyBreaksGrammar, SLUG_KEYED_LAYERS } from "#identity/identityK
 import { pyRepr, sortByCodePoint } from "#util/pythonText.ts";
 import { configFilePath } from "./config.ts";
 import type { GitWorktreeEntry } from "./git.ts";
+import {
+  claudePluginLinkState,
+  codexPluginCacheState,
+  installedPluginVersion,
+} from "./pluginWiring.ts";
 import type { RuntimeStatusReport } from "./status.ts";
+import { CODEX_PLUGIN_ADD_COMMAND } from "./wiring.ts";
 
 export interface DriftFinding {
   code: string;
@@ -114,7 +120,7 @@ export function rootStateFindings(homesRoot: string): DriftFinding[] {
     detail: path,
     recommendation:
       "relocate into the owning mirror home " +
-      "(see REFERENCE.md \u2014 Relocating legacy root runtime state)",
+      "(see REFERENCE.md — Relocating legacy root runtime state)",
     repair_route: "manual relocation",
   }));
 }
@@ -319,6 +325,60 @@ export function ftsConsistencyFindings(report: RuntimeStatusReport): DriftFindin
   return [];
 }
 
+/** A deferred close tail waits for a session start; after this long, nobody started one. */
+const DEFERRED_CLOSE_TAIL_STALE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * CV21.DS4.TS2: a runtime that bounds its SessionEnd hook (Codex, Grok) closes
+ * without the LLM tail and flags the conversation for the next session start to
+ * finish. A user whose last session was on such a runtime, and who starts no
+ * session for a day, has memories and titles waiting and nothing saying so:
+ * this is the one place that says so. Younger flags are the normal state
+ * between two sessions, not a finding.
+ */
+export function deferredCloseTailFindings(
+  report: Pick<RuntimeStatusReport, "db_path" | "db_exists">,
+  now: Date = new Date(),
+): DriftFinding[] {
+  if (report.db_path === null || !report.db_exists) return [];
+  let row: { n: number; oldest: string } | null;
+  try {
+    const db = openDatabaseReadOnly(report.db_path);
+    try {
+      const found = db
+        .prepare(
+          `SELECT COUNT(*) AS n, MIN(ended_at) AS oldest FROM conversations
+           WHERE ended_at IS NOT NULL
+             AND json_extract(metadata, '$.close_tail_pending') IS 1`,
+        )
+        .get();
+      row =
+        found && Number(found.n) > 0 ? { n: Number(found.n), oldest: String(found.oldest) } : null;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return [];
+  }
+  if (row === null) return [];
+  const oldest = Date.parse(row.oldest);
+  if (Number.isNaN(oldest) || now.getTime() - oldest < DEFERRED_CLOSE_TAIL_STALE_MS) return [];
+  return [
+    {
+      code: "deferred_close_tails_waiting",
+      severity: "attention",
+      subject: "conversations",
+      detail:
+        `${row.n} conversation(s) closed by a runtime that defers the close tail are waiting ` +
+        `for a session start to finish it; the oldest ended ${row.oldest}`,
+      recommendation:
+        "start a session on any runtime: its maintenance extracts and finalizes them, " +
+        "five per start",
+      repair_route: "session start",
+    },
+  ];
+}
+
 export interface DiagnoseOptions {
   /** Injected only so the 24h boundary is testable; production passes none. */
   now?: Date;
@@ -340,6 +400,7 @@ export function diagnoseRuntime(
   findings.push(...frontDoorErrorFindings(report, options.now));
   findings.push(...ftsConsistencyFindings(report));
   findings.push(...identityKeyFindings(report));
+  findings.push(...deferredCloseTailFindings(report, options.now));
 
   if (report.mirror_home_error) {
     findings.push({
@@ -442,6 +503,59 @@ export function diagnoseRuntime(
   return findings;
 }
 
+/**
+ * The plugin wiring findings (CV21.DS4.TS6; the debt US1 carried). Codex
+ * copies the plugin into a versioned cache, so an npm update leaves it
+ * behind; Claude Code links it in place, so its failure mode is a dangling
+ * link. Absence is not drift: no cache and no link fire nothing, so an
+ * unwired machine stays green.
+ *
+ * The defaulting happens HERE, from the env the caller hands in — CODEX_HOME
+ * else ~/.codex, and ~/.claude — never inside the readers, so every reader
+ * test is hermetic on a maintainer's machine with real wiring
+ * (CR123/128/137/142).
+ */
+export function pluginWiringFindings(
+  installRoot: string | null,
+  env: NodeJS.ProcessEnv,
+): DriftFinding[] {
+  const findings: DriftFinding[] = [];
+  const home = env.HOME?.trim() || null;
+
+  const codexHome = env.CODEX_HOME?.trim() || (home ? join(home, ".codex") : null);
+  const installedVersion = installRoot ? installedPluginVersion(installRoot) : null;
+  if (codexHome && installedVersion) {
+    const cache = codexPluginCacheState(codexHome, installedVersion);
+    if (cache.state === "behind") {
+      findings.push({
+        code: "codex_plugin_cache_behind",
+        severity: "warning",
+        subject: cache.cachePath,
+        detail: `cached ${cache.newestCached} < installed ${installedVersion}; Codex runs the copy it cached at install`,
+        recommendation: `run \`${CODEX_PLUGIN_ADD_COMMAND}\` to bring the cached plugin level (Codex has no plugin-update verb; re-adding refreshes the cache)`,
+        repair_route: CODEX_PLUGIN_ADD_COMMAND,
+      });
+    }
+  }
+
+  if (home) {
+    const link = claudePluginLinkState(join(home, ".claude"));
+    if (link.state === "dangling") {
+      findings.push({
+        code: "claude_plugin_link_dangling",
+        severity: "warning",
+        subject: link.linkPath,
+        detail: `the link points at ${link.target ?? "an unreadable target"}, which cannot be read`,
+        recommendation:
+          'relink it — `ln -s "<pkg>/plugins/mirror-mind" ~/.claude/skills/mirror-mind` — or remove it if Claude Code is no longer wired',
+        repair_route: "relink or remove",
+      });
+    }
+  }
+
+  return findings;
+}
+
 /** The catalog read `probeModelPins` needs. DS5 replay only until DS8. */
 export interface ModelCatalogProvider {
   listAvailableModels(): Promise<Set<string>>;

package/ts/src/runtime/pluginWiring.ts

@@ -0,0 +1,135 @@
+// The plugin wiring readers (CV21.DS4.TS6).
+//
+// Two runtimes hold the plugin outside the install tree. Codex copies it into
+// a versioned cache (`$CODEX_HOME/plugins/cache/mirror-mind/mirror-mind/
+// <version>`; CV21.DS4.US1), so an npm update changes the install but not
+// that copy — the one wiring that goes stale. Claude Code links the plugin in
+// place (`~/.claude/skills/mirror-mind`), so its failure mode is a dangling
+// link, not a stale copy.
+//
+// Both readers take their roots as ARGUMENTS, always. The defaulting —
+// `$CODEX_HOME` else `~/.codex`, and the Claude home — happens once, at the
+// diagnose entry, from the env the caller already carries, never in here.
+// That is the CR123/128/137/142 lesson: a maintainer's machine has a real
+// ~/.codex and a real ~/.claude, and a reader that consults the environment
+// makes every fixture test machine-dependent exactly where maintainers work.
+//
+// Nothing here runs `codex` or mutates anything: Mirror reads directories and
+// prints a command for the person to run. On the installed Codex 0.163.0,
+// `codex plugin` has no update verb (add, list, marketplace, remove), so the
+// level-up command is the re-add — `CODEX_PLUGIN_ADD_COMMAND`, the same
+// constant `mirror init`'s wiring lines print (the CR071 lesson at the
+// string level).
+
+import { lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { compareSemver, parseSemver } from "#util/semver.ts";
+
+/** Where Codex keeps its copy, below a Codex home. */
+export const CODEX_PLUGIN_CACHE_SEGMENTS: readonly string[] = [
+  "plugins",
+  "cache",
+  "mirror-mind",
+  "mirror-mind",
+];
+
+export interface CodexCacheState {
+  /** `absent` covers no cache and a cache with no version-named entry. */
+  state: "absent" | "current" | "behind" | "ahead";
+  cachePath: string;
+  /** The newest version-named entry, by semver — never a string sort. */
+  newestCached: string | null;
+}
+
+/**
+ * Read the Codex plugin cache below `codexHome`, read-only. Entries whose
+ * names do not parse as versions (a partial download, an editor's leavings)
+ * are ignored; a cache holding only those claims nothing and reads as absent.
+ *
+ * `ahead` is a state, not a finding: `runtime update` refuses downgrades but
+ * `npm install -g mirror-mind@old` does not ask, and the person who
+ * downgraded on purpose needs no Codex advice from the older tree.
+ */
+export function codexPluginCacheState(
+  codexHome: string,
+  installedVersion: string,
+): CodexCacheState {
+  const cachePath = join(codexHome, ...CODEX_PLUGIN_CACHE_SEGMENTS);
+  let entries: string[];
+  try {
+    entries = readdirSync(cachePath);
+  } catch {
+    return { state: "absent", cachePath, newestCached: null };
+  }
+  let newest: string | null = null;
+  for (const entry of entries) {
+    if (parseSemver(entry)[0] < 0) continue;
+    try {
+      if (!statSync(join(cachePath, entry)).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    if (newest === null || compareSemver(entry, newest) > 0) newest = entry;
+  }
+  if (newest === null) return { state: "absent", cachePath, newestCached: null };
+  const order = compareSemver(newest, installedVersion);
+  const state = order < 0 ? "behind" : order > 0 ? "ahead" : "current";
+  return { state, cachePath, newestCached: newest };
+}
+
+export interface ClaudeLinkState {
+  /** `healthy` means the target reads — including a plain directory copy. */
+  state: "absent" | "healthy" | "dangling";
+  linkPath: string;
+  /** The link's own target when it is a symlink, else null. */
+  target: string | null;
+}
+
+/**
+ * Read the Claude Code wiring below `claudeHome`. Healthy means the target
+ * reads; a link that resolves to *another* install tree is deliberately
+ * healthy too (TS6's documented silence) — chasing where it points is a
+ * one-line amendment here if that case ever bites.
+ */
+export function claudePluginLinkState(claudeHome: string): ClaudeLinkState {
+  const linkPath = join(claudeHome, "skills", "mirror-mind");
+  let isLink = false;
+  try {
+    isLink = lstatSync(linkPath).isSymbolicLink();
+  } catch {
+    return { state: "absent", linkPath, target: null };
+  }
+  const target = isLink ? readlinkSync(linkPath) : null;
+  try {
+    statSync(linkPath);
+  } catch {
+    return { state: "dangling", linkPath, target };
+  }
+  return { state: "healthy", linkPath, target };
+}
+
+/**
+ * The install tree's own plugin version, from the generated manifest.
+ * `plugins/mirror-mind/.claude-plugin/plugin.json` is written by
+ * `claudePlugin.ts` from `packageVersion()`, and the guard holds the
+ * committed manifest equal to the generated one — the file is the authority,
+ * not an assumption. Reading it FROM DISK is also what makes a post-update
+ * hint honest: the process that ran the update is the old version's code,
+ * but the tree it reads has already landed the new one.
+ */
+export function installedPluginVersion(installRoot: string): string | null {
+  try {
+    const raw = readFileSync(
+      join(installRoot, "plugins", "mirror-mind", ".claude-plugin", "plugin.json"),
+      "utf8",
+    );
+    const parsed: unknown = JSON.parse(raw);
+    const version =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).version
+        : undefined;
+    return typeof version === "string" && version !== "" ? version : null;
+  } catch {
+    return null;
+  }
+}

package/ts/src/runtime/update.ts

@@ -26,8 +26,10 @@
 // chosen once, below; no step asks which lane it is in.
 
 import { spawnSync } from "node:child_process";
+import { join } from "node:path";
 import { verifyBackupArchive } from "#runtime/backup.ts";
 import type { InstallKind } from "#runtime/installKind.ts";
+import { codexPluginCacheState, installedPluginVersion } from "#runtime/pluginWiring.ts";
 import { cloneStrategy, defaultGitRunner, type GitRunner } from "#runtime/strategies/clone.ts";
 import { defaultNpmRunner, type NpmRunner, packageStrategy } from "#runtime/strategies/package.ts";
 import type { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
@@ -37,6 +39,7 @@ import {
   type UpdateResult,
   type UpdateStage,
 } from "#runtime/updatePipeline.ts";
+import { CODEX_PLUGIN_ADD_COMMAND } from "#runtime/wiring.ts";
 import { commandOnPath } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { shellWord } from "#util/shellWord.ts";
@@ -405,12 +408,42 @@ export function postUpdateHints(
   env: NodeJS.ProcessEnv,
   canExecute?: (path: string) => boolean,
 ): string[] {
-  if (install.kind !== "clone" || !result.success) return [];
-  if (commandOnPath(PROGRAM, env, canExecute) !== null) return [];
-  // A command the person will paste: the path is one shell word (CR104).
-  return [
-    `\`${PROGRAM}\` is not on the PATH: run \`npm link\` once in ${shellWord(install.repository)}, so the skills can call it.`,
-  ];
+  if (!result.success) return [];
+  const hints: string[] = [];
+
+  if (install.kind === "clone" && commandOnPath(PROGRAM, env, canExecute) === null) {
+    // A command the person will paste: the path is one shell word (CR104).
+    hints.push(
+      `\`${PROGRAM}\` is not on the PATH: run \`npm link\` once in ${shellWord(install.repository)}, so the skills can call it.`,
+    );
+  }
+
+  // CV21.DS4.TS6: Codex runs the plugin copy it cached at install, so the
+  // update that just landed did not reach it. The version authority is the
+  // LANDED version, read from the just-updated tree's plugin.json -- this
+  // process is the old version's code, and its own constant would read a
+  // just-staled cache as current.
+  const installRoot =
+    install.kind === "clone"
+      ? install.repository
+      : install.kind === "package"
+        ? install.root
+        : null;
+  const home = env.HOME?.trim() || null;
+  const codexHome = env.CODEX_HOME?.trim() || (home ? join(home, ".codex") : null);
+  if (installRoot && codexHome) {
+    const landed = installedPluginVersion(installRoot);
+    if (landed) {
+      const cache = codexPluginCacheState(codexHome, landed);
+      if (cache.state === "behind") {
+        hints.push(
+          `Codex's cached plugin is behind the update (${cache.newestCached} < ${landed}): run \`${CODEX_PLUGIN_ADD_COMMAND}\` to bring it level.`,
+        );
+      }
+    }
+  }
+
+  return hints;
 }
 
 function firstLine(text: string): string {

package/ts/src/runtime/wiring.ts

@@ -23,17 +23,31 @@
 //               and hooks live in `~/.gemini/settings.json`, absolute paths.
 //               Two steps. The Operating Instructions arrive through the
 //               SessionStart hook (D13).
-//   Codex       `~/.codex/skills/<dir>` is discovered recursively, and
-//               `~/.codex/AGENTS.md` is the global instructions file
-//               (`codex debug prompt-input`, 0.157.0). Two steps, and the
-//               session is run through the shipped wrapper, since Codex has
-//               no hooks this integration uses.
+//   Codex       `codex plugin marketplace add <root>` reads the package's
+//               `.agents/plugins/marketplace.json`, and `codex plugin add
+//               mirror-mind@mirror-mind` copies the plugin into Codex's cache
+//               with its skills, hooks, and MCP server (0.162.1, CV21.DS12.TS2
+//               static 5-7; CV21.DS4.US1). Two steps. Codex asks once, at the
+//               next session, to trust the plugin's hooks (L1); the Operating
+//               Instructions then arrive through its SessionStart hook as a
+//               developer message (L4). Until DS4.US1 the two steps were a
+//               skills link and an AGENTS.md link, with sessions run through
+//               the shipped wrapper.
 
 import { join } from "node:path";
 import { commandOnPath } from "#util/paths.ts";
 
 export type RuntimeName = "pi" | "claude" | "gemini" | "codex";
 
+/**
+ * The one Codex level-up command (CV21.DS4.TS6). Codex 0.163.0 has no
+ * plugin-update verb, so re-adding is how a cached plugin reaches the
+ * installed version. One constant so the wiring line `mirror init` prints
+ * and the recommendation `runtime diagnose` prints cannot disagree (the
+ * CR071 lesson at the string level).
+ */
+export const CODEX_PLUGIN_ADD_COMMAND = "codex plugin add mirror-mind@mirror-mind";
+
 export interface RuntimeWiring {
   /** The runtime, as a person names it. */
   readonly title: string;
@@ -94,11 +108,11 @@ export const RUNTIME_WIRING: Readonly<Record<RuntimeName, RuntimeWiring>> = {
     title: "Codex",
     command: "codex",
     steps: [
-      (root) => [`ln -s "${join(root, ".pi/skills")}" ~/.codex/skills/mirror-mind`],
-      (root) => [
-        `ln -s "${join(root, "AGENTS.md")}" ~/.codex/AGENTS.md`,
-        "(or append that file to the ~/.codex/AGENTS.md you already have)",
-        `then start Codex through "${join(root, "scripts/codex-mirror.sh")}" instead of codex`,
+      (root) => [`codex plugin marketplace add "${root}"`],
+      () => [
+        CODEX_PLUGIN_ADD_COMMAND,
+        "(Codex asks once, at the next session, to trust the plugin's hooks; the plugin",
+        "then loads every session: its skills, the hooks, and the MCP server)",
       ],
     ],
   },

package/scripts/codex-hooks/session-end.sh

@@ -1,85 +0,0 @@
-#!/usr/bin/env bash
-# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
-# Edit the generator, never this file: every wrapper shares these bytes and
-# differs only in the hook name and in how it finds the Mirror entry
-# (CV22.DS10.TS5 decision D4; CV22.DS10.US3 decision D5).
-set -uo pipefail
-HOOK="codex:session-end"
-
-# Resolve the tree from THIS FILE, never from the cwd: a runtime spawns hooks
-# from whatever directory the session is in. The tree is a checkout or the
-# installed package; the wrapper's depth to its root is the same in both.
-HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-REPO_ROOT="$(cd "$HERE/../.." && pwd -P)"
-
-# A hook never fails the user's turn, and never fails in silence: when it
-# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits 0.
-# The home is found the way the core finds it -- MIRROR_HOME, else
-# MIRROR_USER -- from the environment when set there, else from the tree's
-# .env when the wrapper is in a tree, else from the user's config file
-# (~/.config/mirror/env), in the core's order (US3, D3). A GUI launch carries
-# neither variable, and the first wrappers then wrote to a home nobody reads.
-env_file_value() {
-  [ -f "$2" ] || return 0
-  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
-    | tail -n 1 | tr -d "\"'\r"
-}
-env_value() {
-  local value=""
-  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
-  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
-  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
-  printf '%s' "$value"
-}
-note() {
-  local home user
-  home="$(env_value MIRROR_HOME)"
-  user="$(env_value MIRROR_USER)"
-  if [ -n "$home" ]; then
-    home="${home/#\~/$HOME}"
-  elif [ -n "$user" ]; then
-    home="$HOME/.mirror-minds/$user"
-    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
-  else
-    return 0
-  fi
-  mkdir -p "$home" 2>/dev/null \
-    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
-}
-
-ENTRY="$REPO_ROOT/bin/mirror-hook.js"
-
-# Find Node. /usr/bin/python3 exists on every macOS; node usually lives under
-# nvm or Homebrew and is NOT on the PATH of a GUI-launched runtime. The Python
-# hooks could end in `|| true` because they always found their interpreter;
-# the same silence here would hide a new failure — no logging, no inject, no
-# close tail — that a user would meet weeks later as "Mirror stopped
-# remembering". So an unresolvable Node is RECORDED, never swallowed. The
-# directory the entry was found in is searched first: an npm global bin holds
-# the `node` that installed the package beside `mirror-hook`, while a system
-# `/usr/local/bin/node` can be years older (CI's Ubuntu runner has one).
-NODE="${MIRROR_NODE:-}"
-if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
-  NODE="$(command -v node 2>/dev/null || true)"
-fi
-for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
-  [ -n "$NODE" ] && break
-  [ -x "$candidate" ] && NODE="$candidate"
-done
-
-if [ -z "$NODE" ]; then
-  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
-  exit 0
-fi
-
-# Not `exec`: the entry exits 0 whatever happens inside it, so a non-zero exit
-# means Node itself could not run the hook -- too old for the loader shim, or
-# it crashed. That used to vanish into a stderr no runtime shows (TS5 handoff
-# review, finding N1). No flags: the entry reads configuration and silences
-# its own warnings (US3, D3).
-"$NODE" "$ENTRY" "$HOOK" "$@"
-status=$?
-if [ "$status" -ne 0 ]; then
-  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
-fi
-exit 0