mirror-mind 0.32.1 → 0.33.0

package/ts/src/frontDoor/sessionStartWelcomeRoute.ts

@@ -0,0 +1,166 @@
+// `conversation-logger session-start --fast --welcome --format json` (CV9.E2.S32).
+//
+// The Pi extension used to open a session with three awaited front-door
+// processes in a row -- `session-start --fast`, `welcome`, and
+// `welcome --status-line` -- paying the loader's fixed cost three times
+// before the user could type. They cannot run in parallel: the first WRITES
+// the orientation the other two READ. They can run in one process, as long as
+// the write commits before the reads. This route is that sequencing and
+// nothing else.
+//
+// What it deliberately does not do:
+//
+//   * It does not teach `loggerCli.ts` to render a welcome card. That module
+//     is the conversation domain; composition across domains is this layer's
+//     job.
+//   * It does not touch `runWelcomeRoute`'s read-only contract. Both renders
+//     run through that route with captured io, AFTER the write handle has
+//     closed, so the card and the status line are byte-identical to the
+//     standalone commands and never share the live write lock with the
+//     card's bounded update check.
+//   * It has no text form. The card is free text; the only safe delimiter is
+//     a JSON envelope.
+//
+// The envelope is for the extension, not for a skill. A skill that called this
+// would put card text in front of the model through a channel the Ariad
+// surface rules do not cover; `checkSkillCommandParity.ts` refuses the flag in
+// every SKILL.md.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { runConversationLoggerRoute } from "./conversationLoggerRoute.ts";
+import { runWelcomeRoute } from "./runtimeRoute.ts";
+
+export const SESSION_START_WELCOME_SCHEMA_VERSION = "1.0.0";
+
+export interface SessionStartWelcomeEnvelope {
+  schemaVersion: typeof SESSION_START_WELCOME_SCHEMA_VERSION;
+  /** The logger's stdout lines, joined with `\n`: what `session-start --fast` prints. */
+  sessionStart: string;
+  /** `mirror welcome`'s stdout minus the trailing newline; `""` when disabled. */
+  welcome: string;
+  /** `mirror welcome --status-line`'s stdout minus the trailing newline; `""` when empty. */
+  statusLine: string;
+}
+
+export interface SessionStartWelcomeOutcome {
+  exitCode: number;
+  /** Content-free category for the front-door log when a render failed after the write. */
+  detail?: string;
+}
+
+export interface SessionStartWelcomeDeps {
+  /** The real write path: opens the live write database, runs `write`, closes it. */
+  withMirrorWriteDb: (
+    argv: readonly string[],
+    write: (db: WritableDatabase, dbPath: string) => Promise<number> | number,
+  ) => Promise<number>;
+  /**
+   * The welcome renderer. Defaults to the real route; the render-failure test
+   * injects one that throws. The write path is never injected: it is the real
+   * one in every test.
+   */
+  renderWelcome?: typeof runWelcomeRoute;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+/** Only the `--fast --welcome` composite answers here; everything else is the plain logger route. */
+export function isSessionStartWelcome(argv: readonly string[]): boolean {
+  return (
+    argv[0] === "conversation-logger" &&
+    argv.includes("session-start") &&
+    argv.includes("--welcome")
+  );
+}
+
+function optionValue(args: readonly string[], name: string): string | null {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+}
+
+/** The logger's `--mirror-home` reaches the welcome renders too, so both read the same home. */
+function welcomeArgv(argv: readonly string[], statusLine: boolean): string[] {
+  const out = ["welcome"];
+  if (statusLine) out.push("--status-line");
+  const home = optionValue(argv, "--mirror-home");
+  if (home !== null) out.push("--mirror-home", home);
+  const sessionId = optionValue(argv, "--session-id");
+  if (statusLine && sessionId !== null) out.push("--session-id", sessionId);
+  return out;
+}
+
+/** The logger's own argv: the composite flags removed, `--format`'s value with it. */
+function withoutCompositeFlags(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i] as string;
+    if (arg === "--welcome") continue;
+    if (arg === "--format") {
+      i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+export async function runSessionStartWelcomeRoute(
+  argv: readonly string[],
+  deps: SessionStartWelcomeDeps,
+): Promise<SessionStartWelcomeOutcome> {
+  const stdout = deps.stdout ?? ((text: string) => process.stdout.write(text));
+  const stderr = deps.stderr ?? ((text: string) => process.stderr.write(text));
+  const renderWelcome = deps.renderWelcome ?? runWelcomeRoute;
+
+  if (!argv.includes("--fast")) {
+    stderr("session-start: --welcome requires --fast (the full session-start runs maintenance)\n");
+    return { exitCode: 2 };
+  }
+  const format = optionValue(argv, "--format");
+  if (format !== "json") {
+    stderr(
+      "session-start: --welcome requires --format json (the card has no safe text delimiter)\n",
+    );
+    return { exitCode: 2 };
+  }
+
+  // 1. The write, through the real path. Its handle is closed when this returns.
+  const loggerArgv = withoutCompositeFlags(argv);
+  const sessionStartLines: string[] = [];
+  const exitCode = await deps.withMirrorWriteDb(loggerArgv, (db, dbPath) =>
+    runConversationLoggerRoute(db, dbPath, loggerArgv, {
+      stdout: (line) => sessionStartLines.push(line),
+      // The logger's refusals keep going to stderr, as they do standalone.
+      stderr: (line) => stderr(`${line}\n`),
+    }),
+  );
+  if (exitCode !== 0) return { exitCode };
+
+  // 2. The reads, after the write committed and its handle closed. A render
+  //    failure must not lose the unmute: the envelope still goes out, with the
+  //    failed field empty, and the category reaches the front-door log.
+  let detail: string | undefined;
+  const render = (statusLine: boolean): string => {
+    let captured = "";
+    try {
+      renderWelcome(welcomeArgv(argv, statusLine), { stdout: (text) => (captured += text) });
+    } catch (error) {
+      detail = `render-failed=${error instanceof Error ? error.name : "unknown"}`;
+      return "";
+    }
+    return stripTrailingNewline(captured);
+  };
+  const envelope: SessionStartWelcomeEnvelope = {
+    schemaVersion: SESSION_START_WELCOME_SCHEMA_VERSION,
+    sessionStart: sessionStartLines.join("\n"),
+    welcome: render(false),
+    statusLine: render(true),
+  };
+  stdout(`${JSON.stringify(envelope)}\n`);
+  return detail ? { exitCode: 0, detail } : { exitCode: 0 };
+}

package/ts/src/frontDoor/stdinSource.ts

@@ -0,0 +1,37 @@
+// Where a stdin-reading route gets its payload (CV21.DS2.US8).
+//
+// Two of the conversation logger's subcommands read a hook payload from
+// stdin: `user-prompt` and `stop`. Until US8 the Claude hook entries did not
+// touch fd 0 and let the route read it. Now an entry reads the payload first,
+// to detect the runtime it is in (`runtimeDetection.ts`), and fd 0 cannot be
+// read twice. So the entry hands the payload over here, and the route takes
+// it before falling back to fd 0.
+//
+// A one-shot handoff rather than an argument because the hooks run the front
+// door in-process (`runFrontDoor`), through the same `main(argv)` every other
+// caller uses, and a payload does not belong in argv: argv is what `ps`
+// shows, and what the Gemini hooks already put a prompt into is the exception
+// this seam avoids repeating.
+
+import { readFileSync } from "node:fs";
+
+let provided: string | null = null;
+
+/** Hand a payload to the next stdin-reading route in this process. */
+export function provideStdin(text: string): void {
+  provided = text;
+}
+
+/** The provided payload, once; else fd 0 to its end; "" when there is none. */
+export function takeStdin(): string {
+  if (provided !== null) {
+    const text = provided;
+    provided = null;
+    return text;
+  }
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}

package/ts/src/guards/claudePlugin.ts

@@ -66,14 +66,64 @@ export function readVersion(repoRoot: string): string {
   return version;
 }
 
+/**
+ * The directories the MCP entry and the plugin's hook wrappers search for
+ * `mirror` and `node` when the PATH does not hold them: a GUI launch leaves
+ * the npm global bin off it. One list, so `mcpEntry.test.ts` can hold the
+ * entry's search equal to the wrappers' (`generate_hook_wrappers.sh`).
+ */
+export const GLOBAL_BIN_DIRS = ['"$HOME/.nvm/current/bin"', "/opt/homebrew/bin", "/usr/local/bin"];
+
+/**
+ * The MCP entry's locator (CV21.DS2.US6).
+ *
+ * The manifest used to name `${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh`. Claude Code
+ * expands that variable; Codex does not expand it in an MCP command (DS12.TS2
+ * L6), so the server never started there. The locator is the launcher's
+ * search, inline: `MIRROR_BIN`, the PATH, then the global bin directories for
+ * `mirror`; `MIRROR_NODE`, the PATH, the directory `mirror` was found in, then
+ * the same directories for `node`. A client whose PATH holds neither (a GUI
+ * launch) still starts the server, and one with no `mirror` anywhere gets one
+ * stderr line naming the install step, and exit 1.
+ *
+ * Written for what three runtimes do to the string (the US6 spike):
+ *
+ *   * POSIX `sh`: `/bin/sh` is dash on Linux;
+ *   * no `${...}`: Claude Code expands that form in MCP configuration, and a
+ *     runtime that did so with an unset name would blank it;
+ *   * no positional parameter (`$1`, `$@`, ...) and no backtick, for the same
+ *     reason, and because the text travels through two JSON encoders;
+ *   * variables named `mmbin`, `mmnode`, `mmdir`: Grok substitutes SET
+ *     environment variables by name inside MCP args at load time (`$HOME`
+ *     became the path), so a script variable with a name a person exports
+ *     would be replaced before the shell ever saw it.
+ */
+export const MCP_LOCATOR = [
+  'mmbin=""',
+  '[ -n "$MIRROR_BIN" ] && [ -x "$MIRROR_BIN/mirror" ] && mmbin="$MIRROR_BIN/mirror"',
+  '[ -n "$mmbin" ] || mmbin="$(command -v mirror 2>/dev/null)"',
+  `for mmdir in ${GLOBAL_BIN_DIRS.join(" ")}; do [ -n "$mmbin" ] && break; [ -x "$mmdir/mirror" ] && mmbin="$mmdir/mirror"; done`,
+  '[ -n "$mmbin" ] || { echo "mirror-mind: mirror not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory." >&2; exit 1; }',
+  'mmnode="$MIRROR_NODE"',
+  '[ -n "$mmnode" ] && [ -x "$mmnode" ] || mmnode="$(command -v node 2>/dev/null)"',
+  `for mmdir in "$(dirname "$mmbin")" ${GLOBAL_BIN_DIRS.join(" ")}; do [ -n "$mmnode" ] && break; [ -x "$mmdir/node" ] && mmnode="$mmdir/node"; done`,
+  '[ -n "$mmnode" ] || { echo "mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE." >&2; exit 1; }',
+  'exec "$mmnode" "$mmbin" mcp',
+].join("; ");
+
+/** The `mcpServers` entry: the locator, run by the system shell. */
+export const MCP_ENTRY: { readonly command: string; readonly args: readonly string[] } = {
+  command: "/bin/sh",
+  args: ["-c", MCP_LOCATOR],
+};
+
 /**
  * The Claude plugin manifest (minimal; no unsupported keys).
  *
- * Declares the Mirror MCP server so the canonical package carries it. Since
- * CV22.DS9.TS2 the entry is the plugin's own launcher rather than an engine,
- * so reverting never requires editing a plugin installed inside someone's
- * runtime (DS9 decision D5). TS5 removes that launcher's Python branch; US3
- * repoints this at the npm entry point.
+ * Declares the Mirror MCP server so the canonical package carries it. The
+ * entry names no file of the plugin's and no variable a runtime must expand
+ * (`MCP_LOCATOR`): Claude Code, Codex, and Grok render it as written, and
+ * each starts the server from it (CV21.DS2.US6).
  */
 export function buildManifest(version: string): Record<string, unknown> {
   return {
@@ -82,11 +132,7 @@ export function buildManifest(version: string): Record<string, unknown> {
     description: PLUGIN_DESCRIPTION,
     author: { name: PLUGIN_AUTHOR },
     mcpServers: {
-      // The placeholder is Claude Code's, expanded when it loads the plugin. A
-      // JavaScript template would resolve at BUILD time, against this
-      // repository, shipping an absolute path from the release machine.
-      // biome-ignore lint/suspicious/noTemplateCurlyInString: Claude expands this at load time, not JS
-      [PLUGIN_NAME]: { command: "${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh" },
+      [PLUGIN_NAME]: { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] },
     },
   };
 }

package/ts/src/guards/packContents.ts

@@ -56,7 +56,7 @@ export const REQUIRED_FILES: readonly string[] = [
   ".pi/skills/mm-mirror/SKILL.md",
   ".claude/hooks/session-start.sh",
   ".gemini/hooks/session-start.sh",
-  "plugins/mirror-mind/mcp/launch.sh",
+  "plugins/mirror-mind/hooks/hooks.json",
   "scripts/codex-hooks/session-start.sh",
   "scripts/codex-mirror.sh",
 ];

package/ts/src/hooks/claude.ts

@@ -13,6 +13,7 @@
 
 import { resolveDbPath } from "#frontDoor/dbPath.ts";
 import { openLiveWriteDatabase } from "#frontDoor/liveBackup.ts";
+import { mirrorForm } from "#mirror/mirrorForm.ts";
 import { markInjected, needsInject, readMirrorState } from "./mirrorState.ts";
 import { parseHookPayload, readStdin } from "./payload.ts";
 import {
@@ -22,6 +23,7 @@ import {
   runFrontDoorQuietly,
   sessionStartOutput,
 } from "./runtime.ts";
+import { detectHookRuntime } from "./runtimeDetection.ts";
 
 /**
  * `session-start.sh`: make sure logging is on for this session, and hand
@@ -39,17 +41,49 @@ export async function claudeSessionStart(env: NodeJS.ProcessEnv = process.env):
 }
 
 /**
- * `log-user-prompt.sh`: record the user's turn.
+ * `log-user-prompt.sh`: record the user's turn, under the runtime's own label.
  *
- * The shell piped stdin into `hook_user_prompt()`. The front door already owns
- * that surface -- `conversation-logger user-prompt` is one of its two
- * stdin-reading subcommands -- so the payload is handed straight to it rather
- * than re-parsed here.
+ * The shell piped stdin into `hook_user_prompt()`, and the front door owns
+ * that surface: `conversation-logger user-prompt` reads the payload itself.
+ * Since CV21.DS2.US8 the entry reads it first, to tell which runtime it is in
+ * (`runtimeDetection.ts`), and hands it to the route through the one-shot
+ * stdin seam, so fd 0 is read once.
  */
-export async function claudeUserPrompt(): Promise<number> {
-  // stdin is deliberately NOT consumed here: the route reads it itself, so
-  // handing it the payload means not reading it first.
-  await runFrontDoorQuietly("claude:user-prompt", ["conversation-logger", "user-prompt"]);
+export async function claudeUserPrompt(stdin: string): Promise<number> {
+  const runtime = detectHookRuntime(parseHookPayload(stdin).raw);
+  await runFrontDoorQuietly(
+    "claude:user-prompt",
+    ["conversation-logger", "user-prompt", "--interface", runtime],
+    { stdin },
+  );
+  return 0;
+}
+
+/**
+ * `log-assistant-reply.sh`, on Stop: record the turn's final answer beside
+ * its prompt (CV21.DS2.US8). Every Claude-schema runtime hands its Stop hook
+ * `last_assistant_message` (DS12.TS2 L11, TS4 L8; Claude Code 2.1.296's
+ * binary), so the reply needs no transcript.
+ *
+ * This hook prints NOTHING and exits 0, whatever happens: a Stop hook that
+ * printed JSON or exited 2 would keep the agent working instead of logging.
+ * The route's outcome line is captured in-process and never forwarded. Only a
+ * reply lost for no known reason -- its turn's prompt neither logged nor
+ * skipped as a command, the race the plan names -- is recorded in `hooks.log`,
+ * the fact and never the text: `runtime diagnose` reads that file as failures,
+ * and a command turn's reply or a session-scoped Stop is not one.
+ */
+export async function claudeStop(stdin: string): Promise<number> {
+  const runtime = detectHookRuntime(parseHookPayload(stdin).raw);
+  const outcome = await runFrontDoorQuietly(
+    "claude:stop",
+    ["conversation-logger", "stop", "--interface", runtime],
+    { stdin },
+  );
+  const line = outcome.trim();
+  if (line.startsWith("reply skipped: nothing_waiting") || line.startsWith("reply failed")) {
+    noteHookFailure("claude:stop", line);
+  }
   return 0;
 }
 
@@ -65,7 +99,9 @@ export async function claudeSessionEnd(): Promise<number> {
  *
  * Two cases, exactly as the shell had them:
  *
- *   1. an explicit `/mm:mirror [query]` -- load context for that query;
+ *   1. an explicit Mirror form -- `/mm:mirror [query]`, or the same skill in
+ *      any runtime's spelling (`#mirror/mirrorForm.ts`; CV21.DS2.US7) -- load context
+ *      for that query;
  *   2. Mirror Mode already active for this session with context not yet
  *      injected -- load it with the session's persona and journey, then mark
  *      it injected so it happens once.
@@ -79,9 +115,9 @@ export async function claudeInject(stdin: string): Promise<number> {
   const sessionId = payload.sessionId;
 
   // Case 1: the explicit invocation.
-  if (/^\/mm:mirror/.test(payload.prompt)) {
-    const query = payload.prompt.replace(/^\/mm:mirror\s*/, "");
-    const argv = ["mirror", "load", "--context-only", "--query", query];
+  const explicit = mirrorForm(payload.prompt);
+  if (explicit) {
+    const argv = ["mirror", "load", "--context-only", "--query", explicit.query];
     if (sessionId) argv.push("--session-id", sessionId);
     const result = await runFrontDoor(argv);
     if (result.stdout.trim()) process.stdout.write(result.stdout);
@@ -164,7 +200,9 @@ export async function claudeHook(name: string): Promise<number> {
     case "session-start":
       return claudeSessionStart();
     case "user-prompt":
-      return claudeUserPrompt();
+      return claudeUserPrompt(readStdin());
+    case "stop":
+      return claudeStop(readStdin());
     case "session-end":
       return claudeSessionEnd();
     case "inject":

package/ts/src/hooks/payload.ts

@@ -11,16 +11,22 @@
 // user's turn. That posture is preserved exactly.
 
 import { readFileSync } from "node:fs";
+import {
+  type HookPayloadObject,
+  parseHookPayloadObject,
+  promptOf,
+  sessionIdOf,
+} from "#conversation/hookPayload.ts";
 
 export interface HookPayload {
   /** The user's prompt text, or "" when the payload has none. */
   readonly prompt: string;
-  /** The runtime's session id, or "" when the payload has none. */
+  /** 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. */
-  readonly raw: Record<string, unknown>;
+  readonly raw: HookPayloadObject;
 }
 
 const EMPTY: HookPayload = { prompt: "", sessionId: "", response: "", raw: {} };
@@ -29,19 +35,18 @@ function text(value: unknown): string {
   return typeof value === "string" ? value : "";
 }
 
-/** Parse a hook payload. Never throws: an unparseable payload is empty. */
+/**
+ * Parse a hook payload. Never throws: an unparseable payload is empty.
+ *
+ * The field spellings live in `#conversation/hookPayload.ts`, one reader for
+ * the entries and the logger (CV21.DS2.US8).
+ */
 export function parseHookPayload(input: string): HookPayload {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(input);
-  } catch {
-    return EMPTY;
-  }
-  if (typeof parsed !== "object" || parsed === null) return EMPTY;
-  const raw = parsed as Record<string, unknown>;
+  const raw = parseHookPayloadObject(input);
+  if (raw === null) return EMPTY;
   return {
-    prompt: text(raw.prompt),
-    sessionId: text(raw.session_id),
+    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

package/ts/src/hooks/runtime.ts

@@ -21,6 +21,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } fro
 import { dirname, join } from "node:path";
 
 import { resolveMirrorHome } from "#frontDoor/dbPath.ts";
+import { provideStdin } from "#frontDoor/stdinSource.ts";
 import { runningTreeRoot } from "#runtime/treeRoot.ts";
 
 /** Where a hook records that it could not do its job. */
@@ -106,6 +107,14 @@ export interface FrontDoorRun {
   readonly stdout: string;
 }
 
+export interface FrontDoorRunOptions {
+  /**
+   * A payload the entry already read from fd 0, for a route that reads its
+   * payload from stdin (CV21.DS2.US8). The route takes it instead of fd 0.
+   */
+  readonly stdin?: string;
+}
+
 /**
  * Run a front-door command in this process, capturing what it printed.
  *
@@ -113,8 +122,12 @@ export interface FrontDoorRun {
  * produced -- the shell version tested `[ -n "$CONTEXT" ]` on command
  * substitution, and this is the same test without a second process.
  */
-export async function runFrontDoor(argv: readonly string[]): Promise<FrontDoorRun> {
+export async function runFrontDoor(
+  argv: readonly string[],
+  options: FrontDoorRunOptions = {},
+): Promise<FrontDoorRun> {
   const { main } = await import("#frontDoor/cli.ts");
+  if (options.stdin !== undefined) provideStdin(options.stdin);
   const chunks: string[] = [];
   const original = process.stdout.write.bind(process.stdout);
   // biome-ignore lint/suspicious/noExplicitAny: matching Node's overloaded write signature
@@ -145,15 +158,22 @@ function commandName(argv: readonly string[]): string {
 
 /**
  * Run a front-door command for its effect, swallowing failure the way the
- * shell hooks did with `|| true` -- but recording it.
+ * shell hooks did with `|| true` -- but recording it. Returns what the route
+ * printed, for an entry that reads an outcome line from it.
  */
-export async function runFrontDoorQuietly(hook: string, argv: readonly string[]): Promise<void> {
+export async function runFrontDoorQuietly(
+  hook: string,
+  argv: readonly string[],
+  options: FrontDoorRunOptions = {},
+): Promise<string> {
   try {
-    const result = await runFrontDoor(argv);
+    const result = await runFrontDoor(argv, options);
     if (result.code !== 0) {
       noteHookFailure(hook, `\`${commandName(argv)}\` exited ${result.code}`);
     }
+    return result.stdout;
   } catch (error) {
     noteHookFailure(hook, error instanceof Error ? error.message : String(error));
+    return "";
   }
 }

package/ts/src/hooks/runtimeDetection.ts

@@ -0,0 +1,34 @@
+// Which runtime a Claude-schema hook is running in (CV21.DS2.US8).
+//
+// Three runtimes run the plugin's hooks as they are: Claude Code, Codex, and
+// Grok. The hooks are Mirror's `claude:*` family, and until this story every
+// session they logged was labelled `claude_code` (DS12.TS2 L7, TS4 L7). Each
+// runtime leaves a mark the others do not:
+//
+//   * Grok's runner sets `GROK_HOOK_EVENT` and `GROK_SESSION_ID` on every hook
+//     process (Grok's bundled guide, "Runner-injected variables"), and its
+//     payload names the event in camelCase, `hookEventName` (TS4 L8);
+//   * Codex's payload carries `turn_id` (TS2 L11), which Claude Code 2.1.296's
+//     common hook input does not: it carries `prompt_id`, read from the binary;
+//   * Claude Code is what remains.
+//
+// Grok is tested first because it aliases some fields into snake_case and may
+// alias more; its own name for the event is the mark that cannot be a
+// coincidence. A label is attribution, never authority: nothing privileged
+// keys off it, so a payload that claimed another runtime's mark would mislabel
+// its own session and nothing else.
+
+import type { HookPayloadObject } from "#conversation/hookPayload.ts";
+
+export type HookRuntime = "claude_code" | "codex" | "grok_build";
+
+export function detectHookRuntime(
+  payload: HookPayloadObject,
+  env: NodeJS.ProcessEnv = process.env,
+): HookRuntime {
+  if (env.GROK_HOOK_EVENT || env.GROK_SESSION_ID || typeof payload.hookEventName === "string") {
+    return "grok_build";
+  }
+  if (typeof payload.turn_id === "string" && payload.turn_id !== "") return "codex";
+  return "claude_code";
+}

package/ts/src/mirror/mirrorForm.ts

@@ -0,0 +1,43 @@
+// The explicit Mirror Mode form, in every runtime's skill syntax (CV21.DS2.US7).
+//
+// Lives with the mirror core rather than with the hooks because two readers
+// share it: the inject hook (context for the question) and the prompt logger
+// (the question as the conversation turn, US8).
+//
+// A person invokes the Mirror skill by name, and each runtime spells that
+// name its own way before handing the prompt to the hooks (DS12):
+//
+//     /mm:mirror …                 standalone Claude Code
+//     /mirror-mind:mm-mirror …     the Claude Code plugin (TS1 L4)
+//     /mirror-mind:mm:mirror …     Claude Code's menu form (TS1 static 6)
+//     $mirror-mind:mm:mirror …     the Codex plugin (TS2 L10)
+//     /mm-mirror …                 Grok (TS4 L5)
+//     $mm-mirror …                 Codex's own skill form
+//
+// Three choices, each made by the runtime, not the person: the sigil (`/` or
+// `$`), whether the plugin's name prefixes the skill, and whether the skill's
+// `name: "mm:mirror"` or its directory `mm-mirror` is used. The grammar is
+// their product, so a runtime that combines them differently is covered too.
+//
+// The form must open the prompt and end at whitespace or the end of it: a
+// longer skill name (`/mm-mirrors`) is another skill, and a form quoted in the
+// middle of a sentence is a mention. The inject hook loads context for the
+// query that follows the form, and the prompt logger records that query as
+// the conversation turn (US8), so both read the same grammar.
+
+export interface MirrorForm {
+  /** The form as the runtime sent it, e.g. `/mirror-mind:mm-mirror`. */
+  readonly form: string;
+  /** What follows the form, with the whitespace between them removed. */
+  readonly query: string;
+}
+
+const FORM = /^([/$])(mirror-mind:)?mm[:-]mirror(?=\s|$)/;
+
+/** The explicit Mirror Mode form at the start of a prompt, or null. */
+export function mirrorForm(prompt: string): MirrorForm | null {
+  const match = FORM.exec(prompt);
+  if (!match) return null;
+  const form = match[0];
+  return { form, query: prompt.slice(form.length).replace(/^\s+/, "").trimEnd() };
+}

package/plugins/mirror-mind/mcp/launch.sh

@@ -1,52 +0,0 @@
-#!/usr/bin/env bash
-# Mirror Mind plugin — MCP server launcher (CV22.DS9.TS2, DS9 decision D5;
-# CV22.DS10.US3 plateau 3, decision D5).
-#
-# The manifest points here instead of at an engine, so the entry point can
-# change without editing a plugin inside someone's runtime.
-#
-# A plugin is copied into Claude Code's own cache, so no relative path from
-# this file reaches the Mirror tree. The launcher finds the installed `mirror`
-# bin the way the plugin's hook wrappers find `mirror-hook`: MIRROR_BIN (the
-# directory holding both, `$(npm prefix -g)/bin`), then the PATH, then the
-# global bin directories a GUI launch leaves off it. Node is found the same
-# way the wrappers find it, MIRROR_NODE first.
-#
-# Unlike a hook, a server that cannot start has no turn to protect: it says
-# why on stderr, which is the client's log for this server, and exits 1.
-# `runtime diagnose` reports a missing `mirror` from the caller's shell.
-#
-# No flags: `mirror mcp` reads configuration and silences `node:sqlite`'s
-# ExperimentalWarning in-process (US3, D3), precisely because no MCP client
-# will pass --no-warnings and stderr must stay the client's log.
-
-set -u
-
-ENTRY=""
-[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror" ] && ENTRY="$MIRROR_BIN/mirror"
-[ -n "$ENTRY" ] || ENTRY="$(command -v mirror 2>/dev/null || true)"
-for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
-  [ -n "$ENTRY" ] && break
-  [ -x "$candidate/mirror" ] && ENTRY="$candidate/mirror"
-done
-
-if [ -z "$ENTRY" ]; then
-  echo "mirror-mind: \`mirror\` not found on PATH; the MCP server cannot start. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory." >&2
-  exit 1
-fi
-
-NODE="${MIRROR_NODE:-}"
-if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then
-  NODE="$(command -v node 2>/dev/null || true)"
-fi
-for candidate in "$(dirname "$ENTRY")/node" "$HOME/.nvm/current/bin/node" /opt/homebrew/bin/node /usr/local/bin/node; do
-  [ -n "$NODE" ] && break
-  [ -x "$candidate" ] && NODE="$candidate"
-done
-
-if [ -z "$NODE" ]; then
-  echo "mirror-mind: node not found on PATH; the MCP server cannot start. Set MIRROR_NODE." >&2
-  exit 1
-fi
-
-exec "$NODE" "$ENTRY" mcp