mirror-mind 0.32.1 → 0.33.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

package/ts/src/conversation/loggerCli.ts

@@ -21,6 +21,7 @@ import {
   discardCurrentConversation,
   endSession,
   handleSessionEndHook,
+  handleStopHook,
   handleUserPromptHook,
   isMuted,
   logAssistantMessage,
@@ -54,6 +55,7 @@ export const CONVERSATION_LOGGER_SUBCOMMANDS = [
   "log-user",
   "log-assistant",
   "user-prompt",
+  "stop",
   "discard-current",
   "switch",
   "session-end-pi",
@@ -75,7 +77,11 @@ export const LLM_TAIL_SUBCOMMANDS: ReadonlySet<string> = new Set([
 ]);
 
 /** Subcommands that read their JSON payload from stdin. */
-export const STDIN_SUBCOMMANDS: ReadonlySet<string> = new Set(["user-prompt", "session-end"]);
+export const STDIN_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  "user-prompt",
+  "stop",
+  "session-end",
+]);
 
 function extractOption(
   args: string[],
@@ -146,10 +152,43 @@ export async function runConversationLoggerCommand(
       return ok([isMuted(home) ? "MUTED" : "ACTIVE"]);
 
     case "user-prompt":
-      handleUserPromptHook(db, context.stdin ?? "", { mirrorHome: home }, deps);
+      // `--interface` is the runtime the hook detected (US8); without it the
+      // label is Python's hook default.
+      handleUserPromptHook(
+        db,
+        context.stdin ?? "",
+        { mirrorHome: home, interface: interfaceOption(args, "claude_code") },
+        deps,
+      );
       // The hook is silent and always exits 0, whatever the outcome.
       return ok([]);
 
+    case "stop": {
+      // The Stop hook's payload (US8): the turn's final answer, logged beside
+      // its prompt when one is waiting. Exit 0 whatever the outcome, and the
+      // outcome on stdout in one line: the hook entry runs this route
+      // in-process, reads the line, and forwards nothing -- a Stop hook that
+      // printed would keep the agent working on some runtimes -- while a
+      // person running the command from a shell sees what happened.
+      const outcome = handleStopHook(
+        db,
+        context.stdin ?? "",
+        { mirrorHome: home, interface: interfaceOption(args, "claude_code") },
+        deps,
+      );
+      switch (outcome.action) {
+        case "logged":
+          return ok([`reply logged (${outcome.pairedBy})`]);
+        case "skipped":
+          return ok([`reply skipped: ${outcome.reason}`]);
+        case "muted":
+          return ok(["reply not logged: muted"]);
+        default:
+          // The error text is the fault's, never the payload's.
+          return ok([`reply failed: ${outcome.error}`]);
+      }
+    }
+
     case "session-end":
       await handleSessionEndHook(
         db,

package/ts/src/frontDoor/cli.ts

@@ -164,6 +164,7 @@ import { retiredRefusal, routeMemoryCommand } from "./routing.ts";
 import { runRuntimeReadRoute, runWelcomeRoute } from "./runtimeRoute.ts";
 import { runMemorySearchRoute } from "./searchRoute.ts";
 import { resolveSeedPaths } from "./seedPaths.ts";
+import { isSessionStartWelcome, runSessionStartWelcomeRoute } from "./sessionStartWelcomeRoute.ts";
 import { runSoulRoute } from "./soulRoute.ts";
 import {
   applyTasksImport,
@@ -1692,7 +1693,13 @@ async function dispatch(argv: readonly string[]): Promise<DispatchOutcome> {
 
 /** Every route the front door answers once routing has chosen it. */
 async function dispatchTs(argv: readonly string[]): Promise<number | DispatchOutcome> {
-  if (isConversationLoggerCommand(argv)) return runConversationLoggerWrite(argv);
+  if (isConversationLoggerCommand(argv)) {
+    // CV9.E2.S32: the Pi extension's one-process session open. The write is
+    // the same `withMirrorWriteDb`; the welcome renders follow it in-process.
+    if (isSessionStartWelcome(argv))
+      return runSessionStartWelcomeRoute(argv, { withMirrorWriteDb });
+    return runConversationLoggerWrite(argv);
+  }
   if (argv[0] === "build") {
     // The Builder command tree is deliberately lazy: the other commands never
     // pay for loading it, and a broken Builder core cannot take them down.

package/ts/src/frontDoor/conversationLoggerRoute.ts

@@ -6,13 +6,13 @@
 // contract. (Until CV22.DS10.TS5 it could also return `null` to hand an LLM-tail
 // subcommand back to Python; that path left with the fallback.)
 
-import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { createZipBackup } from "#backup/zipBackup.ts";
 import { runConversationLoggerCommand, STDIN_SUBCOMMANDS } from "#conversation/loggerCli.ts";
 import { createLoggerRuntime } from "#conversation/loggerRuntime.ts";
 import type { WritableDatabase } from "#db/database.ts";
+import { takeStdin } from "#frontDoor/stdinSource.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 
 export function isConversationLoggerCommand(argv: readonly string[]): boolean {
@@ -29,19 +29,27 @@ function subcommandOf(args: readonly string[]): string {
   return remaining[0] ?? "";
 }
 
-/** The hook subcommands read their JSON payload from stdin. */
-function readStdin(): string {
-  try {
-    return readFileSync(0, "utf-8");
-  } catch {
-    return "";
-  }
+/**
+ * The hook subcommands read their JSON payload from stdin -- or take the one
+ * a hook entry already read, to detect its runtime (US8, `stdinSource.ts`).
+ */
+const readStdin = takeStdin;
+
+/**
+ * Where the route's lines go. The default is the process's own streams; the
+ * `session-start --welcome` composite (CV9.E2.S32) captures them instead, so
+ * the logger's stdout can travel inside one JSON envelope.
+ */
+export interface ConversationLoggerRouteIo {
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
 }
 
 export async function runConversationLoggerRoute(
   db: WritableDatabase,
   dbPath: string,
   argv: readonly string[],
+  io: ConversationLoggerRouteIo = {},
 ): Promise<number> {
   const args = argv.slice(1);
   const subcommand = subcommandOf(args);
@@ -67,7 +75,9 @@ export async function runConversationLoggerRoute(
   const result = await runConversationLoggerCommand(db, args, runtime, {
     stdin: STDIN_SUBCOMMANDS.has(subcommand) ? readStdin() : undefined,
   });
-  for (const line of result.stdout) process.stdout.write(`${line}\n`);
-  for (const line of result.stderr) process.stderr.write(`${line}\n`);
+  const out = io.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  for (const line of result.stdout) out(line);
+  for (const line of result.stderr) err(line);
   return result.exitCode;
 }

package/ts/src/frontDoor/routing.ts

@@ -370,6 +370,8 @@ const TS_CONVERSATION_LOGGER_SUBCOMMANDS = new Set([
   "log-user",
   "log-assistant",
   "user-prompt",
+  // CV21.DS2.US8: the Stop hook's reply, deterministic like user-prompt.
+  "stop",
   "discard-current",
   // US10 slice F, group 2 (need slice E): diagnose, dry-run repair, Codex import.
   "diagnose-journeys",