mirror-mind 0.32.1 → 0.33.1

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",

package/ts/src/frontDoor/runtimeRoute.ts

@@ -46,13 +46,18 @@ import { detectInstallKind, type InstallKind } from "#runtime/installKind.ts";
 import { MIGRATE_DECLINED_EXIT, renderMigrate, runMigrate } from "#runtime/migrate.ts";
 import {
   buildPendingReleaseNotes,
+  buildPendingReleaseNotesFromRegistry,
+  type ReleaseNotesBundle,
   readReleaseNote,
   renderReleaseNote,
   renderReleaseNotesBundle,
+  unknownReleaseNotes,
 } from "#runtime/releaseNotes.ts";
 import { buildRuntimeStatus, renderRuntimeStatus, statusVerdict } from "#runtime/status.ts";
 import {
   checkPackageUpdateAvailability,
+  defaultNpmRunner,
+  type NpmRunner,
   npmRootGlobal,
   renderPackageUpdateAvailability,
 } from "#runtime/strategies/package.ts";
@@ -61,8 +66,9 @@ import { frontDoorSpawner, postUpdateHints, runUpdate, type UpdateSpawn } from "
 import { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
 import { renderUpdateResult, updateLogDetail } from "#runtime/updatePipeline.ts";
 import { expandHome } from "#util/paths.ts";
-import { composeWelcome, welcomeDisabled } from "#welcome/card.ts";
+import { composeWelcome, type RemoteCheck, welcomeDisabled } from "#welcome/card.ts";
 import { composeStatusLine } from "#welcome/statusLine.ts";
+import { isoNow, recordUpToDate } from "#welcome/updateCache.ts";
 
 /** The `runtime` subcommands this story ports. */
 export const TS_RUNTIME_READ_SUBCOMMANDS = new Set([
@@ -165,18 +171,39 @@ function writeErr(io: RuntimeRouteIo, text: string): void {
   (io.stderr ?? ((value: string) => process.stderr.write(value)))(text);
 }
 
-/** Port of `welcome.main`. Always exits 0, like the oracle. */
-export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}): number {
+/**
+ * The seams of the routes that answer for the running install, beyond the
+ * route's own: the install and its npm, for tests. The welcome (CR135) and
+ * `release-notes pending` (CR134) take them.
+ */
+export interface InstallRouteIo extends RuntimeRouteIo {
+  install?: InstallKind;
+  npm?: NpmRunner;
+  /** The OS home whose config directory holds a package's channel file. */
+  osHome?: string;
+}
+
+export type WelcomeRouteIo = InstallRouteIo;
+
+/**
+ * Port of `welcome.main`. Always exits 0, like the oracle.
+ *
+ * The card and the status line answer for the install that is running, never
+ * for the cwd (CR135): Pi renders both in the person's project.
+ */
+export function runWelcomeRoute(argv: readonly string[], io: WelcomeRouteIo = {}): number {
   const env = io.env ?? process.env;
-  const cwd = io.cwd ?? process.cwd();
   const args = argv.slice(1);
   if (welcomeDisabled(env)) return 0;
 
   const home = resolveWelcomeHome(optionValue(args, "--mirror-home"), env);
+  // The running tree's manifest: a file read, so the status line still spawns nothing.
+  const version = packageVersion(runningTreeRoot()) ?? "unknown";
 
   if (args.includes("--status-line")) {
     const line = composeStatusLine({
       mirrorHome: home,
+      installedVersion: version,
       sessionId: optionValue(args, "--session-id"),
       env,
     });
@@ -184,23 +211,37 @@ export function runWelcomeRoute(argv: readonly string[], io: RuntimeRouteIo = {}
     return 0;
   }
 
-  const version = packageVersion(runningTreeRoot()) ?? "unknown";
-  const card = composeWelcome({
+  const { card, check } = composeWelcome({
     mirrorHome: home,
-    cwd,
-    treeRoot: runningTreeRoot(),
+    install: io.install ?? detectThisInstall(),
     env,
     version,
-    updateChannel: inspectUpdateChannel(cwd, null),
+    ...(io.npm === undefined ? {} : { npm: io.npm }),
+    ...(io.osHome === undefined ? {} : { osHome: io.osHome }),
   });
   if (card) writeOut(io, `${card}\n`);
+  if (home !== null && check !== null) logWelcomeCheck(home, env, check);
   return 0;
 }
 
+/**
+ * One front-door line per remote check, so a slow session start can be
+ * explained later: what was asked, how it answered, how long it took. Never a
+ * path or a version.
+ */
+function logWelcomeCheck(home: string, env: NodeJS.ProcessEnv, check: RemoteCheck): void {
+  logFrontDoor(frontDoorLogPath(join(home, dbNameForEnv(env.MEMORY_ENV || "production"))), {
+    command: "welcome",
+    route: "ts",
+    exitCode: 0,
+    detail: `update-check source=${check.source} verdict=${check.verdict} ms=${check.ms}`,
+  });
+}
+
 /** Port of the read half of `cmd_runtime`. */
 export async function runRuntimeReadRoute(
   argv: readonly string[],
-  io: RuntimeRouteIo = {},
+  io: InstallRouteIo = {},
 ): Promise<number> {
   const env = io.env ?? process.env;
   const cwd = io.cwd ?? process.cwd();
@@ -280,19 +321,14 @@ export async function runRuntimeReadRoute(
   if (subcommand === "release-notes") {
     const target = firstPositional(args.slice(1)) ?? "latest";
     if (target === "pending") {
-      writeOut(
-        io,
-        renderReleaseNotesBundle(
-          buildPendingReleaseNotes({
-            // `--from` omitted falls back to the checkout's own version,
-            // exactly as the oracle does before normalizing.
-            currentVersion: optionValue(args, "--from") ?? version,
-            ref: optionValue(args, "--ref") ?? "origin/stable",
-            fetch: !args.includes("--no-fetch"),
-            start: cwd,
-          }),
-        ),
-      );
+      const pending = pendingReleaseNotes(args, io, env, version);
+      if ("usage" in pending) {
+        writeErr(io, pending.usage);
+        return 2;
+      }
+      writeOut(io, renderReleaseNotesBundle(pending.bundle));
+      // `unknown` exits 1, as `update --check` does on `unresolved` (CR134, decision 3).
+      return pending.bundle.unknown_reason === null ? 0 : 1;
     } else {
       // The notes ship in the package at the same path as in the checkout
       // (US3 D8), read from the tree that holds the running front door --
@@ -459,9 +495,13 @@ function runRuntimeUpdate(
   // The update lane asks npm, once, whether `-g` addresses this install: a
   // package outside npm's own global root is not the one `npm install -g`
   // would replace. The read routes do not pay for the probe.
+  //
+  // npm runs in the tree the front door runs from -- for a package, the
+  // install's own root -- and never in the cwd, whose `.npmrc` could name
+  // another registry or prefix (CR135). The strategy's own calls do the same.
   const install = detectInstallKind({
     frontDoorPath: frontDoorSelfPath(),
-    npmRootGlobal: npmRootGlobal(),
+    npmRootGlobal: npmRootGlobal(runningTreeRoot()),
   });
   const start = install.kind === "clone" ? install.repository : cwd;
   const channel = channelFor(install, env, homedir(), channelOverride);
@@ -548,6 +588,16 @@ function runRuntimeUpdate(
   });
 
   writeOut(io, renderUpdateResult(result));
+  // The install now holds its channel's version: say so where the welcome card
+  // and the status line read it, or they keep announcing what was just
+  // installed (CR135).
+  if (result.success && !args.includes("--dry-run")) {
+    recordUpToDate(mirrorHome, {
+      channel: channel.value,
+      commit: install.kind === "clone" ? result.newRef : null,
+      checkedAt: isoNow(),
+    });
+  }
   if (repair && result.success) {
     // After the stages, not before them: the instruction is what to do NEXT,
     // and it reads as a caption on a result the operator has already seen.
@@ -596,6 +646,74 @@ function detectThisInstall(): InstallKind {
   return detectInstallKind({ frontDoorPath: frontDoorSelfPath() });
 }
 
+/**
+ * `release-notes pending` for the install that is running, never for the cwd
+ * (CR134), which for a skill is the person's project. A clone reads its own
+ * channel's ref -- or `--ref` -- in its own repository; a package asks the
+ * registry what its channel holds; an install that cannot be identified has no
+ * source, and says so.
+ */
+function pendingReleaseNotes(
+  args: readonly string[],
+  io: InstallRouteIo,
+  env: NodeJS.ProcessEnv,
+  version: string,
+): { bundle: ReleaseNotesBundle } | { usage: string } {
+  const install = io.install ?? detectThisInstall();
+  const osHome = io.osHome ?? homedir();
+  const ref = optionValue(args, "--ref");
+  const fetch = !args.includes("--no-fetch");
+
+  if (install.kind === "clone") {
+    return {
+      bundle: buildPendingReleaseNotes({
+        // `--from` omitted falls back to the running tree's own version.
+        currentVersion: optionValue(args, "--from") ?? version,
+        ref: ref ?? upstreamFor(channelFor(install, env, osHome)),
+        repository: install.repository,
+        fetch,
+      }),
+    };
+  }
+
+  if (install.kind === "package") {
+    if (ref !== null) {
+      return {
+        usage:
+          `release-notes pending: --ref names a git ref, and this install is a package ` +
+          `(${install.name}@${install.version}), which reads its channel from the npm registry\n`,
+      };
+    }
+    const currentVersion = optionValue(args, "--from") ?? install.version;
+    const channel = channelFor(install, env, osHome).value;
+    if (!fetch) {
+      return {
+        bundle: unknownReleaseNotes(
+          currentVersion,
+          `npm ${install.name}@${channel}`,
+          "a package keeps no copy of its channel to read offline; run without --no-fetch",
+        ),
+      };
+    }
+    return {
+      bundle: buildPendingReleaseNotesFromRegistry({
+        currentVersion,
+        install,
+        channel,
+        npm: io.npm ?? defaultNpmRunner,
+      }),
+    };
+  }
+
+  return {
+    bundle: unknownReleaseNotes(
+      optionValue(args, "--from") ?? version,
+      null,
+      `install kind unknown (${install.reason})`,
+    ),
+  };
+}
+
 /**
  * argparse's positional for `release-notes`: the first bare token that is not
  * consumed as the VALUE of `--from` or `--ref`. Walking the list is the only

package/ts/src/frontDoor/sessionStartWelcomeRoute.ts

@@ -0,0 +1,166 @@
+// `conversation-logger session-start --fast --welcome --format json` (CV9.E2.S32).
+//
+// The Pi extension used to open a session with three awaited front-door
+// processes in a row -- `session-start --fast`, `welcome`, and
+// `welcome --status-line` -- paying the loader's fixed cost three times
+// before the user could type. They cannot run in parallel: the first WRITES
+// the orientation the other two READ. They can run in one process, as long as
+// the write commits before the reads. This route is that sequencing and
+// nothing else.
+//
+// What it deliberately does not do:
+//
+//   * It does not teach `loggerCli.ts` to render a welcome card. That module
+//     is the conversation domain; composition across domains is this layer's
+//     job.
+//   * It does not touch `runWelcomeRoute`'s read-only contract. Both renders
+//     run through that route with captured io, AFTER the write handle has
+//     closed, so the card and the status line are byte-identical to the
+//     standalone commands and never share the live write lock with the
+//     card's bounded update check.
+//   * It has no text form. The card is free text; the only safe delimiter is
+//     a JSON envelope.
+//
+// The envelope is for the extension, not for a skill. A skill that called this
+// would put card text in front of the model through a channel the Ariad
+// surface rules do not cover; `checkSkillCommandParity.ts` refuses the flag in
+// every SKILL.md.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { runConversationLoggerRoute } from "./conversationLoggerRoute.ts";
+import { runWelcomeRoute } from "./runtimeRoute.ts";
+
+export const SESSION_START_WELCOME_SCHEMA_VERSION = "1.0.0";
+
+export interface SessionStartWelcomeEnvelope {
+  schemaVersion: typeof SESSION_START_WELCOME_SCHEMA_VERSION;
+  /** The logger's stdout lines, joined with `\n`: what `session-start --fast` prints. */
+  sessionStart: string;
+  /** `mirror welcome`'s stdout minus the trailing newline; `""` when disabled. */
+  welcome: string;
+  /** `mirror welcome --status-line`'s stdout minus the trailing newline; `""` when empty. */
+  statusLine: string;
+}
+
+export interface SessionStartWelcomeOutcome {
+  exitCode: number;
+  /** Content-free category for the front-door log when a render failed after the write. */
+  detail?: string;
+}
+
+export interface SessionStartWelcomeDeps {
+  /** The real write path: opens the live write database, runs `write`, closes it. */
+  withMirrorWriteDb: (
+    argv: readonly string[],
+    write: (db: WritableDatabase, dbPath: string) => Promise<number> | number,
+  ) => Promise<number>;
+  /**
+   * The welcome renderer. Defaults to the real route; the render-failure test
+   * injects one that throws. The write path is never injected: it is the real
+   * one in every test.
+   */
+  renderWelcome?: typeof runWelcomeRoute;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+/** Only the `--fast --welcome` composite answers here; everything else is the plain logger route. */
+export function isSessionStartWelcome(argv: readonly string[]): boolean {
+  return (
+    argv[0] === "conversation-logger" &&
+    argv.includes("session-start") &&
+    argv.includes("--welcome")
+  );
+}
+
+function optionValue(args: readonly string[], name: string): string | null {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+}
+
+/** The logger's `--mirror-home` reaches the welcome renders too, so both read the same home. */
+function welcomeArgv(argv: readonly string[], statusLine: boolean): string[] {
+  const out = ["welcome"];
+  if (statusLine) out.push("--status-line");
+  const home = optionValue(argv, "--mirror-home");
+  if (home !== null) out.push("--mirror-home", home);
+  const sessionId = optionValue(argv, "--session-id");
+  if (statusLine && sessionId !== null) out.push("--session-id", sessionId);
+  return out;
+}
+
+/** The logger's own argv: the composite flags removed, `--format`'s value with it. */
+function withoutCompositeFlags(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i] as string;
+    if (arg === "--welcome") continue;
+    if (arg === "--format") {
+      i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+export async function runSessionStartWelcomeRoute(
+  argv: readonly string[],
+  deps: SessionStartWelcomeDeps,
+): Promise<SessionStartWelcomeOutcome> {
+  const stdout = deps.stdout ?? ((text: string) => process.stdout.write(text));
+  const stderr = deps.stderr ?? ((text: string) => process.stderr.write(text));
+  const renderWelcome = deps.renderWelcome ?? runWelcomeRoute;
+
+  if (!argv.includes("--fast")) {
+    stderr("session-start: --welcome requires --fast (the full session-start runs maintenance)\n");
+    return { exitCode: 2 };
+  }
+  const format = optionValue(argv, "--format");
+  if (format !== "json") {
+    stderr(
+      "session-start: --welcome requires --format json (the card has no safe text delimiter)\n",
+    );
+    return { exitCode: 2 };
+  }
+
+  // 1. The write, through the real path. Its handle is closed when this returns.
+  const loggerArgv = withoutCompositeFlags(argv);
+  const sessionStartLines: string[] = [];
+  const exitCode = await deps.withMirrorWriteDb(loggerArgv, (db, dbPath) =>
+    runConversationLoggerRoute(db, dbPath, loggerArgv, {
+      stdout: (line) => sessionStartLines.push(line),
+      // The logger's refusals keep going to stderr, as they do standalone.
+      stderr: (line) => stderr(`${line}\n`),
+    }),
+  );
+  if (exitCode !== 0) return { exitCode };
+
+  // 2. The reads, after the write committed and its handle closed. A render
+  //    failure must not lose the unmute: the envelope still goes out, with the
+  //    failed field empty, and the category reaches the front-door log.
+  let detail: string | undefined;
+  const render = (statusLine: boolean): string => {
+    let captured = "";
+    try {
+      renderWelcome(welcomeArgv(argv, statusLine), { stdout: (text) => (captured += text) });
+    } catch (error) {
+      detail = `render-failed=${error instanceof Error ? error.name : "unknown"}`;
+      return "";
+    }
+    return stripTrailingNewline(captured);
+  };
+  const envelope: SessionStartWelcomeEnvelope = {
+    schemaVersion: SESSION_START_WELCOME_SCHEMA_VERSION,
+    sessionStart: sessionStartLines.join("\n"),
+    welcome: render(false),
+    statusLine: render(true),
+  };
+  stdout(`${JSON.stringify(envelope)}\n`);
+  return detail ? { exitCode: 0, detail } : { exitCode: 0 };
+}

package/ts/src/frontDoor/stdinSource.ts

@@ -0,0 +1,37 @@
+// Where a stdin-reading route gets its payload (CV21.DS2.US8).
+//
+// Two of the conversation logger's subcommands read a hook payload from
+// stdin: `user-prompt` and `stop`. Until US8 the Claude hook entries did not
+// touch fd 0 and let the route read it. Now an entry reads the payload first,
+// to detect the runtime it is in (`runtimeDetection.ts`), and fd 0 cannot be
+// read twice. So the entry hands the payload over here, and the route takes
+// it before falling back to fd 0.
+//
+// A one-shot handoff rather than an argument because the hooks run the front
+// door in-process (`runFrontDoor`), through the same `main(argv)` every other
+// caller uses, and a payload does not belong in argv: argv is what `ps`
+// shows, and what the Gemini hooks already put a prompt into is the exception
+// this seam avoids repeating.
+
+import { readFileSync } from "node:fs";
+
+let provided: string | null = null;
+
+/** Hand a payload to the next stdin-reading route in this process. */
+export function provideStdin(text: string): void {
+  provided = text;
+}
+
+/** The provided payload, once; else fd 0 to its end; "" when there is none. */
+export function takeStdin(): string {
+  if (provided !== null) {
+    const text = provided;
+    provided = null;
+    return text;
+  }
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}