mirror-mind 0.36.1 → 0.36.3

package/ts/src/frontDoor/conversationLoggerRoute.ts

@@ -35,6 +35,24 @@ function subcommandOf(args: readonly string[]): string {
  */
 const readStdin = takeStdin;
 
+/**
+ * `--payload <json>`: a hook subcommand's payload in argv rather than on stdin
+ * (CR160). Pi's extension reaches the core through `pi.exec`, which cannot write
+ * a child's stdin, and since CR160 it sends Pi's turns to `user-prompt` and
+ * `stop`. Pi's prompt has travelled in argv since CV9, as `log-user`'s argument,
+ * so this is the exposure Pi always had, no wider (`stdinSource.ts`). The option
+ * is taken out of argv before the subcommand sees it, and a route given one
+ * never reads fd 0: a stdin pipe nobody closes cannot hang it.
+ */
+function takePayloadOption(args: readonly string[]): { payload: string | null; rest: string[] } {
+  const index = args.indexOf("--payload");
+  if (index === -1 || index + 1 >= args.length) return { payload: null, rest: [...args] };
+  return {
+    payload: args[index + 1] as string,
+    rest: [...args.slice(0, index), ...args.slice(index + 2)],
+  };
+}
+
 /**
  * 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
@@ -51,7 +69,7 @@ export async function runConversationLoggerRoute(
   argv: readonly string[],
   io: ConversationLoggerRouteIo = {},
 ): Promise<number> {
-  const args = argv.slice(1);
+  const { payload, rest: args } = takePayloadOption(argv.slice(1));
   const subcommand = subcommandOf(args);
   const runtime = createLoggerRuntime({
     db,
@@ -73,7 +91,7 @@ export async function runConversationLoggerRoute(
       }),
   });
   const result = await runConversationLoggerCommand(db, args, runtime, {
-    stdin: STDIN_SUBCOMMANDS.has(subcommand) ? readStdin() : undefined,
+    stdin: STDIN_SUBCOMMANDS.has(subcommand) ? (payload ?? readStdin()) : undefined,
   });
   const out = io.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
   const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));

package/ts/src/frontDoor/dbSafetyToolsRoute.ts

@@ -27,6 +27,7 @@ import {
   scanDatabase,
 } from "#repair/encodingRepair.ts";
 import { expandHome } from "#util/paths.ts";
+import { parseArgs } from "#util/strictArgs.ts";
 import { MirrorHomeNotConfiguredError } from "./dbPath.ts";
 
 const BACKUP_USAGE =
@@ -34,41 +35,6 @@ const BACKUP_USAGE =
 const REPAIR_USAGE =
   "usage: repair-encoding [-h] [--mirror-home MIRROR_HOME] [--apply] [--no-backup] [--limit LIMIT]";
 
-interface ParsedArgs {
-  flags: Set<string>;
-  values: Map<string, string>;
-  error: string | null;
-}
-
-/** argparse-shaped parsing: known flags, known valued options, nothing else. */
-function parseArgs(
-  args: readonly string[],
-  spec: { flags: readonly string[]; valued: readonly string[] },
-): ParsedArgs {
-  const flags = new Set<string>();
-  const values = new Map<string, string>();
-  const unrecognized: string[] = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index] as string;
-    if (spec.flags.includes(arg)) {
-      flags.add(arg);
-    } else if (spec.valued.includes(arg)) {
-      const value = args[index + 1];
-      if (value === undefined)
-        return { flags, values, error: `argument ${arg}: expected one argument` };
-      values.set(arg, value);
-      index += 1;
-    } else {
-      unrecognized.push(arg);
-    }
-  }
-  return {
-    flags,
-    values,
-    error: unrecognized.length > 0 ? `unrecognized arguments: ${unrecognized.join(" ")}` : null,
-  };
-}
-
 function usageError(usage: string, program: string, message: string): number {
   process.stderr.write(`${usage}\n${program}: error: ${message}\n`);
   return 2;

package/ts/src/frontDoor/importedConversationsRoute.ts

@@ -0,0 +1,337 @@
+// `mirror conversations imported` (CR154): see the Pi conversations an earlier
+// version imported rather than logged, and remove the ones a person names.
+//
+//   conversations imported [--project TEXT]
+//   conversations imported remove (ID... | --all [--project FOLDER]) [--apply]
+//
+// Folders first: a home holds hundreds of imports, and the decision a person
+// makes is about where they came from. Removal is a dry run until `--apply`,
+// which decides the set first (refusals and an empty set stop there, with no
+// backup), takes the dated backup and verifies it, and only then removes, in
+// one transaction that decides the set again and refuses if it moved. Every
+// option is declared: a typo is refused before anything opens, because under a
+// lenient parser a misspelled `--project` would widen a removal to every import
+// in the home.
+//
+// The module that decides what an import is, and removes it, is
+// `#conversation/importedConversations.ts`; this file parses, opens, and
+// prints. Nothing here is offered to a model: no MCP tool, no skill.
+
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseArchiveStamp, RETENTION_DAYS } from "#backup/zipBackup.ts";
+import {
+  countLiveSessionsByFolder,
+  type ImportedConversation,
+  ImportRemovalRefusedError,
+  type ImportRemovalRequest,
+  ImportRemovalSetMovedError,
+  listImportedPiConversations,
+  planImportRemoval,
+  removeImportedConversations,
+  summarizeImports,
+} from "#conversation/importedConversations.ts";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { PROGRAM } from "#util/program.ts";
+import { shellWord } from "#util/shellWord.ts";
+import { parseArgs } from "#util/strictArgs.ts";
+import { backupPathFor } from "./liveBackup.ts";
+
+const USAGE = [
+  `usage: ${PROGRAM} conversations imported [--project TEXT] [--mirror-home PATH] [--db-path PATH]`,
+  `       ${PROGRAM} conversations imported remove (ID ... | --all [--project FOLDER]) [--apply] [--mirror-home PATH] [--db-path PATH]`,
+].join("\n");
+
+/** How argparse names the program in an error line. */
+const PROG = `${PROGRAM} conversations imported`;
+
+const WHAT_AN_IMPORT_IS =
+  "Mirror copied these from Pi's session files instead of logging them as they happened. " +
+  "Since v0.36.1 it imports none.";
+
+const HOME_OPTIONS = ["--mirror-home", "--db-path"] as const;
+
+export interface ImportedConversationsIo {
+  /** The home's database, read-only: the listing and the dry run. */
+  withReadOnlyDatabase: (read: (db: Database) => number) => number;
+  /** The home's database behind the front door's pre-write backup: `--apply` only. */
+  withLiveWriteDatabase: (write: (db: WritableDatabase, dbPath: string) => number) => number;
+  /** The dated archive `repair-journeys --apply` gates on; its path, or null on failure. */
+  backup: (dbPath: string) => string | null;
+  verifyBackup: (archivePath: string) => { valid: boolean; note: string | null };
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+export function isImportedConversationsCommand(argv: readonly string[]): boolean {
+  return argv[0] === "conversations" && argv[1] === "imported";
+}
+
+function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+
+function day(instant: string): string {
+  return instant.slice(0, 10);
+}
+
+function localDay(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function byFolder(conversations: readonly ImportedConversation[]): [string, number][] {
+  const counts = new Map<string, number>();
+  for (const item of conversations) counts.set(item.folder, (counts.get(item.folder) ?? 0) + 1);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+
+function messagesIn(conversations: readonly ImportedConversation[]): number {
+  return conversations.reduce((sum, item) => sum + item.messageCount, 0);
+}
+
+export function runImportedConversationsRoute(
+  argv: readonly string[],
+  io: ImportedConversationsIo,
+): number {
+  const out = io.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const usageError = (message: string): number => {
+    err(USAGE);
+    err(`${PROG}: error: ${message}`);
+    return 2;
+  };
+
+  const rest = argv.slice(2);
+  if (rest.includes("-h") || rest.includes("--help")) {
+    out(USAGE);
+    return 0;
+  }
+  const removing = rest[0] === "remove";
+  const parsed = parseArgs(removing ? rest.slice(1) : rest, {
+    flags: removing ? ["--all", "--apply"] : [],
+    valued: ["--project", ...HOME_OPTIONS],
+    positionals: removing,
+  });
+  if (parsed.error) return usageError(parsed.error);
+  const project = parsed.values.get("--project") ?? null;
+
+  if (!removing) return list(io, out, project);
+
+  const ids = parsed.positionals;
+  const all = parsed.flags.has("--all");
+  if (ids.length > 0 && all) return usageError("give conversation ids or --all, not both");
+  if (ids.length === 0 && !all) return usageError("give conversation ids, or --all");
+  if (project !== null && !all) {
+    return usageError("--project narrows --all; give it with --all, not with ids");
+  }
+  const request: ImportRemovalRequest = all ? { all: true, folder: project } : { ids };
+
+  if (!parsed.flags.has("--apply")) {
+    // The command that applies this dry run, to the same home, every value quoted.
+    const words = ["conversations", "imported", "remove"];
+    if (all) {
+      words.push("--all");
+      if (project !== null) words.push("--project", project);
+    } else {
+      words.push(...ids);
+    }
+    for (const option of HOME_OPTIONS) {
+      const value = parsed.values.get(option);
+      if (value !== undefined) words.push(option, value);
+    }
+    words.push("--apply");
+    const applyCommand = [PROGRAM, ...words.map(shellWord)].join(" ");
+    return dryRun(io, out, err, request, applyCommand);
+  }
+  return apply(io, out, err, request);
+}
+
+function list(
+  io: ImportedConversationsIo,
+  out: (line: string) => void,
+  project: string | null,
+): number {
+  return io.withReadOnlyDatabase((db) => {
+    const imports = listImportedPiConversations(db);
+    if (imports.length === 0) {
+      out("No imported Pi conversations in this home.");
+      return 0;
+    }
+    const needle = project?.toLowerCase() ?? null;
+    const shown =
+      needle === null
+        ? imports
+        : imports.filter((item) => item.folder.toLowerCase().includes(needle));
+    if (shown.length === 0) {
+      out(`No imported Pi conversations from a folder matching '${project}'.`);
+      return 0;
+    }
+    const summary = summarizeImports(shown, countLiveSessionsByFolder(db));
+    const scope = project === null ? "" : `, from folders matching '${project}'`;
+    out(
+      `Imported Pi conversations: ${summary.conversations} (${plural(summary.messages, "message")}), ` +
+        `imported ${day(summary.firstImportedAt ?? "")} to ${day(summary.lastImportedAt ?? "")}${scope}.`,
+    );
+    out(WHAT_AN_IMPORT_IS);
+    out("");
+    out("  imported  logged live here  folder");
+    for (const folder of summary.folders) {
+      const live = folder.loggedLive === null ? "-" : String(folder.loggedLive);
+      out(`${String(folder.imported).padStart(10)}${live.padStart(18)}  ${folder.folder}`);
+    }
+    if (project !== null) {
+      out("");
+      for (const item of shown) {
+        out(
+          `  ${day(item.importedAt)}  ${item.id}  ${plural(item.messageCount, "msg")}  ${item.folder}  ${item.title ?? "(untitled)"}`,
+        );
+      }
+    }
+    out("");
+    out(`To see a folder's conversations:  ${PROGRAM} conversations imported --project <text>`);
+    out(
+      `To remove a folder's imports:     ${PROGRAM} conversations imported remove --all --project <folder>`,
+    );
+    out("                                  (it shows what it would remove; add --apply to remove)");
+    return 0;
+  });
+}
+
+function dryRun(
+  io: ImportedConversationsIo,
+  out: (line: string) => void,
+  err: (line: string) => void,
+  request: ImportRemovalRequest,
+  applyCommand: string,
+): number {
+  return io.withReadOnlyDatabase((db) => {
+    const plan = planImportRemoval(db, request);
+    if (!plan.ok) {
+      err(`${plan.refusal}. Nothing was removed.`);
+      return 1;
+    }
+    if (plan.conversations.length === 0) {
+      out("Nothing to remove.");
+      return 0;
+    }
+    out(
+      `Would remove ${plural(plan.conversations.length, "imported Pi conversation")} ` +
+        `(${plural(messagesIn(plan.conversations), "message")}):`,
+    );
+    for (const [folder, count] of byFolder(plan.conversations)) {
+      out(`${String(count).padStart(10)}  ${folder}`);
+    }
+    out("Nothing was removed. To remove them, run:");
+    out(`  ${applyCommand}`);
+    return 0;
+  });
+}
+
+function apply(
+  io: ImportedConversationsIo,
+  out: (line: string) => void,
+  err: (line: string) => void,
+  request: ImportRemovalRequest,
+): number {
+  // Decide first, read-only: a refusal or an empty set stops here, and takes no
+  // backup. A holder rather than a variable: it is assigned inside a callback.
+  const decided: { conversations: ImportedConversation[] | null } = { conversations: null };
+  const decidedCode = io.withReadOnlyDatabase((db) => {
+    const plan = planImportRemoval(db, request);
+    if (!plan.ok) {
+      err(`${plan.refusal}. Nothing was removed.`);
+      return 1;
+    }
+    if (plan.conversations.length === 0) {
+      out("Nothing to remove.");
+      return 0;
+    }
+    decided.conversations = plan.conversations;
+    return 0;
+  });
+  const expected = decided.conversations;
+  if (decidedCode !== 0 || expected === null) return decidedCode;
+
+  return io.withLiveWriteDatabase((db, dbPath) => {
+    let archive: string | null;
+    try {
+      archive = io.backup(dbPath);
+    } catch {
+      archive = null;
+    }
+    if (archive === null) {
+      err("The backup failed, so nothing was removed.");
+      return 1;
+    }
+    const verification = io.verifyBackup(archive);
+    if (!verification.valid) {
+      err(
+        `The backup ${archive} did not verify (${verification.note ?? "no reason given"}), so nothing was removed.`,
+      );
+      return 1;
+    }
+    let removed: { conversations: ImportedConversation[]; messages: number };
+    try {
+      removed = removeImportedConversations(
+        db,
+        request,
+        expected.map((item) => item.id),
+      );
+    } catch (error) {
+      if (error instanceof ImportRemovalSetMovedError) {
+        err(
+          "The imports changed while the backup was taken, so nothing was removed. Run it again.",
+        );
+        return 1;
+      }
+      if (error instanceof ImportRemovalRefusedError) {
+        err(`${error.message}. Nothing was removed.`);
+        return 1;
+      }
+      throw error;
+    }
+    out(`Backup: ${archive} (verified).`);
+    out(
+      `Removed ${plural(removed.conversations.length, "imported Pi conversation")} ` +
+        `(${plural(removed.messages, "message")}) from ${plural(byFolder(removed.conversations).length, "folder")}.`,
+    );
+    out("Memories and provider-call records that named them were kept, unlinked.");
+    for (const line of backupsHoldingCopies(dbPath, removed.conversations)) out(line);
+    return 0;
+  });
+}
+
+/**
+ * Where copies of what was just removed still live: the dated archives made
+ * since the earliest removed import, and the pre-write backup. Named so a person
+ * can delete them; nothing here deletes them.
+ */
+function backupsHoldingCopies(dbPath: string, removed: readonly ImportedConversation[]): string[] {
+  // An archive made before the earliest removed import cannot hold any of them.
+  const since = Math.min(...removed.map((item) => Date.parse(item.importedAt)));
+  const backupsDir = join(dirname(dbPath), "backups");
+  const archives = existsSync(backupsDir)
+    ? readdirSync(backupsDir)
+        .map((name) => ({ name, made: parseArchiveStamp(name) }))
+        .filter((entry): entry is { name: string; made: Date } => entry.made !== null)
+        .filter((entry) => entry.made.getTime() >= since)
+        .sort((a, b) => a.made.getTime() - b.made.getTime())
+    : [];
+  const preWrite = backupPathFor(dbPath);
+  const lines: string[] = [];
+  if (archives.length > 0) {
+    const oldest = localDay((archives[0] as { made: Date }).made);
+    const newest = localDay((archives[archives.length - 1] as { made: Date }).made);
+    const made = oldest === newest ? oldest : `${oldest} to ${newest}`;
+    lines.push(
+      `  ${plural(archives.length, "dated archive")} in ${backupsDir}, made ${made} ` +
+        `(archives are removed after ${RETENTION_DAYS} days);`,
+    );
+  }
+  if (existsSync(preWrite)) {
+    lines.push(`  the pre-write backup ${preWrite} (replaced by the next write).`);
+  }
+  if (lines.length === 0) return ["No backup in this home holds a copy."];
+  return ["Copies remain in this home's backups until you delete them or they age out:", ...lines];
+}

package/ts/src/frontDoor/routing.ts

@@ -579,6 +579,28 @@ export function routeByFamily(
         reason: "DS7.US10 conversations append boundary ported to TS",
       };
     }
+    // CR154: allowlisted by name for the same reason, before it shipped. Its
+    // apply is named apart, so the front-door log tells a removal from a look.
+    if (argv[1] === "imported") {
+      const applying = argv[2] === "remove" && argv.includes("--apply");
+      return {
+        command,
+        engine: "ts",
+        reason: applying
+          ? "CR154 conversations imported remove --apply"
+          : "CR154 conversations imported",
+      };
+    }
+    // CR160: allowlisted by name like CR154's, its apply named apart.
+    if (argv[1] === "skill-turns") {
+      return {
+        command,
+        engine: "ts",
+        reason: argv.includes("--apply")
+          ? "CR160 conversations skill-turns --apply"
+          : "CR160 conversations skill-turns",
+      };
+    }
     const writeFlag = TS4_LIFECYCLE_WRITE_FLAGS.find((flag) => argv.includes(flag));
     if (writeFlag) {
       return { command, engine: "ts", reason: `DS7.TS4 ${writeFlag} ported to TS` };

package/ts/src/frontDoor/skillTurnsRoute.ts

@@ -0,0 +1,213 @@
+// `mirror conversations skill-turns` (CR160): see the Pi user turns an earlier
+// version stored as a skill's body, and repair them.
+//
+//   conversations skill-turns [--apply] [--mirror-home PATH] [--db-path PATH]
+//
+// A dry run until `--apply`. The dry run names what the repair would change: by
+// skill, how many rows keep their Mirror question and how many go; each
+// conversation it would delete because it leaves it with no user turn, with its
+// message count (A7); how many titles it would rebuild. `--apply` decides first
+// (nothing to repair stops there, with no backup), takes the dated backup and
+// verifies it, and only then repairs, in one transaction that decides again and
+// refuses if anything moved. Every option is declared: a typo is refused before
+// anything opens. Shaped as CR154's `conversations imported remove`.
+//
+// The module that decides what a stored skill turn is, and repairs it, is
+// `#conversation/piSkillTurns.ts`; this file parses, opens, and prints. Nothing
+// here is offered to a model: no MCP tool, no skill.
+
+import { RETENTION_DAYS } from "#backup/zipBackup.ts";
+import {
+  applySkillTurnRepair,
+  planSkillTurnRepair,
+  type SkillTurnRepairPlan,
+  type SkillTurnRepairResult,
+  SkillTurnRepairSetMovedError,
+  skillTurnRepairKey,
+} from "#conversation/piSkillTurns.ts";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { PROGRAM } from "#util/program.ts";
+import { shellWord } from "#util/shellWord.ts";
+import { parseArgs } from "#util/strictArgs.ts";
+
+const USAGE = `usage: ${PROGRAM} conversations skill-turns [--apply] [--mirror-home PATH] [--db-path PATH]`;
+
+/** How argparse names the program in an error line. */
+const PROG = `${PROGRAM} conversations skill-turns`;
+
+const WHAT_A_SKILL_TURN_IS =
+  "Until CR160, Mirror recorded the skill Pi expanded, instead of what was typed.";
+
+const HOME_OPTIONS = ["--mirror-home", "--db-path"] as const;
+
+export interface SkillTurnsIo {
+  /** The home's database, read-only: the dry run, and the decision before `--apply`. */
+  withReadOnlyDatabase: (read: (db: Database) => number) => number;
+  /** The home's database behind the front door's pre-write backup: `--apply` only. */
+  withLiveWriteDatabase: (write: (db: WritableDatabase, dbPath: string) => number) => number;
+  /** The dated archive; its path, or null on failure. */
+  backup: (dbPath: string) => string | null;
+  verifyBackup: (archivePath: string) => { valid: boolean; note: string | null };
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+export function isSkillTurnsCommand(argv: readonly string[]): boolean {
+  return argv[0] === "conversations" && argv[1] === "skill-turns";
+}
+
+function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+
+function isEmpty(plan: SkillTurnRepairPlan): boolean {
+  return plan.turns.length === 0 && plan.conversationsToRetitle.length === 0;
+}
+
+export function runSkillTurnsRoute(argv: readonly string[], io: SkillTurnsIo): number {
+  const out = io.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const rest = argv.slice(2);
+  if (rest.includes("-h") || rest.includes("--help")) {
+    out(USAGE);
+    return 0;
+  }
+  const parsed = parseArgs(rest, { flags: ["--apply"], valued: [...HOME_OPTIONS] });
+  if (parsed.error) {
+    err(USAGE);
+    err(`${PROG}: error: ${parsed.error}`);
+    return 2;
+  }
+  if (!parsed.flags.has("--apply")) {
+    // The command that applies this dry run, to the same home, every value quoted.
+    const words = ["conversations", "skill-turns"];
+    for (const option of HOME_OPTIONS) {
+      const value = parsed.values.get(option);
+      if (value !== undefined) words.push(option, value);
+    }
+    words.push("--apply");
+    return dryRun(io, out, [PROGRAM, ...words.map(shellWord)].join(" "));
+  }
+  return apply(io, out, err);
+}
+
+function dryRun(io: SkillTurnsIo, out: (line: string) => void, applyCommand: string): number {
+  return io.withReadOnlyDatabase((db) => {
+    const plan = planSkillTurnRepair(db);
+    if (isEmpty(plan)) {
+      out("No Pi user turns stored as a skill's body in this home.");
+      return 0;
+    }
+    if (plan.turns.length > 0) {
+      const conversations = new Set(plan.turns.map((turn) => turn.conversationId)).size;
+      out(
+        `Pi user turns stored as a skill's body: ${plan.turns.length}, in ${plural(conversations, "conversation")}.`,
+      );
+      out(WHAT_A_SKILL_TURN_IS);
+      out("");
+      out("  question kept  removed  skill");
+      for (const [skill, kept, removed] of bySkill(plan)) {
+        out(`${String(kept).padStart(15)}${String(removed).padStart(9)}  ${skill}`);
+      }
+      out("");
+    }
+    if (plan.conversationsToDelete.length > 0) {
+      out(
+        `Would delete ${plural(plan.conversationsToDelete.length, "conversation")} left with no user turn:`,
+      );
+      for (const item of plan.conversationsToDelete) {
+        out(
+          `  ${item.startedAt.slice(0, 10)}  ${item.id.slice(0, 8)}  ${plural(item.messageCount, "message")}  ${item.title ?? "(untitled)"}`,
+        );
+      }
+    }
+    const retitles = plan.conversationsToRetitle.length;
+    if (retitles > 0) {
+      out(
+        `Would retitle ${plural(retitles, "conversation")} from ${retitles === 1 ? "its" : "their"} first remaining user turn.`,
+      );
+    }
+    out("Replies, summaries, and memories stay.");
+    out("Nothing was changed. To repair them, run:");
+    out(`  ${applyCommand}`);
+    return 0;
+  });
+}
+
+/** By skill: [skill, rows that keep their question, rows that go]; most first, then by name. */
+function bySkill(plan: SkillTurnRepairPlan): [string, number, number][] {
+  const counts = new Map<string, [number, number]>();
+  for (const turn of plan.turns) {
+    const [kept, removed] = counts.get(turn.skill) ?? [0, 0];
+    counts.set(turn.skill, turn.question !== null ? [kept + 1, removed] : [kept, removed + 1]);
+  }
+  return [...counts.entries()]
+    .map(([skill, [kept, removed]]): [string, number, number] => [skill, kept, removed])
+    .sort((a, b) => b[1] + b[2] - (a[1] + a[2]) || a[0].localeCompare(b[0]));
+}
+
+function apply(io: SkillTurnsIo, out: (line: string) => void, err: (line: string) => void): number {
+  // Decide first, read-only: nothing to repair stops here, and takes no backup. A
+  // holder rather than a variable: it is assigned inside a callback.
+  const decided: { key: string | null } = { key: null };
+  const decidedCode = io.withReadOnlyDatabase((db) => {
+    const plan = planSkillTurnRepair(db);
+    if (isEmpty(plan)) {
+      out("Nothing to repair.");
+      return 0;
+    }
+    decided.key = skillTurnRepairKey(plan);
+    return 0;
+  });
+  const expectedKey = decided.key;
+  if (decidedCode !== 0 || expectedKey === null) return decidedCode;
+
+  return io.withLiveWriteDatabase((db, dbPath) => {
+    let archive: string | null;
+    try {
+      archive = io.backup(dbPath);
+    } catch {
+      archive = null;
+    }
+    if (archive === null) {
+      err("The backup failed, so nothing was changed.");
+      return 1;
+    }
+    const verification = io.verifyBackup(archive);
+    if (!verification.valid) {
+      err(
+        `The backup ${archive} did not verify (${verification.note ?? "no reason given"}), so nothing was changed.`,
+      );
+      return 1;
+    }
+    let result: SkillTurnRepairResult;
+    try {
+      result = applySkillTurnRepair(db, expectedKey);
+    } catch (error) {
+      if (error instanceof SkillTurnRepairSetMovedError) {
+        err(
+          "The stored skill turns changed while the backup was taken, so nothing was changed. Run it again.",
+        );
+        return 1;
+      }
+      throw error;
+    }
+    out(`Backup: ${archive} (verified).`);
+    out(
+      `Kept ${plural(result.kept, "Mirror question")}; removed ${plural(result.removed, "skill turn")}.`,
+    );
+    if (result.conversationsDeleted > 0) {
+      out(
+        `Deleted ${plural(result.conversationsDeleted, "conversation")} left with no user turn, ` +
+          `with ${plural(result.messagesDeletedWithConversations, "more message")}.`,
+      );
+      out("Memories and provider-call records that named them were kept, unlinked.");
+    }
+    if (result.conversationsRetitled > 0) {
+      out(`Retitled ${plural(result.conversationsRetitled, "conversation")}.`);
+    }
+    out(`Copies remain in this home's backups until they age out (${RETENTION_DAYS} days).`);
+    return 0;
+  });
+}

package/ts/src/frontDoor/stdinSource.ts

@@ -12,6 +12,11 @@
 // caller uses, and a payload does not belong in argv: argv is what `ps`
 // shows, and what the Gemini CLI hooks (retired by CV21.DS8.US1) put a prompt
 // into is the exception this seam avoids repeating.
+//
+// One exception stands, and is no wider than before: Pi's extension reaches the
+// core through `pi.exec`, which cannot write a child's stdin, so it passes the
+// payload as `--payload` (CR160, `conversationLoggerRoute.ts`). Pi's prompt has
+// travelled in argv since CV9, as `log-user`'s argument.
 
 import { readFileSync } from "node:fs";