mirror-mind 0.35.0 → 0.36.0

package/ts/src/extensions/settings.ts

@@ -0,0 +1,147 @@
+// An extension's installation settings: `<mirror-home>/extensions/<id>.env` (CR145).
+//
+// The `mirror-cli-v1` and `mirror-context-v1` contracts hand a spawned
+// extension the environment the `mirror` process had, and nothing else. That
+// left an extension's own installation settings -- which host, which TLS mode,
+// which certificate on this machine -- with nowhere to live but the login
+// shell, where two of them (`PGSSLMODE`, `NODE_EXTRA_CA_CERTS`) broke every
+// other Postgres client and Node process on the machine. Node reads
+// `NODE_EXTRA_CA_CERTS` before any extension code runs, so only the spawner can
+// set it, and the spawner is Mirror.
+//
+// The file sits BESIDE the installed directory, not inside it, for two reasons
+// measured on the maintainer's machine: `extensions install` rewrites the
+// directory, and in a development home the directory is a symlink into the
+// extension's own git repository, where a `.env` would be one `git add .` away
+// from a push.
+//
+// Precedence is the ecosystem's and Mirror's own (`runtime/config.ts`): a
+// variable already in the environment wins, the file fills the gaps, and the
+// five `MIRROR_*` names the dispatcher owns can never come from the file. The
+// merged environment reaches the one spawned process; `process.env` is read,
+// never written.
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { extensionsRootForHome } from "./catalog.ts";
+import { SKILL_ID_RE } from "./manifest.ts";
+
+/**
+ * The names the dispatcher sets last for a subcommand, and that a provider
+ * receives on stdin rather than in its environment. Dropped from the file at
+ * the merge, at both spawn points, so the file can steer neither.
+ */
+export const RESERVED_SETTINGS_NAMES: readonly string[] = [
+  "MIRROR_HOME",
+  "MIRROR_DATABASE_PATH",
+  "MIRROR_EXTENSION_ID",
+  "MIRROR_EXTENSION_ROOT",
+  "MIRROR_TABLE_PREFIX",
+];
+
+export type ExtensionSettings =
+  | { kind: "absent"; path: string }
+  | {
+      kind: "read";
+      path: string;
+      /** Sorted by name, as `parseEnv` yields them; a duplicate key's last value. */
+      variables: Record<string, string>;
+      /** The mode, when group or others can read the file; null when only the owner can. */
+      exposedMode: string | null;
+    }
+  | { kind: "unreadable"; path: string; reason: string };
+
+export function extensionSettingsPath(mirrorHome: string, extensionId: string): string {
+  return join(extensionsRootForHome(mirrorHome), `${extensionId}.env`);
+}
+
+/**
+ * Read the settings file, as a result and never a throw.
+ *
+ * An id outside the manifest's grammar is `unreadable` before any path is
+ * built: the context runtime takes ids from `_ext_bindings` rows, and a path
+ * must not be steerable by database content. "Unreadable" is the fail-closed
+ * answer at both call sites -- the dispatcher refuses, the provider reports.
+ *
+ * A UTF-8 BOM is stripped before parsing: `parseEnv` would otherwise keep it
+ * in the first key's name, and the editor that wrote it never shows it.
+ */
+export function readExtensionSettings(mirrorHome: string, extensionId: string): ExtensionSettings {
+  if (!SKILL_ID_RE.test(extensionId)) {
+    return {
+      kind: "unreadable",
+      path: join(extensionsRootForHome(mirrorHome), "<id>.env"),
+      reason: `'${extensionId}' is not a valid extension id`,
+    };
+  }
+  const path = extensionSettingsPath(mirrorHome, extensionId);
+  let text: string;
+  let mode: number;
+  try {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    if (stat === undefined) return { kind: "absent", path };
+    mode = stat.mode;
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return { kind: "unreadable", path, reason: code ?? (error as Error).message };
+  }
+  const variables: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parseEnv(text.replace(/^\uFEFF/, "")))) {
+    if (value !== undefined) variables[key] = value;
+  }
+  return { kind: "read", path, variables, exposedMode: exposedModeOf(mode) };
+}
+
+/**
+ * The file's mode as `0644` when group or others can read it, else null.
+ * Mode bits mean nothing on Windows, where every file would read as exposed.
+ */
+function exposedModeOf(mode: number): string | null {
+  if (process.platform === "win32") return null;
+  const permissions = mode & 0o777;
+  return (permissions & 0o044) === 0 ? null : `0${permissions.toString(8)}`;
+}
+
+/**
+ * The file UNDER the environment: `{ ...file, ...environment }`, with the
+ * reserved names removed from the file first. A key present in the
+ * environment -- even as an empty string -- is already set and wins, the rule
+ * `loadEnvFileWithoutOverride` applies to the home's own files.
+ */
+export function settingsUnderEnvironment(
+  environment: NodeJS.ProcessEnv,
+  settings: ExtensionSettings,
+): NodeJS.ProcessEnv {
+  if (settings.kind !== "read") return { ...environment };
+  const fromFile: Record<string, string> = {};
+  for (const [key, value] of Object.entries(settings.variables)) {
+    if (RESERVED_SETTINGS_NAMES.includes(key)) continue;
+    fromFile[key] = value;
+  }
+  return { ...fromFile, ...environment };
+}
+
+/**
+ * The `ext <id>` listing's last line. Keys only, never a value: a key's name
+ * says a setting exists, which is what a person checking the file needs; its
+ * value is what must not end up in a transcript.
+ */
+export function describeExtensionSettings(settings: ExtensionSettings): string {
+  switch (settings.kind) {
+    case "absent":
+      return `settings: ${settings.path} (not present — create it to pass settings to this extension)`;
+    case "unreadable":
+      return `settings: ${settings.path} (unreadable: ${settings.reason})`;
+    case "read": {
+      const keys = Object.keys(settings.variables);
+      const state = keys.length === 0 ? "no variables" : keys.join(", ");
+      const exposure =
+        settings.exposedMode === null
+          ? ""
+          : `; mode ${settings.exposedMode}, readable by other users`;
+      return `settings: ${settings.path} (${state}${exposure})`;
+    }
+  }
+}

package/ts/src/frontDoor/cli.ts

@@ -19,7 +19,7 @@
 // so neither a `bin` shim nor a skill line needs `--env-file` or
 // `NODE_OPTIONS=--no-warnings`. Importing this module does neither.
 
-import { existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
@@ -68,6 +68,7 @@ import {
   JOURNAL_TRANSPORT,
   WEEK_PLAN_TRANSPORT,
 } from "#providers/transport.ts";
+import { exitQuietlyOnBrokenPipe } from "#runtime/brokenPipe.ts";
 import {
   configFilePath,
   loadConfiguration,
@@ -769,6 +770,17 @@ async function runExtensionCatalog(argv: readonly string[]): Promise<DispatchOut
     deps: { nowIso: () => pythonUtcIsoformat() },
     withReadOnlyDatabase: (run) => withMirrorReadDb(argv, run),
     withWritableDatabase: (run) => withMirrorWriteDb(argv, run),
+    // CV21.DS5.US2: the extensions-plugin readers take their homes and the
+    // PATH from the process environment here, and from nowhere else.
+    environment: process.env,
+    isExecutable: (path) => {
+      try {
+        accessSync(path, constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    },
   });
 }
 
@@ -1871,6 +1883,9 @@ export async function main(rawArgv = process.argv.slice(2)): Promise<number> {
  */
 export async function runAsEntry(rawArgv = process.argv.slice(2)): Promise<number> {
   silenceExperimentalWarnings();
+  // Before anything that could write (CR148): `mirror … | head -1` ends
+  // quietly, exit 0, instead of an unhandled EPIPE and a stack trace.
+  exitQuietlyOnBrokenPipe(process.exit);
   loadConfiguration({ entryPath: import.meta.filename });
   return main(rawArgv);
 }

package/ts/src/frontDoor/extensionCatalogRoute.ts

@@ -62,6 +62,8 @@ export interface ExtensionRouteDeps {
     run: (db: WritableDatabase) => Promise<number> | number,
   ) => Promise<number>;
   environment?: NodeJS.ProcessEnv;
+  /** Whether a PATH candidate is executable, for the extensions-plugin block (CV21.DS5.US2). */
+  isExecutable?: (path: string) => boolean;
 }
 
 /** The `extensions` verbs that need a writable handle; the rest read. */
@@ -140,7 +142,11 @@ function firstPositional(args: readonly string[]): string | null {
 }
 
 function readContextFor(route: ExtensionRouteDeps): CatalogContext {
-  return { mirrorHome: route.mirrorHome };
+  return {
+    mirrorHome: route.mirrorHome,
+    ...(route.environment ? { env: route.environment } : {}),
+    ...(route.isExecutable ? { isExecutable: route.isExecutable } : {}),
+  };
 }
 
 function dispatchOptions(route: ExtensionRouteDeps) {
@@ -151,7 +157,7 @@ function dispatchOptions(route: ExtensionRouteDeps) {
 }
 
 function writeContextFor(route: ExtensionRouteDeps, db: WritableDatabase): ExtWriteContext {
-  return { mirrorHome: route.mirrorHome, db, deps: route.deps };
+  return { ...readContextFor(route), db, deps: route.deps };
 }
 
 export async function runExtensionCatalogRoute(

package/ts/src/frontDoor/runtimeRoute.ts

@@ -24,6 +24,7 @@ import {
 import { channelFor, channelForReport, renderChannel, setChannel } from "#runtime/channel.ts";
 import {
   diagnoseRuntime,
+  extensionPluginFindings,
   hookFailureFindings,
   hookNodeFindings,
   pluginWiringFindings,
@@ -336,6 +337,16 @@ export async function runRuntimeReadRoute(
       // after an npm update; Claude Code's link can dangle. Absence is not
       // drift, so an unwired machine stays green.
       ...pluginWiringFindings(installRoot, env),
+      // CV21.DS5.US2: the home's extensions plugin, as each runtime on the
+      // PATH holds it. A stale copy is any version other than the home's.
+      ...extensionPluginFindings(report.mirror_home, env, (path) => {
+        try {
+          accessSync(path, constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      }),
       // 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

@@ -193,14 +193,31 @@ export function marketplaceJson(): string {
 // (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 };
+//
+// The marker is also what GROK reads (CV21.DS10.US1). Grok accepts a root
+// `plugin.json` and the `.claude-plugin/` equivalent, and takes the root one
+// first and alone: with a name-only marker, `grok plugin validate` dropped
+// "MCP servers" from the components it had listed on 1.0.52, `plugin list`
+// reported `version: null`, and no shape of install offered the MCP server
+// (probe on grok 1.0.62, 2026-10-18, story package). So the marker carries
+// the manifest's `version` and `mcpServers`, from the same source; agy 1.4.2
+// warns `unknown field "mcpServers" is ignored` and stages the same tree.
+// Hooks stay out of it: agy reads the root `hooks.json` beside it.
+
+/** The native-plugin marker: agy's detection, and the manifest Grok reads. */
+export function buildAgyPluginMarker(version: string): Record<string, unknown> {
+  return {
+    name: PLUGIN_NAME,
+    description: PLUGIN_DESCRIPTION,
+    version,
+    mcpServers: {
+      [PLUGIN_NAME]: { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] },
+    },
+  };
 }
 
-export function agyPluginMarkerJson(): string {
-  return `${JSON.stringify(buildAgyPluginMarker(), null, 2)}\n`;
+export function agyPluginMarkerJson(version: string): string {
+  return `${JSON.stringify(buildAgyPluginMarker(version), null, 2)}\n`;
 }
 
 /**
@@ -335,7 +352,7 @@ export function planGeneratedFiles(repoRoot: string): GeneratedFile[] {
     },
     { relativePath: MARKETPLACE_PATH, content: marketplaceJson() },
     // The agy-native layer (CV21.DS7.US1).
-    { relativePath: join(PLUGIN_DIR, "plugin.json"), content: agyPluginMarkerJson() },
+    { relativePath: join(PLUGIN_DIR, "plugin.json"), content: agyPluginMarkerJson(version) },
     { relativePath: join(PLUGIN_DIR, "hooks.json"), content: agyHooksJson() },
     { relativePath: join(PLUGIN_DIR, "mcp_config.json"), content: agyMcpConfigJson() },
     {

package/ts/src/hooks/claude.ts

@@ -11,6 +11,7 @@
 // for every prompt and the logger decides), a missing session id still fails
 // loud, and every failure is still non-fatal to the user's turn.
 
+import { runtimeReadsPromptContext } from "#conversation/runtimePolicy.ts";
 import { resolveDbPath } from "#frontDoor/dbPath.ts";
 import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
 import { mirrorForm } from "#mirror/mirrorForm.ts";
@@ -124,6 +125,11 @@ export async function claudeSessionEnd(stdin: string): Promise<number> {
  */
 export async function claudeInject(stdin: string): Promise<number> {
   const payload = parseHookPayload(stdin);
+  // CR143: on a runtime that discards what this hook returns (Grok), neither
+  // case is worth its load — nor the state read below, nor the "injected"
+  // mark, which would say the model received what it did not. Detected the
+  // way the sibling hooks detect it, from the payload and the environment.
+  if (!runtimeReadsPromptContext(detectHookRuntime(payload.raw))) return 0;
   const sessionId = payload.sessionId;
 
   // Case 1: the explicit invocation.

package/ts/src/hooks/main.ts

@@ -35,6 +35,7 @@
 // why this file must exit 0: the wrappers read any other exit as Node failing.
 
 import { pathToFileURL } from "node:url";
+import { exitQuietlyOnBrokenPipe } from "#runtime/brokenPipe.ts";
 import { loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
 import { agyPreInvocation, agySessionStart, agyStop } from "./agy.ts";
 import { claudeHook } from "./claude.ts";
@@ -77,8 +78,18 @@ async function dispatch(name: string): Promise<number> {
  */
 export async function runAsEntry(rawArgv = process.argv.slice(2)): Promise<number> {
   silenceExperimentalWarnings();
-  loadConfiguration({ entryPath: import.meta.filename });
   const name = rawArgv[0] ?? "";
+  // The try/catch below is the last line of defense, and it has one hole: a
+  // stream's `error` event is not a throw in that `await` chain. A runtime
+  // that gives up on a hook closes its pipe, and until CR148 the hook answered
+  // the next write with an unhandled EPIPE, a stack trace into the host's log,
+  // and exit 1 -- the one exit code this entry promises never to return. One
+  // line in `hooks.log`, then the quiet exit the contract requires.
+  exitQuietlyOnBrokenPipe((code) => {
+    noteHookFailure(name || "hooks", "stdout closed early");
+    process.exit(code);
+  });
+  loadConfiguration({ entryPath: import.meta.filename });
   try {
     return await dispatch(name);
   } catch (error) {

package/ts/src/runtime/brokenPipe.ts

@@ -0,0 +1,52 @@
+// A closed stdout or stderr ends the command quietly (CR148).
+//
+// `mirror ext <id> | head -1` is a shell idiom, not an error: `head`, `tail`,
+// a pager that quit, a `grep -q` that matched -- every one of them closes its
+// read end on purpose. Node ignores SIGPIPE and surfaces the next write as an
+// `error` event on the stream, and with nobody listening that event is an
+// uncaught exception: `Unhandled 'error' event`, `Error: write EPIPE`, a
+// stack, exit 1. Nothing of ours failed; the reader asked us to stop.
+//
+// One listener at each entry (`frontDoor/cli.ts`, `hooks/main.ts`), nothing
+// per route. On EPIPE: exit 0 and write nothing. The exit status follows
+// `npm`, `cargo`, and `kubectl`, not git's 141: under `set -o pipefail`, 141
+// fails a pipeline the person wrote on purpose, and the fix they reach for is
+// `|| true`, which then hides the real failures too.
+//
+// Stop means stop. The exit happens at the next write after the reader
+// closes, and work the command had not done by then -- a commit after a
+// progress line, a log after an `await` -- is abandoned, exactly as SIGPIPE
+// abandons git's. That is the shell's contract, recorded in the CR.
+//
+// Anything that is not EPIPE is rethrown: a real stream failure keeps the
+// trace it had before. On Linux pipes are synchronous and on macOS
+// asynchronous; in both the failure arrives as this event, never as a throw
+// from `write()`. libuv maps ERROR_BROKEN_PIPE to EPIPE on Windows.
+
+type Exit = (code: number) => void;
+
+/**
+ * Install the handler. `exit` is `process.exit` for the CLI; the hook passes
+ * one that leaves a line in `hooks.log` first, because the hook's promise
+ * that every path returns 0 cannot be kept by its try/catch -- a stream's
+ * `error` event is not a throw in that `await` chain.
+ *
+ * Called once per process by `runAsEntry`; no guard against a second call,
+ * because there is no second call, and no test runs an entry in-process.
+ */
+export function exitQuietlyOnBrokenPipe(
+  exit: Exit,
+  streams: readonly NodeJS.WritableStream[] = [process.stdout, process.stderr],
+): void {
+  let exiting = false;
+  for (const stream of streams) {
+    stream.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code !== "EPIPE") throw error;
+      // Both streams on one pipe (`2>&1 | head`) fail together. A real
+      // `process.exit` never returns; an injected one must still count once.
+      if (exiting) return;
+      exiting = true;
+      exit(0);
+    });
+  }
+}

package/ts/src/runtime/diagnose.ts

@@ -25,19 +25,28 @@
 // inconclusive without a key; the live fetch belongs to DS8.
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { openDatabaseReadOnly } from "#db/database.ts";
+import {
+  type ExtensionPluginReport,
+  extensionPluginDirectory,
+  extensionPluginRoot,
+  readExtensionPlugin,
+} from "#extensions/extensionPlugin.ts";
 import { identityKeyBreaksGrammar, SLUG_KEYED_LAYERS } from "#identity/identityKey.ts";
 import { pyRepr, sortByCodePoint } from "#util/pythonText.ts";
 import { configFilePath } from "./config.ts";
+import { extensionPluginStates } from "./extensionPluginWiring.ts";
 import type { GitWorktreeEntry } from "./git.ts";
 import {
-  claudePluginLinkState,
   codexPluginCacheState,
+  grokPluginCopyState,
   installedPluginVersion,
+  pluginLinkState,
 } from "./pluginWiring.ts";
+
 import type { RuntimeStatusReport } from "./status.ts";
-import { CODEX_PLUGIN_ADD_COMMAND } from "./wiring.ts";
+import { CODEX_PLUGIN_ADD_COMMAND, grokPluginReinstallCommand } from "./wiring.ts";
 
 export interface DriftFinding {
   code: string;
@@ -504,16 +513,19 @@ export function diagnoseRuntime(
 }
 
 /**
- * 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 plugin wiring findings (CV21.DS4.TS6; the debt US1 carried; Grok in
+ * CV21.DS10.US1). Codex and Grok copy the plugin, so an npm update leaves
+ * the copy behind; Claude Code links it in place, so its failure mode is a
+ * dangling link, and Grok's rules link fails the same way. Grok adds one
+ * failure of its own: a respelt install path keys a SECOND copy, and Grok
+ * loads one of the two without saying which. Absence is not drift: no
+ * cache, no registry, 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).
+ * else ~/.codex, GROK_HOME else ~/.grok, 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,
@@ -539,7 +551,7 @@ export function pluginWiringFindings(
   }
 
   if (home) {
-    const link = claudePluginLinkState(join(home, ".claude"));
+    const link = pluginLinkState(join(home, ".claude", "skills", "mirror-mind"));
     if (link.state === "dangling") {
       findings.push({
         code: "claude_plugin_link_dangling",
@@ -547,7 +559,50 @@ export function pluginWiringFindings(
         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',
+          'relink it — `rm ~/.claude/skills/mirror-mind && 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",
+      });
+    }
+  }
+
+  const grokHome = env.GROK_HOME?.trim() || (home ? join(home, ".grok") : null);
+  if (grokHome && installedVersion && installRoot) {
+    const copy = grokPluginCopyState(grokHome, installedVersion);
+    const reinstall = grokPluginReinstallCommand(installRoot);
+    if (copy.copies.length > 1) {
+      findings.push({
+        code: "grok_plugin_copies_duplicated",
+        severity: "warning",
+        subject: copy.registryPath,
+        detail: `${copy.copies.length} copies of the plugin are installed (${copy.copies.map((c) => `${c.key} at ${c.version}`).join(", ")}); Grok loads one of them and does not say which`,
+        recommendation: `run \`grok plugin uninstall mirror-mind --confirm\` until \`grok plugin list\` shows none, then \`${reinstall}\` (a plugin installed from a differently spelt path is a second copy, not an update)`,
+        repair_route: reinstall,
+      });
+    }
+    if (copy.state === "behind") {
+      findings.push({
+        code: "grok_plugin_copy_behind",
+        severity: "warning",
+        subject:
+          copy.copies.length === 1
+            ? (copy.copies[0]?.path ?? copy.registryPath)
+            : copy.registryPath,
+        detail: `copied ${copy.newestCopied} < installed ${installedVersion}; Grok runs the copy it made at install`,
+        recommendation: `run \`${reinstall}\` to bring the copy level (\`grok plugin update\` leaves a local-path copy as it is, and an install over the same path is refused)`,
+        repair_route: reinstall,
+      });
+    }
+  }
+  if (grokHome) {
+    const rules = pluginLinkState(join(grokHome, "rules", "mirror-mind.md"));
+    if (rules.state === "dangling") {
+      findings.push({
+        code: "grok_rules_link_dangling",
+        severity: "warning",
+        subject: rules.linkPath,
+        detail: `the link points at ${rules.target ?? "an unreadable target"}, which cannot be read; Grok loads no Operating Instructions and says nothing`,
+        recommendation:
+          'relink it — `ln -s "<pkg>/AGENTS.md" ~/.grok/rules/mirror-mind.md` — or remove it if Grok Build is no longer wired',
         repair_route: "relink or remove",
       });
     }
@@ -798,3 +853,57 @@ export function hookNodeFindings(
     },
   ];
 }
+
+/**
+ * The extensions plugin findings (CV21.DS5.US2): the same reading the `extensions`
+ * verbs print, as drift. A home with no plugin, a runtime not wired, and a runtime
+ * off the PATH are silence; a dangling link, a stale copy (any version other than
+ * the home's), and two Grok copies are warnings, each naming its repair.
+ */
+export function extensionPluginFindings(
+  mirrorHome: string | null,
+  env: NodeJS.ProcessEnv,
+  isExecutable: (path: string) => boolean,
+): DriftFinding[] {
+  if (mirrorHome === null) return [];
+  const previous = readExtensionPlugin(mirrorHome);
+  if (previous === null) return [];
+  const name = `mirror-ext-${basename(mirrorHome)}`;
+  const skills = Object.keys(previous.files).filter((path) => path.endsWith("/SKILL.md")).length;
+  const plugin: ExtensionPluginReport = {
+    name,
+    directory: extensionPluginDirectory(mirrorHome),
+    marketplaceRoot: extensionPluginRoot(mirrorHome),
+    version: `0.1.${previous.generation}`,
+    skills,
+    changed: false,
+    notCarried: [],
+  };
+  const findings: DriftFinding[] = [];
+  for (const state of extensionPluginStates(plugin, env, isExecutable)) {
+    if (state.state === "wired" || state.state === "not_wired") continue;
+    const code =
+      state.state === "dangling"
+        ? "ext_plugin_claude_link_dangling"
+        : state.state === "duplicated"
+          ? "ext_plugin_grok_copies_duplicated"
+          : state.runtime === "codex"
+            ? "ext_plugin_codex_cache_stale"
+            : state.runtime === "antigravity"
+              ? "ext_plugin_agy_copy_stale"
+              : "ext_plugin_grok_copy_stale";
+    const repair = state.steps.join("; then ");
+    findings.push({
+      code,
+      severity: "warning",
+      subject: state.subject,
+      detail:
+        state.state === "stale"
+          ? `${state.detail}, the home generates ${plugin.version}; ${state.title} runs the copy it made at install`
+          : state.detail,
+      recommendation: `run \`${repair}\` to bring ${state.title}'s copy of ${plugin.name} level`,
+      repair_route: repair,
+    });
+  }
+  return findings;
+}