mirror-mind 0.36.3 → 0.38.0

package/ts/src/mirror/doorman.ts

@@ -0,0 +1,420 @@
+// The one doorman (CV9.DS8.TS2).
+//
+// Mirror Mode is the product: the folder `mirror mirror load` builds from the
+// database, open before the model answers. What is at stake is always whether
+// the folder reaches the model, and when. Until DS8 there were three doormen
+// with three policies (the Claude-family inject hook, Antigravity's
+// PreInvocation, and none on Pi), and wherever one existed the skill's own
+// hard constraint made an explicit turn load twice (CR165, measured on Pi
+// 1.4.0, 2026-10-24).
+//
+// This module is the one decision. Given a turn's prompt and the session's
+// state it answers NOTHING, THE FULL FOLDER, or A DELTA:
+//
+//   1. the explicit Mirror form in the prompt -> the full folder, routed from
+//      the query, before the first token; the session marked active by its id;
+//   2. Mirror Mode active, an ordinary turn -> the prompt is routed with
+//      `detectPersona` (a keyword score, no model call); a persona that newly
+//      scores has its section delivered and becomes the session's; the
+//      memories and attachments relevant to the prompt follow; the identity
+//      layers are not repeated -- they already sit in the transcript;
+//      a skill invocation other than the Mirror form is not a question and
+//      gets nothing (CR160's command-turn rule);
+//   3. Mirror Mode not active -> nothing. The model's own routing may invoke
+//      the skill; the session learns that load from the harness (TS1), and the
+//      doorman takes over from the next turn.
+//
+// `decideDoorman` is pure: no database, no clock, no provider. `runDoorman`
+// renders and writes, at the edge. The hooks (US4, TS6) call both in-process;
+// the Pi extension (US5) reaches them through `mirror doorman`. Neither is
+// rewired here.
+//
+// Every block the doorman delivers opens with one line the model reads
+// (`deliveredLine`), on every active turn, even with nothing under it: it is
+// what carries the persona across the conversation. On an ordinary turn the
+// skill is never invoked, so this line is the only Mirror text that reaches
+// the model -- the signature rule (`AGENTS.md`: `◇ persona-name`) rides in it.
+//
+// What a turn costs: nothing when Mirror Mode is off; on an ordinary active
+// turn, ONE embedding, shared by the memory and attachment searches and
+// counted once in `llm_calls` (DS8 decision 1); on the explicit turn, what
+// `mirror load --query` costs today (reception's LLM call when enabled, the
+// attachment embedding), plus the skill's own load until TS3 teaches it to
+// trust this line.
+
+import { isCommandTurn } from "#conversation/commandTurn.ts";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { memoriesById } from "#frontDoor/searchRoute.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { getActiveOperatingMode } from "#mode/operatingMode.ts";
+import { embeddingLedgerHook } from "#observability/ledgerHooks.ts";
+import { detectPersona, type PersonaRoutingRow } from "#persona/detectPersona.ts";
+import { type EmbeddingProvider, generateEmbeddingSafely } from "#providers/embedding.ts";
+import { searchMemoriesWithStatus } from "#search/memorySearch.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+import { relevantAttachments } from "./context.ts";
+import { personaRoutingRows } from "./defaultResolution.ts";
+import { mirrorForm } from "./mirrorForm.ts";
+import { type MirrorLoadInput, runMirrorLoad } from "./orchestration.ts";
+import {
+  decodeMetadata,
+  getRuntimeSession,
+  updateRuntimeSessionColumns,
+} from "./runtimeSession.ts";
+
+/** The session's Mirror fields as the decision reads them; null when unnamed or unknown. */
+export interface DoormanSessionState {
+  readonly active: boolean;
+  readonly persona: string | null;
+  readonly journey: string | null;
+  /**
+   * The folder left the transcript (the runtime compacted it, and said so
+   * through `forgetDoormanDelivery`): the next ordinary turn is full again.
+   */
+  readonly refresh?: boolean;
+}
+
+export type DoormanDecision =
+  | { readonly kind: "nothing" }
+  | { readonly kind: "full"; readonly query: string }
+  | {
+      readonly kind: "delta";
+      readonly query: string;
+      /** The persona that newly scored, or null when the session's stands. */
+      readonly persona: string | null;
+    };
+
+/** The stable prefix TS3's skill reads; everything after the colon varies. */
+export const DELIVERED_LINE_PREFIX = "=== mirror context delivered by the runtime for this turn";
+
+/** How many memories a delta carries at most. */
+export const DOORMAN_MEMORY_LIMIT = 5;
+
+/**
+ * The threshold DS8's policy names ("injected when any score above the
+ * threshold"), on the SEMANTIC score the ranker reports -- the cosine of the
+ * prompt and the memory -- not the hybrid one (CV9.DS8.US5). The hybrid is
+ * half recency, reinforcement, relevance, and lexical: a fresh, reinforced,
+ * relevance-1 memory floors at 0.35 with no semantic match and would pass a
+ * composite 0.40 at cosine 0.10, which unrelated texts reach routinely; the 27
+ * composite rows TS2 and US4 logged (off-topic deltas topping at 0.331-0.377,
+ * 3 of 5 memories repeating; on-topic at 0.444-0.448 and 0.587-0.591) show the
+ * gap in one home, not a property. 0.4 is the rule `relevantAttachments`
+ * already applies to attachments: one rule for both. Inclusive. A degraded
+ * search (no embedding) reports no semantic score and keeps TS2's FTS
+ * behavior: a lexical hit is relevance by another signal, not a miss.
+ */
+export const DOORMAN_MEMORY_SEMANTIC_THRESHOLD = 0.4;
+
+/**
+ * Where the session remembers the memories the doorman has delivered
+ * (`runtime_sessions.metadata`, beside `operating_mode`). Every delta is a
+ * message that stays in the transcript, and US4 measured 3 of 5 memories
+ * repeating on a follow-up: a delta skips what the conversation already holds
+ * and fills from the next ones above the threshold. A full load starts the
+ * list over -- the folder is fresh, and so is what the model has read.
+ */
+export const DOORMAN_DELIVERED_METADATA_KEY = "doorman_delivered";
+
+/**
+ * Set on the session when the runtime compacted the transcript (the Pi
+ * extension's `session_compact`, CV9.DS8.US5): a delta's premise -- the
+ * identity layers already sit in the transcript -- no longer holds, so the
+ * next ordinary turn in Mirror Mode delivers the full folder, routed from that
+ * prompt, and the full load clears the flag.
+ */
+export const DOORMAN_REFRESH_METADATA_KEY = "doorman_refresh";
+
+/**
+ * The runtime says the folder left the transcript: the next ordinary turn is
+ * full, and the delivered list is forgotten with it. Unknown session: no-op.
+ */
+export function forgetDoormanDelivery(
+  db: WritableDatabase,
+  sessionId: string,
+  nowIso: string,
+): void {
+  const session = getRuntimeSession(db, sessionId);
+  if (!session) return;
+  const metadata = decodeMetadata(session.metadata);
+  metadata[DOORMAN_REFRESH_METADATA_KEY] = true;
+  metadata[DOORMAN_DELIVERED_METADATA_KEY] = [];
+  updateRuntimeSessionColumns(db, sessionId, { metadata: pythonJsonDumps(metadata) }, nowIso);
+}
+
+/** How many ranked memories a delta may read through to fill its five. */
+const DOORMAN_SEARCH_CEILING = 25;
+
+function deliveredMemoryIds(db: Database, sessionId: string | null): Set<string> {
+  if (!sessionId) return new Set();
+  const raw = decodeMetadata(getRuntimeSession(db, sessionId)?.metadata ?? null)[
+    DOORMAN_DELIVERED_METADATA_KEY
+  ];
+  return new Set(
+    Array.isArray(raw) ? raw.filter((id): id is string => typeof id === "string") : [],
+  );
+}
+
+function rememberDelivered(
+  db: WritableDatabase,
+  sessionId: string | null,
+  ids: readonly string[],
+  nowIso: string,
+  options: { clearRefresh?: boolean } = {},
+): void {
+  if (!sessionId) return;
+  const session = getRuntimeSession(db, sessionId);
+  if (!session) return;
+  const metadata = decodeMetadata(session.metadata);
+  metadata[DOORMAN_DELIVERED_METADATA_KEY] = [...ids];
+  if (options.clearRefresh) delete metadata[DOORMAN_REFRESH_METADATA_KEY];
+  updateRuntimeSessionColumns(db, sessionId, { metadata: pythonJsonDumps(metadata) }, nowIso);
+}
+
+/** One ranked memory's scores, content-free, for the front-door log. */
+export interface MemoryScore {
+  readonly score: number;
+  readonly semantic: number;
+}
+
+/**
+ * The session's state as the decision reads it. "Mirror Mode on" is
+ * `mirror_active` -- which only `mirror deactivate` clears -- AND the active
+ * operating mode (the session's own row, else the global one) still being
+ * Mirror Mode (CV9.DS8.US4). `build load`, `explore`, and `soul load` switch the
+ * mode and leave the column set; read alone, it would put "answer as the
+ * mirror" on every Builder turn of a session that was once in Mirror Mode. A
+ * home with no mode record at all leaves the column to decide.
+ */
+export function readDoormanSessionState(
+  db: Database,
+  sessionId: string | null,
+): DoormanSessionState | null {
+  if (!sessionId) return null;
+  const session = getRuntimeSession(db, sessionId);
+  if (!session) return null;
+  const mode = getActiveOperatingMode(db, sessionId);
+  const inMirrorMode = mode === null || mode.mode === "Mirror Mode";
+  return {
+    active: session.mirrorActive && inMirrorMode,
+    persona: session.persona,
+    journey: session.journey,
+    refresh: decodeMetadata(session.metadata)[DOORMAN_REFRESH_METADATA_KEY] === true,
+  };
+}
+
+export function decideDoorman(input: {
+  prompt: string;
+  state: DoormanSessionState | null;
+  personas: readonly PersonaRoutingRow[];
+}): DoormanDecision {
+  const explicit = mirrorForm(input.prompt);
+  if (explicit) return { kind: "full", query: explicit.query };
+  if (!input.state?.active) return { kind: "nothing" };
+  // A skill invocation is not a question to the mirror (CR160's rule for the
+  // logger, held here since CV9.DS8.US5's walk): `/mm-build`, `/mm-journeys`,
+  // `/mm-explore` paid an embedding and got a delta, and one Builder card was
+  // signed. The Mirror form, the one skill whose argument IS the question,
+  // was answered above.
+  if (isCommandTurn(input.prompt)) return { kind: "nothing" };
+  // The runtime compacted the transcript: the folder is a summary now, so this
+  // turn delivers it whole, routed from the prompt, and the deltas resume after.
+  if (input.state.refresh) return { kind: "full", query: input.prompt };
+  const match = detectPersona(input.prompt, input.personas)[0]?.key ?? null;
+  const persona = match !== null && match !== input.state.persona ? match : null;
+  return { kind: "delta", query: input.prompt, persona };
+}
+
+export function deliveredLine(input: {
+  kind: "full" | "delta";
+  persona: string | null;
+  journey: string | null;
+}): string {
+  const clause = input.persona
+    ? `answer as the mirror; sign ◇ ${input.persona}`
+    : "answer as the mirror";
+  const what =
+    input.kind === "full"
+      ? "full"
+      : `delta (persona: ${input.persona ?? "none"} · journey: ${input.journey ?? "none"})`;
+  return `${DELIVERED_LINE_PREFIX}: ${what} — ${clause} ===`;
+}
+
+export interface RunDoormanInput
+  extends Omit<MirrorLoadInput, "query" | "contextOnly" | "sessionId" | "environmentSessionId"> {
+  /** The named session, or null: an unnamed explicit turn loads without marking one. */
+  sessionId: string | null;
+  embeddingProvider?: EmbeddingProvider;
+  /**
+   * Where a delta turn's memory scores go -- every ranked memory's, the ones
+   * under the threshold included -- so the threshold is read against
+   * measurement (US5's live walk), not invented. Content-free: numbers only.
+   */
+  onMemoryScores?: (scores: readonly MemoryScore[]) => void;
+}
+
+export interface RenderedDoorman {
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Render and write for a decision already taken. The caller opened `db` for
+ * writing only because the decision is `full` or `delta`: a `nothing` turn must
+ * never reach a writable handle (the live-write path snapshots the database
+ * first, 95 ms measured), which is why decide and run are two steps.
+ */
+export async function runDoorman(
+  db: WritableDatabase,
+  decision: DoormanDecision,
+  input: RunDoormanInput,
+): Promise<RenderedDoorman> {
+  if (decision.kind === "nothing") return { stdout: "", stderr: "" };
+  if (decision.kind === "full") return runFull(db, decision.query, input);
+  return runDelta(db, decision, input);
+}
+
+async function runFull(
+  db: WritableDatabase,
+  query: string,
+  input: RunDoormanInput,
+): Promise<RenderedDoorman> {
+  const loaded = await runMirrorLoad(db, {
+    ...input,
+    query: query || null,
+    contextOnly: true,
+    sessionId: input.sessionId,
+  });
+  if (input.sessionId) {
+    // The conversation's context starts over with the folder: so does the
+    // list of memories the deltas have put in it, and a compaction's refresh
+    // is answered.
+    rememberDelivered(db, input.sessionId, [], input.nowIso(), { clearRefresh: true });
+  }
+  const line = deliveredLine({
+    kind: "full",
+    persona: loaded.resolved.persona,
+    journey: loaded.resolved.journey,
+  });
+  return { stdout: `${line}\n${loaded.stdout}`, stderr: loaded.stderr };
+}
+
+async function runDelta(
+  db: WritableDatabase,
+  decision: Extract<DoormanDecision, { kind: "delta" }>,
+  input: RunDoormanInput,
+): Promise<RenderedDoorman> {
+  const state = readDoormanSessionState(db, input.sessionId);
+  const persona = decision.persona ?? state?.persona ?? null;
+  const journey = state?.journey ?? null;
+  const parts: string[] = [deliveredLine({ kind: "delta", persona, journey })];
+
+  if (decision.persona) {
+    const content = getIdentityContent(db, "persona", decision.persona);
+    if (content) parts.push(`=== persona/${decision.persona} ===\n${content}`);
+    if (input.sessionId) {
+      updateRuntimeSessionColumns(
+        db,
+        input.sessionId,
+        { persona: decision.persona },
+        input.nowIso(),
+      );
+    }
+  }
+
+  // One embedding for the turn, in the ledger once; both searches share it.
+  // Without a provider, or when it fails, the memory search degrades to FTS
+  // and the attachments are skipped: the delta still carries the line and the
+  // persona.
+  const queryEmbedding = await embedOnce(db, decision.query, input);
+
+  const delivered = deliveredMemoryIds(db, input.sessionId);
+  const memories = await searchMemoriesWithStatus(db, {
+    query: decision.query,
+    // Read past what the transcript already holds, so a delta still fills.
+    limit: Math.min(DOORMAN_MEMORY_LIMIT + delivered.size, DOORMAN_SEARCH_CEILING),
+    provider: input.embeddingProvider,
+    ...(queryEmbedding ? { queryEmbedding } : {}),
+    // The doorman searches on the system's behalf N times a session: a turn's
+    // injection must not raise a memory's reinforcement for the next turn
+    // (AI-12). Reinforcement stays with the explicit load.
+    logAccess: false,
+    recordEmbeddingLedger: false,
+    now: input.nowIso(),
+  });
+  input.onMemoryScores?.(
+    memories.results.map((result) => ({ score: result.score, semantic: result.semantic })),
+  );
+  const relevant = (
+    memories.degraded
+      ? memories.results
+      : memories.results.filter((result) => result.semantic >= DOORMAN_MEMORY_SEMANTIC_THRESHOLD)
+  )
+    .filter((result) => !delivered.has(result.id))
+    .slice(0, DOORMAN_MEMORY_LIMIT);
+  if (relevant.length > 0) {
+    rememberDelivered(
+      db,
+      input.sessionId,
+      [...delivered, ...relevant.map((result) => result.id)],
+      input.nowIso(),
+    );
+    const rows = memoriesById(
+      db,
+      relevant.map((result) => result.id),
+    );
+    const block = ["=== relevant memories ==="];
+    for (const result of relevant) {
+      const memory = rows.get(result.id);
+      if (!memory) continue;
+      block.push(`\n[${memory.layer}] ${memory.title}\n${memory.content}`);
+    }
+    parts.push(block.join("\n"));
+  }
+
+  if (queryEmbedding) {
+    const attachments = await relevantAttachments(
+      db,
+      decision.query,
+      journey,
+      undefined,
+      undefined,
+      queryEmbedding,
+    );
+    if (attachments.length > 0) {
+      const block = ["=== relevant attachments ==="];
+      for (const { row, score } of attachments) {
+        const source = journey ? "" : ` [${row.journeyId}]`;
+        block.push(`--- ${row.name}${source} (score: ${score.toFixed(3)}) ---`);
+        if (row.description) block.push(`Description: ${row.description}`);
+        block.push(row.content);
+      }
+      parts.push(block.join("\n"));
+    }
+  }
+
+  return { stdout: `${parts.join("\n\n")}\n`, stderr: "" };
+}
+
+async function embedOnce(
+  db: WritableDatabase,
+  query: string,
+  input: RunDoormanInput,
+): Promise<readonly number[] | null> {
+  if (!input.embeddingProvider) return null;
+  try {
+    return await generateEmbeddingSafely(input.embeddingProvider, query, {
+      onAttempt: embeddingLedgerHook(db, {
+        sessionId: input.sessionId,
+        now: input.nowIso,
+      }),
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** The persona routing table the decision scores against; read once per turn. */
+export function doormanPersonas(db: Database): PersonaRoutingRow[] {
+  return personaRoutingRows(db);
+}

package/ts/src/mirror/orchestration.ts

@@ -23,6 +23,7 @@ import {
   decodeMetadata,
   GLOBAL_STICKY_DEFAULTS_SESSION_ID,
   getRuntimeSession,
+  resolveNamedRuntimeSessionId,
   resolveRuntimeSessionId,
   upsertRuntimeSession,
 } from "./runtimeSession.ts";
@@ -120,13 +121,33 @@ export async function runMirrorLoad(
   });
   persistStickyDefaults(db, resolved.persona, resolved.journey, input.nowIso());
   activateOperatingMode(db, { mode: "Mirror Mode", journey: resolved.journey }, input.nowIso());
+  // The NAMED session -- explicit, else the one the harness put in the
+  // environment -- never a guess (CV9.DS8.TS2, closing TS1's measured gap:
+  // the skill's own load passed the environment id into the route and this
+  // write ignored it, so a self-started Mirror Mode left `mirror_active`
+  // unwritten and the doorman had nothing to learn from).
+  const namedSessionId = resolveNamedRuntimeSessionId(
+    input.sessionId ?? null,
+    input.environmentSessionId ?? null,
+  );
+  if (namedSessionId) {
+    // The session's own mode row as well as the global one (CV9.DS8.US4): the
+    // doorman reads the session's row first, and `build load` stamps that same
+    // row Builder -- without this write a Mirror re-entry in the same session
+    // would read as Builder and the deltas would never resume.
+    activateOperatingMode(
+      db,
+      { mode: "Mirror Mode", journey: resolved.journey, sessionId: namedSessionId },
+      input.nowIso(),
+    );
+  }
   writeMirrorState(
     db,
     {
       active: true,
       persona: resolved.persona,
       journey: resolved.journey,
-      sessionId: input.sessionId ?? null,
+      sessionId: namedSessionId,
     },
     input.nowIso(),
   );
@@ -246,7 +267,6 @@ export function persistStickyDefaults(
       mirrorActive: false,
       ...(persona !== null ? { persona } : {}),
       ...(journey !== null ? { journey } : {}),
-      hookInjected: true,
       active: false,
     },
     nowIso,
@@ -271,7 +291,6 @@ function writeMirrorState(
       mirrorActive: input.active,
       ...(input.persona !== undefined && input.persona !== null ? { persona: input.persona } : {}),
       ...(input.journey !== undefined && input.journey !== null ? { journey: input.journey } : {}),
-      hookInjected: !input.active,
     },
     nowIso,
   );

package/ts/src/mirror/render.ts

@@ -16,10 +16,16 @@ export function renderMirrorModeTransition(input: {
   return box("◌  MIRROR MODE ACTIVE", rows);
 }
 
+/**
+ * The stderr banner `mirror mirror load` prints. An active persona is signed
+ * `◇ <persona>`, the one rule `AGENTS.md` states (DS8 decision 2) -- on Pi the
+ * model reads stderr inside the tool result, so the banner is also an example
+ * of the signature it is asked to write.
+ */
 export function renderMirrorBanner(persona: string | null): string {
   const first = "\u001b[38;5;183m⏺ Mirror Mode active\u001b[0m\n";
   return persona
-    ? `${first}\u001b[38;5;183m  ✦ Persona: ${persona}\u001b[0m\n`
+    ? `${first}\u001b[38;5;183m  ◇ ${persona}\u001b[0m\n`
     : `${first}\u001b[38;5;183m  Ego responding without persona\u001b[0m\n`;
 }
 

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 {