mirror-mind 0.35.0 → 0.36.0

package/ts/src/runtime/extensionPluginWiring.ts

@@ -0,0 +1,222 @@
+// CV21.DS5.US2 — what each runtime holds of a home's extensions plugin, read from
+// the runtime's own files, and the lines a person reads about it.
+//
+// One reading serves two surfaces. `mirror extensions install|uninstall|sync` print
+// the block after their report: the runtimes on the PATH that still need a step, or
+// one line saying the plugin is wired everywhere. `mirror runtime diagnose` turns the
+// same reading into findings. The two cannot disagree because they do not read twice.
+//
+// Every home is taken from the env the caller hands in (HOME, CODEX_HOME,
+// GROK_HOME), never from the process: a test or a route passes stand-ins and a
+// maintainer's real wiring never reaches a fixture (CR123/128/137/142).
+//
+// For this plugin, stale is NOT EQUAL, not "less than": the home generates every
+// version, so a copy at a version the home does not hold is stale whichever way it
+// differs. A `runtime/plugin/` removed by hand restarts the generation at 1, and a
+// copy that then reads "ahead" must still fire (plan amendment 5).
+
+import { join } from "node:path";
+import type { ExtensionPluginReport } from "#extensions/extensionPlugin.ts";
+import {
+  agyPluginCopyState,
+  codexPluginCacheState,
+  grokPluginCopyState,
+  pluginLinkState,
+} from "./pluginWiring.ts";
+import {
+  detectRuntimes,
+  EXTENSION_PLUGIN_GROK_TRUST_NOTE,
+  type ExtensionPluginPaths,
+  extensionPluginReinstallCommand,
+  extensionPluginWiringSteps,
+  RUNTIME_WIRING,
+  type RuntimeName,
+} from "./wiring.ts";
+
+export type ExtensionPluginState = "not_wired" | "wired" | "stale" | "dangling" | "duplicated";
+
+export interface ExtensionPluginRuntimeState {
+  readonly runtime: RuntimeName;
+  readonly title: string;
+  readonly state: ExtensionPluginState;
+  /** What the runtime holds: `copy at 0.1.2`, `2 copies`, `link dangling`. */
+  readonly detail: string;
+  /** The path the finding names. */
+  readonly subject: string;
+  /** The commands that bring the runtime level, in order; empty when wired. */
+  readonly steps: readonly string[];
+}
+
+export interface ExtensionPluginHomes {
+  readonly home: string | null;
+  readonly codexHome: string | null;
+  readonly grokHome: string | null;
+  readonly geminiHome: string | null;
+}
+
+/** The homes, defaulted here from the env and never inside a reader. */
+export function extensionPluginHomes(env: NodeJS.ProcessEnv): ExtensionPluginHomes {
+  const home = env.HOME?.trim() || null;
+  return {
+    home,
+    codexHome: env.CODEX_HOME?.trim() || (home ? join(home, ".codex") : null),
+    grokHome: env.GROK_HOME?.trim() || (home ? join(home, ".grok") : null),
+    geminiHome: home ? join(home, ".gemini") : null,
+  };
+}
+
+export function extensionPluginPaths(plugin: ExtensionPluginReport): ExtensionPluginPaths {
+  return { dir: plugin.directory, marketplace: plugin.marketplaceRoot, name: plugin.name };
+}
+
+/** One runtime's reading. Pi takes extensions through its catalog and is never read. */
+export function extensionPluginRuntimeState(
+  runtime: RuntimeName,
+  plugin: ExtensionPluginReport,
+  homes: ExtensionPluginHomes,
+): ExtensionPluginRuntimeState | null {
+  const paths = extensionPluginPaths(plugin);
+  const title = RUNTIME_WIRING[runtime].title;
+  const wire = extensionPluginWiringSteps(runtime, paths);
+  const reinstall = extensionPluginReinstallCommand(runtime, paths);
+  const notWired = (subject: string): ExtensionPluginRuntimeState => ({
+    runtime,
+    title,
+    state: "not_wired",
+    detail: "not wired",
+    subject,
+    steps: wire,
+  });
+  const stale = (subject: string, held: string): ExtensionPluginRuntimeState => ({
+    runtime,
+    title,
+    state: "stale",
+    detail: `copy at ${held}`,
+    subject,
+    steps: reinstall === null ? [] : [reinstall],
+  });
+  const wired = (subject: string): ExtensionPluginRuntimeState => ({
+    runtime,
+    title,
+    state: "wired",
+    detail: "wired",
+    subject,
+    steps: [],
+  });
+
+  switch (runtime) {
+    case "pi":
+      return null;
+    case "claude": {
+      if (homes.home === null) return null;
+      const link = pluginLinkState(join(homes.home, ".claude", "skills", plugin.name));
+      if (link.state === "absent") return notWired(link.linkPath);
+      if (link.state === "dangling") {
+        return {
+          runtime,
+          title,
+          state: "dangling",
+          detail: `link dangling (points at ${link.target ?? "an unreadable target"})`,
+          subject: link.linkPath,
+          steps: [
+            `rm ~/.claude/skills/${plugin.name} && ln -s "${paths.dir}" ~/.claude/skills/${plugin.name}`,
+          ],
+        };
+      }
+      return wired(link.linkPath);
+    }
+    case "codex": {
+      if (homes.codexHome === null) return null;
+      const cache = codexPluginCacheState(homes.codexHome, plugin.version, {
+        marketplace: plugin.name,
+        name: plugin.name,
+      });
+      if (cache.state === "absent") return notWired(cache.cachePath);
+      if (cache.state === "current") return wired(cache.cachePath);
+      return stale(cache.cachePath, cache.newestCached ?? "?");
+    }
+    case "antigravity": {
+      if (homes.geminiHome === null) return null;
+      const copy = agyPluginCopyState(homes.geminiHome, plugin.version, plugin.name);
+      if (copy.state === "absent") return notWired(copy.copyPath);
+      if (copy.state === "current") return wired(copy.copyPath);
+      return stale(copy.copyPath, copy.copiedVersion ?? "?");
+    }
+    case "grok": {
+      if (homes.grokHome === null) return null;
+      const copy = grokPluginCopyState(homes.grokHome, plugin.version, plugin.name);
+      if (copy.copies.length > 1) {
+        return {
+          runtime,
+          title,
+          state: "duplicated",
+          detail: `${copy.copies.length} copies (${copy.copies.map((c) => `${c.key} at ${c.version}`).join(", ")}); Grok loads one and does not say which`,
+          subject: copy.registryPath,
+          steps: [
+            `grok plugin uninstall ${plugin.name} --confirm (until \`grok plugin list\` shows none)`,
+            ...(reinstall === null ? [] : [reinstall]),
+          ],
+        };
+      }
+      if (copy.state === "absent") return notWired(copy.registryPath);
+      const subject = copy.copies[0]?.path ?? copy.registryPath;
+      if (copy.state === "current") return wired(subject);
+      return stale(subject, copy.newestCopied ?? "?");
+    }
+  }
+}
+
+/** The readings for the runtimes on the PATH, in display order; Pi never appears. */
+export function extensionPluginStates(
+  plugin: ExtensionPluginReport,
+  env: NodeJS.ProcessEnv,
+  isExecutable: (path: string) => boolean,
+): ExtensionPluginRuntimeState[] {
+  const homes = extensionPluginHomes(env);
+  const states: ExtensionPluginRuntimeState[] = [];
+  for (const runtime of detectRuntimes(env, isExecutable)) {
+    const state = extensionPluginRuntimeState(runtime, plugin, homes);
+    if (state !== null) states.push(state);
+  }
+  return states;
+}
+
+/**
+ * The block a person reads after an `extensions` report: what needs action and
+ * nothing else (plan amendment 18); after an uninstall, a stale copy "still has"
+ * what was removed (amendment 19). With no runtime on the PATH, the first line alone.
+ */
+export function renderExtensionPluginBlock(
+  plugin: ExtensionPluginReport,
+  states: readonly ExtensionPluginRuntimeState[],
+  removed: readonly string[] = [],
+): string[] {
+  const skills = `${plugin.skills} skill${plugin.skills === 1 ? "" : "s"}`;
+  // An installed extension with no `claude` block is off the four runtimes, and the
+  // person is told which, not left to count (plan amendment 6 of the Debt Review).
+  const notCarried =
+    plugin.notCarried.length === 0
+      ? []
+      : [`    not carried (no claude block in skill.yaml): ${plugin.notCarried.join(", ")}`];
+  const actionable = states.filter((state) => state.state !== "wired");
+  if (states.length > 0 && actionable.length === 0) {
+    return [
+      `  plugin: ${plugin.name} ${plugin.version}, ${skills}, wired on ${states.map((s) => s.title).join(", ")}`,
+      ...notCarried,
+    ];
+  }
+  const lines = [`  plugin: ${plugin.name} ${plugin.version}, ${skills}`, ...notCarried];
+  for (const state of actionable) {
+    const detail =
+      state.state === "stale" && removed.length > 0
+        ? `still has ${removed.join(", ")}`
+        : state.detail;
+    const [first, ...rest] = state.steps;
+    lines.push(`    ${state.title}: ${detail}${first ? ` — ${first}` : ""}`);
+    for (const step of rest) lines.push(`    ${" ".repeat(state.title.length + 2)}then ${step}`);
+    if (state.runtime === "grok" && state.state === "not_wired") {
+      lines.push(`    ${" ".repeat(state.title.length + 2)}${EXTENSION_PLUGIN_GROK_TRUST_NOTE}`);
+    }
+  }
+  return lines;
+}

package/ts/src/runtime/pluginWiring.ts

@@ -1,15 +1,20 @@
-// The plugin wiring readers (CV21.DS4.TS6).
+// The plugin wiring readers (CV21.DS4.TS6; Grok in CV21.DS10.US1).
 //
-// Two runtimes hold the plugin outside the install tree. Codex copies it into
-// a versioned cache (`$CODEX_HOME/plugins/cache/mirror-mind/mirror-mind/
+// Three 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.
+// that copy. Grok copies it too, under `$GROK_HOME/installed-plugins/<name>-
+// <hash of the source path string>/`, recorded in `installed-plugins/
+// registry.json` (grok 1.0.62); its copy carries the plugin's own
+// `.claude-plugin/plugin.json`, so the version reads the same way the install
+// tree's does. Claude Code links the plugin in place (`~/.claude/skills/
+// mirror-mind`), so its failure mode is a dangling link, not a stale copy —
+// and Grok's rules link (`~/.grok/rules/mirror-mind.md`) fails the same way.
 //
-// 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.
+// Every reader takes its root as an ARGUMENT, always. The defaulting —
+// `$CODEX_HOME` else `~/.codex`, `$GROK_HOME` else `~/.grok`, 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.
@@ -25,13 +30,30 @@ import { lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from "no
 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",
-];
+/**
+ * A plugin as Codex caches it: `plugins/cache/<marketplace>/<name>/<version>`.
+ * The canonical plugin is `mirror-mind/mirror-mind`; a home's extensions
+ * plugin is `mirror-ext-<user>/mirror-ext-<user>` (CV21.DS5.US2).
+ */
+export interface CodexPluginIdentity {
+  readonly marketplace: string;
+  readonly name: string;
+}
+
+export const CANONICAL_CODEX_PLUGIN: CodexPluginIdentity = {
+  marketplace: "mirror-mind",
+  name: "mirror-mind",
+};
+
+/** Where Codex keeps a plugin's copies, below a Codex home. */
+export function codexPluginCacheSegments(
+  identity: CodexPluginIdentity = CANONICAL_CODEX_PLUGIN,
+): readonly string[] {
+  return ["plugins", "cache", identity.marketplace, identity.name];
+}
+
+/** The canonical plugin's cache path segments, as before DS5.US2. */
+export const CODEX_PLUGIN_CACHE_SEGMENTS: readonly string[] = codexPluginCacheSegments();
 
 export interface CodexCacheState {
   /** `absent` covers no cache and a cache with no version-named entry. */
@@ -46,6 +68,13 @@ export interface CodexCacheState {
  * 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.
  *
+ * `codex plugin add` REPLACES the cache directory (measured on 0.163.0,
+ * CV21.DS5.US2's Debt Review): after a re-add at 0.1.2 only `0.1.2` remains,
+ * and after a re-add at a lower 0.1.0 only `0.1.0`, which the prompt then
+ * lists. So the newest entry is the only entry, and a reader that compared a
+ * generation restarted below an older cache would still be reading what Codex
+ * loads.
+ *
  * `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.
@@ -53,8 +82,9 @@ export interface CodexCacheState {
 export function codexPluginCacheState(
   codexHome: string,
   installedVersion: string,
+  identity: CodexPluginIdentity = CANONICAL_CODEX_PLUGIN,
 ): CodexCacheState {
-  const cachePath = join(codexHome, ...CODEX_PLUGIN_CACHE_SEGMENTS);
+  const cachePath = join(codexHome, ...codexPluginCacheSegments(identity));
   let entries: string[];
   try {
     entries = readdirSync(cachePath);
@@ -77,8 +107,8 @@ export function codexPluginCacheState(
   return { state, cachePath, newestCached: newest };
 }
 
-export interface ClaudeLinkState {
-  /** `healthy` means the target reads — including a plain directory copy. */
+export interface LinkState {
+  /** `healthy` means the target reads — including a plain directory or file copy. */
   state: "absent" | "healthy" | "dangling";
   linkPath: string;
   /** The link's own target when it is a symlink, else null. */
@@ -86,13 +116,13 @@ export interface ClaudeLinkState {
 }
 
 /**
- * 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.
+ * Read one wiring link: Claude Code's plugin link (`~/.claude/skills/
+ * mirror-mind`) or Grok's rules link (`~/.grok/rules/mirror-mind.md`).
+ * 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");
+export function pluginLinkState(linkPath: string): LinkState {
   let isLink = false;
   try {
     isLink = lstatSync(linkPath).isSymbolicLink();
@@ -108,6 +138,111 @@ export function claudePluginLinkState(claudeHome: string): ClaudeLinkState {
   return { state: "healthy", linkPath, target };
 }
 
+/** Where Grok keeps its copies and their registry, below a Grok home. */
+export const GROK_INSTALLED_PLUGINS_SEGMENTS: readonly string[] = ["installed-plugins"];
+
+export interface GrokCopy {
+  /** The registry key: `<name>-<hash of the source path string>`. */
+  key: string;
+  path: string;
+  version: string;
+}
+
+export interface GrokCopyState {
+  /** `absent` covers no registry, no Mirror entry, and entries with no readable manifest. */
+  state: "absent" | "current" | "behind" | "ahead";
+  registryPath: string;
+  /** Every copy carrying the plugin, with its manifest version. */
+  copies: GrokCopy[];
+  /** The newest copy's version, by semver — never a string sort. */
+  newestCopied: string | null;
+}
+
+/**
+ * Read Grok's install registry below `grokHome`, read-only. The registry
+ * names each repo's `path` and the plugins it carries; a repo whose
+ * `plugins` include `mirror-mind` is a copy, and its version is the copy's
+ * own `.claude-plugin/plugin.json`, read by the same function the install
+ * tree uses. A registry that does not parse, or a copy with no manifest,
+ * claims nothing.
+ *
+ * The state is judged by the newest copy, as Codex's cache is. Two copies
+ * are a finding of their own at the diagnose entry: a respelt install path
+ * keys a second copy (probe, grok 1.0.62), and Grok loads one of them
+ * without saying which.
+ */
+export function grokPluginCopyState(
+  grokHome: string,
+  installedVersion: string,
+  pluginName = "mirror-mind",
+): GrokCopyState {
+  const registryPath = join(grokHome, ...GROK_INSTALLED_PLUGINS_SEGMENTS, "registry.json");
+  const copies: GrokCopy[] = [];
+  let repos: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(registryPath, "utf8"));
+    const candidate =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).repos
+        : undefined;
+    if (typeof candidate !== "object" || candidate === null) {
+      return { state: "absent", registryPath, copies, newestCopied: null };
+    }
+    repos = candidate as Record<string, unknown>;
+  } catch {
+    return { state: "absent", registryPath, copies, newestCopied: null };
+  }
+  for (const [key, entry] of Object.entries(repos)) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const repo = entry as Record<string, unknown>;
+    const plugins = repo.plugins;
+    if (typeof plugins !== "object" || plugins === null || !(pluginName in plugins)) continue;
+    const path =
+      typeof repo.path === "string"
+        ? repo.path
+        : join(grokHome, ...GROK_INSTALLED_PLUGINS_SEGMENTS, key);
+    const version = pluginManifestVersion(join(path, ".claude-plugin", "plugin.json"));
+    if (version === null) continue;
+    copies.push({ key, path, version });
+  }
+  if (copies.length === 0) return { state: "absent", registryPath, copies, newestCopied: null };
+  let newest: string | null = null;
+  for (const copy of copies) {
+    if (newest === null || compareSemver(copy.version, newest) > 0) newest = copy.version;
+  }
+  const order = compareSemver(newest as string, installedVersion);
+  const state = order < 0 ? "behind" : order > 0 ? "ahead" : "current";
+  return { state, registryPath, copies, newestCopied: newest };
+}
+
+export interface AgyCopyState {
+  /** `absent` covers no staged tree and a staged tree with no readable manifest. */
+  state: "absent" | "current" | "behind" | "ahead";
+  copyPath: string;
+  copiedVersion: string | null;
+}
+
+/**
+ * Read agy's staged copy of a plugin below a `.gemini` home, read-only:
+ * `agy plugin install <dir>` stages the tree under `config/plugins/<name>/`
+ * (CV21.DS7.US1), and the copy's own `.claude-plugin/plugin.json` carries
+ * its version. Written for the extensions plugin (CV21.DS5.US2); the
+ * canonical plugin has no agy finding yet, and this reader serves it when
+ * one is added.
+ */
+export function agyPluginCopyState(
+  geminiHome: string,
+  installedVersion: string,
+  pluginName: string,
+): AgyCopyState {
+  const copyPath = join(geminiHome, "config", "plugins", pluginName);
+  const copiedVersion = pluginManifestVersion(join(copyPath, ".claude-plugin", "plugin.json"));
+  if (copiedVersion === null) return { state: "absent", copyPath, copiedVersion: null };
+  const order = compareSemver(copiedVersion, installedVersion);
+  const state = order < 0 ? "behind" : order > 0 ? "ahead" : "current";
+  return { state, copyPath, copiedVersion };
+}
+
 /**
  * The install tree's own plugin version, from the generated manifest.
  * `plugins/mirror-mind/.claude-plugin/plugin.json` is written by
@@ -118,11 +253,15 @@ export function claudePluginLinkState(claudeHome: string): ClaudeLinkState {
  * but the tree it reads has already landed the new one.
  */
 export function installedPluginVersion(installRoot: string): string | null {
+  return pluginManifestVersion(
+    join(installRoot, "plugins", "mirror-mind", ".claude-plugin", "plugin.json"),
+  );
+}
+
+/** The `version` of one plugin manifest on disk, or null when it does not read. */
+function pluginManifestVersion(manifestPath: string): string | null {
   try {
-    const raw = readFileSync(
-      join(installRoot, "plugins", "mirror-mind", ".claude-plugin", "plugin.json"),
-      "utf8",
-    );
+    const raw = readFileSync(manifestPath, "utf8");
     const parsed: unknown = JSON.parse(raw);
     const version =
       typeof parsed === "object" && parsed !== null

package/ts/src/runtime/status.ts

@@ -17,10 +17,11 @@
 // the 2026-09-07 decision assigned to CV22.DS10.
 
 import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { type Database, openDatabaseReadOnly } from "#db/database.ts";
 import { KNOWN_MIGRATION_IDS } from "#db/schemaState.ts";
 import { ExtensionError } from "#extensions/errors.ts";
+import { readExtensionPlugin } from "#extensions/extensionPlugin.ts";
 import { loadExtensionManifest } from "#extensions/manifest.ts";
 import { inspectMigrationFiles } from "#extensions/migrations.ts";
 import { type DbPathEnv, dbNameForEnv, resolveMirrorHome } from "#frontDoor/dbPath.ts";
@@ -61,6 +62,12 @@ export interface ExtensionHealth {
   unknown_migrations: string[];
 }
 
+export interface ExtensionPluginSummary {
+  name: string;
+  version: string;
+  skills: number;
+}
+
 export interface RuntimeStatusReport {
   version: string;
   /** How the running front door is installed (CV22.DS10.US3 plateau 4; US2 D3). */
@@ -73,6 +80,8 @@ export interface RuntimeStatusReport {
   core_migrations: CoreMigrationHealth;
   extensions: string[];
   extension_health: ExtensionHealth[];
+  /** The home's generated extensions plugin (CV21.DS5.US2), or null when none. */
+  extension_plugin: ExtensionPluginSummary | null;
   clone_role: MarkerValue;
   memory_env: string;
   update_channel: MarkerValue;
@@ -425,6 +434,7 @@ export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeSta
     core_migrations: inspectCoreMigrations(dbPath, dbExists),
     extensions: listInstalledExtensions(mirrorHome),
     extension_health: inspectExtensionHealth(mirrorHome, dbPath, dbExists),
+    extension_plugin: inspectExtensionPlugin(mirrorHome),
     clone_role: cloneRoleFor(install, root),
     memory_env: memoryEnv,
     update_channel: channelForReport(install, root, env, undefined, options.channel ?? null),
@@ -461,6 +471,18 @@ export function renderCoreMigrations(item: CoreMigrationHealth): string {
   return `Core migrations: attention needed (${detail})`;
 }
 
+/** The generated extensions plugin, read from its manifest; absent is null, not an error. */
+export function inspectExtensionPlugin(mirrorHome: string | null): ExtensionPluginSummary | null {
+  if (mirrorHome === null) return null;
+  const previous = readExtensionPlugin(mirrorHome);
+  if (previous === null) return null;
+  return {
+    name: `mirror-ext-${basename(mirrorHome)}`,
+    version: `0.1.${previous.generation}`,
+    skills: Object.keys(previous.files).filter((path) => path.endsWith("/SKILL.md")).length,
+  };
+}
+
 /** Port of `_render_extension_health`. */
 export function renderExtensionHealth(items: readonly ExtensionHealth[]): string[] {
   if (items.length === 0) return ["Extension health: ready (0 checked)"];
@@ -528,6 +550,11 @@ export function renderRuntimeStatus(
     lines.push("Installed extensions: 0");
   }
   lines.push(...renderExtensionHealth(report.extension_health));
+  // Printed only when the home has one, so a report without extensions reads as before.
+  if (report.extension_plugin) {
+    const { name, version, skills } = report.extension_plugin;
+    lines.push(`Extensions plugin: ${name} ${version} (${skills} skill${skills === 1 ? "" : "s"})`);
+  }
   lines.push(...renderCloneRoleLines(report.install, report.clone_role));
   lines.push(`Update channel: ${report.update_channel.value}`);
   if (report.update_channel.note) lines.push(`Update channel note: ${report.update_channel.note}`);

package/ts/src/runtime/update.ts

@@ -29,7 +29,11 @@ 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 {
+  codexPluginCacheState,
+  grokPluginCopyState,
+  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";
@@ -39,7 +43,7 @@ import {
   type UpdateResult,
   type UpdateStage,
 } from "#runtime/updatePipeline.ts";
-import { CODEX_PLUGIN_ADD_COMMAND } from "#runtime/wiring.ts";
+import { CODEX_PLUGIN_ADD_COMMAND, grokPluginReinstallCommand } from "#runtime/wiring.ts";
 import { commandOnPath } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { shellWord } from "#util/shellWord.ts";
@@ -431,15 +435,25 @@ export function postUpdateHints(
         : 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.`,
-        );
-      }
+  const grokHome = env.GROK_HOME?.trim() || (home ? join(home, ".grok") : null);
+  const landed = installRoot ? installedPluginVersion(installRoot) : null;
+  if (installRoot && codexHome && 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.`,
+      );
+    }
+  }
+  // CV21.DS10.US1: Grok copies the plugin too, and its update verb leaves a
+  // local-path copy as it is; the level-up is uninstall, then install with
+  // the path init printed.
+  if (installRoot && grokHome && landed) {
+    const copy = grokPluginCopyState(grokHome, landed);
+    if (copy.state === "behind") {
+      hints.push(
+        `Grok's copy of the plugin is behind the update (${copy.newestCopied} < ${landed}): run \`${grokPluginReinstallCommand(installRoot)}\` to bring it level.`,
+      );
     }
   }