mirror-mind 0.35.0 → 0.36.1

package/ts/src/guards/retiredSurfaces.ts

@@ -280,9 +280,9 @@ export const RETIRED: readonly RetiredSurface[] = [
     absentPaths: [],
     forbiddenPatterns: [
       // The flags and the two service methods. NOT the bare word `backfill`:
-      // `conversation-logger backfill-pi-sessions` and
-      // `ts/src/conversation/backfill.ts` are the TRANSCRIPT backfills, a
-      // different feature that is ported and staying.
+      // the transcript backfill (`ts/src/conversation/transcriptBackfill.ts`)
+      // is a different feature, ported and staying. (The Pi session backfill
+      // that stood beside it is retired by its own row, `pi-session-backfill`.)
       "--metadata-backfill-",
       "metadata_backfill",
       "preview_metadata_backfill",
@@ -492,8 +492,6 @@ export const RETIRED: readonly RetiredSurface[] = [
     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",
     },
   },
   {
@@ -545,6 +543,45 @@ export const RETIRED: readonly RetiredSurface[] = [
     ],
     exemptions: {},
   },
+  {
+    surfaceId: "pi-session-backfill",
+    story: "CR153",
+    // Session maintenance's Pi backfill: a walk of Pi's session directory that
+    // imported every file this home's `runtime_sessions` did not track. That
+    // held while a machine had one home. With two, each imported the other's
+    // sessions -- 543 conversations on the maintainer's machine, both ways,
+    // each titled again through the provider -- and both imported the sessions
+    // of scratch homes and of Pi run without Mirror, while the gap it existed
+    // to fill, a session the home's own extension never logged, came up once
+    // in three months. A home's Pi conversations are the ones the Pi extension
+    // logged into it, and nothing reads a Pi session file. `importClosedConversation`
+    // went with it: the Codex importer that also wrote through it retired with
+    // DS4.TS5. `PI_SESSIONS_DIR` is inert, and only the records that say so,
+    // and the test that proves it, may name it.
+    absentPaths: [
+      "ts/src/conversation/backfill.ts",
+      "ts/src/conversation/sessionImport.ts",
+      "ts/test/conversation/backfill.test.ts",
+      "ts/test/db/homeBornAt.test.ts",
+      "ts/test/fixtures/backfill/pi-sessions/",
+    ],
+    forbiddenPatterns: [
+      "backfillPiSessions",
+      "resolvePiSessionsDir",
+      "homeBornAt",
+      "importClosedConversation",
+      "PI_SESSIONS_DIR",
+      "Backfilled Pi sessions",
+    ],
+    exemptions: {
+      "docs/reference/configuration.md":
+        "the inert-values record: a `.env` may still carry PI_SESSIONS_DIR, and the reference says nothing reads it",
+      ".env.example.advanced":
+        "marks PI_SESSIONS_DIR inert, so a leftover line is recognized rather than trusted",
+      "ts/test/conversation/loggerCli.test.ts":
+        "sets PI_SESSIONS_DIR to a directory holding a fresh session and proves maintenance imports nothing from it",
+    },
+  },
 ];
 
 export interface SurfaceProblem {

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

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