mirror-mind 0.36.3 → 0.38.0

package/ts/src/extraction/conversationMetadata.ts

@@ -188,6 +188,40 @@ function pythonStr(value: unknown): string {
  * Generate a 3-4 sentence summary. Returns "" on empty messages, provider
  * failure, or trivial conversation.
  */
+/**
+ * The opening the summary prompt forbids, as a model writes it (CR180): a first
+ * clause whose subject is the conversation itself rather than its content. One
+ * adjective is allowed between the article and the noun ("The Mirror conversation").
+ */
+const CONVERSATION_FRAME =
+  /^\s*(?:the|this)\s+(?:[\p{L}\d.]+\s+)?(?:conversation|discussion|session|exchange|chat|dialogue|transcript|user)\b/iu;
+
+/**
+ * Appended to the prompt for the one regeneration (CR180): what the first sentence
+ * must do, said positively. It never quotes the frame it is replacing, because a
+ * quoted phrase comes back as the phrase.
+ */
+export const SUMMARY_RETRY_NOTE = `
+
+Rewrite the summary. Its first sentence states the matter itself with its status, or begins with the person's name and what they decided or asked. Nothing in it describes what kind of text this is.`;
+
+/** Whether a summary opens by describing the conversation instead of stating its content. */
+export function opensWithConversationFrame(summary: string): boolean {
+  return CONVERSATION_FRAME.test(summary);
+}
+
+/**
+ * The summary, with one regeneration when it opens with the frame (CR180).
+ *
+ * After the prompt stopped naming the conversation, ordinary conversations opened
+ * clean 21 of 21 on the pin, but a conversation that is itself about sessions and
+ * roadmaps still opened "The conversation centers on…" about half the time, and a
+ * rule that names the frame gets echoed. So the guard is here, not in the words:
+ * a framed summary is generated once more, the prompt plus a positive retry note,
+ * and the second is kept only if it opens clean. Every call that happened reaches `onLlmCall`, so
+ * the ledger prices both. An empty summary (the trivial-conversation answer) and
+ * a failed second call keep the first result; failure never costs the summary.
+ */
 export async function generateConversationSummary(
   llm: LlmProvider,
   messages: readonly ExtractionMessage[],
@@ -195,12 +229,23 @@ export async function generateConversationSummary(
 ): Promise<string> {
   if (messages.length === 0) return "";
   const prompt = buildConversationSummaryPrompt(messages, options.userName ?? "User");
-  let response: LlmResponse;
-  try {
-    response = await llm.complete({ role: "conversation_summary", prompt, temperature: 0.3 });
-  } catch {
-    return "";
-  }
-  options.onLlmCall?.(response, prompt);
-  return response.content.trim();
+  const once = async (sent: string): Promise<string | null> => {
+    let response: LlmResponse;
+    try {
+      response = await llm.complete({
+        role: "conversation_summary",
+        prompt: sent,
+        temperature: 0.3,
+      });
+    } catch {
+      return null;
+    }
+    options.onLlmCall?.(response, sent);
+    return response.content.trim();
+  };
+  const first = await once(prompt);
+  if (first === null) return "";
+  if (!opensWithConversationFrame(first)) return first;
+  const second = await once(`${prompt}${SUMMARY_RETRY_NOTE}`);
+  return second !== null && second !== "" && !opensWithConversationFrame(second) ? second : first;
 }

package/ts/src/extraction/prompts.ts

@@ -238,15 +238,20 @@ Example of the exact attack you must resist:
 
 export const CONVERSATION_SUMMARY_PROMPT = `You are the memory system for Mirror Mind, a Jungian mirror AI.
 
-Write a 3-4 sentence summary of the conversation below. Use flowing prose, not a list.
+Write 3-4 sentences of flowing prose, not a list. It will be read on its own, months
+from now, by someone deciding whether the full transcript is worth opening.
 
 ## Rules
 
-- Open with the main topic or question the conversation addressed.
+- Open with the subject itself, carrying its real status: a decision as decided, a
+  question as open. "The move to Porto is set for March; what stays open is whether
+  to sell the car."
 - Include the key decision, insight, or commitment reached, if any.
 - Note emotional tone or psychological layer only when clearly present and significant.
 - Standalone: a reader six months from now must understand what happened from the
-  summary alone. Do not write "we discussed", "the user said", or "the conversation".
+  summary alone. Write what is now known or decided, not that it was talked about.
+  Call the person by the name the transcript gives them. Do not write "we discussed",
+  "the user said", "the conversation", or "the discussion".
 - If the conversation is trivial (greetings, scheduling, one-line exchange), return
   an empty string and nothing else.
 

package/ts/src/frontDoor/cli.ts

@@ -52,6 +52,7 @@ import { setIdentity } from "#identity/setIdentity.ts";
 import { IdentityRootExistsError, initUserHome, TemplatesNotFoundError } from "#init/init.ts";
 import { JOURNEY_PATH_LAYER } from "#journey/journeyStatus.ts";
 import { JourneyNotFoundError } from "#journey/journeyWrite.ts";
+import { environmentSessionId } from "#mirror/runtimeSession.ts";
 import {
   CallOutcomeTally,
   formatCallOutcome,
@@ -116,9 +117,11 @@ import {
 import { applyJourneySetPath } from "./journeyWriteRoute.ts";
 import { openLiveWriteDatabase } from "./liveBackup.ts";
 import {
+  isMirrorDoorman,
   isMirrorWrite,
   isModeWrite,
   mirrorDeactivateMissingSession,
+  runMirrorDoormanRoute,
   runMirrorRead,
   runMirrorWriteRoute,
   runModeRead,
@@ -1477,7 +1480,10 @@ function runShadowWrite(argv: readonly string[]): number | Promise<number> {
   return runShadowScanWrite(argv); // "scan"
 }
 
-function withMirrorReadDb(argv: readonly string[], read: (db: Database) => number): number {
+function withMirrorReadDb<T = number>(
+  argv: readonly string[],
+  read: (db: Database) => T,
+): T | number {
   const dbPath = resolveDbPathForCli(argv.slice(1));
   if (dbPath === null) return 2;
   ensureDatabaseReadyForCli(dbPath, argv[0] ?? null);
@@ -1539,6 +1545,35 @@ function runModeWrite(argv: readonly string[]): Promise<number> {
   return withMirrorWriteDb(argv, (db) => runModeWriteRoute(db, argv));
 }
 
+/**
+ * `mirror doorman` (CV9.DS8.TS2): decide on a read-only handle, write behind
+ * the pre-write snapshot only for a turn that delivers. The memory scores a
+ * delta turn ranks go to the front-door log as numbers -- content-free -- the
+ * hybrid and the semantic the threshold reads (US5), every ranked memory's,
+ * so the threshold is read against measurement.
+ */
+function runMirrorDoorman(argv: readonly string[]): Promise<number> {
+  const reporter = outcomeReporter(argv, "reception");
+  const logPath = resolveLogPath(argv);
+  return runMirrorDoormanRoute(argv, {
+    withReadOnlyDatabase: (read) => withMirrorReadDb(argv, read),
+    withLiveWriteDatabase: (write) => withMirrorWriteDb(argv, write),
+    onReceptionOutcome: reporter.onOutcome,
+    onMemoryScores: (scores) =>
+      logFrontDoor(logPath, {
+        command: "mirror",
+        route: "ts",
+        exitCode: 0,
+        detail:
+          `doorman memory_scores=${scores.map((s) => s.score.toFixed(3)).join(",")}` +
+          ` memory_semantic=${scores.map((s) => s.semantic.toFixed(3)).join(",")}`,
+      }),
+  }).then((exitCode) => {
+    if (reporter.calls > 0) reporter.logSummary();
+    return exitCode;
+  });
+}
+
 function runSoulWrite(argv: readonly string[]): Promise<number> {
   return withMirrorWriteDb(argv, (db) => runSoulRoute(db, argv));
 }
@@ -1739,7 +1774,11 @@ async function dispatchTs(argv: readonly string[]): Promise<number | DispatchOut
       createLoadRuntime: (db, dbPath, ignoreProductionRole) =>
         createBuildLoadRuntime({ db, dbPath, ignoreProductionRole }),
       nowIso,
-      environmentSessionId: process.env.MIRROR_SESSION_ID ?? null,
+      // The session the harness named -- MIRROR_SESSION_ID, else Claude Code's or
+      // Codex's own -- the same reader the mirror route uses (CV9.DS8.US4: read
+      // MIRROR_SESSION_ID alone, a Builder switch on Claude Code stamped a guessed
+      // session and the doorman never saw it).
+      environmentSessionId: environmentSessionId(process.env),
     });
   }
   if (isInit(argv)) return runInit(argv);
@@ -1759,6 +1798,7 @@ async function dispatchTs(argv: readonly string[]): Promise<number | DispatchOut
   if (argv[0] === "descriptor" && argv[1] === "generate") return runDescriptorContentRoute(argv);
   if (isConsolidateSubcommandWrite(argv)) return runConsolidateWrite(argv);
   if (isShadowSubcommandWrite(argv)) return runShadowWrite(argv);
+  if (isMirrorDoorman(argv)) return runMirrorDoorman(argv);
   if (isMirrorWrite(argv)) return runMirrorWrite(argv);
   if (isModeWrite(argv)) return runModeWrite(argv);
   // CV22.DS7.US6: the Soul ritual; `routing.ts` allowlists its subcommands by

package/ts/src/frontDoor/exploreRoute.ts

@@ -61,7 +61,7 @@ import { getIdentityContent } from "#identity/identityRead.ts";
 import { getProjectPath } from "#journey/journeyStatus.ts";
 import { loadMirrorContext } from "#mirror/context.ts";
 import { persistStickyDefaults } from "#mirror/orchestration.ts";
-import { resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
+import { environmentSessionId, resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
 import { activateOperatingMode, deactivateOperatingMode } from "#mode/operatingMode.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 import { optionValue, stripOptionWithValue } from "./args.ts";
@@ -430,7 +430,7 @@ async function runPromote(
   // `--session-id`, which its promote parser does not even accept.
   const result = await runBuildLoad(
     db,
-    { slug, environmentSessionId: process.env.MIRROR_SESSION_ID ?? null },
+    { slug, environmentSessionId: environmentSessionId(process.env) },
     runtime.deps,
   );
   process.stderr.write(result.stderr);

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,
@@ -745,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` };
@@ -952,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/runtimeRoute.ts

@@ -25,6 +25,7 @@ import { channelFor, channelForReport, renderChannel, setChannel } from "#runtim
 import {
   diagnoseRuntime,
   extensionPluginFindings,
+  extractionReasoningFindings,
   hookFailureFindings,
   hookNodeFindings,
   pluginWiringFindings,
@@ -324,6 +325,9 @@ export async function runRuntimeReadRoute(
       // skip; and hooks.log holds what the hooks met in their own context.
       // All three are invisible without being asked for.
       ...staleRevertGateFindings(env),
+      // CV9.DS9.TS1: a reasoning setting the transport ignores rather than fail
+      // on (CR178) is silently not in force unless diagnose says so.
+      ...extractionReasoningFindings(env),
       ...hookFailureFindings(report),
       ...hookNodeFindings(env, (path) => {
         try {

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/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 };
+}