mirror-mind 0.33.4 → 0.35.0

package/ts/src/hooks/agy.ts

@@ -0,0 +1,229 @@
+// Antigravity hook entries (CV21.DS7.TS2).
+//
+// agy runs the plugin's `hooks.json` handlers with camelCase protojson on
+// stdin and reads JSON from stdout (`injectSteps`; a `systemMessage` step
+// nests its text, an `ephemeralMessage` is a plain string). The contracts
+// are committed bytes in CV21.DS7.US1's `evidence/` (agy 1.4.2).
+//
+// Two handlers:
+//
+//   * `agy:session-start` — turn conversation logging on, the posture every
+//     runtime's session-start shares, and answer `{}`. The Operating
+//     Instructions are NOT delivered here: `rules/AGENTS.md` carries them
+//     (US1), unless TS2's live route shows otherwise — the measured
+//     fallback would add an `injectSteps` `systemMessage` in this handler.
+//
+//   * `agy:pre-invocation` — inject Mirror Mode context once per user turn.
+//     `PreInvocation` fires before EVERY model call (32 times over two
+//     turns, DS12.TS3 L2), with `invocationNum` resetting to 0 at each user
+//     turn; protojson omits zero-valued fields, so an ABSENT invocationNum
+//     is 0. The generated wrapper already gates on this before Node is
+//     spawned; the gate here is defense in depth. The injection is an
+//     `ephemeralMessage` — dropped after the turn — for two reasons: the
+//     adapter re-injects per turn, so a persistent step would accumulate;
+//     and the content is identity and memory, so ephemeral is the
+//     data-minimizing choice against agy's stored trajectory.
+//
+// agy payloads carry no prompt or reply text (L7): there is no `--query`,
+// and the explicit Mirror form reaches the model through the skill (L4),
+// never through these hooks. The quiet session — a `conversationId` no
+// runtime session binds (every session until TS3 lands), or one bound with
+// Mirror Mode off — answers `{}`: Mirror on agy is invisible until invoked.
+//
+// Payload fields stay inert: `conversationId` flows only through array
+// argv, never a shell, and failures recorded in hooks.log are facts, never
+// payload text.
+
+import { readAgyTurns } from "#conversation/agyTranscript.ts";
+import { isCommandTurn } from "#conversation/commandTurn.ts";
+import { logAssistantMessage, logUserMessage } from "#conversation/logger.ts";
+import { resolveDbPath } from "#frontDoor/dbPath.ts";
+import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
+import { decodeMetadata, getRuntimeSession, upsertRuntimeSession } from "#mirror/runtimeSession.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { readMirrorState } from "./mirrorState.ts";
+import { noteHookFailure, runFrontDoor, runFrontDoorQuietly } from "./runtime.ts";
+
+/** agy's empty answer, which every path that injects nothing must print. */
+const EMPTY = "{}\n";
+
+interface AgyPayload {
+  readonly conversationId: string;
+  readonly invocationNum: number;
+  readonly transcriptPath: string;
+}
+
+/** The key under which the Stop handler stores its high-water step_index. */
+const HIGH_WATER_KEY = "agy_last_step_index";
+
+/**
+ * Parse agy's camelCase protojson payload. Anything malformed reads as the
+ * empty payload: a hook never fails the turn over stdin it did not write.
+ */
+export function parseAgyPayload(stdin: string): AgyPayload {
+  try {
+    const raw: unknown = JSON.parse(stdin);
+    if (typeof raw !== "object" || raw === null) {
+      return { conversationId: "", invocationNum: 0, transcriptPath: "" };
+    }
+    const record = raw as Record<string, unknown>;
+    return {
+      conversationId: typeof record.conversationId === "string" ? record.conversationId : "",
+      // protojson omits zero-valued fields: absent IS 0.
+      invocationNum: typeof record.invocationNum === "number" ? record.invocationNum : 0,
+      transcriptPath: typeof record.transcriptPath === "string" ? record.transcriptPath : "",
+    };
+  } catch {
+    return { conversationId: "", invocationNum: 0, transcriptPath: "" };
+  }
+}
+
+/**
+ * `SessionStart`: logging on, activate Mirror Mode for the session, answer
+ * the contract.
+ *
+ * Mirror Mode activation (CV21.DS7.US4 scope change). agy's `PreInvocation`
+ * carries no prompt text (DS12.TS3 L7), so the injection hook cannot detect
+ * the Mirror form to self-activate, and the `/mirror-mind:mm:*` skill runs
+ * `mirror load` as an agent command that cannot bind the agy session id. So
+ * SessionStart — the one hook that carries the `conversationId` at the start
+ * of the session — sets `mirror_active`, and the per-turn `PreInvocation`
+ * injection (built in TS2, gated on that flag) fires from then on. This
+ * matches Gemini CLI's always-on per-turn injection, the runtime Antigravity
+ * replaces; a session that never ran SessionStart stays quiet, which the
+ * negative probe pins.
+ */
+export async function agySessionStart(stdin: string): Promise<number> {
+  await runFrontDoorQuietly("agy:session-start", ["conversation-logger", "session-start"]);
+
+  const conversationId = parseAgyPayload(stdin).conversationId;
+  if (conversationId) {
+    try {
+      const dbPath = resolveDbPath([], process.env);
+      const db = openLiveWriteDatabase(dbPath);
+      try {
+        upsertRuntimeSession(
+          db,
+          conversationId,
+          { interface: "antigravity", mirrorActive: true },
+          nowIso(),
+        );
+      } finally {
+        db.close();
+      }
+    } catch (error) {
+      noteHookFailure("agy:session-start", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  process.stdout.write(EMPTY);
+  return 0;
+}
+
+/**
+ * `Stop`: fires at the end of each user turn (agy has no SessionEnd hook).
+ * Read the transcript, append the turns past the stored high-water
+ * `step_index` as `antigravity`, and leave the conversation open — session
+ * maintenance closes it as a stale orphan, the path Codex uses (Shape A).
+ *
+ * A re-fired Stop, or a grown transcript whose turns are all logged, adds
+ * nothing: the high-water mark is the idempotency key. A skill turn is
+ * skipped, the one-home rule. Any failure is recorded in hooks.log, never
+ * fails the turn, and the handler always answers agy's contract.
+ */
+export async function agyStop(stdin: string): Promise<number> {
+  const payload = parseAgyPayload(stdin);
+  if (!payload.conversationId || !payload.transcriptPath) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  const turns = readAgyTurns(payload.transcriptPath);
+  if (turns.length === 0) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  let dbPath: string;
+  try {
+    dbPath = resolveDbPath([], process.env);
+  } catch {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  try {
+    const db = openLiveWriteDatabase(dbPath);
+    try {
+      const sessionId = payload.conversationId;
+      const existing = getRuntimeSession(db, sessionId);
+      const stored = decodeMetadata(existing?.metadata ?? null);
+      const highWater =
+        typeof stored[HIGH_WATER_KEY] === "number" ? (stored[HIGH_WATER_KEY] as number) : -1;
+      const deps = { newId, nowIso };
+      const options = { interface: "antigravity" };
+
+      let newHighWater = highWater;
+      for (const turn of turns) {
+        if (turn.lastStepIndex <= highWater) continue;
+        if (!isCommandTurn(turn.userText)) {
+          logUserMessage(db, sessionId, turn.userText, options, deps);
+          logAssistantMessage(db, sessionId, turn.replyText, options, deps);
+        }
+        if (turn.lastStepIndex > newHighWater) newHighWater = turn.lastStepIndex;
+      }
+
+      if (newHighWater !== highWater) {
+        const current = getRuntimeSession(db, sessionId);
+        const metadata = decodeMetadata(current?.metadata ?? null);
+        metadata[HIGH_WATER_KEY] = newHighWater;
+        upsertRuntimeSession(db, sessionId, { metadata: JSON.stringify(metadata) }, nowIso());
+      }
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    noteHookFailure("agy:stop", error instanceof Error ? error.message : String(error));
+  }
+
+  process.stdout.write(EMPTY);
+  return 0;
+}
+
+/** `PreInvocation`: one ephemeral context step per user turn, when owed. */
+export async function agyPreInvocation(stdin: string): Promise<number> {
+  const payload = parseAgyPayload(stdin);
+
+  // Defense in depth behind the wrapper's shell gate: only the turn's first
+  // invocation injects; the other ~30 answer instantly.
+  if (payload.invocationNum !== 0 || !payload.conversationId) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  let dbPath: string;
+  try {
+    dbPath = resolveDbPath([], process.env);
+  } catch {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  // The quiet session: unbound, or bound with Mirror Mode off.
+  const state = readMirrorState(dbPath, payload.conversationId);
+  if (!state.active) {
+    process.stdout.write(EMPTY);
+    return 0;
+  }
+
+  const argv = ["mirror", "load", "--context-only", "--session-id", payload.conversationId];
+  if (state.persona) argv.push("--persona", state.persona);
+  if (state.journey) argv.push("--journey", state.journey);
+
+  const result = await runFrontDoor(argv);
+  const context = result.stdout.trim() ? result.stdout : "";
+  process.stdout.write(
+    context ? `${JSON.stringify({ injectSteps: [{ ephemeralMessage: context }] })}\n` : EMPTY,
+  );
+  return 0;
+}

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/main.ts

@@ -4,12 +4,15 @@
 //
 // CV22.DS10.TS5 plateau 1, decision D4. Twelve shell scripts across four
 // runtimes each spawned the interpreter one to five times per event. They now
-// run one Node process and name which hook they are:
+// run one Node process and name which hook they are (the Gemini CLI family,
+// `gemini:*`, retired with CV21.DS8.US1; Antigravity is its successor):
 //
 //     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
@@ -33,44 +36,27 @@
 
 import { pathToFileURL } from "node:url";
 import { loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
+import { agyPreInvocation, agySessionStart, agyStop } from "./agy.ts";
 import { claudeHook } from "./claude.ts";
-import { codexSessionEnd, codexSessionStart } from "./codex.ts";
-import {
-  geminiLogAssistant,
-  geminiLogUser,
-  geminiSessionEnd,
-  geminiSessionStart,
-} from "./gemini.ts";
 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) {
     case "claude":
       return claudeHook(hook ?? "");
-    case "gemini":
+    case "agy":
+      // The Antigravity plugin's handlers (CV21.DS7.TS2), called through the
+      // generated agy-form wrappers in `plugins/mirror-mind/agy/`.
       switch (hook) {
-        case "log-user":
-          return geminiLogUser(readStdin());
-        case "log-assistant":
-          return geminiLogAssistant(readStdin());
-        case "session-end":
-          return geminiSessionEnd(readStdin());
         case "session-start":
-          return geminiSessionStart();
-        default:
-          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] ?? "");
+          return agySessionStart(readStdin());
+        case "pre-invocation":
+          return agyPreInvocation(readStdin());
+        case "stop":
+          return agyStop(readStdin());
         default:
           break;
       }
@@ -94,7 +80,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/hooks/payload.ts

@@ -1,8 +1,8 @@
 // Reading a runtime's hook payload from stdin.
 //
 // Replaces the Python hook module `extract_prompt` (25 lines) and the four
-// inline interpreter one-liners the Claude and Gemini hooks used to parse the
-// same JSON. None of them was a command, so none was in
+// inline interpreter one-liners the Claude and Gemini CLI hooks used to parse
+// the same JSON (the Gemini CLI hooks retired with CV21.DS8.US1). None of them was a command, so none was in
 // DS7's denominator of 29 -- which is why TS5's inventory had to find them by
 // reading the hooks rather than by counting commands.
 //
@@ -23,17 +23,11 @@ export interface HookPayload {
   readonly prompt: string;
   /** The runtime's session id (`session_id`, or Grok's `sessionId`), or "". */
   readonly sessionId: string;
-  /** The assistant's response text (Gemini's `prompt_response`), or "". */
-  readonly response: string;
-  /** Everything else, for hooks that need a field these three do not cover. */
+  /** Everything else, for hooks that need a field these two do not cover. */
   readonly raw: HookPayloadObject;
 }
 
-const EMPTY: HookPayload = { prompt: "", sessionId: "", response: "", raw: {} };
-
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
-}
+const EMPTY: HookPayload = { prompt: "", sessionId: "", raw: {} };
 
 /**
  * Parse a hook payload. Never throws: an unparseable payload is empty.
@@ -47,11 +41,10 @@ export function parseHookPayload(input: string): HookPayload {
   return {
     prompt: promptOf(raw),
     sessionId: sessionIdOf(raw),
-    // Gemini's AfterAgent payload names it `prompt_response`, and that is the
-    // field the Python hook read. The first port read three guessed names
-    // instead and dropped every Gemini assistant turn in silence until
-    // `smoke_gemini_cli.sh` caught it (CV22.DS10.TS5 plateau 3).
-    response: text(raw.prompt_response),
+    // A `response` field read Gemini CLI's `prompt_response` here until
+    // CV21.DS8.US1; no living runtime hands the reply to a hook payload by
+    // name (Claude-family hooks read the transcript, agy's Stop reads its
+    // JSONL), so the field went with its only reader.
     raw,
   };
 }

package/ts/src/hooks/runtime.ts

@@ -61,11 +61,11 @@ export function noteHookFailure(hook: string, reason: string, env = process.env)
  * The Operating Instructions a SessionStart hook should hand its runtime, or
  * null when the project already carries this same file.
  *
- * CV22.DS10.US3, decision D13. An installed package reaches Claude Code and
- * Gemini CLI through hooks, skills, and an MCP server; none of those reads a
- * CLAUDE.md or GEMINI.md, so a session wired to the package would answer
- * `/mm-mirror` and still route no mode, sign no persona, and hold no Builder
- * boundary. Both runtimes read SessionStart's
+ * CV22.DS10.US3, decision D13. An installed package reaches Claude Code (and
+ * reached Gemini CLI, until CV21.DS8.US1) through hooks, skills, and an MCP
+ * server; none of those reads a CLAUDE.md, so a session wired to the package
+ * would answer `/mm-mirror` and still route no mode, sign no persona, and hold
+ * no Builder boundary. The runtime reads SessionStart's
  * `hookSpecificOutput.additionalContext`, so the session-start hook returns
  * `AGENTS.md` from the tree THIS code runs from -- the instructions always
  * match the core they ship with -- unless the project the session opened in
@@ -92,8 +92,9 @@ export function operatingInstructionsFor(
 }
 
 /**
- * The SessionStart answer both runtimes read: context as JSON, or `nothing`
- * -- what each runtime's hook printed before D13 (Gemini `{}`, Claude none).
+ * The SessionStart answer the runtime reads: context as JSON, or `nothing`
+ * -- what the runtime's hook printed before D13 (Claude none; Gemini CLI's
+ * `{}`, until CV21.DS8.US1 retired it).
  */
 export function sessionStartOutput(instructions: string | null, nothing = ""): string {
   if (instructions === null) return nothing;
@@ -148,9 +149,9 @@ export async function runFrontDoor(
 /**
  * The command a failure line may name: the family and its subcommand, never
  * the arguments. Arguments are where hooks put what the user said and what the
- * model answered -- the Gemini logger passes the prompt and the response as
- * argv -- and the first version of the failure line printed all of them (TS5
- * handoff review, finding P1).
+ * model answered -- the Gemini CLI logger, retired by CV21.DS8.US1, passed the
+ * prompt and the response as argv -- and the first version of the failure
+ * line printed all of them (TS5 handoff review, finding P1).
  */
 function commandName(argv: readonly string[]): string {
   return argv.slice(0, 2).join(" ");

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>>;