mirror-mind 0.36.2 → 0.37.0

package/ts/src/mode/operatingMode.ts

@@ -36,18 +36,36 @@ export function modeLabel(state: OperatingModeState): string {
 export interface OperatingModeState {
   mode: string;
   journey: string | null;
+  /**
+   * Present, and true, only on a session's stamp written under the session's
+   * NAME (`--session-id` or the harness's variable), never on a guessed one
+   * or the global row (CR008 option B, landed by CV9.DS8.US5). A lifecycle
+   * command binds a journey from a named session's Builder stamp only when
+   * this is set: `build load` with no name still stamps a guessed session,
+   * so another window's load can land on this one's row.
+   */
+  namedSession?: true;
 }
 
 export function activateOperatingMode(
   db: WritableDatabase,
-  input: { mode: string; journey?: string | null; sessionId?: string | null },
+  input: { mode: string; journey?: string | null; sessionId?: string | null; named?: boolean },
   nowIso: string,
 ): OperatingModeState {
   const mode = input.mode.trim();
   if (!mode) throw new Error("mode must not be empty");
   const journey = input.journey?.trim() || null;
-  const state = { mode, journey };
-  const payload = { active_mode: mode, active_journey: journey };
+  const named = Boolean(input.sessionId) && input.named === true;
+  const state: OperatingModeState = named
+    ? { mode, journey, namedSession: true }
+    : { mode, journey };
+  // The key only when true: an unnamed stamp's bytes are what they were
+  // (`operating-mode-metadata.golden.json`).
+  const payload = {
+    active_mode: mode,
+    active_journey: journey,
+    ...(named ? { named_session: true } : {}),
+  };
   if (input.sessionId) {
     const session = getRuntimeSession(db, input.sessionId);
     const metadata = decodeMetadata(session?.metadata ?? null);
@@ -133,7 +151,7 @@ function stateFromPayload(payload: unknown): OperatingModeState | null {
     typeof record.active_journey === "string" && record.active_journey.trim()
       ? record.active_journey.trim()
       : null;
-  return { mode, journey };
+  return record.named_session === true ? { mode, journey, namedSession: true } : { mode, journey };
 }
 
 export function renderModeActivation(state: OperatingModeState): string {

package/ts/src/providers/transport.ts

@@ -321,6 +321,20 @@ export const MIRROR_QUERY_TRANSPORT: ProviderTransportSpec = {
   liveReason: "DS8.US3 mirror load --query live",
 };
 
+/**
+ * The mirror-query spec as the environment narrows it: with
+ * `MEMORY_RECEPTION=0` the classifier never runs, so the chat fixture stops
+ * being required and the embedding fixture alone is a complete replay. The
+ * router decided this way for `load --query` since CV22.DS8.US3; the doorman's
+ * route (CV9.DS8.TS2) resolves its providers from the same answer, so the
+ * route and the resolution cannot disagree about what "complete" means.
+ */
+export function mirrorQueryTransportFor(env: { MEMORY_RECEPTION?: string }): ProviderTransportSpec {
+  return env.MEMORY_RECEPTION === "0"
+    ? { ...MIRROR_QUERY_TRANSPORT, replay: { embedding: MIRROR_QUERY_TRANSPORT.replay?.embedding } }
+    : MIRROR_QUERY_TRANSPORT;
+}
+
 /**
  * `consolidate scan` and `shadow scan` -- the two cultivation leaves that send
  * a PROMPT. Everything around the call landed in CV22.DS8.US3; the flip

package/ts/src/runtime/diagnose.ts

@@ -39,6 +39,7 @@ import { configFilePath } from "./config.ts";
 import { extensionPluginStates } from "./extensionPluginWiring.ts";
 import type { GitWorktreeEntry } from "./git.ts";
 import {
+  agyPluginCopyState,
   codexPluginCacheState,
   grokPluginCopyState,
   installedPluginVersion,
@@ -46,7 +47,11 @@ import {
 } from "./pluginWiring.ts";
 
 import type { RuntimeStatusReport } from "./status.ts";
-import { CODEX_PLUGIN_ADD_COMMAND, grokPluginReinstallCommand } from "./wiring.ts";
+import {
+  agyPluginInstallCommand,
+  CODEX_PLUGIN_ADD_COMMAND,
+  grokPluginReinstallCommand,
+} from "./wiring.ts";
 
 export interface DriftFinding {
   code: string;
@@ -514,18 +519,19 @@ export function diagnoseRuntime(
 
 /**
  * The plugin wiring findings (CV21.DS4.TS6; the debt US1 carried; Grok in
- * CV21.DS10.US1). Codex and Grok copy the plugin, so an npm update leaves
- * the copy behind; Claude Code links it in place, so its failure mode is a
- * dangling link, and Grok's rules link fails the same way. Grok adds one
+ * CV21.DS10.US1; agy in CV21.DS11.TS4). Codex, agy, and Grok copy the plugin,
+ * so an npm update leaves the copy behind; Claude Code links it in place, so
+ * its failure mode is a dangling link, and Grok's rules link fails the same
+ * way. Grok adds one
  * failure of its own: a respelt install path keys a SECOND copy, and Grok
  * loads one of the two without saying which. Absence is not drift: no
  * cache, no registry, and no link fire nothing, so an unwired machine stays
  * green.
  *
  * The defaulting happens HERE, from the env the caller hands in — CODEX_HOME
- * else ~/.codex, GROK_HOME else ~/.grok, and ~/.claude — never inside the
- * readers, so every reader test is hermetic on a maintainer's machine with
- * real wiring (CR123/128/137/142).
+ * else ~/.codex, GROK_HOME else ~/.grok, ~/.claude, and ~/.gemini — never
+ * inside the readers, so every reader test is hermetic on a maintainer's
+ * machine with real wiring (CR123/128/137/142).
  */
 export function pluginWiringFindings(
   installRoot: string | null,
@@ -550,6 +556,25 @@ export function pluginWiringFindings(
     }
   }
 
+  // agy stages a copy under ~/.gemini/config/plugins/mirror-mind/ (agy 1.4.7,
+  // DS11.TS4's route), read the way the extensions plugin's copy is read: the
+  // `.gemini` home from HOME, with no Mirror variable to override it.
+  const geminiHome = home ? join(home, ".gemini") : null;
+  if (geminiHome && installedVersion && installRoot) {
+    const copy = agyPluginCopyState(geminiHome, installedVersion, "mirror-mind");
+    if (copy.state === "behind") {
+      const install = agyPluginInstallCommand(installRoot);
+      findings.push({
+        code: "agy_plugin_copy_behind",
+        severity: "warning",
+        subject: copy.copyPath,
+        detail: `copied ${copy.copiedVersion} < installed ${installedVersion}; agy runs the copy it staged at install`,
+        recommendation: `run \`${install}\` to bring the copy level (an update leaves agy's copy as it was, and installing again replaces it)`,
+        repair_route: install,
+      });
+    }
+  }
+
   if (home) {
     const link = pluginLinkState(join(home, ".claude", "skills", "mirror-mind"));
     if (link.state === "dangling") {

package/ts/src/runtime/pluginWiring.ts

@@ -1,4 +1,5 @@
-// The plugin wiring readers (CV21.DS4.TS6; Grok in CV21.DS10.US1).
+// The plugin wiring readers (CV21.DS4.TS6; Grok in CV21.DS10.US1; agy's
+// reader in CV21.DS5.US2, read for the canonical plugin since CV21.DS11.TS4).
 //
 // Three runtimes hold the plugin outside the install tree. Codex copies it
 // into a versioned cache (`$CODEX_HOME/plugins/cache/mirror-mind/mirror-mind/
@@ -226,9 +227,10 @@ export interface AgyCopyState {
  * Read agy's staged copy of a plugin below a `.gemini` home, read-only:
  * `agy plugin install <dir>` stages the tree under `config/plugins/<name>/`
  * (CV21.DS7.US1), and the copy's own `.claude-plugin/plugin.json` carries
- * its version. Written for the extensions plugin (CV21.DS5.US2); the
- * canonical plugin has no agy finding yet, and this reader serves it when
- * one is added.
+ * its version. Written for the extensions plugin (CV21.DS5.US2); since
+ * CV21.DS11.TS4 it reads the canonical plugin's copy too, which agy 1.4.7
+ * stages the same way (`mirror-mind/.claude-plugin/plugin.json`, measured in
+ * a scratch HOME on 2026-10-24).
  */
 export function agyPluginCopyState(
   geminiHome: string,

package/ts/src/runtime/status.ts

@@ -119,7 +119,8 @@ function errorMessage(error: unknown): string {
  *
  * One rule, `assertSchemaState`'s, so the codebase keeps ONE definition of a
  * healthy ledger: every id in `KNOWN_MIGRATION_IDS` is required, and an id
- * outside it is unknown. A current database renders `current (17/17)`.
+ * outside it is unknown. A current database renders `current (18/18)` (CV9.DS8.US5's
+ * 018 is the eighteenth; the history below is TS5's).
  *
  * Until CV22.DS10.TS5 this grader kept a second rule for one migration.
  * `017_journey_parent_column` is the first one TypeScript authored, and the
@@ -131,7 +132,7 @@ function errorMessage(error: unknown): string {
  * the forgiveness hid a pending migration behind "ready" on exactly the
  * databases `runtime migrate` exists to bring forward. TS5 finding F19 (a
  * removal the comment here promised for plateau 3 and nobody performed) made
- * the denominator honest: seventeen, everywhere.
+ * the denominator honest: every known migration, everywhere.
  */
 export function inspectCoreMigrations(
   dbPath: string | null,

package/ts/src/runtime/update.ts

@@ -30,6 +30,7 @@ import { join } from "node:path";
 import { verifyBackupArchive } from "#runtime/backup.ts";
 import type { InstallKind } from "#runtime/installKind.ts";
 import {
+  agyPluginCopyState,
   codexPluginCacheState,
   grokPluginCopyState,
   installedPluginVersion,
@@ -43,7 +44,11 @@ import {
   type UpdateResult,
   type UpdateStage,
 } from "#runtime/updatePipeline.ts";
-import { CODEX_PLUGIN_ADD_COMMAND, grokPluginReinstallCommand } from "#runtime/wiring.ts";
+import {
+  agyPluginInstallCommand,
+  CODEX_PLUGIN_ADD_COMMAND,
+  grokPluginReinstallCommand,
+} from "#runtime/wiring.ts";
 import { commandOnPath } from "#util/paths.ts";
 import { PROGRAM } from "#util/program.ts";
 import { shellWord } from "#util/shellWord.ts";
@@ -456,6 +461,17 @@ export function postUpdateHints(
       );
     }
   }
+  // CV21.DS11.TS4: agy stages a copy too, and an update leaves it as it was;
+  // installing again from the path init printed brings it level.
+  const geminiHome = home ? join(home, ".gemini") : null;
+  if (installRoot && geminiHome && landed) {
+    const copy = agyPluginCopyState(geminiHome, landed, "mirror-mind");
+    if (copy.state === "behind") {
+      hints.push(
+        `Antigravity's copy of the plugin is behind the update (${copy.copiedVersion} < ${landed}): run \`${agyPluginInstallCommand(installRoot)}\` to bring it level.`,
+      );
+    }
+  }
 
   return hints;
 }

package/ts/src/runtime/wiring.ts

@@ -83,6 +83,19 @@ function grokPluginInstallCommand(root: string): string {
   return `grok plugin install "${pluginDirectory(root)}" --trust`;
 }
 
+/**
+ * The one agy install command (CV21.DS7.US1), which is also its level-up
+ * (CV21.DS11.TS4). agy stages a copy of the plugin under
+ * `~/.gemini/config/plugins/mirror-mind/` (agy 1.4.7), an update leaves that
+ * copy as it was, and installing again replaces it (by name, from any path). A
+ * function of the root, so the line `init` prints, the recommendation
+ * `diagnose` prints, and the hint `update` prints cannot disagree (the CR071
+ * lesson at the string level).
+ */
+export function agyPluginInstallCommand(root: string): string {
+  return `agy plugin install "${pluginDirectory(root)}"`;
+}
+
 export interface RuntimeWiring {
   /** The runtime, as a person names it. */
   readonly title: string;
@@ -121,7 +134,7 @@ export const RUNTIME_WIRING: Readonly<Record<RuntimeName, RuntimeWiring>> = {
       // the Claude surfaces and overwrites the layer's hooks file). Per-turn
       // injection and logging land with DS7's TS2/TS3; this line promises
       // the install, nothing more.
-      (root) => [`agy plugin install "${root}/plugins/mirror-mind"`],
+      (root) => [agyPluginInstallCommand(root)],
     ],
   },
   grok: {

package/ts/src/search/memorySearch.ts

@@ -54,9 +54,22 @@ export interface FreshSearchOptions extends FreshSearchFilters {
    * tool: search never learns it exists.
    */
   recordEmbeddingLedger?: boolean | ((info: EmbeddingAttemptInfo) => void);
+  /**
+   * The query's embedding, already generated (CV9.DS8.TS2). The doorman embeds
+   * a turn's prompt once and hands the vector to this search and to the
+   * attachment search, so a Mirror Mode turn costs one embedding call, counted
+   * once (DS8 decision 1). When given, no provider is called and nothing is
+   * recorded here: the caller that embedded owns the ledger row.
+   */
+  queryEmbedding?: readonly number[];
   frozenNowMs?: number;
   now?: string;
-  provider: EmbeddingProvider;
+  /**
+   * Absent only with `queryEmbedding` given, or on a turn with no provider at
+   * all (the doorman without a key, CV9.DS8.TS2): the search then degrades to
+   * FTS as it does when the provider fails, with `no_provider` as the kind.
+   */
+  provider?: EmbeddingProvider;
   /** Test-injectable override for generateEmbeddingSafely's retry backoff
    * (real timers by default) -- avoids paying real backoff wait time in tests
    * that exercise the transient-retry path. */
@@ -111,26 +124,33 @@ export async function searchMemoriesWithStatus(
   options: FreshSearchOptions,
 ): Promise<FreshSearchOutcome> {
   const limit = options.limit ?? 5;
-  let queryEmbedding: readonly number[] = [];
+  let queryEmbedding: readonly number[] = options.queryEmbedding ?? [];
   let degraded = false;
   let degradedKind: string | undefined;
-  try {
-    // generateEmbeddingSafely (CR043) retries a transient empty response up to
-    // its default budget before giving up -- matching Python's search, which
-    // calls the same generate_embedding used everywhere else, not a bespoke
-    // single-shot attempt. Any exhausted/permanent/provider-exception failure
-    // still maps to degraded=true here, preserving CR037's contract exactly.
-    queryEmbedding = await generateEmbeddingSafely(options.provider, options.query, {
-      onAttempt: resolveLedgerSink(db, options.recordEmbeddingLedger),
-      sleep: options.embeddingRetrySleep,
-    });
-  } catch (error) {
+  if (options.queryEmbedding !== undefined) {
+    // The caller embedded: nothing to generate, nothing to record.
+  } else if (!options.provider) {
     degraded = true;
-    // Keep the CLASS of failure (AI-18 taxonomy) so an operator can tell an
-    // expired key from a timeout from a rate limit. Without this the front
-    // door only ever says "offline or no API key", which is a guess -- and
-    // the taxonomy the live transport builds would die here unseen.
-    degradedKind = classifyDegradedCause(error);
+    degradedKind = "no_provider";
+  } else {
+    try {
+      // generateEmbeddingSafely (CR043) retries a transient empty response up to
+      // its default budget before giving up -- matching Python's search, which
+      // calls the same generate_embedding used everywhere else, not a bespoke
+      // single-shot attempt. Any exhausted/permanent/provider-exception failure
+      // still maps to degraded=true here, preserving CR037's contract exactly.
+      queryEmbedding = await generateEmbeddingSafely(options.provider, options.query, {
+        onAttempt: resolveLedgerSink(db, options.recordEmbeddingLedger),
+        sleep: options.embeddingRetrySleep,
+      });
+    } catch (error) {
+      degraded = true;
+      // Keep the CLASS of failure (AI-18 taxonomy) so an operator can tell an
+      // expired key from a timeout from a rate limit. Without this the front
+      // door only ever says "offline or no API key", which is a guess -- and
+      // the taxonomy the live transport builds would die here unseen.
+      degradedKind = classifyDegradedCause(error);
+    }
   }
 
   const memories = listSearchMemoryRows(db, options);

package/ts/src/search/ranker.ts

@@ -33,12 +33,22 @@ export interface RankableMemory {
 
 export interface RankedMemory {
   id: string;
+  /** The hybrid score the order is by. */
   score: number;
+  /**
+   * The semantic component alone: the cosine of the query and the memory, 0 on
+   * a degraded search. Reported, not ranked by (CV9.DS8.US5): the doorman's
+   * memory threshold reads it, because half of `score` is recency,
+   * reinforcement, relevance, and lexical, and a fresh, reinforced memory
+   * floors near 0.35 with no semantic match at all.
+   */
+  semantic: number;
 }
 
 interface Candidate {
   id: string;
   score: number;
+  semantic: number;
   embedding: Float32Array;
 }
 
@@ -131,7 +141,7 @@ export function rankMemories(
       lexical: memory.lexical_score ?? 0,
       weights: config.weights,
     });
-    return { id: memory.id, score, embedding };
+    return { id: memory.id, score, semantic, embedding };
   });
 
   candidates.sort((a, b) => b.score - a.score);
@@ -150,5 +160,9 @@ export function rankMemories(
     if (selected.length >= config.limit) break;
   }
 
-  return selected.map((candidate) => ({ id: candidate.id, score: candidate.score }));
+  return selected.map((candidate) => ({
+    id: candidate.id,
+    score: candidate.score,
+    semantic: candidate.semantic,
+  }));
 }