mirror-mind 0.37.0 → 0.38.1

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,
@@ -25,8 +26,10 @@ import { channelFor, channelForReport, renderChannel, setChannel } from "#runtim
 import {
   diagnoseRuntime,
   extensionPluginFindings,
+  extractionReasoningFindings,
   hookFailureFindings,
   hookNodeFindings,
+  openRouterKeyFindings,
   pluginWiringFindings,
   probeModelPins,
   renderRuntimeDiagnosis,
@@ -318,12 +321,18 @@ 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.
       // 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),
+      // 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 {
@@ -774,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";
@@ -18,7 +24,14 @@ const ARG_SECRET_PATTERN =
 // Model pins (AI-06, CV9.E2.S12): a deprecated pinned model would fail every
 // extraction/embedding call, and those paths fail soft -- so the pins must be
 // env-overridable to repoint a deployed instance without a release.
-export const DEFAULT_EXTRACTION_MODEL = "google/gemini-2.5-flash-lite";
+//
+// The extraction pin moved from `google/gemini-2.5-flash-lite` to Claude Haiku 5.5
+// on 2026-10-28 (CV9.DS9.US3), on DS9's measurement: the Navigator's own blind
+// rankings on his conversations, the suite at reasoning off, and Flash Lite's
+// upstream rate limits. A pin change is a migration: the pin, its entry in
+// MODEL_DEFAULT_REASONING, and MODEL_PRICES (cost.ts) move in one commit, behind
+// a green `eval --all` (the development guide's model upgrade playbook).
+export const DEFAULT_EXTRACTION_MODEL = "anthropic/claude-haiku-5.5";
 export const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
 
 export interface ModelPinOptions {
@@ -51,6 +64,103 @@ export function resolveEmbeddingModel(options: ModelPinOptions = {}): string {
   return env.MEMORY_EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL;
 }
 
+/**
+ * The reasoning efforts OpenRouter's catalogue lists across its models (checked
+ * 2026-10-26, CV9.DS9.TS1). `none` turns reasoning off. Whether a given model
+ * honours a given effort is the operator's choice; this list is the vocabulary.
+ */
+export const REASONING_EFFORTS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+/** What `MEMORY_EXTRACTION_REASONING` says: an effort to send, or a value that is not one. */
+export interface ExtractionReasoning {
+  /** The effort to send as `reasoning.effort`, or null to send no reasoning field. */
+  effort: ReasoningEffort | null;
+  /** The value as written when it is not an effort; null otherwise. */
+  invalid: string | null;
+}
+
+/**
+ * Read `MEMORY_EXTRACTION_REASONING` (CV9.DS9.TS1): the reasoning effort every
+ * extraction-family call sends. Absent or blank sends nothing, which is the request
+ * as it was before the setting existed.
+ *
+ * Unlike the numeric resolvers below, this never throws. They fail loudly, but they
+ * are read inside the session-end hooks, where a throw becomes an extraction attempt
+ * and three attempts quarantine a conversation for good (CR178). So a value that is
+ * not an effort sends nothing too, and comes back as `invalid` for `runtime status`
+ * and `runtime diagnose` to show.
+ */
+export function readExtractionReasoning(options: ModelPinOptions = {}): ExtractionReasoning {
+  const env = options.env ?? process.env;
+  const raw = env.MEMORY_EXTRACTION_REASONING ?? "";
+  const value = raw.trim().toLowerCase();
+  if (value === "") return { effort: null, invalid: null };
+  const effort = REASONING_EFFORTS.find((candidate) => candidate === value);
+  return effort ? { effort, invalid: null } : { effort: null, invalid: raw.trim() };
+}
+
+/**
+ * The reasoning effort a model sends when `MEMORY_EXTRACTION_REASONING` is unset
+ * (CV9.DS9.US3). A property of the model, because what DS9 measured is: Haiku
+ * reasons by default and spent the title call's 40-token budget, so it was
+ * measured and chosen at `none`; Flash Lite was measured with no reasoning field,
+ * and a model absent from this table gets none, which is the request as it was
+ * before the setting existed. So the playbook's rollback, `MEMORY_EXTRACTION_MODEL`
+ * set to the old pin, reproduces exactly the request the old pin was measured with,
+ * and naming the default pin explicitly sends the same request as leaving it unset.
+ */
+export const MODEL_DEFAULT_REASONING: Readonly<Record<string, ReasoningEffort>> = {
+  "anthropic/claude-haiku-5.5": "none",
+};
+
+/** Where the effective effort came from: the setting, the model's default, or nowhere. */
+export type ReasoningSource = "setting" | "model_default";
+
+/** The effective pair every extraction-family call sends: the model and its effort. */
+export interface EffectiveExtractionReasoning {
+  /** The model the call names: `MEMORY_EXTRACTION_MODEL` or the default pin. */
+  model: string;
+  /** The effort to send as `reasoning.effort`, or null to send no reasoning field. */
+  effort: ReasoningEffort | null;
+  /** What decided `effort`; null when no field is sent. */
+  source: ReasoningSource | null;
+  /** `MEMORY_EXTRACTION_REASONING` as written when it is not an effort; null otherwise. */
+  invalid: string | null;
+}
+
+/**
+ * Resolve the model and the reasoning effort an extraction-family call sends
+ * (CV9.DS9.US3): the model first, then the effort: the setting when it names an
+ * effort, else the model's entry in `MODEL_DEFAULT_REASONING`, else no field. An
+ * invalid setting reads as unset, so the default pin still sends its model default;
+ * `invalid` carries the value for `runtime status` and `runtime diagnose`. The
+ * transport, the eval harness, and `runtime status` all read this one resolver.
+ */
+export function resolveExtractionReasoning(
+  options: ModelPinOptions = {},
+): EffectiveExtractionReasoning {
+  const model = resolveExtractionModel(options);
+  const setting = readExtractionReasoning(options);
+  if (setting.effort !== null) {
+    return { model, effort: setting.effort, source: "setting", invalid: null };
+  }
+  const modelDefault = MODEL_DEFAULT_REASONING[model];
+  if (modelDefault !== undefined) {
+    return { model, effort: modelDefault, source: "model_default", invalid: setting.invalid };
+  }
+  return { model, effort: null, source: null, invalid: setting.invalid };
+}
+
 // Observability (AI-09, CV9.E2.S13): mirrors Python's MEMORY_LOG_LLM_CALLS
 // resolution exactly -- off | metadata | full, default metadata (never a
 // silent full -- bodies are opt-in only). Legacy "1" maps to "full" for
@@ -80,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/cost.ts

@@ -29,7 +29,11 @@ export interface ModelPrice {
 
 /** Estimated OpenRouter list prices (USD / 1K tokens). Verify on every pin change. */
 export const MODEL_PRICES: Readonly<Record<string, ModelPrice>> = {
-  // Extraction pin -- google/gemini-2.5-flash-lite: ~$0.10/M in, ~$0.40/M out.
+  // Extraction pin since CV9.DS9.US3 -- anthropic/claude-haiku-5.5: $0.10/M in,
+  // $0.50/M out, read from OpenRouter's catalogue on 2026-10-28.
+  "anthropic/claude-haiku-5.5": { promptPer1k: 0.0001, completionPer1k: 0.0005 },
+  // The pin before it, kept so a rolled-back install (`MEMORY_EXTRACTION_MODEL`)
+  // keeps pricing its calls -- google/gemini-2.5-flash-lite: ~$0.10/M in, ~$0.40/M out.
   "google/gemini-2.5-flash-lite": { promptPer1k: 0.0001, completionPer1k: 0.0004 },
   // Embedding pin -- openai/text-embedding-3-small: ~$0.02/M, no completion side.
   "openai/text-embedding-3-small": { promptPer1k: 0.00002, completionPer1k: 0.0 },

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) {

package/ts/src/providers/familyProviders.ts

@@ -15,6 +15,7 @@
  * are required to replay" and "these are the providers this family uses".
  */
 
+import { requireOpenRouterKey } from "#providers/config.ts";
 import {
   type CreditProvider,
   LiveCreditProvider,
@@ -110,6 +111,48 @@ export async function resolveFamilyProviders(
     : liveProviders(env, owner, decision, overrides);
 }
 
+/**
+ * `resolveFamilyProviders` for a command that cannot do its job without the
+ * key (CR187): `consult`, `journal`, `week plan`, `descriptor generate`,
+ * `consolidate scan` and `apply`, and `shadow scan`.
+ *
+ * The contract is the call site's: it is the route's first statement, before
+ * the database is opened or anything is read, so the refusal's "nothing was
+ * done" -- or the `consequence` a route names instead -- is true. Live mode only:
+ * a replay fixture needs no key. The family returned is the one
+ * `resolveFamilyProviders` builds.
+ *
+ * A command that can still answer without the key (search, `build load`,
+ * `mirror load`) keeps calling `resolveFamilyProviders`, and degrades.
+ */
+export async function requireFamilyProviders(
+  env: ProviderTransportEnv,
+  spec: FamilyTransport,
+  options: { consequence?: string; overrides?: FamilyProviderOverrides } = {},
+): Promise<FamilyProviders> {
+  requireKeyForFamily(env, spec, options);
+  return resolveFamilyProviders(env, spec, options.overrides);
+}
+
+/**
+ * The key check alone, from the transport decision, with no provider built. For
+ * a route that must refuse before a step that comes ahead of its providers:
+ * `consult` ask opens its ledger database first, and that open takes the
+ * pre-write snapshot. Half a replay fixture is left to `resolveFamilyProviders`,
+ * which refuses it by name.
+ */
+export function requireKeyForFamily(
+  env: ProviderTransportEnv,
+  spec: FamilyTransport,
+  options: { consequence?: string } = {},
+): void {
+  const decision = isComposed(spec)
+    ? resolveComposedProviderTransport(env, spec)
+    : resolveProviderTransport(env, spec);
+  if (decision.mode !== "live") return;
+  requireOpenRouterKey(env, options.consequence === undefined ? {} : options);
+}
+
 async function replayProviders(
   decision: ProviderTransportDecision,
   overrides: FamilyProviderOverrides,

package/ts/src/providers/llm.ts

@@ -4,6 +4,7 @@ import {
   type LlmTimeoutRole,
   type ProviderConfig,
   resolveExtractionModel,
+  resolveExtractionReasoning,
   resolveLlmMaxRetries,
   resolveLlmTimeoutMs,
   resolveProviderConfig,
@@ -76,6 +77,33 @@ const LLM_TIMEOUT_TIER: Readonly<Record<LlmRole, LlmTimeoutRole>> = {
   descriptor: "extraction",
 };
 
+/**
+ * Which roles carry `MEMORY_EXTRACTION_REASONING` (CV9.DS9.TS1): every role that
+ * runs on the extraction pin. `consult` picks its own model on every call, so a
+ * setting meant for the extraction pin must not reach it.
+ *
+ * A full `Record<LlmRole, boolean>` for the reason `LLM_TIMEOUT_TIER` is one: a
+ * role added to `LLM_ROLES` cannot compile without declaring it. A check against
+ * `"consult"` would let the next role that names its own model inherit the
+ * setting silently.
+ */
+export const CARRIES_EXTRACTION_REASONING: Readonly<Record<LlmRole, boolean>> = {
+  extraction: true,
+  task_extraction: true,
+  summary: true,
+  curation: true,
+  consult: false,
+  reception: true,
+  consolidation: true,
+  shadow_scan: true,
+  conversation_title: true,
+  conversation_tags: true,
+  conversation_summary: true,
+  journal_classification: true,
+  week_plan: true,
+  descriptor: true,
+};
+
 /**
  * The roles a message in Python's envelope can carry.
  *
@@ -273,6 +301,16 @@ export class LiveLlmProvider implements LlmProvider {
   async complete(request: LlmRequest): Promise<LlmResponse> {
     const client = this.resolveClient();
     const model = request.model ?? resolveExtractionModel({ env: this.env });
+    // CV9.DS9.TS1: the one added field; US3: the setting, else the model's own
+    // default (Haiku sends `none`; a model outside the table sends nothing). An
+    // invalid value reads as unset, so it fails nothing (a failed call would
+    // become an extraction attempt, CR178); `runtime status` and `diagnose`
+    // report it.
+    const { effort } = resolveExtractionReasoning({ env: this.env });
+    const reasoning =
+      effort !== null && CARRIES_EXTRACTION_REASONING[request.role]
+        ? { reasoning: { effort } }
+        : {};
     const startedAt = Date.now();
     const body = await client.postJson(
       "/chat/completions",
@@ -286,6 +324,8 @@ export class LiveLlmProvider implements LlmProvider {
           : [{ role: "user", content: request.prompt }],
         temperature: request.temperature ?? DEFAULT_TEMPERATURE,
         max_tokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
+        // Unset, this adds nothing: the body is the one it was before the setting.
+        ...reasoning,
       },
       {
         timeoutMs: resolveLlmTimeoutMs(LLM_TIMEOUT_TIER[request.role], { env: this.env }),