mirror-mind 0.38.0 → 0.38.1

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

package/ts/src/frontDoor/namedRefusal.ts

@@ -9,12 +9,20 @@
 //     which had no replay transport and would have called the live provider;
 //   * a new journey slug or persona id outside the grammar, which the identity
 //     store refuses for any route that did not ask first (CR104). Today every route
-//     asks first, so this answers the next route that creates a key.
+//     asks first, so this answers the next route that creates a key;
+//   * a missing OpenRouter key (CR187), refused up front by the commands that
+//     cannot work without one and lazily, at a first model call, by the rest --
+//     and a key OpenRouter refused (HTTP 401 or 403), whether a chat call or an
+//     embedding call met it. A configuration failure, so exit 2, as a missing
+//     home is.
 //
 // Like every `Error:` line, the answer claims nothing about what changed before
 // the refusal was raised.
 
 import { InvalidIdentityKeyError } from "#identity/identityKey.ts";
+import { keyRefusedMessage, ProviderConfigError } from "#providers/config.ts";
+import { EmbeddingError } from "#providers/embedding.ts";
+import { LlmTransportError } from "#providers/openrouter.ts";
 import { ReplayFixtureIncompleteError } from "#providers/transport.ts";
 
 export interface NamedRefusal {
@@ -31,5 +39,25 @@ export function namedRefusal(error: unknown): NamedRefusal | null {
   if (error instanceof InvalidIdentityKeyError) {
     return { line: `Error: ${error.message}`, exitCode: 1 };
   }
+  if (error instanceof ProviderConfigError) {
+    return { line: `Error: ${error.message}`, exitCode: 2 };
+  }
+  const refusedStatus = refusedKeyStatus(error);
+  if (refusedStatus !== undefined) {
+    return { line: `Error: ${keyRefusedMessage(refusedStatus)}`, exitCode: 2 };
+  }
   return null;
 }
+
+/**
+ * The HTTP status of a key OpenRouter refused, null when it was not kept, or
+ * undefined when `error` is not a refused key. Only the classification is read:
+ * the transport keeps nothing the provider sent back, and neither does this.
+ */
+function refusedKeyStatus(error: unknown): number | null | undefined {
+  if (error instanceof LlmTransportError && error.kind === "auth") return error.status;
+  if (error instanceof EmbeddingError && error.transport?.kind === "auth") {
+    return error.transport.status;
+  }
+  return undefined;
+}

package/ts/src/frontDoor/runtimeRoute.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { createZipBackup } from "#backup/zipBackup.ts";
 import { dbNameForEnv, resolveMirrorHome } from "#frontDoor/dbPath.ts";
 import { frontDoorLogPath, logFrontDoor } from "#frontDoor/frontDoorLog.ts";
+import { homesRoot } from "#frontDoor/mirrorHomes.ts";
 import { renderUnknownSubcommand } from "#frontDoor/usage.ts";
 import {
   renderBackupVerification,
@@ -28,6 +29,7 @@ import {
   extractionReasoningFindings,
   hookFailureFindings,
   hookNodeFindings,
+  openRouterKeyFindings,
   pluginWiringFindings,
   probeModelPins,
   renderRuntimeDiagnosis,
@@ -319,7 +321,7 @@ export async function runRuntimeReadRoute(
           : null;
     const findings = [
       ...diagnoseRuntime(report, inspectGitWorktree(report.git.repository)),
-      ...rootStateFindings(homesRoot(env)),
+      ...rootStateFindings(ambientHomesRoot(env)),
       // CV22.DS10.TS5: the transition's own leftovers. A stale MIRROR_TS_*
       // gate is inert and silently so; an unresolvable Node makes every hook
       // skip; and hooks.log holds what the hooks met in their own context.
@@ -328,6 +330,9 @@ export async function runRuntimeReadRoute(
       // 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),
+      // CR187: with no key, memory extraction, embeddings, and consult are off,
+      // and nothing else on this report would say so.
+      ...openRouterKeyFindings(env),
       ...hookFailureFindings(report),
       ...hookNodeFindings(env, (path) => {
         try {
@@ -778,8 +783,7 @@ function firstPositional(args: readonly string[]): string | null {
   return null;
 }
 
-/** Python's ambient `DEFAULT_USER_HOMES_DIR`: `<home>/.mirror-minds`. */
-function homesRoot(env: NodeJS.ProcessEnv): string {
-  const home = env.HOME ?? env.USERPROFILE ?? "";
-  return join(home, ".mirror-minds");
+/** Python's ambient `DEFAULT_USER_HOMES_DIR`: the homes root under the environment's home. */
+function ambientHomesRoot(env: NodeJS.ProcessEnv): string {
+  return homesRoot(env.HOME ?? env.USERPROFILE ?? "");
 }

package/ts/src/frontDoor/searchRoute.ts

@@ -1,5 +1,6 @@
 import type { WritableDatabase } from "#db/database.ts";
 import { requireString } from "#db/rowDecode.ts";
+import { keyFileTarget } from "#providers/config.ts";
 import type { EmbeddingProvider } from "#providers/embedding.ts";
 import { resolveFamilyProviders } from "#providers/familyProviders.ts";
 import { SEARCH_TRANSPORT } from "#providers/transport.ts";
@@ -14,6 +15,32 @@ import { tagsText } from "./render/memories.ts";
 const DEGRADED_NOTE =
   "⚠ Degraded: lexical-only search (embedding unavailable — offline or no API key).";
 
+/**
+ * The degraded note for the cause the search reported (CR187). The general
+ * note guesses "offline or no API key"; for the two causes the person can fix
+ * themselves, the note says which one, and where.
+ *
+ * `config` means a missing key here: the search's embedding provider is the
+ * live one, and nothing else in its path raises `ProviderConfigError`. `auth`
+ * is a key OpenRouter refused, kept through the embedding wrapper.
+ */
+export function degradedNoteFor(
+  kind: string | undefined,
+  env: Record<string, string | undefined> = process.env,
+  home?: string,
+): string {
+  if (kind === "config") {
+    return (
+      "⚠ Degraded: lexical-only search (OPENROUTER_API_KEY is not configured: " +
+      `add it to ${keyFileTarget(env, home)}).`
+    );
+  }
+  if (kind === "auth") {
+    return "⚠ Degraded: lexical-only search (OpenRouter refused OPENROUTER_API_KEY: check the key where it is set).";
+  }
+  return DEGRADED_NOTE;
+}
+
 export interface SearchMemoryRow {
   id: string;
   memory_type: string;
@@ -87,7 +114,7 @@ export async function runMemorySearchRoute(
     db,
     results.map((result) => result.id),
   );
-  return formatSearchResults(query, results, rows, degraded);
+  return formatSearchResults(query, results, rows, degraded, degradedNoteFor(degradedKind));
 }
 
 /**
@@ -101,13 +128,14 @@ export function formatSearchResults(
   results: readonly FreshSearchResult[],
   rows: ReadonlyMap<string, SearchMemoryRow>,
   degraded: boolean,
+  note: string = DEGRADED_NOTE,
 ): string {
   if (results.length === 0) {
-    return degraded ? `${DEGRADED_NOTE}\n` : "No memories found.\n";
+    return degraded ? `${note}\n` : "No memories found.\n";
   }
   const lines: string[] = [];
   if (degraded) {
-    lines.push(`${DEGRADED_NOTE} Ranked by keyword match.`, "");
+    lines.push(`${note} Ranked by keyword match.`, "");
   }
   lines.push(`🔍 Search: "${query}" (${results.length} results)`, "");
   for (const result of results) {

package/ts/src/frontDoor/usage.ts

@@ -131,6 +131,11 @@ export function renderUnknownSubcommand(
 export interface UsageContext {
   readonly userConfigured: boolean;
   readonly configFile: string;
+  /**
+   * "To use the home at <path>, run: mirror init <name>" when a home `init` can
+   * name is on disk and nothing selects it (CR185), else absent.
+   */
+  readonly useHome?: string | null;
 }
 
 /**
@@ -139,11 +144,16 @@ export interface UsageContext {
  * usage dump -- three lines that say what is missing, what to run, and where
  * the configuration will live. With a user configured, bare `mirror` is the
  * usage block, as before.
+ *
+ * CR185: when a home is on disk that nothing selects -- a move from a clone to
+ * the package -- what to run is the command that uses it, the sentence the
+ * not-configured error gives.
  */
-export function renderOrientation(configFile: string): string {
+export function renderOrientation(configFile: string, useHome: string | null = null): string {
+  const create = `  Run: ${PROGRAM} init <your-name>`;
   return [
     "No user configured yet.",
-    `  Run: ${PROGRAM} init <your-name>`,
+    useHome === null ? create : `  ${useHome}`,
     `  Configuration will live at: ${configFile}`,
     "",
   ].join("\n");
@@ -156,7 +166,11 @@ export function answerUsage(request: UsageRequest, context?: UsageContext): Usag
       return { stream: "stdout", exitCode: 0, text: USAGE };
     }
     if (request.given === null && context !== undefined && !context.userConfigured) {
-      return { stream: "stdout", exitCode: 1, text: renderOrientation(context.configFile) };
+      return {
+        stream: "stdout",
+        exitCode: 1,
+        text: renderOrientation(context.configFile, context.useHome ?? null),
+      };
     }
     const unknown = request.given === null ? "" : `Unknown command: ${request.given}\n\n`;
     return { stream: "stdout", exitCode: 1, text: `${unknown}${USAGE}` };

package/ts/src/init/init.ts

@@ -15,6 +15,7 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHomePath } from "#frontDoor/mirrorHomes.ts";
 import { runningTreeRoot } from "#runtime/treeRoot.ts";
 
 /** Port of Python's uncaught `FileNotFoundError` for a missing templates root. */
@@ -51,7 +52,7 @@ export function templatesIdentityRoot(treeRoot: string = runningTreeRoot()): str
  * make every later command print the legacy-path warning (D14).
  */
 export function defaultUserHome(user: string, home: string = homedir()): string {
-  return join(home, ".mirror-minds", user);
+  return userHomePath(user, home);
 }
 
 /** Every `.yaml` file under `root`, recursively (mirrors `Path.rglob("*.yaml")`). */

package/ts/src/providers/config.ts

@@ -1,3 +1,7 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { configFilePath } from "#runtime/config.ts";
+
 export type ProviderName = "openrouter";
 
 export interface ProviderConfig {
@@ -9,6 +13,8 @@ export interface ProviderConfig {
 export interface ProviderConfigOptions {
   env?: Record<string, string | undefined>;
   argv?: readonly string[];
+  /** The OS user's home, where the config file is named from (tests only). */
+  home?: string;
 }
 
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
@@ -184,11 +190,92 @@ export function resolveProviderConfig(
   const env = options.env ?? process.env;
   const apiKey = env.OPENROUTER_API_KEY?.trim();
   if (!apiKey) {
-    throw new ProviderConfigError("OPENROUTER_API_KEY is not configured.");
+    // Reached lazily, at a command's first model call, so it claims nothing
+    // about what the command did before it (CR187).
+    const where = keyFileInstruction(env, options.home);
+    throw new ProviderConfigError(`OPENROUTER_API_KEY is not configured. Add ${where}.`);
   }
   return { provider, apiKey, baseUrl: OPENROUTER_BASE_URL };
 }
 
+// --- CR187: the key's presence, and the sentences that say where it goes ---
+//
+// A missing key reached Node as a stack trace that named no file, and a key
+// OpenRouter refused did the same. Every sentence about the key is built here,
+// from one predicate, so the refusal, the status line, and the diagnose finding
+// cannot disagree about what "configured" means. None of them carries the key.
+
+/** Whether a key is configured: present and not blank, trimmed as the provider reads it. */
+export function hasOpenRouterKey(env: Record<string, string | undefined>): boolean {
+  return Boolean(env.OPENROUTER_API_KEY?.trim());
+}
+
+/**
+ * "OPENROUTER_API_KEY=<your key> to <config>", naming the file this install
+ * reads (`XDG_CONFIG_HOME` honoured). When that file does not exist yet, the
+ * person is about to create it by hand, where the usual umask makes it 0644 --
+ * the key readable by every account on the machine -- so the instruction says
+ * to make it owner-only. A file `init` created is 0600 already.
+ */
+export function keyFileInstruction(
+  env: Record<string, string | undefined>,
+  home: string = homedir(),
+): string {
+  return `OPENROUTER_API_KEY=<your key> to ${keyFileTarget(env, home)}`;
+}
+
+/** The config file to add the key to, with the owner-only clause when it is new. */
+export function keyFileTarget(
+  env: Record<string, string | undefined>,
+  home: string = homedir(),
+): string {
+  const config = configFilePath({ XDG_CONFIG_HOME: env.XDG_CONFIG_HOME }, home);
+  const created = existsSync(config)
+    ? ""
+    : ` (a new file; make it readable only by you: chmod 600 ${config})`;
+  return `${config}${created}`;
+}
+
+/**
+ * Refuse, before a command does anything, when the key it cannot work without
+ * is missing. The sentence says first what was not done, then how to fix it:
+ * the person's first question is whether their entry, plan, or question went
+ * anywhere.
+ */
+export function requireOpenRouterKey(
+  env: Record<string, string | undefined>,
+  options: { consequence?: string; home?: string } = {},
+): void {
+  if (hasOpenRouterKey(env)) return;
+  const consequence = options.consequence ?? "nothing was done";
+  throw new ProviderConfigError(
+    `${consequence}, because OPENROUTER_API_KEY is not configured. ` +
+      `Add ${keyFileInstruction(env, options.home)}, then run the same command again.`,
+  );
+}
+
+/**
+ * A key OpenRouter refused (HTTP 401 or 403), named by status and by where a
+ * key can be set -- never by value, and never with anything the provider sent
+ * back. The key may come from the shell or a clone's `.env` as well as the
+ * config file, so all three are named, as diagnose does for its own settings.
+ */
+export function keyRefusedMessage(
+  status: number | null,
+  options: { env?: Record<string, string | undefined>; home?: string } = {},
+): string {
+  const env = options.env ?? process.env;
+  const config = configFilePath(
+    { XDG_CONFIG_HOME: env.XDG_CONFIG_HOME },
+    options.home ?? homedir(),
+  );
+  const code = status === null ? "" : ` (HTTP ${status})`;
+  return (
+    `OpenRouter refused OPENROUTER_API_KEY${code}. Check the key where it is set: ` +
+    `the environment, the clone's .env, or ${config}.`
+  );
+}
+
 function rejectArgvSecrets(argv: readonly string[]): void {
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index] ?? "";

package/ts/src/providers/embedding.ts

@@ -6,7 +6,12 @@ import {
   resolveLlmTimeoutMs,
   resolveProviderConfig,
 } from "./config.ts";
-import { createOpenRouterClient, LlmTransportError, type OpenRouterClient } from "./openrouter.ts";
+import {
+  createOpenRouterClient,
+  LlmTransportError,
+  type LlmTransportErrorKind,
+  type OpenRouterClient,
+} from "./openrouter.ts";
 import { loadReplayFixture } from "./replay.ts";
 
 /**
@@ -33,12 +38,28 @@ export const EMBEDDING_DIMENSIONS = 1536;
 export const DEFAULT_EMBEDDING_ATTEMPTS = 3;
 export const DEFAULT_EMBEDDING_RETRY_BACKOFF_MS = 500;
 
+/** The classification a wrapped transport failure carried: nothing else of it (CR187). */
+export interface WrappedTransport {
+  readonly kind: LlmTransportErrorKind;
+  readonly status: number | null;
+}
+
 export class EmbeddingError extends Error {
   readonly permanent: boolean;
-  constructor(message: string, options: { permanent?: boolean } = {}) {
+  /**
+   * The transport failure this wraps, by kind and status, or null. Kept so a key
+   * OpenRouter refused on an embedding call can be named like one refused on a
+   * chat call (CR187); a message or a cause would carry what the provider sent.
+   */
+  readonly transport: WrappedTransport | null;
+  constructor(
+    message: string,
+    options: { permanent?: boolean; transport?: WrappedTransport | null } = {},
+  ) {
     super(message);
     this.name = "EmbeddingError";
     this.permanent = options.permanent ?? false;
+    this.transport = options.transport ?? null;
   }
 }
 
@@ -116,7 +137,9 @@ export async function generateEmbeddingSafely(
       // Provider/transport exception: terminal at this layer, not retried.
       options.onAttempt?.({ text, vector: null, latencyMs: Date.now() - t0, promptTokens: null });
       const detail = error instanceof Error ? error.message : String(error);
-      throw new EmbeddingError(`Embedding provider call failed: ${detail}`);
+      const transport =
+        error instanceof LlmTransportError ? { kind: error.kind, status: error.status } : null;
+      throw new EmbeddingError(`Embedding provider call failed: ${detail}`, { transport });
     }
     const { vector, promptTokens } = result;
     if (!vector || vector.length === 0) {