mirror-mind 0.38.1 → 0.39.0

package/bin/loader.js

@@ -24,34 +24,52 @@
 // stands on; `scripts/smoke_npm_package.sh` runs both bins from a real global
 // install on CI's Node 24.
 //
-// The warning filter below is the shim's own copy, because the hook emits its
+// The warning filter is the shim's own copy, because the hook emits its
 // ExperimentalWarning before the core's filter can be imported through it.
+// `boot` installs it; `registerTypeStripping` alone does not (CV24.DS1).
 
 import { readFileSync } from "node:fs";
 import { registerHooks, stripTypeScriptTypes } from "node:module";
 import { fileURLToPath } from "node:url";
 
-process.removeAllListeners("warning");
-process.on("warning", (warning) => {
-  if (warning.name === "ExperimentalWarning") return;
-  process.stderr.write(`${warning.name}: ${warning.message}\n`);
-});
-
 const packageRoot = new URL("../", import.meta.url).href;
+const REGISTERED = Symbol.for("mirror-mind.typeStripping");
 
-registerHooks({
-  load(url, context, nextLoad) {
-    if (url.startsWith(packageRoot) && url.endsWith(".ts")) {
-      const source = readFileSync(fileURLToPath(url), "utf8");
-      return {
-        format: "module",
-        source: stripTypeScriptTypes(source, { mode: "strip" }),
-        shortCircuit: true,
-      };
-    }
-    return nextLoad(url, context);
-  },
-});
+/**
+ * Register the load hook that strips types for `.ts` files under this package
+ * root. Idempotent per package root, so the bins and the library entry
+ * (`lib/desktop.js`, CV24.DS1) can both call it in one process.
+ *
+ * It does nothing to the process's warnings: a library entry runs inside a
+ * host that owns them. Only `boot`, which owns its process, filters them.
+ */
+export function registerTypeStripping() {
+  if (!globalThis[REGISTERED]) globalThis[REGISTERED] = new Set();
+  const roots = globalThis[REGISTERED];
+  if (roots.has(packageRoot)) return;
+  roots.add(packageRoot);
+  registerHooks({
+    load(url, context, nextLoad) {
+      if (url.startsWith(packageRoot) && url.endsWith(".ts")) {
+        const source = readFileSync(fileURLToPath(url), "utf8");
+        return {
+          format: "module",
+          source: stripTypeScriptTypes(source, { mode: "strip" }),
+          shortCircuit: true,
+        };
+      }
+      return nextLoad(url, context);
+    },
+  });
+}
+
+function filterExperimentalWarnings() {
+  process.removeAllListeners("warning");
+  process.on("warning", (warning) => {
+    if (warning.name === "ExperimentalWarning") return;
+    process.stderr.write(`${warning.name}: ${warning.message}\n`);
+  });
+}
 
 /**
  * Import the entry at `entryPath` (relative to the package root) and run its
@@ -62,6 +80,9 @@ registerHooks({
  * @returns {Promise<number>}
  */
 export async function boot(entryPath) {
+  // The filter first: registering the hook emits its own ExperimentalWarning.
+  filterExperimentalWarnings();
+  registerTypeStripping();
   const { runAsEntry } = await import(new URL(entryPath, packageRoot).href);
   return runAsEntry();
 }

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.39.0 — The Core as a Library](v0.39.0.md) — minor release of CV24's first eight Delivery Stories: `mirror-mind/desktop`, a library entry through which a host such as Mirror Desktop 0.3 embeds this core; calls for a home's migration state, Conversations, sidebar reads, home creation, migration on request, Mirror's context, learning from open Conversations, and Journey administration, each with an explicit path and no environment. The new `exports` field closes every other deep import. No migration.
 - [v0.38.1 — The Refusal Names the Way Out](v0.38.1.md) — patch release of three Change Requests, CR185, CR186, and CR187: a package with no home configured names the homes it finds and the `mirror init <name>` that selects one, and `init` adopts a home that already exists; a missing or refused OpenRouter key is one line that names the file, before anything is touched; a `stable` clone ahead only by `main`'s commits is told that `stable` is behind it, not to push or reset. No migration.
 - [v0.38.0 — The Model Behind the Memories, Chosen by Measurement](v0.38.0.md) — minor release closing CV9.DS9: the model behind memories, tasks, titles, summaries, tags, reception, journal, shadow, and consolidation is Claude Haiku 5.5 at reasoning off, chosen on the eval suite with reasoning on and off and on 24 of the owner's own conversations ranked blind, where it came first on 16 of 26 surfaces. Every extraction-pin call can carry a reasoning effort, and a pin carries its own default. With CR180, summaries open with their subject, every lifecycle prompt sees the owner's name, and a framed opening is written once more. Release gate 70 of 70 probes. Rollback is one env line. No migration.
 - [v0.37.0 — The Mirror Stays in the Conversation](v0.37.0.md) — minor release closing CV9.DS8 and, with CV21.DS11, CV21: on Pi, Claude Code, Codex, and Antigravity one doorman in the core puts Mirror's context before the model on every turn of Mirror Mode, all of it on the turn Mirror Mode starts and then the persona and memories each question calls for; an explicit turn loads once; one signature, `◇ persona-name`; Pi reaches L4, measured live. One parity matrix in the runtime interface contract, sourced and held by a test. Codex, Antigravity, and Grok Build need their plugin copy brought level. Migration 018, applied on its own.

package/docs/releases/v0.39.0.md

@@ -0,0 +1,110 @@
+---
+digest: >
+  v0.39.0 is a minor release that ships CV24's first eight Delivery Stories: a library
+  entry, `mirror-mind/desktop`, through which a host such as Mirror Desktop 0.3 embeds
+  this core in its own Node process instead of spawning a CLI. Twenty-five calls and refusal
+  classes, beside `DESKTOP_API_VERSION`, cover a
+  home's migration state, Conversations, sidebar reads, home creation, migration on
+  request, Mirror's context for a turn, learning from open Conversations, and Journey
+  administration, each taking an explicit path and reading no environment. The package
+  gains an `exports` field, which closes every deep import other than the new entry. The
+  terminal, the bins and the hooks behave as before. No migration, and no model or prompt
+  change.
+---
+
+# v0.39.0 — The Core as a Library
+
+**Date:** 2026-10-31
+
+## Highlights
+
+- **`mirror-mind/desktop`, a library entry for a host**
+  ([CV24](../project/roadmap/cv24-embeddable-core-for-mirror-desktop/index.md)). Imported by
+  package name from a host's `node_modules`, with no flags: the entry registers the bins'
+  type-stripping hook itself. Everything a host may call is re-exported there by name, with
+  `DESKTOP_API_VERSION = 1`; a name not in that file is not part of the contract.
+- **Eight stories, one rule.** Every call takes an explicit database or home path, never reads
+  `MIRROR_HOME`, `MIRROR_USER`, `DB_PATH` or a key from the environment, never migrates as a side
+  effect, and refuses a database that is not `current` before opening it for writing.
+- **Custody chosen per write, with a decision for each.** Conversation writes go through a
+  narrowed handle instead of a per-write snapshot; a home is created beside its target and renamed
+  into place; a home migrates only behind a uniquely named, verified backup the core never deletes.
+- **Breaking for deep imports only.** The package now declares `exports` with `./desktop` and
+  `./package.json`. Any other `import "mirror-mind/…"` path that resolved before no longer does.
+  The `mirror` and `mirror-hook` bins are unaffected.
+- No migration, and no model or prompt change, so the model-behavior release gate does not apply.
+
+## Where We Started
+
+Decision CV22.DS10.TS1 left Mirror Desktop outside the TypeScript migration: it kept calling the
+Python core through the retired Journey administration and a catalog script. On 2026-10-28 Mirror
+Desktop decided to follow this core instead. It froze its 0.2 line on Python and opened a 0.3 line
+that hosts the core in its own Node process, on its own home.
+
+That host could not use the CLI's way in. It runs from `node_modules`, where Node refuses to strip
+TypeScript types. A shell that starts it may export another home's `MIRROR_HOME`. It writes on every
+turn of a Conversation that never ends. And it has to ask the person before a home is migrated,
+while every open through the front door migrates first.
+
+## What Changed
+
+The contract grew one story at a time on `desktop/library-seam-1a`, each with its spec first, and
+merged as PR #52.
+
+- **DS1, inspect a home without migrating.** `inspectMigrationState` reports `missing`,
+  `not_mirror`, `current`, `pending` or `ahead`, with the pending list. It shares its three
+  ledger readers with `ensureMigratedOnOpen`, so what it calls pending is exactly what an open
+  would apply. The loader became `boot` plus an idempotent `registerTypeStripping`; only `boot`,
+  which owns its process, filters warnings.
+- **DS2, Conversations as calls.** `ensureConversation`, `appendConversationMessages` (the
+  `conversations append` contract, byte for byte), `renameConversation` and
+  `rebindConversationJourney`, written through `openDatabaseForConversationWrites`. That handle
+  prepares only a single SELECT, INSERT … VALUES into three tables, and an UPDATE of four
+  `conversations` columns by id. The per-write `VACUUM INTO` measured about 0.9 s on a 108 MB
+  home, too much for every turn.
+- **DS3, Journey reads.** `readJourneyTree` (a new contract in the stored sibling order, not a
+  revival of the retired registry dump), `listJourneyConversations` and `inspectConversation`,
+  read-only.
+- **DS4, create a home.** `createHome` copies the templates with the person's name, bootstraps,
+  and seeds in a staging directory, renaming it into place only when the home reads `current`.
+  It never writes `~/.config/mirror/env`.
+- **DS5, migrate on request.** `migrateHome` applies exactly the pending list the person was
+  shown, under the bootstrap lock, behind a backup that is quick-checked, hashed, and read back as
+  the same pre-image.
+- **DS6, Mirror's context as a call.** `deliverMirrorContext` is the doorman for a host's turn,
+  with the key as an argument and Mirror Mode from the first turn; each provider call is tried
+  once within its own bound. Its write is `mirror doorman`'s, behind the front door's snapshot.
+- **DS7, learning from an open Conversation.** `learnFromConversations` extracts the stretch an
+  idle, unended Conversation gained since its `learned_through` watermark, in bounded pieces,
+  with the terminal's prompts, and never ends it.
+- **DS8, Journey administration as calls.** `addJourney`, `setJourneyProjectPath`, `moveJourney`
+  and `deleteJourney` port Python 0.31.14's administration, so the requests Desktop 0.2 sent keep
+  their meaning. `updateJourney` is new: it edits a Journey's name, description and status, and
+  refuses `journey_changed` when the row changed since the host read it.
+
+Existing code changed only where the entry needed it: the loader, three exported readers, two
+`export` keywords in `extraction.ts`, the tarball guard (`lib/` allowed, `lib/desktop.js`
+required), and `package.json`. No existing test changed. The npm smoke installs the package and
+imports the entry from a host project for DS1 to DS5.
+
+## Conscious Exclusions
+
+- **Renaming a Journey's slug.** The slug keys Conversations, memories and tasks; renaming it is a
+  migration, not a call.
+- **A Journey's icon and color, and a receipt ledger for Journey calls.**
+- **The front door's own migration custody.** `ensureMigratedOnOpen` still overwrites one fixed
+  backup; giving it DS5's custody is a separate decision.
+- **Installed-package smoke for DS6 to DS8.** DS6 and DS7 need a provider key. DS8 is exercised
+  end to end by Mirror Desktop's real-host test; a keyless smoke probe is a cheap follow-up.
+
+## What We Learned
+
+A library entry is a stricter consumer than a CLI. Every assumption the bins could make about
+their own process — environment, warnings, migrate-on-open, a snapshot per write — had to become
+an explicit argument or a decision. The retired-surfaces sweep also caught the port twice naming a
+retired verb in comments, which says the sweep is doing its job on new files.
+
+## Next Horizon
+
+Mirror Desktop moves its pin from a branch tarball to this release, then its first 0.3 alpha. CV24
+stays open for the pieces that alpha's use asks for.

package/lib/desktop.js

@@ -0,0 +1,72 @@
+// `mirror-mind/desktop` — the core's library entry for Mirror Desktop. CV24.DS1.
+//
+// Mirror Desktop hosts this core in its own Node process and imports it from
+// `node_modules`, where Node refuses to strip TypeScript types. So this entry
+// registers the same type-stripping hook the bins use, and only then imports
+// the TypeScript modules -- dynamically, because a static `export ... from
+// "./x.ts"` would be loaded before the hook exists.
+//
+// Everything Desktop may call is re-exported here BY NAME. A name missing from
+// this file is not part of the contract, whatever the TypeScript tree holds.
+// `DESKTOP_API_VERSION` changes when a name is removed or changes meaning.
+
+import { registerTypeStripping } from "../bin/loader.js";
+
+registerTypeStripping();
+
+const migrationReport = await import("../ts/src/db/migrationReport.ts");
+const conversations = await import("../ts/src/conversation/hostCalls.ts");
+const reads = await import("../ts/src/conversation/hostReads.ts");
+const homes = await import("../ts/src/init/createHome.ts");
+const migration = await import("../ts/src/db/migrateHome.ts");
+const context = await import("../ts/src/mirror/deliverContext.ts");
+const learning = await import("../ts/src/conversation/learnFromConversations.ts");
+const journeys = await import("../ts/src/journey/journeyCalls.ts");
+
+export const DESKTOP_API_VERSION = 1;
+export const inspectMigrationState = migrationReport.inspectMigrationState;
+
+// CV24.DS2: Conversations as calls. Each opens only a `current` database,
+// never migrates, and writes through the narrowed Conversation handle.
+export const ensureConversation = conversations.ensureConversation;
+export const appendConversationMessages = conversations.appendConversationMessages;
+export const renameConversation = conversations.renameConversation;
+export const rebindConversationJourney = conversations.rebindConversationJourney;
+export const DatabaseNotCurrentError = conversations.DatabaseNotCurrentError;
+export const ConversationCallRejectedError = conversations.ConversationCallRejectedError;
+
+// CV24.DS3: the reads a sidebar is built from. Read-only, `current` homes only.
+export const readJourneyTree = reads.readJourneyTree;
+export const listJourneyConversations = reads.listJourneyConversations;
+export const inspectConversation = reads.inspectConversation;
+
+// CV24.DS4: create a complete, seeded home at an explicit path, all or nothing.
+// Writes nothing outside it, never the machine-wide ~/.config/mirror/env.
+export const createHome = homes.createHome;
+export const CreateHomeRejectedError = homes.CreateHomeRejectedError;
+
+// CV24.DS5: migrate a home on request, applying exactly the pending list the
+// person was shown, behind a uniquely named, verified, retained backup.
+export const migrateHome = migration.migrateHome;
+export const MigrateHomeRejectedError = migration.MigrateHomeRejectedError;
+
+// CV24.DS6: Mirror's context for a host's turn -- the doorman as a call. The
+// key is an argument; nothing is read from the environment. A Conversation is
+// in Mirror Mode from its first turn.
+export const deliverMirrorContext = context.deliverMirrorContext;
+export const forgetMirrorContext = context.forgetMirrorContext;
+export const MirrorContextRejectedError = context.MirrorContextRejectedError;
+
+// CV24.DS7: learn from a host's idle Conversations without ending them -- the
+// stretch each gained since it was last learned from. The key is an argument.
+export const learnFromConversations = learning.learnFromConversations;
+export const LearningRejectedError = learning.LearningRejectedError;
+
+// CV24.DS8: Journeys as calls -- create, edit, move, set a project path,
+// delete -- each answering with the tree `readJourneyTree` reads.
+export const addJourney = journeys.addJourney;
+export const updateJourney = journeys.updateJourney;
+export const setJourneyProjectPath = journeys.setJourneyProjectPath;
+export const moveJourney = journeys.moveJourney;
+export const deleteJourney = journeys.deleteJourney;
+export const JourneyCallRejectedError = journeys.JourneyCallRejectedError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Codex, Antigravity)",
   "license": "MIT",
   "repository": {
@@ -27,8 +27,13 @@
     "mirror": "bin/mirror.js",
     "mirror-hook": "bin/mirror-hook.js"
   },
+  "exports": {
+    "./desktop": "./lib/desktop.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin",
+    "lib",
     "ts/src",
     "templates",
     "docs/releases",

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/plugins/mirror-mind/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mirror-mind",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "mcpServers": {
     "mirror-mind": {
       "command": "/bin/sh",

package/ts/src/conversation/extraction.ts

@@ -179,7 +179,7 @@ export async function runConversationExtraction(
   return { memoryIds, taskIds, extracted: memoryIds.length };
 }
 
-async function persistExtractedTasks(
+export async function persistExtractedTasks(
   db: WritableDatabase,
   llm: LlmProvider,
   messages: readonly ExtractionMessage[],
@@ -295,7 +295,7 @@ function logEmbeddingAttempt(
   return embeddingLedgerHook(db, { conversationId, now });
 }
 
-function insertMemory(
+export function insertMemory(
   db: WritableDatabase,
   id: string,
   conversationId: string,

package/ts/src/conversation/hostCalls.ts

@@ -0,0 +1,204 @@
+// Conversations as calls — CV24.DS2.
+//
+// A host that embeds this core (Mirror Desktop 0.3) records Conversations
+// through four calls instead of the CLI and Python's `MemoryClient`:
+//
+//   - `ensureConversation`: the Conversation bound to a runtime session,
+//     created and bound when none is live. A port of Mirror Desktop's
+//     `provision_mirror_conversation.py`, step for step:
+//     `get_or_create_conversation`, `upsert_runtime_session`, then
+//     `update_conversation(title, journey, interface)`.
+//   - `appendConversationMessages`: the `conversations append` contract, the
+//     same request and the same receipts, byte for byte.
+//   - `renameConversation`: a manual title, locked against the close tail.
+//   - `rebindConversationJourney`: move a Conversation to another Journey.
+//
+// Every call:
+//
+//   - takes an explicit database path and never reads the environment;
+//   - asks the migration report first (CV24.DS1), and refuses a database that
+//     is not `current` without opening it for writing, so it never migrates;
+//   - writes through `openDatabaseForConversationWrites`, the narrowed handle,
+//     instead of the CLI's per-write snapshot (see the decision "A host's
+//     Conversation writes are narrowed, not snapshotted").
+//
+// The caller names the `interface`; this module does not know which host it
+// serves.
+
+import {
+  type AppendReceipt,
+  AppendRejectedError,
+  appendConversationMessages as appendBatch,
+  parseAppendRequest,
+} from "#conversation/append.ts";
+import { cleanTitle, updateConversation, writeTitle } from "#conversation/lifecycleWrites.ts";
+import { getOrCreateSessionConversation } from "#conversation/logger.ts";
+import { openDatabaseForConversationWrites, type WritableDatabase } from "#db/database.ts";
+import {
+  inspectMigrationState,
+  type MigrationReport,
+  type MigrationState,
+} from "#db/migrationReport.ts";
+import { upsertRuntimeSession } from "#mirror/runtimeSession.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+
+/** The database is not one these calls may write: anything but `current`. */
+export class DatabaseNotCurrentError extends Error {
+  readonly state: MigrationState;
+  readonly report: MigrationReport;
+
+  constructor(report: MigrationReport) {
+    super(`database is ${report.state}, not current; no Conversation was written`);
+    this.state = report.state;
+    this.report = report;
+  }
+}
+
+export type ConversationCallRejection =
+  | "invalid_request"
+  | "conversation_unavailable"
+  | "invalid_title";
+
+/** A call's own refusal, named as Mirror Desktop's catalog script named it. */
+export class ConversationCallRejectedError extends Error {
+  readonly reason: ConversationCallRejection;
+
+  constructor(reason: ConversationCallRejection) {
+    super(reason);
+    this.reason = reason;
+  }
+}
+
+function withConversationWrites<T>(dbPath: string, write: (db: WritableDatabase) => T): T {
+  const report = inspectMigrationState(dbPath);
+  if (report.state !== "current") throw new DatabaseNotCurrentError(report);
+  const db = openDatabaseForConversationWrites(dbPath);
+  try {
+    return write(db);
+  } finally {
+    db.close();
+  }
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ConversationCallRejectedError("invalid_request");
+  }
+  return value;
+}
+
+/** The Conversation row by EXACT id: a host names one, never a prefix. */
+function exactConversation(
+  db: WritableDatabase,
+  conversationId: unknown,
+): { id: string; journey: unknown } {
+  const id = text(conversationId);
+  const found = db.prepare("SELECT id, journey FROM conversations WHERE id = ?").get(id);
+  if (!found) throw new ConversationCallRejectedError("conversation_unavailable");
+  return { id: String(found.id), journey: found.journey };
+}
+
+export interface EnsureConversationRequest {
+  sessionId: string;
+  journeyId: string;
+  title: string;
+  interface: string;
+}
+
+/** The live Conversation bound to `sessionId`, created and bound if there is none. */
+export function ensureConversation(
+  dbPath: string,
+  request: EnsureConversationRequest,
+): { conversationId: string; journeyId: string } {
+  const sessionId = text(request?.sessionId);
+  const journeyId = text(request?.journeyId);
+  const title = text(request?.title);
+  const surface = text(request?.interface);
+  return withConversationWrites(dbPath, (db) => {
+    const conversationId = getOrCreateSessionConversation(
+      db,
+      sessionId,
+      { interface: surface, journey: journeyId, title },
+      { newId, nowIso },
+    );
+    upsertRuntimeSession(
+      db,
+      sessionId,
+      { conversationId, interface: surface, journey: journeyId, active: true, closedAt: null },
+      nowIso(),
+    );
+    updateConversation(db, conversationId, { title, journey: journeyId, interface: surface });
+    return { conversationId, journeyId };
+  });
+}
+
+/** What `conversations append` would print as its rejection. */
+type AppendRejectionReceipt = ReturnType<AppendRejectedError["receipt"]>;
+
+/**
+ * Append one batch under the `conversations append` contract. Returns the
+ * receipt the CLI would print, accepted or rejected; a database that is not
+ * `current` throws `DatabaseNotCurrentError` instead, because the CLI would
+ * have migrated it and these calls never do.
+ */
+export function appendConversationMessages(
+  dbPath: string,
+  payload: unknown,
+): AppendReceipt | AppendRejectionReceipt {
+  let request: ReturnType<typeof parseAppendRequest>;
+  try {
+    request = parseAppendRequest(payload);
+  } catch (error) {
+    if (error instanceof AppendRejectedError) return error.receipt();
+    return new AppendRejectedError("malformed_request").receipt();
+  }
+  try {
+    return withConversationWrites(dbPath, (db) => appendBatch(db, request));
+  } catch (error) {
+    if (error instanceof DatabaseNotCurrentError) throw error;
+    if (error instanceof AppendRejectedError) return error.receipt();
+    return new AppendRejectedError("persistence_failure").receipt();
+  }
+}
+
+/** Give a Conversation of `journeyId` a manual title, which the close tail will not replace. */
+export function renameConversation(
+  dbPath: string,
+  request: { conversationId: string; journeyId: string; title: string },
+): { conversationId: string; journeyId: string; title: string } {
+  const journeyId = text(request?.journeyId);
+  let title: string;
+  try {
+    title = cleanTitle(typeof request?.title === "string" ? request.title : "");
+  } catch {
+    throw new ConversationCallRejectedError("invalid_title");
+  }
+  return withConversationWrites(dbPath, (db) => {
+    const conversation = exactConversation(db, request?.conversationId);
+    if (conversation.journey !== journeyId)
+      throw new ConversationCallRejectedError("conversation_unavailable");
+    writeTitle(db, conversation.id, title, "manual");
+    return { conversationId: conversation.id, journeyId, title };
+  });
+}
+
+/** Move a Conversation to `journeyId`; a no-op when it is already there. */
+export function rebindConversationJourney(
+  dbPath: string,
+  request: { conversationId: string; journeyId: string },
+): {
+  conversationId: string;
+  journeyId: string;
+  rebound: boolean;
+  previousJourneyId: string | null;
+} {
+  const journeyId = text(request?.journeyId);
+  return withConversationWrites(dbPath, (db) => {
+    const conversation = exactConversation(db, request?.conversationId);
+    const previousJourneyId =
+      typeof conversation.journey === "string" ? conversation.journey : null;
+    const rebound = previousJourneyId !== journeyId;
+    if (rebound) updateConversation(db, conversation.id, { journey: journeyId });
+    return { conversationId: conversation.id, journeyId, rebound, previousJourneyId };
+  });
+}

package/ts/src/conversation/hostReads.ts

@@ -0,0 +1,126 @@
+// The reads a host's sidebar is built from — CV24.DS3.
+//
+// Three calls for a host that embeds this core (Mirror Desktop 0.3), each
+// replacing a route it took through Python:
+//
+//   - `readJourneyTree`: every Journey as a tree (was the Journey registry dump
+//     CV22.DS10.TS4 retired as `journey-admin-verbs`; this is a new contract,
+//     see `journey/journeyTree.ts`);
+//   - `listJourneyConversations`: one Journey's Conversations, newest first
+//     (was the catalog script's `catalog`);
+//   - `inspectConversation`: one Conversation by EXACT id (was its `inspect`).
+//
+// Like the Conversation calls (`hostCalls.ts`), each asks the migration report
+// first and refuses a database that is not `current`, never migrates, and reads
+// only the path it is given. Unlike them, each opens read-only: on a WAL
+// database the only trace is the `-wal` and `-shm` every reader leaves.
+
+import { listRecentConversationSummaries } from "#conversation/listing.ts";
+import { type Database, openDatabaseReadOnly } from "#db/database.ts";
+import { inspectMigrationState } from "#db/migrationReport.ts";
+import { buildJourneyTree, type JourneyTree, type JourneyTreeRow } from "#journey/journeyTree.ts";
+import { ConversationCallRejectedError, DatabaseNotCurrentError } from "./hostCalls.ts";
+
+/** The catalog's bound, as Mirror Desktop's catalog script set it. */
+const MAX_LIST_LIMIT = 100;
+
+function withRead<T>(dbPath: string, read: (db: Database) => T): T {
+  const report = inspectMigrationState(dbPath);
+  if (report.state !== "current") throw new DatabaseNotCurrentError(report);
+  const db = openDatabaseReadOnly(dbPath);
+  try {
+    return read(db);
+  } finally {
+    db.close();
+  }
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ConversationCallRejectedError("invalid_request");
+  }
+  return value;
+}
+
+/** Every Journey in the home, as a tree in its stored sibling order. */
+export function readJourneyTree(dbPath: string): JourneyTree {
+  return withRead(dbPath, (db) =>
+    buildJourneyTree(
+      db
+        .prepare(
+          "SELECT key, content, updated_at, metadata FROM identity WHERE layer = 'journey' ORDER BY key",
+        )
+        .all() as unknown as JourneyTreeRow[],
+    ),
+  );
+}
+
+export interface JourneyConversationEntry {
+  conversationId: string;
+  title: string | null;
+  startedAt: string | null;
+  messageCount: number;
+  persona: string | null;
+}
+
+/** A Journey's Conversations, newest first, at most `limit` (1 to 100). */
+export function listJourneyConversations(
+  dbPath: string,
+  request: { journeyId: string; limit: number },
+): JourneyConversationEntry[] {
+  const journeyId = text(request?.journeyId);
+  const limit = request?.limit;
+  if (
+    typeof limit !== "number" ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > MAX_LIST_LIMIT
+  ) {
+    throw new ConversationCallRejectedError("invalid_request");
+  }
+  return withRead(dbPath, (db) =>
+    listRecentConversationSummaries(db, { journey: journeyId, limit }).map((summary) => ({
+      conversationId: summary.id,
+      title: summary.title,
+      startedAt: summary.started_at,
+      messageCount: summary.message_count,
+      persona: summary.persona,
+    })),
+  );
+}
+
+export interface ConversationInspection {
+  conversationId: string;
+  journeyId: string | null;
+  title: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  messageCount: number;
+}
+
+/** One Conversation by exact id; a prefix is never resolved. */
+export function inspectConversation(
+  dbPath: string,
+  request: { conversationId: string },
+): ConversationInspection {
+  const conversationId = text(request?.conversationId);
+  return withRead(dbPath, (db) => {
+    const found = db
+      .prepare(
+        "SELECT id, journey, title, started_at, ended_at, " +
+          "(SELECT COUNT(*) FROM messages WHERE conversation_id = c.id) AS message_count " +
+          "FROM conversations c WHERE id = ?",
+      )
+      .get(conversationId);
+    if (!found) throw new ConversationCallRejectedError("conversation_unavailable");
+    const nullable = (value: unknown): string | null => (typeof value === "string" ? value : null);
+    return {
+      conversationId: String(found.id),
+      journeyId: nullable(found.journey),
+      title: nullable(found.title),
+      startedAt: nullable(found.started_at),
+      endedAt: nullable(found.ended_at),
+      messageCount: Number(found.message_count),
+    };
+  });
+}