mirror-mind 0.32.1 → 0.33.1

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/ts/src/runtime/git.ts

@@ -13,7 +13,9 @@
 // Timeouts follow the oracle's two budgets, and for the reason recorded there:
 // local inspections are near-instant, while a single shared 2 s budget once
 // made a network operation report failure after it had already succeeded
-// (the v0.30.1 release incident). Network reads get 120 s.
+// (the v0.30.1 release incident). Network reads get 120 s, except where a
+// caller holds a tighter budget of its own: the welcome card's update check
+// runs inside the session start and passes what is left of its 5 s (CR135).
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -260,11 +262,15 @@ function availability(
  * Is the channel's remote branch ahead of HEAD? The remote query is the only
  * authority: remote-tracking refs are only as fresh as the last fetch, and
  * trusting them is how a clone two releases behind gets told it is ahead.
+ *
+ * `networkTimeoutMs` bounds that query; `runtime update --check` keeps the
+ * network budget, and the welcome card passes what is left of its own.
  */
 export function checkUpdateAvailability(
   start: string,
   channel: string | null,
   version: string,
+  networkTimeoutMs: number = GIT_NETWORK_TIMEOUT_MS,
 ): UpdateAvailability {
   const startPath = resolve(start);
   const git = inspectGit(startPath);
@@ -303,7 +309,7 @@ export function checkUpdateAvailability(
   const lsRemote = runGit(
     ["ls-remote", remote, `refs/heads/${branch}`],
     git.repository,
-    GIT_NETWORK_TIMEOUT_MS,
+    networkTimeoutMs,
   );
   if (lsRemote.code !== 0 || !lsRemote.stdout) {
     return availability(version, updateChannel, {