mirror-mind 0.32.1 → 0.33.0

package/.claude/hooks/log-assistant-reply.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every wrapper shares these bytes and
+# differs only in the hook name and in how it finds the Mirror entry
+# (CV22.DS10.TS5 decision D4; CV22.DS10.US3 decision D5).
+set -uo pipefail
+HOOK="claude:stop"
+
+# Resolve the tree from THIS FILE, never from the cwd: a runtime spawns hooks
+# from whatever directory the session is in. The tree is a checkout or the
+# installed package; the wrapper's depth to its root is the same in both.
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd "$HERE/../.." && pwd -P)"
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits 0.
+# The home is found the way the core finds it -- MIRROR_HOME, else
+# MIRROR_USER -- from the environment when set there, else from the tree's
+# .env when the wrapper is in a tree, else from the user's config file
+# (~/.config/mirror/env), in the core's order (US3, D3). A GUI launch carries
+# neither variable, and the first wrappers then wrote to a home nobody reads.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+ENTRY="$REPO_ROOT/bin/mirror-hook.js"
+
+# Find Node. /usr/bin/python3 exists on every macOS; node usually lives under
+# nvm or Homebrew and is NOT on the PATH of a GUI-launched runtime. The Python
+# hooks could end in `|| true` because they always found their interpreter;
+# the same silence here would hide a new failure — no logging, no inject, no
+# close tail — that a user would meet weeks later as "Mirror stopped
+# remembering". So an unresolvable Node is RECORDED, never swallowed. The
+# directory the entry was found in is searched first: an npm global bin holds
+# the `node` that installed the package beside `mirror-hook`, while a system
+# `/usr/local/bin/node` can be years older (CI's Ubuntu runner has one).
+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
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# Not `exec`: the entry exits 0 whatever happens inside it, so a non-zero exit
+# means Node itself could not run the hook -- too old for the loader shim, or
+# it crashed. That used to vanish into a stderr no runtime shows (TS5 handoff
+# review, finding N1). No flags: the entry reads configuration and silences
+# its own warnings (US3, D3).
+"$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0

package/.pi/extensions/mirror-logger.ts

@@ -4,10 +4,12 @@
  * Integrates Pi with the Mirror Mind memory system.
  *
  * Events handled:
- * - session_start      → unmute + close stale orphans + extract pending memories
- * - before_agent_start → log user prompt with explicit session id
- * - agent_end          → log assistant response (all messages in the turn)
- * - session_shutdown   → close conversation + backup database
+ * - session_start      → unmute + welcome card + status line, in ONE front-door
+ *                        process (CV9.E2.S32); maintenance detached
+ * - before_agent_start → log user prompt, NOT awaited: queued on a per-session
+ *                        chain so the turn starts at once (CV9.E2.S32)
+ * - agent_end          → log assistant response, after the chain settles
+ * - session_shutdown   → close conversation (after the chain settles) + backup
  *
  * All heavy logic lives in the TypeScript core, reached through the `mirror`
  * bin that ships beside this file (`bin/mirror.js`). This extension is a thin
@@ -274,8 +276,21 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	/**
+	 * CV9.E2.S32 test knob: a delay before each awaited front-door exec, so the
+	 * quit-mid-write and ordering cases can be driven deterministically.
+	 * Honored ONLY under `MEMORY_ENV=test`; a production session never sleeps.
+	 */
+	function testFrontDoorDelayMs(): number {
+		if (process.env.MEMORY_ENV !== "test") return 0;
+		const raw = Number.parseInt(process.env.MIRROR_TEST_FRONT_DOOR_DELAY_MS ?? "", 10);
+		return Number.isFinite(raw) && raw > 0 ? raw : 0;
+	}
+
 	async function runMirror(args: string[]): Promise<string> {
 		try {
+			const delay = testFrontDoorDelayMs();
+			if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
 			const result = await pi.exec("node", [...FRONT_DOOR_ARGV, ...args], {
 				timeout: 30_000,
 			});
@@ -291,6 +306,60 @@ export default function (pi: ExtensionAPI) {
 		}
 	}
 
+	/**
+	 * The `session-start --fast --welcome --format json` envelope (CV9.E2.S32).
+	 * One process answers what used to take three: the unmute, the welcome
+	 * card, and the status line. A parse failure is a WARN and the same empty
+	 * result the three calls used to yield when one of them failed.
+	 */
+	interface SessionOpenEnvelope {
+		sessionStart: string;
+		welcome: string;
+		statusLine: string;
+	}
+
+	function parseSessionOpenEnvelope(stdout: string): SessionOpenEnvelope | null {
+		if (!stdout.trim()) return null;
+		try {
+			const parsed: unknown = JSON.parse(stdout);
+			if (!parsed || typeof parsed !== "object") throw new Error("not an object");
+			const record = parsed as Record<string, unknown>;
+			const field = (name: string): string => (typeof record[name] === "string" ? (record[name] as string) : "");
+			return { sessionStart: field("sessionStart"), welcome: field("welcome"), statusLine: field("statusLine") };
+		} catch (err: unknown) {
+			log("WARN", `session-open envelope unreadable: ${err instanceof Error ? err.message : String(err)}`);
+			return null;
+		}
+	}
+
+	/**
+	 * CV9.E2.S32: the per-session chain of pending `log-user` writes.
+	 *
+	 * The invariant protected: the `log-user` process has EXITED before the
+	 * `log-assistant` process for the same turn is SPAWNED, and before
+	 * `session-end-pi` runs. Message reads are `ORDER BY created_at, id` and
+	 * `created_at` is stamped by the writing process at insert time, so order
+	 * in the database is wall-clock order of the inserts; the chain is what
+	 * makes that order the prompt order. Consecutive prompts serialize on the
+	 * same chain. A link that fails (or times out at `pi.exec`'s 30 s) settles
+	 * the chain all the same: `runMirror` swallows, and the `.then(\u2026, \u2026)` is
+	 * belt and braces so a rejection can never wedge it.
+	 */
+	const pendingUserLog = new Map<string, Promise<void>>();
+
+	function enqueueUserLog(sessionId: string, args: string[]): void {
+		const prior = pendingUserLog.get(sessionId) ?? Promise.resolve();
+		const next = prior.then(() => runMirror(args)).then(
+			() => undefined,
+			() => undefined,
+		);
+		pendingUserLog.set(sessionId, next);
+	}
+
+	async function settleUserLog(sessionId: string): Promise<void> {
+		await (pendingUserLog.get(sessionId) ?? Promise.resolve());
+	}
+
 	/** Extract readable text from a content blocks array or plain string. */
 	function extractText(content: unknown): string {
 		if (typeof content === "string") return content;
@@ -307,14 +376,9 @@ export default function (pi: ExtensionAPI) {
 		return text.slice(0, MAX_CONTENT_SIZE) + "\n[… truncated]";
 	}
 
-	async function refreshMirrorStatus(ctx: MirrorStatusContext): Promise<void> {
+	/** The status bar line: the front door's compact status, or `?`, plus the external-skill count. */
+	function setMirrorStatus(ctx: MirrorStatusContext, compactStatus: string): void {
 		if (!ctx.hasUI) return;
-		const sessionId = ctx.sessionManager.getSessionFile() ?? null;
-		const statusArgs = ["welcome", "--status-line"];
-		if (sessionId) {
-			statusArgs.push("--session-id", sessionId);
-		}
-		const compactStatus = (await runMirror(statusArgs)).trim();
 		const externalCatalog = loadInstalledPiExternalSkills();
 		const externalSkills = externalCatalog?.extensions ?? [];
 		const status = compactStatus || "◇ Mirror · ?";
@@ -324,6 +388,16 @@ export default function (pi: ExtensionAPI) {
 		);
 	}
 
+	async function refreshMirrorStatus(ctx: MirrorStatusContext): Promise<void> {
+		if (!ctx.hasUI) return;
+		const sessionId = ctx.sessionManager.getSessionFile() ?? null;
+		const statusArgs = ["welcome", "--status-line"];
+		if (sessionId) {
+			statusArgs.push("--session-id", sessionId);
+		}
+		setMirrorStatus(ctx, (await runMirror(statusArgs)).trim());
+	}
+
 	// Resolve the active Mirror home the same way the Python core does
 	// (src/memory/config.py resolve_mirror_home), including the per-workspace
 	// .env that Node would otherwise never see.
@@ -436,7 +510,12 @@ export default function (pi: ExtensionAPI) {
 		log("INFO", `operating instructions appended from ${AGENTS_FILE}`);
 	});
 
-	// --- 1. session_start → unmute + close stale orphans + extract pending ---
+	// --- 1. session_start → unmute + welcome + status line in one process ---
+	//
+	// CV9.E2.S32. `session-start --fast` WRITES the orientation that `welcome`
+	// and `welcome --status-line` READ, so the three cannot run in parallel;
+	// the composite runs them in one process, write first. Maintenance stays
+	// detached. Fires on startup, reload, new, resume, and fork alike.
 
 	pi.on("session_start", async (_event, ctx) => {
 		log("INFO", "session_start fired");
@@ -452,10 +531,11 @@ export default function (pi: ExtensionAPI) {
 			log("WARN", line);
 			if (ctx.hasUI) ctx.ui.notify(line, "warning");
 		}
-		const summary = await runMirror(["conversation-logger", "session-start", "--fast"]);
-		if (ctx.hasUI) {
-			ctx.ui.setStatus("mirror", "◇ Mirror · checking release status…");
-		}
+		const sessionId = ctx.sessionManager.getSessionFile() ?? null;
+		const openArgs = ["conversation-logger", "session-start", "--fast", "--welcome", "--format", "json"];
+		if (sessionId) openArgs.push("--session-id", sessionId);
+		const envelope = parseSessionOpenEnvelope(await runMirror(openArgs));
+		const summary = envelope?.sessionStart ?? "";
 		const externalCatalog = loadInstalledPiExternalSkills();
 		const externalSkills = externalCatalog?.extensions ?? [];
 		const externalSkillSummary = externalSkills.length
@@ -464,7 +544,7 @@ export default function (pi: ExtensionAPI) {
 		log("INFO", `session-start result: ${summary || "(empty)"}`);
 		log("INFO", externalSkillSummary);
 
-		const welcome = (await runMirror(["welcome"])).trim();
+		const welcome = (envelope?.welcome ?? "").trim();
 		if (welcome) {
 			log("INFO", `welcome: ${welcome.split("\n")[0]}`);
 		}
@@ -473,11 +553,9 @@ export default function (pi: ExtensionAPI) {
 			if (welcome) {
 				ctx.ui.notify(welcome, "info");
 			}
-			await refreshMirrorStatus(ctx);
-			runMirrorBackground(["conversation-logger", "session-maintenance"], "session-maintenance");
-		} else {
-			runMirrorBackground(["conversation-logger", "session-maintenance"], "session-maintenance");
+			setMirrorStatus(ctx, (envelope?.statusLine ?? "").trim());
 		}
+		runMirrorBackground(["conversation-logger", "session-maintenance"], "session-maintenance");
 	});
 
 	// --- 2. before_agent_start → log user prompt with explicit session id ---
@@ -490,7 +568,9 @@ export default function (pi: ExtensionAPI) {
 		if (!prompt || prompt.startsWith("/")) return;
 
 		log("INFO", `log-user: ${prompt.slice(0, 80)}...`);
-		await runMirror([
+		// Not awaited (CV9.E2.S32): the turn starts now; `agent_end` and
+		// `session_shutdown` settle the chain before anything that must follow.
+		enqueueUserLog(sessionId, [
 			"conversation-logger",
 			"log-user",
 			sessionId,
@@ -535,6 +615,8 @@ export default function (pi: ExtensionAPI) {
 		const combined = assistantTexts.join("\n\n---\n\n");
 		const content = truncate(combined);
 
+		// The user message's process has exited before this one is spawned.
+		await settleUserLog(sessionId);
 		runMirrorBackground(
 			["conversation-logger", "log-assistant", sessionId, content, "--interface", "pi"],
 			"log-assistant",
@@ -551,6 +633,9 @@ export default function (pi: ExtensionAPI) {
 		const sessionId = ctx.sessionManager.getSessionFile() ?? null;
 
 		if (sessionId) {
+			// A prompt still in flight must land before the conversation closes.
+			await settleUserLog(sessionId);
+			pendingUserLog.delete(sessionId);
 			await runMirror(["conversation-logger", "session-end-pi", sessionId]);
 			log("INFO", `session closed: ${sessionId}`);
 		}

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.33.0 — One Plugin, Three Runtimes](v0.33.0.md) — minor release closing CV21.DS2: the one plugin works as it is on Claude Code, Codex, and Grok. Its MCP server starts on all three, the explicit Mirror form is recognized in every runtime's spelling, and each session is logged under its runtime with every reply beside its prompt. Also: a faster Pi session start, and notice that Gemini CLI is retired in favor of Antigravity.
 - [v0.32.1 — The Release That Shipped](v0.32.1.md) — patch release that is the published CV22 release: `v0.32.0` was tagged and its publication refused by the retired-surface tripwire over one sentence in Getting Started, now rephrased. No code, behavior, or schema differs from `v0.32.0`; read that note for the release itself.
 - [v0.32.0 — One Language, One Install](v0.32.0.md) — minor release that closes CV22, the TypeScript Core Port. Mirror Mind is one TypeScript package run by Node.js 24, installed with `npm install -g mirror-mind` and wired to Pi, Claude Code, Gemini CLI, or Codex by one documented step each; no Python remains in the repository or the shipped artifact; every command answers as it did. Eleven surfaces are retired with cutoffs, recorded in [Pending Cutoffs](pending-cutoffs.md), which this note carries. A new home imports only the Pi sessions newer than itself.
 - [v0.31.14 — Change Request Resume](v0.31.14.md) — patch release that adds the public Ariad Workbench `change-request resume` verb so a non-terminal advanced Change Request that lost the active pointer can continue without direct SQLite edits or artificial status regression. Resume preserves the CR record, restores only the Refinement cursor, allows `implemented` to proceed to `validate` and `validated` to proceed to `done`, and keeps terminal CRs closed.

package/docs/releases/v0.33.0.md

@@ -0,0 +1,164 @@
+---
+digest: >
+  v0.33.0 closes CV21.DS2, the Mirror Plugin & MCP Foundation: the one plugin
+  Mirror ships now works as it is on Claude Code, Codex, and Grok. Its MCP
+  server starts on all three, from a GUI launch too, because its manifest no
+  longer names a path a runtime must expand; the explicit Mirror form is
+  recognized in every runtime's spelling; and each session is logged under
+  its own runtime, with the Mirror question and every reply logged beside
+  its prompt. It was validated in isolated live sessions on Claude Code
+  2.1.296, Codex 0.162.1, and Grok 1.0.52. The release also carries a
+  faster Pi session start (CV9.E2.S32). Package and Claude Code users update
+  as usual; a plugin installed into Codex or Grok by copy is re-installed to
+  receive the new entry.
+---
+
+# v0.33.0 — One Plugin, Three Runtimes
+
+**Date:** 2026-10-13
+
+## Highlights
+
+- **The MCP server starts on every runtime that takes the plugin.** The manifest's entry
+  used to name `${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh`, which Codex never expanded, so the
+  server never started there. It is now a small locator run by `/bin/sh` that finds the
+  installed `mirror` and `node` itself (`MIRROR_BIN`, the `PATH`, the global bin
+  directories), so it also starts when a runtime is launched from the GUI without your
+  shell's `PATH`.
+- **Every reply is logged, beside its prompt, under the runtime it came from.** The shared
+  hooks detect Claude Code, Codex, or Grok, label the session `claude_code`, `codex`, or
+  `grok_build`, and log the turn's final answer from the runtime's Stop event, paired with
+  its prompt by the runtime's own turn id.
+- **A Mirror turn is a conversation turn.** `/mirror-mind:mm-mirror …`, `$mirror-mind:mm:mirror …`,
+  `/mm-mirror …`, and the other spellings are recognized by the inject hook, and the
+  question is logged without the form, so memory extraction sees the question with its
+  answer.
+- **The plugin validates cleanly and its hooks cannot hang a turn.** Hook commands quote
+  the plugin root, so `claude plugin validate` passes with no warnings, and hook timeouts
+  are the seconds the runtimes read them as. The values shipped before meant hours.
+- **Codex's plugin tools, and Grok's, are not yet in the model's hands.** Codex starts the
+  server and keeps a plugin's MCP tools behind its own `tool_search`; Grok starts it and
+  lists its seven tools, but does not attach it to a session. The second is the next Grok
+  story's to investigate.
+
+## Where We Started
+
+CV21 converges Mirror's runtimes on one artifact: a Claude-format plugin carrying the
+skills, the lifecycle hooks, and the Mirror MCP server, taken by each runtime by install
+rather than wired by hand. Its re-baseline, earlier the same day, measured what the
+installed runtimes do with the plugin `v0.32.1` ships. Three of four take it as it is,
+and four things in it were wrong:
+- Claude Code's validator warned on every hook command;
+- the MCP entry did not start on Codex;
+- the inject hook missed the Mirror skill on every plugin install, because each runtime
+  spells it differently;
+- the shared hooks logged Codex and Grok sessions as Claude Code's, without their replies.
+
+## What Changed
+
+The four fixes were planned as one Delivery Story, after a review through six lenses
+(engineering, operations, quality, security, data, and model behavior).
+
+**The MCP entry was chosen by measurement.** Two placeholder-free entries were run on all
+three runtimes before either was written: the inline locator, and the bare `mirror mcp`.
+Both start from a terminal. Only the locator starts from a GUI-launch `PATH`, as written
+and inside Claude Code, where `mirror mcp` failed with "executable not found". The
+measurement also showed Grok substituting set environment variables inside MCP arguments,
+so the locator's own variables carry names nobody exports. `mcp/launch.sh` is retired.
+
+**The reply rule changed before a line was written.** The plan first paired replies with
+logged prompts and kept skipping slash commands. The review showed that would drop the
+Mirror answers on Claude Code, which until now reached the database only through the
+transcript import at session end. So the Mirror question is logged too, and the reply
+beside it. Replies to other slash commands, such as `/mm-journeys`, are not recorded:
+they are commands, not conversation.
+
+**Sessions know their runtime.** Grok's runner sets its own variables on every hook and
+names events in camelCase, and Codex's payload carries a `turn_id`; Claude Code is what
+remains. The label is stamped on every prompt, so a conversation the Mirror skill opens
+inherits it.
+
+**A defect of the release's own was paid before it shipped.** A skipped reply was written
+to `hooks.log`, which `runtime diagnose` reads as failures, so every slash command would
+have raised a warning. Only a reply genuinely lost, its prompt never having reached
+Mirror, is written there now.
+
+### What you will notice
+
+- **On Claude Code**, replies are logged as each turn ends rather than imported when the
+  session closes, and an explicit Mirror turn's question is logged with its answer. The
+  `mm-mirror` skill no longer records a summary by hand where the hooks run.
+- **In `runtime diagnose`**, a hook warning now means a real failure.
+- **For a plugin installed by copy** (Codex from a marketplace, Grok with `grok plugin
+  install`), nothing changes until you re-install: the copy keeps its own manifest and
+  launcher, and keeps working as before.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration in this release.
+
+- **Claude Code**, wired the documented way (`~/.claude/skills/mirror-mind` linked to the
+  package's plugin), reads the plugin in place: new sessions get the new hooks and MCP
+  entry with nothing to do.
+- **Codex and Grok, if you installed the plugin into them**, re-install it to receive
+  the new MCP entry and the Stop hook. Codex copies a plugin into its cache at a version;
+  Grok copies it on install. Codex's documented wiring is still `v0.32.1`'s two steps and
+  wrapper, which this release does not change.
+- **Pi** gets the faster session start described below, with nothing to do.
+- **Gemini CLI** is unaffected by this release; see the notice below.
+
+## Also In This Release
+
+- **Pi opens a session in one front-door call** (CV9.E2.S32). The orientation write and
+  the two renders that read it, the welcome card and the status line, run in one process
+  instead of three. Startup to the status line went from 846 ms to 470 ms, the median of
+  five starts in the development home. The prompt log no longer holds the turn: it is
+  queued, and settled before the reply is logged.
+- **Notice: Gemini CLI is retired as a Mirror runtime, and Antigravity is its
+  successor** ([decision](../project/decisions.md#gemini-cli-is-retired-and-antigravity-is-its-successor)).
+  Google deprecated the Gemini Code Assist backend for individuals. The integration still
+  ships in this release and still works. CV21.DS8 removes it behind a documented cutoff,
+  only once Antigravity gives a Gemini CLI user what they have now.
+
+## Conscious Exclusions
+
+- **Codex through the plugin, as the documented route**, and its marketplace: CV21.DS4.
+- **Grok's attachment of the MCP server to a session**, and Grok's honest L3 (it offers no
+  per-turn injection): CV21.DS10.
+- **The SessionEnd time bound.** Codex gives a SessionEnd hook with no timeout 1 second,
+  Grok 1.5 seconds. With a provider key the close tail's extraction may not finish in
+  that time; the conversation is closed first and extracted at the next session start, so
+  nothing is lost. Left to CV21.DS4 and DS10.
+- **A status line in the plugin.** A plugin cannot carry one (CV21.DS12); CV21.DS11 will
+  document it as a user step.
+- **Three small findings, captured** as CR129 (`mirror mcp` with no home prints a stack
+  trace), CR130 (double-encoded dashes in the configuration reference), and CR131
+  (`runtime diagnose` does not run the MCP locator).
+
+## What We Learned
+
+The instrument needs proving before the thing it measures. The live validation found four
+defects in its own route before it found anything about the plugin:
+- the real config file reaching a scratch session;
+- Claude Code remembering an earlier MCP failure for fifteen minutes;
+- macOS's bash 3.2 refusing a construct;
+- a static step that could not run twice.
+
+Writing the proof of the last fix found a fifth: Codex leaves an app-server daemon running
+from its home after a session, and it had outlived the previous story's cleanup too.
+
+A runtime's own view is often the better witness. Codex's log showed the server's
+handshake, and its `/mcp` view showed the seven tools, where the model could not name
+them. Grok's MCP view showed the server ready while its session log said none was
+attached. That contradiction is now the next Grok story's starting point.
+
+## Next Horizon
+
+CV21 continues with Codex through the canonical plugin (DS4), then Antigravity through
+its skills and a native layer (DS7) and the Gemini CLI sunset behind it (DS8), Grok
+through the plugin (DS10), user extensions on every runtime (DS5), and the contract and
+docs refresh (DS11).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
   "license": "MIT",
   "repository": {

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,13 +1,17 @@
 {
   "name": "mirror-mind",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"
   },
   "mcpServers": {
     "mirror-mind": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh"
+      "command": "/bin/sh",
+      "args": [
+        "-c",
+        "mmbin=\"\"; [ -n \"$MIRROR_BIN\" ] && [ -x \"$MIRROR_BIN/mirror\" ] && mmbin=\"$MIRROR_BIN/mirror\"; [ -n \"$mmbin\" ] || mmbin=\"$(command -v mirror 2>/dev/null)\"; for mmdir in \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; 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\")\" \"$HOME/.nvm/current/bin\" /opt/homebrew/bin /usr/local/bin; 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"
+      ]
     }
   }
 }

package/plugins/mirror-mind/hooks/hooks.json

@@ -6,8 +6,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
-            "timeout": 15000
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 300
           }
         ]
       }
@@ -18,8 +18,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/mirror-inject.sh",
-            "timeout": 30000
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/mirror-inject.sh\"",
+            "timeout": 30
           }
         ]
       },
@@ -28,7 +28,19 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/log-user-prompt.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/log-user-prompt.sh\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/log-assistant-reply.sh\"",
             "async": true
           }
         ]
@@ -40,7 +52,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/log-session-end.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/log-session-end.sh\"",
             "async": true
           }
         ]

package/plugins/mirror-mind/hooks/log-assistant-reply.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Mirror Mind hook wrapper — GENERATED by scripts/generate_hook_wrappers.sh.
+# Edit the generator, never this file: every wrapper shares these bytes and
+# differs only in the hook name and in how it finds the Mirror entry
+# (CV22.DS10.TS5 decision D4; CV22.DS10.US3 decision D5).
+set -uo pipefail
+HOOK="claude:stop"
+
+# This wrapper is the Claude plugin's, and a plugin is copied into Claude
+# Code's own cache: no relative path from here reaches the Mirror tree. It
+# runs the installed `mirror-hook` bin instead, and reads no tree .env.
+REPO_ROOT=""
+
+# A hook never fails the user's turn, and never fails in silence: when it
+# cannot do its job it appends ONE line to <mirror home>/hooks.log and exits 0.
+# The home is found the way the core finds it -- MIRROR_HOME, else
+# MIRROR_USER -- from the environment when set there, else from the tree's
+# .env when the wrapper is in a tree, else from the user's config file
+# (~/.config/mirror/env), in the core's order (US3, D3). A GUI launch carries
+# neither variable, and the first wrappers then wrote to a home nobody reads.
+env_file_value() {
+  [ -f "$2" ] || return 0
+  sed -n -E "s/^[[:space:]]*(export[[:space:]]+)?$1[[:space:]]*=[[:space:]]*//p" "$2" \
+    | tail -n 1 | tr -d "\"'\r"
+}
+env_value() {
+  local value=""
+  if [ -n "${!1+set}" ]; then printf '%s' "${!1}"; return; fi
+  [ -z "$REPO_ROOT" ] || value="$(env_file_value "$1" "$REPO_ROOT/.env")"
+  [ -n "$value" ] || value="$(env_file_value "$1" "${XDG_CONFIG_HOME:-$HOME/.config}/mirror/env")"
+  printf '%s' "$value"
+}
+note() {
+  local home user
+  home="$(env_value MIRROR_HOME)"
+  user="$(env_value MIRROR_USER)"
+  if [ -n "$home" ]; then
+    home="${home/#\~/$HOME}"
+  elif [ -n "$user" ]; then
+    home="$HOME/.mirror-minds/$user"
+    [ -d "$home" ] || [ ! -d "$HOME/.mirror/$user" ] || home="$HOME/.mirror/$user"
+  else
+    return 0
+  fi
+  mkdir -p "$home" 2>/dev/null \
+    && printf '%s %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$HOOK" "$1" >> "$home/hooks.log" 2>/dev/null
+}
+
+# Find the bin. MIRROR_BIN names the directory holding `mirror` and
+# `mirror-hook` (`$(npm prefix -g)/bin`), the same trust class as MIRROR_NODE;
+# then the PATH; then the global bin directories a GUI launch leaves off it.
+ENTRY=""
+[ -n "${MIRROR_BIN:-}" ] && [ -x "$MIRROR_BIN/mirror-hook" ] && ENTRY="$MIRROR_BIN/mirror-hook"
+[ -n "$ENTRY" ] || ENTRY="$(command -v mirror-hook 2>/dev/null || true)"
+for candidate in "$HOME/.nvm/current/bin" /opt/homebrew/bin /usr/local/bin; do
+  [ -n "$ENTRY" ] && break
+  [ -x "$candidate/mirror-hook" ] && ENTRY="$candidate/mirror-hook"
+done
+
+if [ -z "$ENTRY" ]; then
+  note "mirror-hook not found on PATH; hook skipped. Install mirror-mind (npm install -g mirror-mind) or set MIRROR_BIN to its bin directory."
+  exit 0
+fi
+
+# Find Node. /usr/bin/python3 exists on every macOS; node usually lives under
+# nvm or Homebrew and is NOT on the PATH of a GUI-launched runtime. The Python
+# hooks could end in `|| true` because they always found their interpreter;
+# the same silence here would hide a new failure — no logging, no inject, no
+# close tail — that a user would meet weeks later as "Mirror stopped
+# remembering". So an unresolvable Node is RECORDED, never swallowed. The
+# directory the entry was found in is searched first: an npm global bin holds
+# the `node` that installed the package beside `mirror-hook`, while a system
+# `/usr/local/bin/node` can be years older (CI's Ubuntu runner has one).
+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
+  note "node not found on PATH; hook skipped. Set MIRROR_NODE."
+  exit 0
+fi
+
+# Not `exec`: the entry exits 0 whatever happens inside it, so a non-zero exit
+# means Node itself could not run the hook -- too old for the loader shim, or
+# it crashed. That used to vanish into a stderr no runtime shows (TS5 handoff
+# review, finding N1). No flags: the entry reads configuration and silences
+# its own warnings (US3, D3).
+"$NODE" "$ENTRY" "$HOOK" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  note "node exited $status before the hook finished ($NODE, $("$NODE" --version 2>/dev/null || echo 'version unknown')); Mirror needs Node 24 or later. Set MIRROR_NODE."
+fi
+exit 0