mirror-mind 0.38.0 → 0.38.1

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/runtime/diagnose.ts

@@ -34,7 +34,12 @@ import {
   readExtensionPlugin,
 } from "#extensions/extensionPlugin.ts";
 import { identityKeyBreaksGrammar, SLUG_KEYED_LAYERS } from "#identity/identityKey.ts";
-import { REASONING_EFFORTS, resolveExtractionReasoning } from "#providers/config.ts";
+import {
+  hasOpenRouterKey,
+  keyFileInstruction,
+  REASONING_EFFORTS,
+  resolveExtractionReasoning,
+} from "#providers/config.ts";
 import { pyRepr, sortByCodePoint } from "#util/pythonText.ts";
 import { configFilePath } from "./config.ts";
 import { extensionPluginStates } from "./extensionPluginWiring.ts";
@@ -772,6 +777,28 @@ export function staleRevertGateFindings(env: NodeJS.ProcessEnv): DriftFinding[]
   ];
 }
 
+/**
+ * No OpenRouter key (CR187), read by the predicate every refusal uses, so
+ * diagnose and the refusals cannot disagree about what "configured" means.
+ * Presence only: the value is never read into a finding. Attention, not a
+ * blocker -- a keyless install still runs and updates; it just remembers
+ * nothing new and answers no `consult`. The recommendation names the file the
+ * key goes in, and says to make it owner-only when it does not exist yet.
+ */
+export function openRouterKeyFindings(env: NodeJS.ProcessEnv, home?: string): DriftFinding[] {
+  if (hasOpenRouterKey(env)) return [];
+  return [
+    {
+      code: "openrouter_key_missing",
+      severity: "attention",
+      subject: "OPENROUTER_API_KEY",
+      detail: "not set, so embeddings, memory extraction, and consult are off",
+      recommendation: `add ${keyFileInstruction(env, home)}`,
+      repair_route: "configuration",
+    },
+  ];
+}
+
 /**
  * A `MEMORY_EXTRACTION_REASONING` that is not a reasoning effort (CV9.DS9.TS1).
  *

package/ts/src/runtime/git.ts

@@ -84,6 +84,17 @@ export interface UpdateAvailability {
   target_release: null;
 }
 
+/**
+ * How a caller asks git for something. `runGit` is one; the update pipeline
+ * injects others, so its decisions can be driven in tests without a remote.
+ * Without a timeout, a command gets `runGit`'s local budget.
+ */
+export type GitRunner = (
+  args: readonly string[],
+  cwd: string,
+  timeoutMs?: number,
+) => { code: number; stdout: string; stderr: string };
+
 /** `(exit code, trimmed stdout, trimmed stderr)`, tolerant like the oracle's. */
 export function runGit(
   args: readonly string[],
@@ -217,6 +228,16 @@ export function upstreamFor(channel: MarkerValue): string {
   return `origin/${channel.value}`;
 }
 
+/** `origin/main` -> `["origin", "main"]`; anything else is refused. */
+export function splitUpstream(upstream: string): [string, string] | null {
+  const index = upstream.indexOf("/");
+  if (index <= 0 || index === upstream.length - 1) return null;
+  const remote = upstream.slice(0, index);
+  const branch = upstream.slice(index + 1);
+  if (remote.startsWith("-") || branch.startsWith("-")) return null;
+  return [remote, branch];
+}
+
 // Lives in `runtime/version.ts` now -- the MCP server needs it and should not
 // import this module to get it. Re-exported so runtime call sites do not move.
 export { packageVersion } from "./version.ts";
@@ -338,6 +359,117 @@ export function checkUpdateAvailability(
   });
 }
 
+/**
+ * Where a checkout stands against the channel branch it follows: one reading
+ * for both the update plan (`strategies/clone.ts`) and `inspectGitUpdatePlan`,
+ * so the two cannot disagree (CR186). `ahead` counts the checkout's commits
+ * that the upstream lacks; `behind`, the upstream's commits that the checkout lacks.
+ */
+export type ChannelPosition =
+  /** The two could not be compared; `reason` is git's, when it gave one. */
+  | { kind: "unreadable"; reason: string }
+  | { kind: "current" }
+  /** The channel has commits to take, and the checkout has none of its own. */
+  | { kind: "pull"; behind: number }
+  /**
+   * Every commit past the channel is already on the other channel's branch:
+   * the channel is behind the checkout, and nothing here is the person's own.
+   * Release promotion only fast-forwards `stable` to `main`, so this is a
+   * `stable` clone that took `main`'s commits before their release.
+   */
+  | {
+      kind: "channel_behind";
+      ahead: number;
+      channel: string;
+      carriedBy: string;
+      carriedByRef: string;
+    }
+  /** At least one commit past the channel is on no channel's branch. */
+  | { kind: "local_commits"; ahead: number }
+  | { kind: "diverged"; ahead: number; behind: number };
+
+type CommitCount = { value: number } | { reason: string };
+
+function countCommits(
+  repository: string,
+  revisions: readonly string[],
+  git: GitRunner,
+): CommitCount {
+  const result = git(["rev-list", "--count", ...revisions], repository);
+  const value = Number.parseInt(result.stdout.trim(), 10);
+  if (result.code !== 0 || Number.isNaN(value)) {
+    return { reason: result.stderr.trim() || "cannot compare upstream" };
+  }
+  return { value };
+}
+
+/**
+ * The other channel whose branch already has every commit past `upstream`, if
+ * one does. Its ref is read as last fetched. A stale or missing ref can only
+ * make published commits look local, which is the refusal a clone always had;
+ * it can never make local work look published.
+ */
+function channelBehind(
+  repository: string,
+  upstream: string,
+  ahead: number,
+  git: GitRunner,
+): ChannelPosition | null {
+  const split = splitUpstream(upstream);
+  if (split === null) return null;
+  const [remote, channel] = split;
+  if (!KNOWN_UPDATE_CHANNELS.has(channel)) return null;
+  for (const other of KNOWN_UPDATE_CHANNELS) {
+    if (other === channel) continue;
+    const ref = `${remote}/${other}`;
+    const unpublished = countCommits(repository, [`${upstream}..HEAD`, `^${ref}`], git);
+    if ("value" in unpublished && unpublished.value === 0) {
+      return { kind: "channel_behind", ahead, channel, carriedBy: other, carriedByRef: ref };
+    }
+  }
+  return null;
+}
+
+/** Read from the local object database only: the plan, not the remote check. */
+export function readChannelPosition(
+  repository: string,
+  upstream: string,
+  git: GitRunner = runGit,
+): ChannelPosition {
+  const ahead = countCommits(repository, [`${upstream}..HEAD`], git);
+  if ("reason" in ahead) return { kind: "unreadable", reason: ahead.reason };
+  const behind = countCommits(repository, [`HEAD..${upstream}`], git);
+  if ("reason" in behind) return { kind: "unreadable", reason: behind.reason };
+  if (ahead.value === 0) {
+    return behind.value === 0 ? { kind: "current" } : { kind: "pull", behind: behind.value };
+  }
+  if (behind.value > 0) return { kind: "diverged", ahead: ahead.value, behind: behind.value };
+  return (
+    channelBehind(repository, upstream, ahead.value, git) ?? {
+      kind: "local_commits",
+      ahead: ahead.value,
+    }
+  );
+}
+
+/** The words both readers give a position: the plan's detail, the inspection's note. */
+export function describeChannelPosition(position: ChannelPosition): string {
+  switch (position.kind) {
+    case "unreadable":
+      return position.reason;
+    case "current":
+      return "already up to date";
+    case "pull":
+      return `pull ${position.behind} remote commit(s)`;
+    case "channel_behind":
+      return `'${position.channel}' is behind this checkout (${position.ahead} commit(s), all on ${position.carriedByRef})`;
+    case "local_commits":
+      return "local commits present";
+    case "diverged":
+      return "branch diverged";
+  }
+}
+
 /**
  * Port of `inspect_git_update_plan`: how far HEAD is from the channel's
  * upstream, and whether a fast-forward is the honest move.
@@ -381,49 +513,28 @@ export function inspectGitUpdatePlan(
     }
   }
 
-  const counted = runGit(
-    ["rev-list", "--left-right", "--count", `HEAD...${upstream}`],
-    git.repository,
-  );
-  if (counted.code !== 0 || !counted.stdout) {
-    return blocked(upstream, counted.stderr || "cannot compare upstream");
-  }
-  const [aheadText, behindText] = counted.stdout.split(/\s+/);
-  const ahead = Number(aheadText);
-  const behind = Number(behindText);
-  if (
-    aheadText === undefined ||
-    behindText === undefined ||
-    !Number.isInteger(ahead) ||
-    !Number.isInteger(behind)
-  ) {
-    return blocked(upstream, `unexpected git count: ${counted.stdout}`);
-  }
-
-  if (ahead === 0 && behind === 0) {
-    return { upstream, ahead, behind, ready: true, action: "none", note: "already up to date" };
-  }
-  if (ahead === 0 && behind > 0) {
-    return {
-      upstream,
-      ahead,
-      behind,
-      ready: true,
-      action: "pull",
-      note: `pull ${behind} remote commit(s)`,
-    };
-  }
-  if (ahead > 0 && behind === 0) {
-    return {
-      upstream,
-      ahead,
-      behind,
-      ready: false,
-      action: "blocked",
-      note: "local commits present",
-    };
+  const position = readChannelPosition(git.repository, upstream);
+  const note = describeChannelPosition(position);
+  switch (position.kind) {
+    case "unreadable":
+      return blocked(upstream, note);
+    case "current":
+      return { upstream, ahead: 0, behind: 0, ready: true, action: "none", note };
+    case "pull":
+      return { upstream, ahead: 0, behind: position.behind, ready: true, action: "pull", note };
+    case "diverged":
+      return {
+        upstream,
+        ahead: position.ahead,
+        behind: position.behind,
+        ready: false,
+        action: "blocked",
+        note,
+      };
+    case "channel_behind":
+    case "local_commits":
+      return { upstream, ahead: position.ahead, behind: 0, ready: false, action: "blocked", note };
   }
-  return { upstream, ahead, behind, ready: false, action: "blocked", note: "branch diverged" };
 }
 
 /** A package's git facts: it has none, and none is not an error. */

package/ts/src/runtime/status.ts

@@ -25,7 +25,11 @@ import { readExtensionPlugin } from "#extensions/extensionPlugin.ts";
 import { loadExtensionManifest } from "#extensions/manifest.ts";
 import { inspectMigrationFiles } from "#extensions/migrations.ts";
 import { type DbPathEnv, dbNameForEnv, resolveMirrorHome } from "#frontDoor/dbPath.ts";
-import { DEFAULT_EMBEDDING_MODEL, resolveExtractionReasoning } from "#providers/config.ts";
+import {
+  DEFAULT_EMBEDDING_MODEL,
+  hasOpenRouterKey,
+  resolveExtractionReasoning,
+} from "#providers/config.ts";
 import { sortByCodePoint } from "#util/pythonText.ts";
 import { channelForReport } from "./channel.ts";
 import type { MarkerValue } from "./git.ts";
@@ -373,28 +377,30 @@ export interface BuildStatusOptions {
    * front door with no npm probe (see `installKind.ts`).
    */
   install?: InstallKind;
+  /**
+   * The OS user's home, where the homes root and the config file are found when
+   * no home is configured; `composeWelcome` takes the same seam. The golden tests
+   * pin it, since the not-configured sentence names what is found there.
+   */
+  osHome?: string;
 }
 
 /**
  * Python's `resolve_mirror_home` raises `ValueError`, and
- * `build_runtime_status` prints `str(exc)` as `Mirror home note:`. The front
- * door's own resolver adds a MEMORY_DIR/DB_PATH hint that is right for a
- * front-door failure and wrong for this report, which is graded against the
- * oracle -- so the not-configured sentence is restated in the oracle's words.
- * The conflict sentence already matches byte-for-byte.
+ * `build_runtime_status` prints `str(exc)` as `Mirror home note:`. Until CR185
+ * the not-configured sentence was restated here in the oracle's shorter words;
+ * it is now the front door's own, the same on every surface, saying what to
+ * run and which file that writes.
  */
-function mirrorHomeForStatus(env: DbPathEnv): { home: string | null; error: string | null } {
+function mirrorHomeForStatus(
+  env: DbPathEnv,
+  osHome: string | undefined,
+): { home: string | null; error: string | null } {
   try {
-    return { home: resolveMirrorHome(env), error: null };
+    const io = osHome === undefined ? {} : { home: osHome };
+    return { home: resolveMirrorHome(env, io), error: null };
   } catch (error) {
-    const message = errorMessage(error);
-    if (message.startsWith("Mirror home is not configured")) {
-      return {
-        home: null,
-        error: "Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER.",
-      };
-    }
-    return { home: null, error: message };
+    return { home: null, error: errorMessage(error) };
   }
 }
 
@@ -417,7 +423,7 @@ export function buildRuntimeStatus(options: BuildStatusOptions = {}): RuntimeSta
     mirrorHome = existsSync(expanded) ? realpathSync(expanded) : expanded;
     mirrorHomeError = null;
   } else {
-    ({ home: mirrorHome, error: mirrorHomeError } = mirrorHomeForStatus(env));
+    ({ home: mirrorHome, error: mirrorHomeError } = mirrorHomeForStatus(env, options.osHome));
   }
 
   const memoryEnv = env.MEMORY_ENV || "production";
@@ -592,6 +598,10 @@ export function renderRuntimeStatus(
       reasoningClause(env) +
       `embedding=${env.MEMORY_EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL}`,
   );
+  // CR187: whether those models can be called at all. Presence only, by the
+  // predicate every refusal uses; never the value, and never the verdict -- the
+  // update gate reads the verdict, and a keyless install must still update.
+  lines.push(`OpenRouter key: ${hasOpenRouterKey(env) ? "configured" : "not configured"}`);
   lines.push("");
   lines.push(`Status: ${statusVerdict(report)}`);
   return `${lines.join("\n")}\n`;

package/ts/src/runtime/strategies/clone.ts

@@ -9,29 +9,19 @@
 // decisions can be driven in tests without a remote, and so this module can be
 // read as "what we ask git for" rather than "how we spawn it".
 
-import { GIT_NETWORK_TIMEOUT_MS, runGit } from "#runtime/git.ts";
-import type { ApplyStrategy } from "#runtime/updatePipeline.ts";
-
-/** Without a timeout, a command gets `runGit`'s local budget. */
-export type GitRunner = (
-  args: readonly string[],
-  cwd: string,
-  timeoutMs?: number,
-) => { code: number; stdout: string; stderr: string };
+import {
+  describeChannelPosition,
+  GIT_NETWORK_TIMEOUT_MS,
+  type GitRunner,
+  readChannelPosition,
+  runGit,
+  splitUpstream,
+} from "#runtime/git.ts";
+import type { ApplyStrategy, PlanOutcome } from "#runtime/updatePipeline.ts";
 
 export const defaultGitRunner: GitRunner = (args, cwd, timeoutMs) =>
   runGit([...args], cwd, timeoutMs);
 
-/** `origin/main` -> `["origin", "main"]`; anything else is refused. */
-export function splitUpstream(upstream: string): [string, string] | null {
-  const index = upstream.indexOf("/");
-  if (index <= 0 || index === upstream.length - 1) return null;
-  const remote = upstream.slice(0, index);
-  const branch = upstream.slice(index + 1);
-  if (remote.startsWith("-") || branch.startsWith("-")) return null;
-  return [remote, branch];
-}
-
 /** The commit this install is on, read BEFORE anything moves. */
 export function captureCommit(repository: string, git: GitRunner): string | null {
   const result = git(["rev-parse", "--short", "HEAD"], repository);
@@ -95,11 +85,72 @@ export function cloneRecoveryCommand(previous: string | null): string {
   return previous === null ? "git reset --hard <previous commit>" : `git reset --hard ${previous}`;
 }
 
-function countCommits(repository: string, range: string, git: GitRunner): number | null {
-  const result = git(["rev-list", "--count", range], repository);
-  if (result.code !== 0) return null;
-  const value = Number.parseInt(result.stdout.trim(), 10);
-  return Number.isNaN(value) ? null : value;
+/**
+ * Where the checkout stands against `upstream`, as the update plan answers it.
+ * The position is the one `inspectGitUpdatePlan` reads, in the same words
+ * (CR186); what is added here is the way out of each refusal.
+ */
+function planFrom(
+  repository: string,
+  upstream: string,
+  previousRef: string,
+  git: GitRunner,
+): PlanOutcome {
+  const position = readChannelPosition(repository, upstream, git);
+  const detail = describeChannelPosition(position);
+  const unchanged = "The working tree and the database are unchanged.";
+  switch (position.kind) {
+    case "unreadable":
+      return {
+        kind: "blocked",
+        detail: `cannot compare against ${upstream}`,
+        recovery: [`Resolve upstream tracking for ${upstream}, then retry runtime update.`],
+      };
+    case "current":
+      return { kind: "current", detail };
+    case "pull":
+      return {
+        kind: "ahead",
+        target: upstream,
+        detail,
+        dryRun: `would pull ${position.behind} commit(s) from ${upstream}`,
+      };
+    case "channel_behind":
+      // The package lane's refusal of a channel behind the installed version,
+      // in its words: the same state, whichever way Mirror was installed. No
+      // reset to the channel: the commits past it may already have migrated
+      // the database, and the channel's code refuses a database newer than it.
+      return {
+        kind: "blocked",
+        detail,
+        recovery: [
+          "A downgrade is refused: migrations do not run backwards.",
+          `Follow the channel that carries ${previousRef}: runtime channel ${position.carriedBy}`,
+          `Or stay on ${previousRef} until '${position.channel}' reaches it: the next release contains these commits.`,
+          unchanged,
+        ],
+      };
+    case "local_commits":
+      return {
+        kind: "blocked",
+        detail,
+        recovery: [
+          "Local branch is ahead of upstream; push or reset before updating.",
+          unchanged,
+          `Current commit: ${previousRef}`,
+        ],
+      };
+    case "diverged":
+      return {
+        kind: "blocked",
+        detail,
+        recovery: [
+          "Branch diverged; reconcile local and upstream commits manually.",
+          unchanged,
+          `Current commit: ${previousRef}`,
+        ],
+      };
+  }
 }
 
 /**
@@ -151,37 +202,7 @@ export function cloneStrategy(repository: string, upstream: string, git: GitRunn
           };
     },
 
-    plan: (previousRef) => {
-      const ahead = countCommits(repository, `${upstream}..HEAD`, git);
-      const behind = countCommits(repository, `HEAD..${upstream}`, git);
-      if (ahead === null || behind === null) {
-        return {
-          kind: "blocked",
-          detail: `cannot compare against ${upstream}`,
-          recovery: [`Resolve upstream tracking for ${upstream}, then retry runtime update.`],
-        };
-      }
-      if (ahead === 0 && behind === 0) return { kind: "current", detail: "already up to date" };
-      if (ahead > 0) {
-        return {
-          kind: "blocked",
-          detail: behind > 0 ? "branch diverged" : "local commits present",
-          recovery: [
-            behind > 0
-              ? "Branch diverged; reconcile local and upstream commits manually."
-              : "Local branch is ahead of upstream; push or reset before updating.",
-            "The working tree and the database are unchanged.",
-            `Current commit: ${previousRef}`,
-          ],
-        };
-      }
-      return {
-        kind: "ahead",
-        target: upstream,
-        detail: `pull ${behind} remote commit(s)`,
-        dryRun: `would pull ${behind} commit(s) from ${upstream}`,
-      };
-    },
+    plan: (previousRef) => planFrom(repository, upstream, previousRef, git),
 
     apply: (previousRef, target) => {
       const applied = fastForward(repository, target, git);

package/ts/src/runtime/update.ts

@@ -28,6 +28,7 @@
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { verifyBackupArchive } from "#runtime/backup.ts";
+import type { GitRunner } from "#runtime/git.ts";
 import type { InstallKind } from "#runtime/installKind.ts";
 import {
   agyPluginCopyState,
@@ -35,7 +36,7 @@ import {
   grokPluginCopyState,
   installedPluginVersion,
 } from "#runtime/pluginWiring.ts";
-import { cloneStrategy, defaultGitRunner, type GitRunner } from "#runtime/strategies/clone.ts";
+import { cloneStrategy, defaultGitRunner } from "#runtime/strategies/clone.ts";
 import { defaultNpmRunner, type NpmRunner, packageStrategy } from "#runtime/strategies/package.ts";
 import type { statusAllowsUpdatePreflight } from "#runtime/updateGate.ts";
 import {

package/ts/src/search/memorySearch.ts

@@ -350,8 +350,10 @@ function classifyDegradedCause(error: unknown): string {
   if (error instanceof ProviderConfigError) return "config";
   if (error instanceof LlmTransportError) return error.kind;
   if (error instanceof EmbeddingError) {
-    // generateEmbeddingSafely wraps a provider exception; the inner kind is
-    // gone by then, so the honest answer is the layer that failed.
+    // generateEmbeddingSafely wraps a provider exception. Since CR187 the
+    // wrapper keeps a transport failure's kind, so a refused key reads `auth`;
+    // anything else is still answered by the layer that failed.
+    if (error.transport !== null) return error.transport.kind;
     return error.permanent ? "embedding_permanent" : "embedding_exhausted";
   }
   return "unknown";