mirror-mind 0.37.0 → 0.38.1

package/ts/src/frontDoor/cli.ts

@@ -44,12 +44,11 @@ import { type Database, openDatabaseReadOnly, type WritableDatabase } from "#db/
 import { ensureDatabaseReady } from "#db/readyOnOpen.ts";
 import { assertSchemaState, SchemaStateError } from "#db/schemaState.ts";
 import { allDescriptors, descriptorsByLayer } from "#descriptor/descriptorRead.ts";
-import { newIdentityKeyProblem, newUserNameProblem } from "#identity/identityKey.ts";
+import { newIdentityKeyProblem } from "#identity/identityKey.ts";
 import { identityRowExists, listIdentityByLayer } from "#identity/identityRead.ts";
 import { listJourneysForListCommand } from "#identity/journeyListing.ts";
 import { listPersonas } from "#identity/personaListing.ts";
 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";
@@ -61,9 +60,14 @@ import {
 import { chatLedgerHook } from "#observability/ledgerHooks.ts";
 import { runWeekSave } from "#planning/weekSave.ts";
 import type { EmbeddingProvider } from "#providers/embedding.ts";
-import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import {
+  requireFamilyProviders,
+  requireKeyForFamily,
+  resolveFamilyProviders,
+} from "#providers/familyProviders.ts";
 import type { LlmProvider } from "#providers/llm.ts";
 import {
+  CONSULT_ASK_TRANSPORT,
   CULTIVATION_APPLY_TRANSPORT,
   CULTIVATION_SCAN_TRANSPORT,
   DESCRIPTOR_TRANSPORT,
@@ -72,18 +76,10 @@ import {
 } from "#providers/transport.ts";
 import { verifyBackupArchive } from "#runtime/backup.ts";
 import { exitQuietlyOnBrokenPipe } from "#runtime/brokenPipe.ts";
-import {
-  configFilePath,
-  loadConfiguration,
-  silenceExperimentalWarnings,
-  writeConfigValue,
-} from "#runtime/config.ts";
-import { runningTreeRoot } from "#runtime/treeRoot.ts";
-import { detectRuntimes, runtimeWiringLines } from "#runtime/wiring.ts";
+import { configFilePath, loadConfiguration, silenceExperimentalWarnings } from "#runtime/config.ts";
 import { runSeed } from "#seed/seed.ts";
 import { getTasksForWeek, listTasks } from "#tasks/taskStore.ts";
 import { computeWeekRange } from "#tasks/weekView.ts";
-import { isExecutable } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { newId, nowIso } from "#util/pyGenerators.ts";
 import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
@@ -105,7 +101,7 @@ import {
   runReject,
   runShadowApply as runShadowApplyRoute,
 } from "./cultivationRoute.ts";
-import { MirrorHomeNotConfiguredError, resolveDbPath } from "./dbPath.ts";
+import { initCommandFor, MirrorHomeNotConfiguredError, resolveDbPath } from "./dbPath.ts";
 import { runBackupRoute, runRepairEncodingRoute } from "./dbSafetyToolsRoute.ts";
 import { defaultExploreRouteDeps, runExploreRoute } from "./exploreRoute.ts";
 import { frontDoorLogPath, logFrontDoor } from "./frontDoorLog.ts";
@@ -114,8 +110,10 @@ import {
   isImportedConversationsCommand,
   runImportedConversationsRoute,
 } from "./importedConversationsRoute.ts";
+import { runInit } from "./initRoute.ts";
 import { applyJourneySetPath } from "./journeyWriteRoute.ts";
 import { openLiveWriteDatabase } from "./liveBackup.ts";
+import { findMirrorHomes, homesRoot } from "./mirrorHomes.ts";
 import {
   isMirrorDoorman,
   isMirrorWrite,
@@ -454,7 +452,10 @@ function runWeekSaveWrite(argv: readonly string[]): number {
  * in depth.
  */
 async function runJournalContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, JOURNAL_TRANSPORT);
+  // CR187: refused before the database opens, saying what was not kept.
+  const family = await requireFamilyProviders(process.env, JOURNAL_TRANSPORT, {
+    consequence: "the journal entry was not saved",
+  });
   if (!family?.llm || !family.embedding) {
     throw new Error("journal requires an LLM and an embedding provider");
   }
@@ -467,14 +468,15 @@ async function runJournalContentRoute(argv: readonly string[]): Promise<number>
 }
 
 async function runWeekPlanContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, WEEK_PLAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, WEEK_PLAN_TRANSPORT);
   if (!family?.llm) throw new Error("week plan requires an LLM provider");
   const llm = family.llm;
   return withLiveWriteDbAsync(argv, (db) => runWeekPlanRoute(db, argv.slice(2), llm));
 }
 
 async function runDescriptorContentRoute(argv: readonly string[]): Promise<number> {
-  const family = await resolveFamilyProviders(process.env, DESCRIPTOR_TRANSPORT);
+  // CR187: without the key every persona would read "skipped (empty response)".
+  const family = await requireFamilyProviders(process.env, DESCRIPTOR_TRANSPORT);
   if (!family?.llm) throw new Error("descriptor generate requires an LLM provider");
   const llm = family.llm;
   const reporter = outcomeReporter(argv, "descriptor");
@@ -884,90 +886,6 @@ function isInit(argv: readonly string[]): boolean {
   return argv[0] === "init";
 }
 
-/**
- * Serve `init <user>` (DS7.US1 Slice B). Filesystem-only — no database is
- * opened. Python's argparse defines only the `user` positional (no
- * --mirror-home/--db-path), so none are stripped here.
- *
- * Deliberate divergence: an already-populated identity root or a missing
- * templates root are uncaught exceptions in Python (a raw traceback, exit 1) --
- * not a designed message. This preserves the contract (exit 1, a stderr
- * message naming the failure) without fabricating a fake traceback.
- *
- * CV22.DS10.US3 (D3): when no source configured a user, `init` writes
- * `MIRROR_USER=<user>` into `~/.config/mirror/env` (0600 in 0700) and says
- * where to add `OPENROUTER_API_KEY` by hand. The key is never read from argv.
- * When a user IS configured -- the checkout's `.env`, or a shell running a
- * second mirror -- the file is left alone and the person is told how to
- * select the new home.
- *
- * Plateau 3: it ends with the wiring step for each runtime found on the PATH
- * (`#runtime/wiring.ts`), with this tree's path in it, so the person is handed
- * the next line rather than a page. Printing is not automating.
- */
-function runInit(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): number {
-  const user = argv[1];
-  // A word that starts with `-` is a flag this command does not have, not a
-  // user: `init --help` once created a home named `--help`.
-  if (!user || user.startsWith("-")) {
-    console.error("Usage: init <user>");
-    return 2;
-  }
-  // And any other word is a key: the home's directory name and the value of
-  // MIRROR_USER in the wiring commands printed below. CR104's rule for slugs
-  // and persona ids, asked before anything is created (CR141).
-  const problem = newUserNameProblem(user);
-  if (problem !== null) {
-    console.error(`Error: ${problem}`);
-    return 2;
-  }
-  try {
-    const identityRoot = initUserHome(user);
-    const mirrorHome = dirname(identityRoot);
-    const configured = Boolean(env.MIRROR_USER || env.MIRROR_HOME);
-    const configuration = configured
-      ? [
-          `  1. This machine already selects a user; to use this one, run with MIRROR_USER=${user}`,
-          `     or set it in ${configFilePath(env)}`,
-        ]
-      : [
-          `Configuration: ${writeConfigValue("MIRROR_USER", user, { env })} (MIRROR_USER=${user})`,
-          "",
-          "Next steps:",
-          "  1. Add OPENROUTER_API_KEY=<your key> to that file (it is created readable by you only)",
-        ];
-    const prints = [
-      `Created user home: ${mirrorHome}`,
-      `Identity ready at: ${identityRoot}`,
-      ...(configured ? ["", "Next steps:"] : []),
-      ...configuration,
-      `  2. Run: ${PROGRAM} seed`,
-      "\nYour identity is ready to use. Deepen it over time with:",
-      `  ${PROGRAM} identity edit user identity`,
-      ...runtimeWiringSection(env),
-    ];
-    process.stdout.write(prints.map((line) => `${line}\n`).join(""));
-    return 0;
-  } catch (error) {
-    if (error instanceof IdentityRootExistsError || error instanceof TemplatesNotFoundError) {
-      console.error(error.message);
-      return 1;
-    }
-    throw error;
-  }
-}
-
-/** The "Wire your runtime" tail of `init`, empty when no runtime is on the PATH. */
-function runtimeWiringSection(env: NodeJS.ProcessEnv): string[] {
-  const detected = detectRuntimes(env, isExecutable);
-  if (detected.length === 0) return [];
-  const root = runningTreeRoot();
-  return [
-    "\nWire your runtime to this install (each step is one you run and can read first):",
-    ...detected.flatMap((runtime) => ["", ...runtimeWiringLines(runtime, root)]),
-  ];
-}
-
 function isSeed(argv: readonly string[]): boolean {
   return argv[0] === "seed";
 }
@@ -1408,7 +1326,7 @@ async function runConsolidateScanWrite(argv: readonly string[]): Promise<number>
   const limit = limitRaw !== null ? Number(limitRaw) : DEFAULT_CONSOLIDATE_SCAN_LIMIT;
   const thresholdRaw = optionValue(args, "--threshold");
   const threshold = thresholdRaw !== null ? Number(thresholdRaw) : DEFAULT_CLUSTER_THRESHOLD;
-  const family = await resolveFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
   if (!family?.llm) throw new Error("consolidate scan requires an LLM provider");
   const provider = family.llm;
   const reporter = outcomeReporter(argv, "consolidation");
@@ -1435,7 +1353,7 @@ async function runShadowScanWrite(argv: readonly string[]): Promise<number> {
   const args = argv.slice(2);
   const limitRaw = optionValue(args, "--limit");
   const limit = limitRaw !== null ? Number(limitRaw) : DEFAULT_SHADOW_SCAN_LIMIT;
-  const family = await resolveFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
+  const family = await requireFamilyProviders(process.env, CULTIVATION_SCAN_TRANSPORT);
   if (!family?.llm) throw new Error("shadow scan requires an LLM provider");
   const provider = family.llm;
   const reporter = outcomeReporter(argv, "shadow_scan");
@@ -1663,6 +1581,9 @@ function resolveLogPath(argv: readonly string[]): string | null {
  * itself, extended to db resolution.
  */
 async function runConsultAskWithDb(argv: readonly string[]): Promise<number> {
+  // CR187: before the ledger database opens, because that open takes the
+  // pre-write snapshot; the route checks again, for `consult credits`.
+  requireKeyForFamily(process.env, CONSULT_ASK_TRANSPORT);
   const db = tryOpenDbForConsultLogging(argv);
   try {
     process.stdout.write(await runConsultRoute(db, argv.slice(1)));
@@ -1904,9 +1825,17 @@ export async function main(rawArgv = process.argv.slice(2)): Promise<number> {
   // name is whatever the caller typed, and it stays out of the log.
   if (decision.engine === "usage") {
     const env = process.env;
+    const userConfigured = Boolean(
+      env.MIRROR_USER || env.MIRROR_HOME || env.MEMORY_DIR || env.DB_PATH,
+    );
     const answer = answerUsage(decision.request, {
-      userConfigured: Boolean(env.MIRROR_USER || env.MIRROR_HOME || env.MEMORY_DIR || env.DB_PATH),
+      userConfigured,
       configFile: configFilePath(env),
+      // CR185: a home on disk that nothing selects is named, read only when no
+      // user is configured -- the one case the orientation is rendered.
+      useHome: userConfigured
+        ? null
+        : (initCommandFor(findMirrorHomes(), homesRoot())?.sentence ?? null),
     });
     (answer.stream === "stdout" ? process.stdout : process.stderr).write(answer.text);
     logFrontDoor(logPath, {

package/ts/src/frontDoor/consultRoute.ts

@@ -1,7 +1,7 @@
 import { parseConsultArgs } from "#consult/args.ts";
 import { runConsult } from "#consult/core.ts";
 import type { WritableDatabase } from "#db/database.ts";
-import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { requireFamilyProviders } from "#providers/familyProviders.ts";
 import { CONSULT_ASK_TRANSPORT, CONSULT_CREDITS_TRANSPORT } from "#providers/transport.ts";
 
 /**
@@ -17,7 +17,9 @@ export async function runConsultRoute(
   // Per leaf, from the same specs `routing.ts` decided with: `credits` needs
   // only a credit provider, `ask` needs a chat provider too (CV22.DS8.US3).
   const spec = command.command === "credits" ? CONSULT_CREDITS_TRANSPORT : CONSULT_ASK_TRANSPORT;
-  const family = await resolveFamilyProviders(process.env, spec);
+  // CR187: no provider call without the key; `ask` checked before its ledger
+  // database opened, `credits` has none to open.
+  const family = await requireFamilyProviders(process.env, spec);
   if (!family?.credits) {
     // `routing.ts` sends a reverted or half-configured family to Python before
     // the route is reached, so this is defense in depth.

package/ts/src/frontDoor/dbPath.ts

@@ -14,7 +14,10 @@
 //   modern `~/.mirror-minds/<user>` does not exist (one-line stderr warning,
 //   permanent support — see docs/project/decisions.md).
 // - Nothing configured fails loudly (CV9.E2.S6: unconfigured resolution must
-//   not write to the homes root), unlike the pre-CR024 silent fallback.
+//   not write to the homes root), unlike the pre-CR024 silent fallback. The
+//   sentence says what to run and which file that writes, naming the homes it
+//   finds (CR185): a move from a clone to the package leaves a home that no
+//   configuration points at, and the person needs the command, not the cause.
 //
 // Front-door-only extension: the CLI flags `--db-path` and `--mirror-home`
 // are explicit per-invocation intent and take precedence over all env vars.
@@ -22,8 +25,13 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { configFilePath } from "#runtime/config.ts";
 import { expandHome } from "#util/paths.ts";
+import { PROGRAM } from "#util/program.ts";
+import { pyRepr } from "#util/pythonText.ts";
+import { shellWord } from "#util/shellWord.ts";
 import { optionValue } from "./args.ts";
+import { type FoundHome, findMirrorHomes, homesRoot, userHomePath } from "./mirrorHomes.ts";
 
 /** Raised when no database location can be resolved — maps to CLI exit 2. */
 export class MirrorHomeNotConfiguredError extends Error {}
@@ -34,7 +42,6 @@ const DB_NAMES: Record<string, string> = {
   test: "memory_test.db",
 };
 
-const DEFAULT_USER_HOMES_DIR = ".mirror-minds";
 const LEGACY_USER_HOMES_DIR = ".mirror";
 
 /** Port of Python `db_name_for_env`: one (environment) → one database name. */
@@ -50,6 +57,8 @@ export interface DbPathEnv {
   MEMORY_DIR?: string;
   MIRROR_HOME?: string;
   MIRROR_USER?: string;
+  /** Read only to name the config file in the not-configured sentence. */
+  XDG_CONFIG_HOME?: string;
 }
 
 /** Injection points so tests can run without touching the real filesystem. */
@@ -57,6 +66,8 @@ export interface DbPathIo {
   home?: string;
   exists?: (path: string) => boolean;
   warn?: (message: string) => void;
+  /** The homes under `<home>/.mirror-minds`, for the not-configured sentence. */
+  homes?: (home: string) => readonly FoundHome[];
 }
 
 /**
@@ -72,7 +83,7 @@ export function resolveMirrorHome(env: DbPathEnv, io: DbPathIo = {}): string {
   const explicitHome = env.MIRROR_HOME ?? "";
   const explicitUser = env.MIRROR_USER ?? "";
   const resolvedHome = explicitHome ? expandHome(explicitHome) : null;
-  const derivedHome = explicitUser ? join(home, DEFAULT_USER_HOMES_DIR, explicitUser) : null;
+  const derivedHome = explicitUser ? userHomePath(explicitUser, home) : null;
 
   if (resolvedHome && explicitUser && basename(resolvedHome) !== explicitUser) {
     throw new MirrorHomeNotConfiguredError(
@@ -94,10 +105,72 @@ export function resolveMirrorHome(env: DbPathEnv, io: DbPathIo = {}): string {
     }
     return derivedHome;
   }
-  throw new MirrorHomeNotConfiguredError(
-    "Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER " +
-      "(or pass an explicit MEMORY_DIR/DB_PATH override).",
-  );
+  throw new MirrorHomeNotConfiguredError(homeNotConfiguredMessage(env, io));
+}
+
+/**
+ * The not-configured sentence (CR185), one line: what to run, and which file
+ * that command writes.
+ *
+ * Every surface prints it: `runtime update`, `migrate`, and `backup` bare, the
+ * other commands after `Mirror TS front door:`, and `runtime status` as its
+ * `Mirror home note:`. Built only when nothing resolves, so a hook on an
+ * unconfigured machine pays one directory read for a message it discards.
+ *
+ * A home name reaches the line bare only when `init` accepts it, so the line
+ * cannot be broken, or carry an escape sequence, by a directory name. Any other
+ * home is offered `MIRROR_HOME`, its path printed as a repr.
+ */
+export function homeNotConfiguredMessage(env: DbPathEnv, io: DbPathIo = {}): string {
+  const home = io.home ?? homedir();
+  const config = configFilePath({ XDG_CONFIG_HOME: env.XDG_CONFIG_HOME }, home);
+  const homes = (io.homes ?? findMirrorHomes)(home);
+  const sentences: string[] = [];
+  const command = initCommandFor(homes, homesRoot(home));
+  if (command !== null) {
+    sentences.push(`${command.sentence} (it writes MIRROR_USER=${command.name} to ${config}).`);
+  }
+  for (const other of homes.filter((found) => !found.nameable)) {
+    const path = pyRepr(other.path);
+    sentences.push(`To use the home at ${path}, add MIRROR_HOME=${path} to ${config}.`);
+  }
+  if (sentences.length === 0) {
+    const create = `${PROGRAM} init <your-name>`;
+    sentences.push(
+      `To create one, run: ${create} (it writes MIRROR_USER=<your-name> to ${config}).`,
+      `If yours lives elsewhere, add MIRROR_HOME=<path> to ${config}.`,
+    );
+  }
+  return ["Mirror home is not configured.", ...sentences].join(" ");
+}
+
+/**
+ * "To use the home at <path>, run: mirror init <name>", or the form for
+ * several, for the homes `init` can name; null when there are none. `name` is
+ * what the command takes: the one home's own name, or `<name>`. Bare `mirror`
+ * prints the same sentence.
+ *
+ * The command is built on a line of its own, its value through `shellWord`
+ * (CR104): an agent runs it as printed. A name `init` accepts is a plain token,
+ * so it prints unchanged. The path and the names around the command are prose.
+ */
+export function initCommandFor(
+  homes: readonly FoundHome[],
+  root: string,
+): { sentence: string; name: string } | null {
+  const nameable = homes.filter((found) => found.nameable);
+  const [only] = nameable;
+  if (only === undefined) return null;
+  if (nameable.length === 1) {
+    const command = `${PROGRAM} init ${shellWord(only.name)}`;
+    return { sentence: `To use the home at ${only.path}, run: ${command}`, name: only.name };
+  }
+  const names = nameable.map((found) => found.name).join(", ");
+  const command = `${PROGRAM} init <name>`;
+  return {
+    sentence: `To use one of the homes in ${root} (${names}), run: ${command}`,
+    name: "<name>",
+  };
 }
 
 /**

package/ts/src/frontDoor/initRoute.ts

@@ -0,0 +1,190 @@
+// `init <user>`: the front door route that creates a user home (DS7.US1 Slice B).
+// It moved out of cli.ts when it learned to adopt a home that already exists (CR185).
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { newUserNameProblem } from "#identity/identityKey.ts";
+import {
+  defaultUserHome,
+  IdentityRootExistsError,
+  initUserHome,
+  TemplatesNotFoundError,
+} from "#init/init.ts";
+import { configFilePath, writeConfigValue } from "#runtime/config.ts";
+import { runningTreeRoot } from "#runtime/treeRoot.ts";
+import { detectRuntimes, runtimeWiringLines } from "#runtime/wiring.ts";
+import { isExecutable } from "#util/paths.ts";
+import { PROGRAM } from "#util/program.ts";
+import { dbNameForEnv, resolveMirrorHome } from "./dbPath.ts";
+import { isMirrorHome } from "./mirrorHomes.ts";
+
+/**
+ * Serve `init <user>` (DS7.US1 Slice B). Filesystem-only — no database is
+ * opened. Python's argparse defines only the `user` positional (no
+ * --mirror-home/--db-path), so none are stripped here.
+ *
+ * Deliberate divergence: a missing templates root is an uncaught exception in
+ * Python (a raw traceback, exit 1) -- not a designed message. This preserves
+ * the contract (exit 1, a stderr message naming the failure) without
+ * fabricating a fake traceback.
+ *
+ * CV22.DS10.US3 (D3): when no source configured a user, `init` writes
+ * `MIRROR_USER=<user>` into `~/.config/mirror/env` (0600 in 0700) and says
+ * where to add `OPENROUTER_API_KEY` by hand. The key is never read from argv.
+ * When a user IS configured -- the checkout's `.env`, or a shell running a
+ * second mirror -- the file is left alone and the person is told how to
+ * select the new home, or that it is already selected.
+ *
+ * CR185: a home that already exists is used as it is, never refused. It is
+ * the route the not-configured sentence names, and Getting Started's for
+ * moving from a clone to the package and for printing the wiring again. Nothing
+ * in the home is copied or changed; the configuration is written as for a new
+ * home, and only the steps still left are printed.
+ *
+ * Plateau 3: it ends with the wiring step for each runtime found on the PATH
+ * (`#runtime/wiring.ts`), with this tree's path in it, so the person is handed
+ * the next line rather than a page. Printing is not automating.
+ */
+export function runInit(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): number {
+  const user = argv[1];
+  // A word that starts with `-` is a flag this command does not have, not a
+  // user: `init --help` once created a home named `--help`.
+  if (!user || user.startsWith("-")) {
+    console.error("Usage: init <user>");
+    return 2;
+  }
+  // And any other word is a key: the home's directory name and the value of
+  // MIRROR_USER in the wiring commands printed below. CR104's rule for slugs
+  // and persona ids, asked before anything is created or looked at (CR141).
+  const problem = newUserNameProblem(user);
+  if (problem !== null) {
+    console.error(`Error: ${problem}`);
+    return 2;
+  }
+  // Decided before `initUserHome` runs: its refusal of a populated identity
+  // stays the guard under this branch, never the way into it.
+  const existing = defaultUserHome(user);
+  if (isMirrorHome(existing)) return adoptUserHome(user, existing, env);
+  try {
+    const identityRoot = initUserHome(user);
+    const mirrorHome = dirname(identityRoot);
+    const selection = selectionFor(mirrorHome, env);
+    const steps: Step[] =
+      selection === "none"
+        ? [["Add OPENROUTER_API_KEY=<your key> to that file (it is created readable by you only)"]]
+        : selection === "other"
+          ? [selectThisOne(user, env)]
+          : [];
+    const prints = [
+      `Created user home: ${mirrorHome}`,
+      `Identity ready at: ${identityRoot}`,
+      ...configurationLine(user, selection, env),
+      "",
+      "Next steps:",
+      ...numbered([...steps, [`Run: ${PROGRAM} seed`]]),
+      "\nYour identity is ready to use. Deepen it over time with:",
+      `  ${PROGRAM} identity edit user identity`,
+      ...runtimeWiringSection(env),
+    ];
+    process.stdout.write(prints.map((line) => `${line}\n`).join(""));
+    return 0;
+  } catch (error) {
+    if (error instanceof IdentityRootExistsError || error instanceof TemplatesNotFoundError) {
+      console.error(error.message);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+/**
+ * `init <user>` on a home that exists (CR185). The first line is a one-line
+ * summary, as for a new home: the Windows installer (PR #45) reads it. Then
+ * only what is left: the configuration, the key when none is set, `seed` when
+ * the home has no database, and the wiring.
+ */
+function adoptUserHome(user: string, home: string, env: NodeJS.ProcessEnv): number {
+  const selection = selectionFor(home, env);
+  const config = configFilePath(env);
+  const steps: Step[] = [];
+  if (selection === "other") steps.push(selectThisOne(user, env));
+  else if (!env.OPENROUTER_API_KEY) {
+    steps.push([
+      `Add OPENROUTER_API_KEY=<your key> to ${config} (moving from a clone? copy the line from its .env)`,
+    ]);
+  }
+  if (!existsSync(join(home, dbNameForEnv(env.MEMORY_ENV || "production")))) {
+    steps.push([`Run: ${PROGRAM} seed`]);
+  }
+  const prints = [
+    `Found user home: ${home} (nothing in it was changed)`,
+    ...configurationLine(user, selection, env),
+    ...(steps.length > 0 ? ["", "Next steps:", ...numbered(steps)] : []),
+    ...runtimeWiringSection(env),
+  ];
+  process.stdout.write(prints.map((line) => `${line}\n`).join(""));
+  return 0;
+}
+
+/** Which home this machine already selects: none, this one, or another. */
+type Selection = "none" | "this" | "other";
+
+/**
+ * Read once, for a new home and an existing one alike. Compared as real paths,
+ * so a home reached through a symlink, or named by a `MIRROR_HOME` spelled
+ * another way, is still this one. A selection that does not resolve (a
+ * `MIRROR_HOME` that conflicts with `MIRROR_USER`) is not this home, and not
+ * `init`'s to repair.
+ */
+function selectionFor(home: string, env: NodeJS.ProcessEnv): Selection {
+  if (!env.MIRROR_USER && !env.MIRROR_HOME) return "none";
+  try {
+    const selected = resolveMirrorHome(env, { warn: () => {} });
+    return realPath(selected) === realPath(home) ? "this" : "other";
+  } catch {
+    return "other";
+  }
+}
+
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** The `Configuration:` line: written now, already this home, or nothing when another is selected. */
+function configurationLine(user: string, selection: Selection, env: NodeJS.ProcessEnv): string[] {
+  if (selection === "none") {
+    return [
+      `Configuration: ${writeConfigValue("MIRROR_USER", user, { env })} (MIRROR_USER=${user})`,
+    ];
+  }
+  return selection === "this" ? ["Configuration: already selects this home"] : [];
+}
+
+/** One numbered step: its first line takes the number, the rest are indented under it. */
+type Step = readonly string[];
+
+function selectThisOne(user: string, env: NodeJS.ProcessEnv): Step {
+  return [
+    `This machine already selects a user; to use this one, run with MIRROR_USER=${user}`,
+    `     or set it in ${configFilePath(env)}`,
+  ];
+}
+
+function numbered(steps: readonly Step[]): string[] {
+  return steps.flatMap(([first, ...rest], index) => [`  ${index + 1}. ${first}`, ...rest]);
+}
+
+/** The "Wire your runtime" tail of `init`, empty when no runtime is on the PATH. */
+function runtimeWiringSection(env: NodeJS.ProcessEnv): string[] {
+  const detected = detectRuntimes(env, isExecutable);
+  if (detected.length === 0) return [];
+  const root = runningTreeRoot();
+  return [
+    "\nWire your runtime to this install (each step is one you run and can read first):",
+    ...detected.flatMap((runtime) => ["", ...runtimeWiringLines(runtime, root)]),
+  ];
+}

package/ts/src/frontDoor/mirrorHomes.ts

@@ -0,0 +1,95 @@
+// The homes root, and what counts as a home in it (CR185).
+//
+// `<home>/.mirror-minds` holds one directory per user home: the place
+// `MIRROR_USER=<user>` resolves to and `init <user>` creates. The root used to
+// be spelled in three places (`dbPath.ts`, `init.ts`, `runtimeRoute.ts`); it is
+// spelled here. This module also owns the rule for what a home is, because two
+// readers have to agree on it: the not-configured error, which names the homes
+// it finds, and `init <name>`, which adopts an existing home instead of
+// refusing it. If they disagreed, the error could print a command that `init`
+// then answers differently.
+//
+// Filesystem reads only, and every one of them is allowed to fail: a root that
+// is missing, a file, or unreadable has no homes. The callers are error paths
+// and a bootstrap command, and neither may fail for a second reason.
+
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { newUserNameProblem } from "#identity/identityKey.ts";
+import { sortByCodePoint } from "#util/pythonText.ts";
+
+/** The homes root's name under the OS user's home directory. */
+export const HOMES_DIR = ".mirror-minds";
+
+/** `<home>/.mirror-minds`. */
+export function homesRoot(home: string = homedir()): string {
+  return join(home, HOMES_DIR);
+}
+
+/** `<home>/.mirror-minds/<user>`: where `MIRROR_USER=<user>` resolves, and where `init <user>` creates. */
+export function userHomePath(user: string, home: string = homedir()): string {
+  return join(homesRoot(home), user);
+}
+
+/** Every database name `dbNameForEnv` gives: `memory.db`, `memory_dev.db`, `memory_<env>.db`. */
+const DATABASE_NAME = /^memory(?:_.+)?\.db$/;
+
+/**
+ * Whether `path` is a Mirror home: a directory, through a symlink if need be,
+ * that holds a non-empty `identity/` or a database file.
+ *
+ * A directory holding only a log is not a home: an unresolved Pi session leaves
+ * one under the root. An empty `identity/` is not a home either, because `init`
+ * may still fill it. That is also the boundary `initUserHome` refuses at, so
+ * `init` adopts exactly what it would otherwise have to refuse, and also a home
+ * whose identity lives only in its database.
+ */
+export function isMirrorHome(path: string): boolean {
+  if (!isDirectory(path)) return false;
+  const identity = join(path, "identity");
+  if (isDirectory(identity) && entries(identity).length > 0) return true;
+  return entries(path).some((name) => DATABASE_NAME.test(name) && isFile(join(path, name)));
+}
+
+/** A home found under the root. */
+export interface FoundHome {
+  /** The directory's name. */
+  readonly name: string;
+  /** `<root>/<name>`: the entry itself, never a symlink's target. */
+  readonly path: string;
+  /** Whether `init <name>` accepts the name (CR141): only then can a message print it bare. */
+  readonly nameable: boolean;
+}
+
+/** The homes in `<home>/.mirror-minds`, in code-point order. Hidden entries are skipped. */
+export function findMirrorHomes(home: string = homedir()): FoundHome[] {
+  const root = homesRoot(home);
+  return sortByCodePoint(entries(root).filter((name) => !name.startsWith(".")))
+    .map((name) => ({ name, path: join(root, name), nameable: newUserNameProblem(name) === null }))
+    .filter((found) => isMirrorHome(found.path));
+}
+
+function entries(path: string): string[] {
+  try {
+    return readdirSync(path);
+  } catch {
+    return [];
+  }
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}