mirror-mind 0.36.3 → 0.37.0

package/ts/src/mirror/runtimeSession.ts

@@ -10,7 +10,6 @@ export interface RuntimeSessionRow {
   mirrorActive: boolean;
   persona: string | null;
   journey: string | null;
-  hookInjected: boolean;
   active: boolean;
   startedAt: string;
   updatedAt: string;
@@ -24,7 +23,6 @@ export interface RuntimeSessionPatch {
   mirrorActive?: boolean;
   persona?: string | null;
   journey?: string | null;
-  hookInjected?: boolean;
   active?: boolean;
   closedAt?: string | null;
   metadata?: string | null;
@@ -40,7 +38,6 @@ export function getRuntimeSession(db: Database, sessionId: string): RuntimeSessi
     mirrorActive: Boolean(row.mirror_active),
     persona: nullableString(row.persona),
     journey: nullableString(row.journey),
-    hookInjected: Boolean(row.hook_injected),
     active: Boolean(row.active),
     startedAt: String(row.started_at),
     updatedAt: String(row.updated_at),
@@ -67,7 +64,6 @@ export function upsertRuntimeSession(
     mirrorActive: value("mirrorActive", existing?.mirrorActive ?? false) as boolean,
     persona: value("persona", existing?.persona ?? null) as string | null,
     journey: value("journey", existing?.journey ?? null) as string | null,
-    hookInjected: value("hookInjected", existing?.hookInjected ?? false) as boolean,
     active: value("active", existing?.active ?? true) as boolean,
     startedAt: existing?.startedAt ?? nowIso,
     updatedAt: nowIso,
@@ -77,15 +73,14 @@ export function upsertRuntimeSession(
   db.prepare(
     `INSERT INTO runtime_sessions
        (session_id, conversation_id, interface, mirror_active, persona, journey,
-        hook_injected, active, started_at, updated_at, closed_at, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        active, started_at, updated_at, closed_at, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(session_id) DO UPDATE SET
        conversation_id = excluded.conversation_id,
        interface = excluded.interface,
        mirror_active = excluded.mirror_active,
        persona = excluded.persona,
        journey = excluded.journey,
-       hook_injected = excluded.hook_injected,
        active = excluded.active,
        updated_at = excluded.updated_at,
        closed_at = excluded.closed_at,
@@ -97,7 +92,6 @@ export function upsertRuntimeSession(
     Number(row.mirrorActive),
     row.persona,
     row.journey,
-    Number(row.hookInjected),
     Number(row.active),
     row.startedAt,
     row.updatedAt,
@@ -136,6 +130,70 @@ export function compareAndSwapRuntimeSessionMetadata(
   return Number(result.changes) === 1;
 }
 
+/**
+ * Columns the doorman moves one at a time (CV9.DS8.TS2).
+ *
+ * `upsertRuntimeSession` reads the row, rebuilds it, and writes every column
+ * back, with no transaction around the read and the write. Two writers on the
+ * same turn -- the prompt logger setting `conversation_id`/`active`, the doorman
+ * setting `persona` -- would each overwrite the other's column with the stale
+ * copy it read. A single-column UPDATE touches nothing it was not asked to.
+ */
+export interface RuntimeSessionColumnPatch {
+  persona?: string | null;
+  /** The whole metadata JSON, as the caller re-dumped it after its own read. */
+  metadata?: string | null;
+}
+
+/** Set only the named columns on an existing row; false when there is no row. */
+export function updateRuntimeSessionColumns(
+  db: WritableDatabase,
+  sessionId: string,
+  patch: RuntimeSessionColumnPatch,
+  nowIso: string,
+): boolean {
+  const assignments: string[] = [];
+  const params: (string | number | null)[] = [];
+  if (patch.persona !== undefined) {
+    assignments.push("persona = ?");
+    params.push(patch.persona);
+  }
+  if (patch.metadata !== undefined) {
+    assignments.push("metadata = ?");
+    params.push(patch.metadata);
+  }
+  if (assignments.length === 0) return false;
+  assignments.push("updated_at = ?");
+  params.push(nowIso, sessionId);
+  const result = db
+    .prepare(`UPDATE runtime_sessions SET ${assignments.join(", ")} WHERE session_id = ?`)
+    .run(...params);
+  return Number(result.changes) === 1;
+}
+
+/**
+ * The session the harness named in the environment (CV9.DS8.TS1, measured
+ * 2026-10-24): `MIRROR_SESSION_ID`, which the Pi extension sets at
+ * `session_start`; else `CLAUDE_CODE_SESSION_ID` (Claude Code 2.1.310) or
+ * `CODEX_SESSION_ID` (Codex 0.164.0), both undocumented, both equal to the
+ * session row the runtime's hooks write, both present in the model's own shell
+ * -- so a `mirror mirror load` the model runs by itself names the same session
+ * the hooks do. One reader, as `runtimeDetection` reads Grok's variables.
+ *
+ * Read by the mirror load route and the doorman only (TS2): widening it to the
+ * Builder, Soul, and Explorer routes would bind those sessions on Claude Code
+ * and Codex too, a CR008 question a later story may open.
+ */
+export function environmentSessionId(
+  env: Readonly<Record<string, string | undefined>>,
+): string | null {
+  for (const name of ["MIRROR_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_SESSION_ID"]) {
+    const value = env[name]?.trim();
+    if (value) return value;
+  }
+  return null;
+}
+
 /**
  * The session a caller was TOLD about: `--session-id`, else `MIRROR_SESSION_ID`.
  * `null` means nobody named one. It never guesses, so it is the only resolver a

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