mirror-mind 0.32.1 → 0.33.1

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

@@ -1,13 +1,17 @@
 {
   "name": "mirror-mind",
-  "version": "0.32.1",
+  "version": "0.33.1",
   "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

package/plugins/mirror-mind/skills/mm-mirror/SKILL.md

@@ -29,7 +29,7 @@ Use this procedure to answer in Mirror Mode. Automatic routing in `CLAUDE.md` de
 
 This is always the first action, before any visible output to the user.
 
-> **Automatic hook:** When the user invokes `/mm:mirror` explicitly, `mirror-inject.sh` already performs the session-aware mirror activation and injects the base context using the Claude hook `session_id`. You should still run `mirror mirror load` to satisfy the load-first rule and refresh context, but session routing is hook-owned in Claude Code.
+> **Automatic hook:** When the user invokes this skill explicitly, `mirror-inject.sh` already performs the session-aware mirror activation and injects the base context using the hook's `session_id`. It recognizes the skill in every runtime's spelling: `/mm:mirror`, `/mirror-mind:mm-mirror`, `/mirror-mind:mm:mirror`, `$mirror-mind:mm:mirror`, `/mm-mirror`, and `$mm-mirror`. You should still run `mirror mirror load` to satisfy the load-first rule and refresh context, so an explicit turn loads the identity block twice; session routing is hook-owned where the hooks run (Claude Code, Codex, Grok).
 
 ```bash
 mirror mirror load \
@@ -62,4 +62,6 @@ Use the `load` output as the complete response context.
 
 ## 3. Record Response
 
-If the runtime has an explicit session-aware logging path, record a concise 2-3 sentence summary there. In Claude Code, do **not** invent a session id — runtime logging and transcript backfill already capture the response safely.
+Where Mirror's hooks run (Claude Code, Codex, Grok), record **nothing** yourself: do **not** run `mirror mirror log`, and do not invent a session id. The prompt hook logs the question (without the `/mm:mirror` form) and the Stop hook logs your reply beside it, under the runtime's own name; a summary logged by hand would sit beside the reply as a second answer.
+
+Elsewhere, if the runtime has an explicit session-aware logging path, record a concise 2-3 sentence summary there.

package/ts/src/conversation/hookPayload.ts

@@ -0,0 +1,51 @@
+// The fields a Claude-schema hook payload carries, in both spellings
+// (CV21.DS2.US8).
+//
+// Three runtimes hand the shared hooks a payload: Claude Code and Codex in
+// snake_case, Grok in camelCase with a snake_case alias on some fields but
+// not all (DS12.TS4 L8). The turn is correlated under three names: Claude
+// Code's `prompt_id`, Codex's `turn_id`, Grok's `promptId`. One reader, so
+// the logger and the hook entries cannot disagree about where a field lives.
+//
+// Every reader returns "" for a missing or non-string field, and the parser
+// returns null rather than throwing: a hook that threw on a payload it did
+// not recognize would break the user's turn (the `extract_prompt` posture).
+
+export type HookPayloadObject = Record<string, unknown>;
+
+/** Parse a hook payload. Null for anything but a JSON object. */
+export function parseHookPayloadObject(raw: string): HookPayloadObject | null {
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+    return value as HookPayloadObject;
+  } catch {
+    return null;
+  }
+}
+
+/** The first of the named fields that holds a string, else "". */
+export function payloadText(payload: HookPayloadObject, ...names: string[]): string {
+  for (const name of names) {
+    const value = payload[name];
+    if (typeof value === "string") return value;
+  }
+  return "";
+}
+
+export const sessionIdOf = (payload: HookPayloadObject): string =>
+  payloadText(payload, "session_id", "sessionId");
+
+export const promptOf = (payload: HookPayloadObject): string => payloadText(payload, "prompt");
+
+/** The runtime's correlation id for the turn, whatever it calls it. */
+export const turnIdOf = (payload: HookPayloadObject): string =>
+  payloadText(payload, "prompt_id", "turn_id", "promptId");
+
+/** The turn's final answer, as the Stop hook receives it. */
+export const lastAssistantMessageOf = (payload: HookPayloadObject): string =>
+  payloadText(payload, "last_assistant_message", "lastAssistantMessage");
+
+/** Set only inside a subagent (Grok names it; Claude Code and Codex fire SubagentStop instead). */
+export const subagentTypeOf = (payload: HookPayloadObject): string =>
+  payloadText(payload, "subagentType", "subagent_type");

package/ts/src/conversation/logger.ts

@@ -12,8 +12,17 @@
 
 import { closeSync, existsSync, mkdirSync, openSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import {
+  lastAssistantMessageOf,
+  parseHookPayloadObject,
+  promptOf,
+  sessionIdOf,
+  subagentTypeOf,
+  turnIdOf,
+} from "#conversation/hookPayload.ts";
 import { backfillAssistantMessages } from "#conversation/transcriptBackfill.ts";
 import { type WritableDatabase, withTransaction } from "#db/database.ts";
+import { mirrorForm } from "#mirror/mirrorForm.ts";
 import {
   decodeMetadata,
   getRuntimeSession,
@@ -187,17 +196,39 @@ function discardMarkerActive(session: RuntimeSessionRow | null): boolean {
   return Boolean(decodeMetadata(session?.metadata ?? null).discard_current_conversation);
 }
 
+/**
+ * What a message row may carry beside its text. The runtime's turn id (US8)
+ * is the one field today: written by the prompt and Stop hooks, read by the
+ * reply rule, and NULL for every message logged another way, as before.
+ */
+export interface MessageMetadata {
+  readonly turn_id?: string;
+}
+
+export interface LogMessageOptions {
+  interface: string;
+  metadata?: MessageMetadata | null;
+}
+
 function addMessage(
   db: WritableDatabase,
   conversationId: string,
   role: "user" | "assistant",
   content: string,
   deps: LoggerDeps,
+  metadata: MessageMetadata | null = null,
 ): void {
   db.prepare(
     `INSERT INTO messages (id, conversation_id, role, content, created_at, token_count, metadata)
-     VALUES (?, ?, ?, ?, ?, NULL, NULL)`,
-  ).run(deps.newId(), conversationId, role, content, deps.nowIso());
+     VALUES (?, ?, ?, ?, ?, NULL, ?)`,
+  ).run(
+    deps.newId(),
+    conversationId,
+    role,
+    content,
+    deps.nowIso(),
+    metadata ? pythonJsonDumps(metadata) : null,
+  );
 }
 
 /** Python `log_user_message`: discard-marker reset, bind, title-on-first, append. */
@@ -205,7 +236,7 @@ export function logUserMessage(
   db: WritableDatabase,
   sessionId: string,
   content: string,
-  options: { interface: string },
+  options: LogMessageOptions,
   deps: LoggerDeps,
 ): void {
   let existing = getRuntimeSession(db, sessionId);
@@ -234,7 +265,7 @@ export function logUserMessage(
   if (isNew) {
     setProvisionalTitle(db, conversationId, generateTitle(content));
   }
-  addMessage(db, conversationId, "user", content, deps);
+  addMessage(db, conversationId, "user", content, deps, options.metadata ?? null);
 }
 
 /** Python `log_assistant_message`: silent no-op while the discard marker holds. */
@@ -242,7 +273,7 @@ export function logAssistantMessage(
   db: WritableDatabase,
   sessionId: string,
   content: string,
-  options: { interface: string },
+  options: LogMessageOptions,
   deps: LoggerDeps,
 ): void {
   const existing = getRuntimeSession(db, sessionId);
@@ -253,7 +284,7 @@ export function logAssistantMessage(
     { interface: options.interface },
     deps,
   );
-  addMessage(db, conversationId, "assistant", content, deps);
+  addMessage(db, conversationId, "assistant", content, deps, options.metadata ?? null);
 }
 
 /** Python `ConversationService.start_conversation`: always a fresh row. */
@@ -444,53 +475,139 @@ export type UserPromptHookOutcome =
   | { action: "muted" }
   | {
       action: "skipped";
-      reason: "malformed_payload" | "missing_session" | "missing_prompt" | "slash_command";
+      reason:
+        | "malformed_payload"
+        | "missing_session"
+        | "missing_prompt"
+        | "slash_command"
+        | "bare_mirror_form";
     }
   | { action: "logged"; sessionId: string }
   | { action: "failed"; error: string };
 
+export type StopHookOutcome =
+  | { action: "muted" }
+  | {
+      action: "skipped";
+      reason:
+        | "malformed_payload"
+        | "missing_session"
+        | "subagent"
+        | "empty_message"
+        | "discarded"
+        | "already_answered"
+        // Expected: the turn's prompt was a command, which history skips.
+        | "command_turn"
+        // Expected: the Stop names no turn (Grok's at session end).
+        | "session_event"
+        // Unexplained: the turn's prompt was neither logged nor skipped as a
+        // command -- the reply is lost. The only skip the caller reports.
+        | "nothing_waiting";
+    }
+  | { action: "logged"; sessionId: string; pairedBy: "turn_id" | "last_message" }
+  | { action: "failed"; error: string };
+
+export interface HookLoggingOptions {
+  mirrorHome: string;
+  /** The runtime the hook detected (`claude_code`, `codex`, `grok_build`). */
+  interface?: string;
+}
+
 export type SessionEndHookOutcome =
   | { action: "skipped"; reason: "malformed_payload" | "nothing_to_do" }
   | { action: "ended"; sessionId: string; transcriptPath: string | null; backfilled: boolean }
   | { action: "backfilled"; transcriptPath: string }
   | { action: "failed"; error: string };
 
-function parsePayload(raw: string): Record<string, unknown> | null {
-  try {
-    const value: unknown = JSON.parse(raw);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
-    return value as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-}
+const parsePayload = parseHookPayloadObject;
 
 function payloadString(payload: Record<string, unknown>, key: string): string {
   const value = payload[key];
   return typeof value === "string" ? value : "";
 }
 
-/** Python `hook_user_prompt`: mute gate, slash-command skip, never throw. */
+function turnMetadata(turnId: string): MessageMetadata | null {
+  return turnId ? { turn_id: turnId } : null;
+}
+
+/**
+ * The session-metadata key that names the last turn the prompt hook skipped as a
+ * command, so the Stop hook can tell that turn's reply -- expected to go
+ * unrecorded -- from a reply lost because its prompt never reached Mirror.
+ */
+const SKIPPED_TURN_KEY = "skipped_turn_id";
+
+/**
+ * Record the turn a command prompt occupied. `runtime_sessions.metadata` is a
+ * shared JSON object (the discard marker, the operating mode, Soul, Explorer,
+ * and Builder keep keys there), so the key is merged in, never written over.
+ */
+function recordSkippedTurn(
+  db: WritableDatabase,
+  sessionId: string,
+  turnId: string,
+  deps: LoggerDeps,
+): void {
+  if (!turnId) return;
+  const metadata = decodeMetadata(getRuntimeSession(db, sessionId)?.metadata ?? null);
+  metadata[SKIPPED_TURN_KEY] = turnId;
+  upsertRuntimeSession(db, sessionId, { metadata: pythonJsonDumps(metadata) }, deps.nowIso());
+}
+
+/**
+ * Python `hook_user_prompt`: mute gate, slash-command skip, never throw.
+ *
+ * Two additions since CV21.DS2.US8. The session's label is stamped on every
+ * prompt, skipped or not, before anything else can create the conversation:
+ * the Mirror Mode path creates one with `session?.interface ?? "claude_code"`,
+ * and `guessRuntimeSessionId` ignores a session row with no interface, so a
+ * Grok session whose first turn was a Mirror turn used to be labelled
+ * `claude_code` and bound to someone else's session (DS12.TS4 L7, TS2 L9).
+ * And a Mirror turn is a conversation turn: its question is logged without
+ * the form, where every other slash command stays a command.
+ */
 export function handleUserPromptHook(
   db: WritableDatabase,
   rawPayload: string,
-  options: { mirrorHome: string; interface?: string },
+  options: HookLoggingOptions,
   deps: LoggerDeps,
 ): UserPromptHookOutcome {
   try {
-    if (isMuted(options.mirrorHome)) return { action: "muted" };
-
     const payload = parsePayload(rawPayload);
     if (!payload) return { action: "skipped", reason: "malformed_payload" };
 
-    const sessionId = payloadString(payload, "session_id");
-    const prompt = payloadString(payload, "prompt");
+    const sessionId = sessionIdOf(payload);
+    const prompt = promptOf(payload);
     if (!sessionId) return { action: "skipped", reason: "missing_session" };
+
+    const interfaceName = options.interface ?? "claude_code";
+    upsertRuntimeSession(db, sessionId, { interface: interfaceName }, deps.nowIso());
+
+    if (isMuted(options.mirrorHome)) return { action: "muted" };
     if (!prompt) return { action: "skipped", reason: "missing_prompt" };
-    // Slash commands never enter conversation history.
-    if (prompt.startsWith("/")) return { action: "skipped", reason: "slash_command" };
 
-    logUserMessage(db, sessionId, prompt, { interface: options.interface ?? "claude_code" }, deps);
+    const mirror = mirrorForm(prompt);
+    let content = prompt;
+    if (mirror) {
+      if (!mirror.query) {
+        recordSkippedTurn(db, sessionId, turnIdOf(payload), deps);
+        return { action: "skipped", reason: "bare_mirror_form" };
+      }
+      content = mirror.query;
+    } else if (prompt.startsWith("/")) {
+      // Slash commands never enter conversation history, and neither does
+      // their reply: the turn is recorded so the Stop hook knows why.
+      recordSkippedTurn(db, sessionId, turnIdOf(payload), deps);
+      return { action: "skipped", reason: "slash_command" };
+    }
+
+    logUserMessage(
+      db,
+      sessionId,
+      content,
+      { interface: interfaceName, metadata: turnMetadata(turnIdOf(payload)) },
+      deps,
+    );
     return { action: "logged", sessionId };
   } catch (error) {
     // Python swallows everything here; the runtime must survive a logging fault.
@@ -498,6 +615,164 @@ export function handleUserPromptHook(
   }
 }
 
+interface MessageRow {
+  rowid: number;
+  role: string;
+  created_at: string;
+  metadata: string | null;
+}
+
+/** The conversation's last message, in the order the rows were written. */
+function lastMessage(db: WritableDatabase, conversationId: string): MessageRow | null {
+  const row = db
+    .prepare(
+      `SELECT rowid, role, created_at, metadata FROM messages
+       WHERE conversation_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`,
+    )
+    .get(conversationId);
+  return (row as MessageRow | undefined) ?? null;
+}
+
+/** The latest logged prompt of the turn, if the turn's prompt was logged. */
+function promptOfTurn(
+  db: WritableDatabase,
+  conversationId: string,
+  turnId: string,
+): MessageRow | null {
+  const row = db
+    .prepare(
+      `SELECT rowid, role, created_at, metadata FROM messages
+       WHERE conversation_id = ? AND role = 'user' AND json_extract(metadata, '$.turn_id') = ?
+       ORDER BY created_at DESC, rowid DESC LIMIT 1`,
+    )
+    .get(conversationId, turnId);
+  return (row as MessageRow | undefined) ?? null;
+}
+
+/**
+ * Whether the turn already has its reply: an assistant row carrying the same
+ * turn id, after the prompt. Only a Stop reply carries one, so an assistant row
+ * written another way -- a summary `mirror mirror log` appended by hand, a
+ * transcript backfill -- never stands in for the turn's answer.
+ */
+function answeredAfter(
+  db: WritableDatabase,
+  conversationId: string,
+  prompt: MessageRow,
+  turnId: string,
+): boolean {
+  const row = db
+    .prepare(
+      `SELECT 1 FROM messages
+       WHERE conversation_id = ? AND role = 'assistant'
+         AND json_extract(metadata, '$.turn_id') = ?
+         AND (created_at > ? OR (created_at = ? AND rowid > ?)) LIMIT 1`,
+    )
+    .get(conversationId, turnId, prompt.created_at, prompt.created_at, prompt.rowid);
+  return row !== undefined;
+}
+
+function turnIdOfRow(row: MessageRow): string {
+  const value = decodeMetadata(row.metadata).turn_id;
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * The Stop hook (CV21.DS2.US8): log the turn's final answer beside its prompt.
+ *
+ * A reply is logged when it answers a logged prompt, and never otherwise:
+ *
+ *   * by turn id, when the payload carries one and a logged prompt carries the
+ *     same -- unless a reply with that turn id already follows it, which is a
+ *     repeat Stop (a Stop re-fired after another hook blocked). An assistant
+ *     row without the turn id (a hand-logged summary) does not count;
+ *   * else by position, when the conversation's last message is a logged
+ *     prompt -- unless both sides carry a turn id and they differ, which means
+ *     this turn's prompt was a command and an older prompt is waiting because
+ *     its own Stop was lost; attaching the new answer to the old question
+ *     would record a conversation that never happened.
+ *
+ * The handler never creates a conversation. When nothing is waiting, it says
+ * why: `command_turn` when the prompt hook skipped this turn as a command,
+ * `session_event` when the Stop names no turn (Grok's at session end), and
+ * `nothing_waiting` only when nothing explains it -- the turn's prompt never
+ * reached Mirror, the async race the plan names, a reply lost. The caller
+ * writes a `hooks.log` line for that one alone: `runtime diagnose` reads every
+ * line there as a failure, and an expected skip is not one (Debt Review,
+ * 2026-10-13).
+ */
+export function handleStopHook(
+  db: WritableDatabase,
+  rawPayload: string,
+  options: HookLoggingOptions,
+  deps: LoggerDeps,
+): StopHookOutcome {
+  try {
+    const payload = parsePayload(rawPayload);
+    if (!payload) return { action: "skipped", reason: "malformed_payload" };
+
+    const sessionId = sessionIdOf(payload);
+    if (!sessionId) return { action: "skipped", reason: "missing_session" };
+    if (isMuted(options.mirrorHome)) return { action: "muted" };
+    if (subagentTypeOf(payload)) return { action: "skipped", reason: "subagent" };
+
+    const message = lastAssistantMessageOf(payload);
+    if (!message.trim()) return { action: "skipped", reason: "empty_message" };
+
+    const session = getRuntimeSession(db, sessionId);
+    if (discardMarkerActive(session)) return { action: "skipped", reason: "discarded" };
+    const turnId = turnIdOf(payload);
+    const nothingWaiting = (): StopHookOutcome => {
+      if (!turnId) return { action: "skipped", reason: "session_event" };
+      if (decodeMetadata(session?.metadata ?? null)[SKIPPED_TURN_KEY] === turnId) {
+        return { action: "skipped", reason: "command_turn" };
+      }
+      return { action: "skipped", reason: "nothing_waiting" };
+    };
+    const conversationId = session?.conversationId ?? null;
+    if (!conversationId) return nothingWaiting();
+
+    const interfaceName = options.interface ?? session?.interface ?? "claude_code";
+    const last = lastMessage(db, conversationId);
+
+    if (turnId) {
+      const prompt = promptOfTurn(db, conversationId, turnId);
+      if (prompt) {
+        if (answeredAfter(db, conversationId, prompt, turnId)) {
+          return { action: "skipped", reason: "already_answered" };
+        }
+        logAssistantMessage(
+          db,
+          sessionId,
+          message,
+          { interface: interfaceName, metadata: turnMetadata(turnId) },
+          deps,
+        );
+        return { action: "logged", sessionId, pairedBy: "turn_id" };
+      }
+      if (last && last.role === "user" && !turnIdOfRow(last)) {
+        logAssistantMessage(
+          db,
+          sessionId,
+          message,
+          { interface: interfaceName, metadata: turnMetadata(turnId) },
+          deps,
+        );
+        return { action: "logged", sessionId, pairedBy: "last_message" };
+      }
+      return nothingWaiting();
+    }
+
+    if (last && last.role === "user") {
+      logAssistantMessage(db, sessionId, message, { interface: interfaceName }, deps);
+      return { action: "logged", sessionId, pairedBy: "last_message" };
+    }
+    return nothingWaiting();
+  } catch (error) {
+    return { action: "failed", error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 /**
  * Python `hook_session_end`: end the session when the payload names one, then
  * backfill assistant turns from the transcript when it exists -- in that