mirror-mind 0.36.2 → 0.37.0

package/ts/src/frontDoor/mirrorModeRoute.ts

@@ -1,12 +1,22 @@
 import { existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import type { Database, WritableDatabase } from "#db/database.ts";
+import {
+  type DoormanDecision,
+  decideDoorman,
+  doormanPersonas,
+  forgetDoormanDelivery,
+  type MemoryScore,
+  readDoormanSessionState,
+  runDoorman,
+} from "#mirror/doorman.ts";
 import {
   deactivateMirrorState,
   listActiveMirrorJourneys,
   logMirrorResponse,
   runMirrorLoad,
 } from "#mirror/orchestration.ts";
+import { environmentSessionId, resolveNamedRuntimeSessionId } from "#mirror/runtimeSession.ts";
 import {
   activateOperatingMode,
   deactivateOperatingMode,
@@ -16,7 +26,7 @@ import {
 } from "#mode/operatingMode.ts";
 import type { OnProviderCallOutcome } from "#observability/callOutcome.ts";
 import { resolveFamilyProviders } from "#providers/familyProviders.ts";
-import { MIRROR_QUERY_TRANSPORT } from "#providers/transport.ts";
+import { MIRROR_QUERY_TRANSPORT, mirrorQueryTransportFor } from "#providers/transport.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
 
@@ -28,6 +38,8 @@ import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
  */
 export type MirrorRouteEnvironment = {
   MIRROR_SESSION_ID?: string;
+  CLAUDE_CODE_SESSION_ID?: string;
+  CODEX_SESSION_ID?: string;
   MEMORY_RECEPTION?: string;
   MIRROR_TS_MIRROR_LLM_REPLAY?: string;
   MIRROR_TS_MIRROR_EMBEDDING_REPLAY?: string;
@@ -37,14 +49,119 @@ export function isMirrorWrite(argv: readonly string[]): boolean {
   return argv[0] === "mirror" && ["load", "deactivate", "log"].includes(argv[1] ?? "");
 }
 
+/**
+ * `mirror doorman` is a write surface with its own handle discipline
+ * (CV9.DS8.TS2): it is not `isMirrorWrite`, because the front door's shared
+ * write seam opens the live-write path -- a database snapshot -- before any
+ * route runs, and a doorman turn that owes nothing must never pay that.
+ */
+export function isMirrorDoorman(argv: readonly string[]): boolean {
+  return argv[0] === "mirror" && argv[1] === "doorman";
+}
+
+export interface DoormanRouteDeps {
+  /** The database, read-only: enough to decide. */
+  withReadOnlyDatabase: (read: (db: Database) => DoormanDecision) => DoormanDecision | number;
+  /** The database behind the pre-write snapshot: only for a turn that delivers. */
+  withLiveWriteDatabase: (
+    write: (db: WritableDatabase, dbPath: string) => Promise<number>,
+  ) => Promise<number>;
+  onReceptionOutcome?: OnProviderCallOutcome;
+  /** Content-free: the turn's memory scores, hybrid and semantic, for the front-door log. */
+  onMemoryScores?: (scores: readonly MemoryScore[]) => void;
+}
+
+/**
+ * `mirror doorman --prompt "<text>" [--session-id <id>]`: the one doorman as a
+ * command, for the Pi extension (US5). Prints the block or nothing; exit 0.
+ * `mirror doorman --forget [--session-id <id>]`: the runtime compacted the
+ * transcript; the named session's next ordinary turn is full again (US5's
+ * debt). Nothing printed; an unnamed session is nothing to mark.
+ *
+ * Two steps on purpose. The decision is read from a read-only handle; the
+ * live-write handle -- `VACUUM INTO` first, 95 ms measured on a 53 MB database
+ * -- opens only when the decision is `full` or `delta`. The ordinary turn
+ * outside Mirror Mode costs a read and nothing else, as the inject hook's does.
+ */
+export async function runMirrorDoormanRoute(
+  argv: readonly string[],
+  deps: DoormanRouteDeps,
+  env: MirrorRouteEnvironment = process.env,
+): Promise<number> {
+  const args = argv.slice(2);
+  const sessionId = resolveNamedRuntimeSessionId(
+    optionValue(args, "--session-id") ?? null,
+    environmentSessionId(env),
+  );
+  if (hasOption(args, "--forget")) {
+    if (!sessionId) return 0;
+    return deps.withLiveWriteDatabase(async (db) => {
+      forgetDoormanDelivery(db, sessionId, nowIso());
+      return 0;
+    });
+  }
+  const prompt = optionValue(args, "--prompt");
+  if (prompt === null || prompt === undefined) {
+    console.error("mirror doorman requires --prompt");
+    return 2;
+  }
+  const decided = deps.withReadOnlyDatabase((db) =>
+    decideDoorman({
+      prompt,
+      state: readDoormanSessionState(db, sessionId),
+      personas: doormanPersonas(db),
+    }),
+  );
+  if (typeof decided === "number") return decided;
+  if (decided.kind === "nothing") return 0;
+
+  // Providers only now: a turn that delivers may embed (delta) or route
+  // (full); the turn above resolved none, let alone a key.
+  const receptionEnabled = env.MEMORY_RECEPTION !== "0";
+  const family = await resolveFamilyProviders(env, mirrorQueryTransportFor(env));
+  return deps.withLiveWriteDatabase(async (db, dbPath) => {
+    const mirrorHome = dirname(dbPath);
+    const rendered = await runDoorman(db, decided, {
+      identity: basename(mirrorHome),
+      databasePath: dbPath,
+      mirrorHome,
+      user: basename(mirrorHome),
+      sessionId,
+      receptionEnabled,
+      onReceptionOutcome: deps.onReceptionOutcome,
+      llmProvider: receptionEnabled ? family.llm : undefined,
+      embeddingProvider: family.embedding,
+      onMemoryScores: deps.onMemoryScores,
+      newId,
+      nowIso,
+    });
+    process.stdout.write(rendered.stdout);
+    process.stderr.write(rendered.stderr);
+    return 0;
+  });
+}
+
 export function isModeWrite(argv: readonly string[]): boolean {
   if (argv[0] !== "mode") return false;
   const args = modePositionals(argv.slice(1));
   return args[0] === "activate" || args[0] === "deactivate";
 }
 
-export function mirrorDeactivateMissingSession(argv: readonly string[]): boolean {
-  return argv[0] === "mirror" && argv[1] === "deactivate" && !optionValue(argv, "--session-id");
+/**
+ * `mirror deactivate` with nobody naming a session: `--session-id` absent AND
+ * no harness variable (CV9.DS8.US5 -- until then `--session-id` alone, so
+ * `/mm-new` on a Pi whose extension had named the session still refused).
+ */
+export function mirrorDeactivateMissingSession(
+  argv: readonly string[],
+  env: MirrorRouteEnvironment = process.env,
+): boolean {
+  return (
+    argv[0] === "mirror" &&
+    argv[1] === "deactivate" &&
+    !optionValue(argv, "--session-id") &&
+    environmentSessionId(env) === null
+  );
 }
 
 export function runMirrorRead(db: Database, args: readonly string[]): number {
@@ -70,7 +187,10 @@ export async function runMirrorWriteRoute(
   const args = argv.slice(2);
   const sessionId = optionValue(args, "--session-id");
   if (sub === "deactivate") {
-    deactivateMirrorState(db, sessionId as string, nowIso());
+    // The session the caller named, else the harness's (TS2's reader): the
+    // unnamed case was refused before this route ran.
+    const named = resolveNamedRuntimeSessionId(sessionId ?? null, environmentSessionId(env));
+    deactivateMirrorState(db, named as string, nowIso());
     console.error("Mirror Mode deactivated.");
     return 0;
   }
@@ -112,7 +232,11 @@ export async function runMirrorWriteRoute(
     org: hasOption(args, "--org"),
     contextOnly: hasOption(args, "--context-only"),
     sessionId,
-    environmentSessionId: env.MIRROR_SESSION_ID ?? null,
+    // The harness's variable, whichever runtime set it (CV9.DS8.TS2): the
+    // skill's own load on Claude Code or Codex names the session the hooks
+    // write. `mirror log` keeps reading `MIRROR_SESSION_ID` alone: its
+    // fallback is a guess, and widening that is a CR008 question.
+    environmentSessionId: environmentSessionId(env),
     receptionEnabled,
     onReceptionOutcome: options.onReceptionOutcome,
     llmProvider: receptionEnabled ? family?.llm : undefined,

package/ts/src/frontDoor/routing.ts

@@ -8,7 +8,7 @@ import {
   CULTIVATION_SCAN_TRANSPORT,
   DESCRIPTOR_TRANSPORT,
   JOURNAL_TRANSPORT,
-  MIRROR_QUERY_TRANSPORT,
+  mirrorQueryTransportFor,
   type ProviderTransportSpec,
   resolveComposedProviderTransport,
   resolveProviderTransport,
@@ -591,6 +591,16 @@ export function routeByFamily(
           : "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` };
@@ -735,22 +745,23 @@ export function routeByFamily(
 
   if (command === "mirror") {
     const sub = argv[1];
-    if (sub === "load") {
-      const hasQuery = argv.includes("--query");
+    // CV9.DS8.TS2: the doorman decides before it resolves a provider, and a
+    // `nothing` turn resolves none -- but a `full` turn is `load --query`, so
+    // the route answers for the doorman exactly as it answers for that.
+    if (sub === "load" || sub === "doorman") {
+      const hasQuery = sub === "doorman" || argv.includes("--query");
       if (!hasQuery) {
         return { command, engine: "ts", reason: "DS7.US4 deterministic mirror load ported to TS" };
       }
-      // `MEMORY_RECEPTION=0` skips the classifier on both engines, so the
-      // chat fixture stops being required for a replay run; the embedding half
-      // still is, because the query still searches attachments and journeys.
-      const spec =
-        env.MEMORY_RECEPTION === "0"
-          ? {
-              ...MIRROR_QUERY_TRANSPORT,
-              replay: { embedding: MIRROR_QUERY_TRANSPORT.replay?.embedding },
-            }
-          : MIRROR_QUERY_TRANSPORT;
-      return providerRoute(command, env, spec, "load --query");
+      // `MEMORY_RECEPTION=0` skips the classifier, so the chat fixture stops
+      // being required for a replay run; the embedding half still is, because
+      // the query still searches attachments and journeys.
+      return providerRoute(
+        command,
+        env,
+        mirrorQueryTransportFor(env),
+        sub === "doorman" ? "doorman" : "load --query",
+      );
     }
     if (sub === "deactivate" || sub === "log" || sub === "journeys") {
       return { command, engine: "ts", reason: `DS7.US4 mirror ${sub} ported to TS` };
@@ -942,7 +953,7 @@ const TASKS_SUBCOMMANDS = [
 const WEEK_SUBCOMMANDS = ["view", "plan", "save"];
 const CONSOLIDATE_SUBCOMMANDS = ["scan", "apply", "reject", "list"];
 const SHADOW_SUBCOMMANDS = ["scan", "apply", "reject", "list", "show"];
-const MIRROR_SUBCOMMANDS = ["load", "deactivate", "log", "journeys"];
+const MIRROR_SUBCOMMANDS = ["load", "deactivate", "log", "journeys", "doorman"];
 const MODE_SUBCOMMANDS = ["activate", "deactivate", "status"];
 
 /** `mode`'s first positional, past the two options its parser declares; "" when none. */

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/soulRoute.ts

@@ -15,7 +15,7 @@
 import type { Database, WritableDatabase } from "#db/database.ts";
 import { getIdentityContent } from "#identity/identityRead.ts";
 import { persistStickyDefaults } from "#mirror/orchestration.ts";
-import { resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
+import { environmentSessionId, resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
 import { activateOperatingMode } from "#mode/operatingMode.ts";
 import { embeddingLedgerHook } from "#observability/ledgerHooks.ts";
 import { generateEmbeddingSafely } from "#providers/embedding.ts";
@@ -310,7 +310,7 @@ function runLoad(
   const resolvedSessionId = resolveRuntimeSessionId(
     db,
     sessionId,
-    process.env.MIRROR_SESSION_ID ?? null,
+    environmentSessionId(process.env),
   );
   activateOperatingMode(
     db,
@@ -355,7 +355,7 @@ function runFruit(
   sessionId: string | null,
   deps: SoulRouteDeps,
 ): number {
-  const resolved = resolveCliSoulSessionId(db, sessionId, process.env.MIRROR_SESSION_ID ?? null);
+  const resolved = resolveCliSoulSessionId(db, sessionId, environmentSessionId(process.env));
   if (action === "set") {
     if (fruit === null) return usageError("soul fruit set requires a fruit");
     const state = setFruitInMaturation(db, fruit, resolved, deps.nowIso());
@@ -384,7 +384,7 @@ async function runHarvest(
   const resolved = resolveCliSoulSessionId(
     db,
     option("--session-id"),
-    process.env.MIRROR_SESSION_ID ?? null,
+    environmentSessionId(process.env),
   );
   if (action === "set") {
     const state = harvestFruit(db, { fruit, sessionId: resolved }, deps.nowIso());

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

package/ts/src/guards/testTempHomes.ts

@@ -0,0 +1,92 @@
+// CR163 — no test makes a temp home under a literal /tmp.
+//
+// The suite's temp homes are made with `tempDir` (ts/test/helpers/tempDir.ts),
+// under os.tmpdir(), and removed when the test file's process exits. The
+// run-level check (scripts/test_leaves_nothing.sh) proves a run leaves nothing
+// by pointing TMPDIR at an empty directory; it sees every home only because
+// none is made anywhere else. A home under a literal /tmp would escape it, so
+// this guard keeps one from coming back: every `.ts` under ts/test, helpers and
+// support included, in each form the tree has used.
+//
+// A line that is a comment is not a finding, nor is a /tmp that names a path
+// no test creates (an asserted string, a golden's literal). An exception names
+// its reason, and one that no longer matches anything is reported as stale, so
+// it cannot outlive that reason.
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Files allowed a literal /tmp temp home, each with the reason it must stay. */
+export const EXCEPTIONS: Readonly<Record<string, string>> = {
+  "ts/test/helpers/builderWorld.ts":
+    "CR164: pathsWalk sees a leaked absolute path only under a short root",
+  "ts/test/scripts/testTempHomes.test.ts": "this guard's own cases, held as strings",
+};
+
+/** Each form the tree has used to make a temp home under a literal /tmp. */
+const FORMS: readonly RegExp[] = [
+  // mkdtempSync("/tmp/…"), a template, the async mkdtemp; the argument may open a new line.
+  /\bmkdtemp(?:Sync)?\(\s*["'`]\/tmp\//g,
+  // mkdtempSync(join("/tmp", …))
+  /\bmkdtemp(?:Sync)?\(\s*join\(\s*["'`]\/tmp["'`]/g,
+  // realpathSync("/tmp"), as in mkdtempSync(join(realpathSync("/tmp"), …))
+  /\brealpathSync\(\s*["'`]\/tmp["'`]\s*\)/g,
+];
+
+export interface TempHomeFinding {
+  /** Repository-relative, with forward slashes. */
+  readonly file: string;
+  readonly line: number;
+  readonly text: string;
+}
+
+export interface TempHomeSweep {
+  readonly findings: readonly TempHomeFinding[];
+  /** Exceptions whose file no longer makes such a home. */
+  readonly staleExceptions: readonly string[];
+}
+
+function isComment(line: string): boolean {
+  const text = line.trimStart();
+  return text.startsWith("//") || text.startsWith("*") || text.startsWith("/*");
+}
+
+function testFiles(repoRoot: string): string[] {
+  const testRoot = join(repoRoot, "ts", "test");
+  return readdirSync(testRoot, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".ts"))
+    .map((entry) => relative(repoRoot, join(entry.parentPath, entry.name)).split(sep).join("/"))
+    .sort();
+}
+
+function scan(source: string): { line: number; text: string }[] {
+  const lines = source.split("\n");
+  const hits = new Map<number, string>();
+  for (const form of FORMS) {
+    for (const match of source.matchAll(form)) {
+      const line = source.slice(0, match.index).split("\n").length;
+      if (!isComment(lines[line - 1])) hits.set(line, lines[line - 1].trim());
+    }
+  }
+  return [...hits].sort(([a], [b]) => a - b).map(([line, text]) => ({ line, text }));
+}
+
+/** Every temp home under a literal /tmp in `ts/test` below `repoRoot`, but the exceptions. */
+export function findLiteralTmpHomes(
+  repoRoot: string,
+  exceptions: Readonly<Record<string, string>> = EXCEPTIONS,
+): TempHomeSweep {
+  const findings: TempHomeFinding[] = [];
+  const excepted = new Set<string>();
+  for (const file of testFiles(repoRoot)) {
+    const hits = scan(readFileSync(join(repoRoot, file), "utf8"));
+    if (hits.length === 0) continue;
+    if (file in exceptions) {
+      excepted.add(file);
+      continue;
+    }
+    for (const hit of hits) findings.push({ file, ...hit });
+  }
+  const staleExceptions = Object.keys(exceptions).filter((file) => !excepted.has(file));
+  return { findings, staleExceptions };
+}