mirror-mind 0.32.1 → 0.33.1

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,8 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.33.1 — The Install Answers For Itself](v0.33.1.md) — patch release of six RS010 Change Requests: the welcome card, the status line, and both `release-notes` readers answer for the install that is running, never for the cwd or the repository around the install. A package asks its own tree and the npm registry, a clone its own checkout and remote; `pending` says `unknown` when it cannot tell, and a `--ref` value can no longer run a command through git. No migration.
+- [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/docs/releases/v0.33.1.md

@@ -0,0 +1,174 @@
+---
+digest: >
+  v0.33.1 is a maintenance release: six Change Requests from RS010, closed
+  since v0.33.0, and no story or epic. Its subject is one defect in four
+  surfaces. The welcome card, the status line, and both release-notes readers
+  answered for the directory the person was in, or for the git repository
+  around the install, instead of for the install that was running. Each now
+  asks the install itself: a package its own tree and the npm registry, a
+  clone its own checkout and remote. `release-notes pending` says `unknown`
+  when it cannot tell, and a `--ref` value can no longer run a command through
+  git. Upgrade with `mirror runtime update`; there is no migration.
+---
+
+# v0.33.1 — The Install Answers For Itself
+
+**Date:** 2026-10-15
+
+## Highlights
+
+- **The welcome card and the status line announce the update the running install
+  has** (CR135). A package asks the registry for its channel's version, a clone its own
+  checkout and remote. Before, both asked the git repository of whatever directory the
+  session started in: another project's tag could be announced, a package was never told
+  of a release, and the status line kept a stale `⬆` after the update.
+- **npm runs in the install's own directory**, for the card and for `runtime update`, so
+  a project's `.npmrc` can no longer choose the registry the card reads and the update
+  installs from.
+- **`release-notes latest` and `vX.Y.Z` read the notes the package ships** (CR133). On a
+  Homebrew install on Apple Silicon, where `/opt/homebrew` is itself a git repository,
+  they answered `Release notes: not found`.
+- **`release-notes pending` answers for the install, never the cwd** (CR134). A clone
+  reads its own channel's ref in its own checkout. A package asks the registry which
+  version its channel holds and reads that version's notes from its tarball. When
+  nothing can answer it says `Pending releases: unknown` with a reason and exits 1, so
+  `none` always means a source answered.
+- **`--ref` can no longer run a command.** A value like `--upload-pack=<command>`
+  reached `git fetch` as an option, and git ran it. Refs beginning with `-` are refused,
+  and every git call takes `--end-of-options` before its operands.
+- **A clone's update fetch has git's network budget again** (CR132): 120 seconds, not
+  the 2 seconds a local git call gets.
+
+## Where We Started
+
+`v0.33.0` was installed onto a Homebrew package on 2026-10-14, and three surfaces
+answered wrongly the same day. `mirror runtime release-notes v0.33.0` said `not found`, with
+the note sitting in the package. `release-notes pending` said `none` from `/tmp` and,
+from inside an unrelated project, listed that project's releases after fetching from its
+remote. The welcome card asked the same wrong repository whether Mirror had an update.
+
+The three had one root. The readers were ported faithfully from a Python core that ran
+from a checkout, where the cwd, git's top level, and the install were usually one
+directory. Under npm distribution they are three: a skill runs in the person's project,
+and a global prefix can sit inside someone else's repository. CV22 had already moved the
+version and the welcome card's release note onto the running tree, and handed `latest`
+that tree. But the reader still climbed out of it to git's top level, and `pending` and
+the update check still began at the cwd.
+
+The promotion of `v0.33.0` itself had stumbled on the same day. Its push timed out at two
+seconds and was finished by hand (CR132), and npm's `latest` had needed a move nobody's
+route printed (CR125).
+
+## What Changed
+
+**Each install asks about itself.** The card, the status line, and `pending` detect the
+install from where the front door lives, as `runtime channel` does, with nothing spawned
+and no cwd involved. A package reads its channel's dist-tag through the same call `runtime
+update --check` makes. A clone runs its check, its tag lookup, and its "commits behind"
+count in its own checkout. The channel shown is the install's. On `stable` the card checks
+at every render; on `main` it never checks and shows the cached verdict.
+
+**npm's directory is a trust decision.** A four-lens review of CR135's plan found that npm
+reads the `.npmrc` of the directory it runs in. A cloned project that ships
+`registry=` could therefore choose what the card announced and what `runtime update`
+installed. Every npm call the product makes now runs in the install's own root, whose
+project config is the package's own.
+
+**One bound for the session start.** The card's remote reads share one 5-second deadline,
+and the registry read does not retry, so an unreachable registry costs at most that. A
+cached update the install already has is shown by neither surface, and a successful
+`runtime update` records `up_to_date`.
+
+**Release notes come from the install.** `latest` and `vX.Y.Z` read `docs/releases` under
+the running tree and ask git nothing. `pending` reads, for a clone, `origin/<channel>`
+(or `--ref`) in the clone's own repository, after fetching it there. For a package, it
+resolves the channel's dist-tag to a version, as `runtime update` does when it plans.
+When that version is newer, `npm pack --ignore-scripts` fetches that exact tarball into a
+private directory, and its notes are read in memory and the directory removed. When it is
+not newer, nothing is downloaded.
+
+Three choices shaped the package path:
+
+- the registry tarball, not the GitHub branch: the branch is a second authority that can
+  disagree with the dist-tag, as a half-promoted release does;
+- not version numbers alone, which would not answer "what's new in this update?";
+- a reader of its own over `node:zlib` rather than a spawned `tar`, which would take
+  archive-chosen names as arguments. It stops at 64 MB inflated. It refuses an archive
+  that ends before its end-of-archive block, so a cut tarball cannot pass for a whole one
+  missing its newest notes.
+
+**`unknown` is said.** A failed fetch, a ref or dist-tag that does not resolve, an
+unreachable registry, or an install that cannot be identified answers `Pending releases:
+unknown` with a `Reason:` line and exit 1. `--no-fetch` reads a clone's ref as last
+fetched; a package keeps no copy of its channel, so it cannot answer offline.
+
+**The ref is an operand.** `--ref` was split at its first slash into a remote and a
+branch for `git fetch`, so `--upload-pack=touch X/y`, or `origin/--upload-pack=touch X`,
+reached git as an option, and git ran the command. A test claimed this could not happen.
+It passed only because its marker path was absolute, which the split cuts at the leading
+`/`. The exposure was local: whoever can pass `--ref` can run commands anyway. Refs
+beginning with `-` are now refused, and `fetch`, `ls-tree`, and `show` take
+`--end-of-options`, which covers the half after the slash.
+
+### What you will notice
+
+- On a package, `release-notes pending` shows `Source: npm mirror-mind@stable (<version>)`.
+  On a clone it shows `Source: origin/<channel>`, so a clone on `main` now reads
+  `origin/main`, where it used to read `origin/stable`.
+- A package on `main` answers `unknown`: npm has no `main` dist-tag, as `runtime update
+  --check` already says.
+- A `⬆` that the status line kept after an update is no longer shown once the install
+  has that version.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration, and no runtime wiring changes. The update itself is run
+by the version you have now, so this release's changes to it apply from the next update
+on: npm running in the install's root, and recording `up_to_date` when it succeeds. A
+Homebrew package on Apple Silicon reads its release notes again from the first command
+after the update.
+
+## Also In This Release
+
+- **For maintainers.** `release:promote` pushes with the network budget, and a failed push
+  shows git's message with a recovery that says what is where (CR132). A `stable` release
+  now ends, in both places the route is printed, with `npm dist-tag add
+  mirror-mind@<version> latest`. The publish workflow stages under `stable` or `next` and
+  nothing else (CR125).
+- **For contributors.** The updater smoke gives the same result on any machine, whatever
+  the shell exports (CR137). The npm package smoke installs into a prefix that is a git
+  repository, the Homebrew shape. Its `npm` is a stub after the install, so it never
+  reaches the live registry.
+
+## Conscious Exclusions
+
+- **`runtime status` and `runtime version` on a clone**, which still read the clone's
+  repository and channel from the cwd, so a healthy clone reads `attention needed` outside
+  its checkout. It is the same family, captured as CR138.
+- **The `release` environment's ref check.** It accepts a dispatch from any ref, so a
+  branch's own copy of the publish workflow could stage (CR136).
+- **A `--channel` option on `pending`**, which `update --check` and `version` have.
+- **The `mm-release-notes` skill's wording**, which still says "the current stable
+  release", true on the default channel.
+
+## What We Learned
+
+A faithful port inherits its oracle's idea of where it runs. Each of these readers matched
+the Python core's goldens, and each was wrong once the program stopped living in the
+directory it was asked about. The tests agreed with the oracle for the same reason: they
+ran from a clone's root, where the cwd, git, and the install coincide. The new tests for
+the card and for `pending` run every case from two places, outside any repository and
+inside an unrelated one, and the answer must not move.
+
+A validation route must say which install it tests. On a machine with both a package and
+a linked checkout, a bare `mirror` runs whichever comes first on the PATH, and both
+report the same version.
+
+## Next Horizon
+
+CR138, the same defect in `runtime status` and `runtime version`, is the visible next
+step. CR136 would harden the publish route. RS010's other hygiene requests follow.

package/package.json

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