mirror-mind 0.0.1 → 0.32.1

package/ts/src/frontDoor/searchRoute.ts

@@ -0,0 +1,166 @@
+import type { WritableDatabase } from "#db/database.ts";
+import { requireString } from "#db/rowDecode.ts";
+import type { EmbeddingProvider } from "#providers/embedding.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { SEARCH_TRANSPORT } from "#providers/transport.ts";
+import type { FreshSearchResult } from "#search/memorySearch.ts";
+import { searchMemoriesWithStatus } from "#search/memorySearch.ts";
+import { optionValue } from "./args.ts";
+import { ICONS } from "./render/icons.ts";
+import { tagsText } from "./render/memories.ts";
+
+// Mirrors Python's cli/memories.py degraded_note wording exactly (AI-04),
+// including under a degraded search with zero results.
+const DEGRADED_NOTE =
+  "⚠ Degraded: lexical-only search (embedding unavailable — offline or no API key).";
+
+export interface SearchMemoryRow {
+  id: string;
+  memory_type: string;
+  layer: string;
+  title: string;
+  content: string;
+  created_at: string;
+  journey: string | null;
+  tags: string | null;
+}
+
+/**
+ * Resolve the embedding provider by the same precedence the router used
+ * (CV22.DS8.US1), so the route can never disagree with the routing decision
+ * about which transport is in play.
+ */
+export async function resolveSearchEmbeddingProvider(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<EmbeddingProvider> {
+  // The live provider resolves its config lazily, so a missing key surfaces
+  // inside searchMemoriesWithStatus and degrades to lexical-only rather than
+  // failing the command -- Python's behavior for an unconfigured install.
+  const family = await resolveFamilyProviders(env, SEARCH_TRANSPORT);
+  if (!family.embedding) {
+    // The search family declares an embedding fixture, so replay and live both
+    // build one; this is defense in depth, not a reachable state.
+    throw new Error("memories --search requires an embedding provider");
+  }
+  return family.embedding;
+}
+
+export interface MemorySearchRouteOptions {
+  /** Receives a content-free degraded category for the front-door log. */
+  onDegraded?: (detail: string) => void;
+}
+
+export async function runMemorySearchRoute(
+  db: WritableDatabase,
+  args: readonly string[],
+  options: MemorySearchRouteOptions = {},
+): Promise<string> {
+  const query = optionValue(args, "--search");
+  if (!query) throw new Error("memories --search requires a query");
+  const provider = await resolveSearchEmbeddingProvider();
+  const limit = Number(optionValue(args, "--limit") ?? 20);
+  const { results, degraded, degradedKind } = await searchMemoriesWithStatus(db, {
+    query,
+    limit,
+    memoryType: optionValue(args, "--type"),
+    layer: optionValue(args, "--layer"),
+    journey: optionValue(args, "--journey"),
+    provider,
+    // An exploratory CLI search is not a genuine context load, so it must not
+    // reinforce: `access_count` feeds `reinforcement_score` and the hybrid
+    // ranker, and a ranker fed by its own exhaust drifts toward whatever was
+    // searched for rather than whatever was used (AI-12). Python's
+    // `cli/memories.py` has passed `log_access=False` since 2026-07-16; this
+    // port did not, and reinforced on every `memories --search` from the flip
+    // until CV22.DS9.US2 measured it. Builder context load deliberately keeps
+    // the default and still reinforces -- that one IS a genuine load.
+    logAccess: false,
+  });
+  // A degraded live search is the one failure an operator has to diagnose
+  // without a re-run, so the taxonomy class reaches the front-door log rather
+  // than dying inside the degrade path. Category only -- never a message,
+  // never the query (RS005/CR026).
+  if (degraded && degradedKind) {
+    options.onDegraded?.(`embedding_degraded kind=${degradedKind}`);
+  }
+  const rows = memoriesById(
+    db,
+    results.map((result) => result.id),
+  );
+  return formatSearchResults(query, results, rows, degraded);
+}
+
+/**
+ * Pure rendering of a fresh-search outcome (AI-04). Split out from
+ * `runMemorySearchRoute` so the degraded/normal render branches are directly
+ * unit-testable without a database or a live-failing embedding provider (none
+ * exists yet -- see CR037 plan).
+ */
+export function formatSearchResults(
+  query: string,
+  results: readonly FreshSearchResult[],
+  rows: ReadonlyMap<string, SearchMemoryRow>,
+  degraded: boolean,
+): string {
+  if (results.length === 0) {
+    return degraded ? `${DEGRADED_NOTE}\n` : "No memories found.\n";
+  }
+  const lines: string[] = [];
+  if (degraded) {
+    lines.push(`${DEGRADED_NOTE} Ranked by keyword match.`, "");
+  }
+  lines.push(`🔍 Search: "${query}" (${results.length} results)`, "");
+  for (const result of results) {
+    const memory = rows.get(result.id);
+    if (!memory) continue;
+    const icon = ICONS[memory.memory_type] ?? "•";
+    const date = memory.created_at ? memory.created_at.slice(0, 10) : "?";
+    const journey = memory.journey ? ` 🧭 ${memory.journey}` : "";
+    const tags = tagsText(memory.tags);
+    lines.push(`${icon} **${memory.title}** (score: ${result.score.toFixed(3)})`);
+    lines.push(
+      `  ${date} | \`${memory.id.slice(0, 8)}\` | ${memory.memory_type} [${memory.layer}]${journey}`,
+    );
+    lines.push(`  ${memory.content.slice(0, 200)}`);
+    if (tags) lines.push(`  🏷 ${tags}`);
+    lines.push("");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The row reader both search faces share.
+ *
+ * Exported for `build load` (CV22.DS7.US8 plateau 7), which renders the same
+ * memories from the same ranked ids: the ranker returns `{id, score}` only, so a
+ * second copy of this query is a second chance for the two blocks to disagree
+ * about what a memory says.
+ */
+export function memoriesById(
+  db: WritableDatabase,
+  ids: readonly string[],
+): Map<string, SearchMemoryRow> {
+  if (ids.length === 0) return new Map();
+  const placeholders = ids.map(() => "?").join(", ");
+  const rows = db
+    .prepare(
+      `SELECT id, memory_type, layer, title, content, created_at, journey, tags FROM memories ` +
+        `WHERE id IN (${placeholders})`,
+    )
+    .all(...ids);
+  return new Map(
+    rows.map((row) => [
+      requireString(row, "id"),
+      {
+        id: requireString(row, "id"),
+        memory_type: requireString(row, "memory_type"),
+        layer: requireString(row, "layer"),
+        title: requireString(row, "title"),
+        content: requireString(row, "content"),
+        created_at: requireString(row, "created_at"),
+        journey: typeof row.journey === "string" ? row.journey : null,
+        tags: typeof row.tags === "string" ? row.tags : null,
+      },
+    ]),
+  );
+}

package/ts/src/frontDoor/seedPaths.ts

@@ -0,0 +1,98 @@
+// `seed` path resolution — the port of the bespoke resolution inside
+// memory.cli.seed.seed(), which is NOT the same precedence chain
+// `resolveDbPath` (dbPath.ts) uses for every other command. Verified against
+// the live oracle (never assumed) because it diverges in a genuinely
+// surprising way:
+//
+// - `identity_root`/`mirror_home` resolve via `--mirror-home` or the plain
+//   MIRROR_HOME/MIRROR_USER chain (`resolveMirrorHome`) -- completely
+//   independent of `--env`, `MEMORY_DIR`, or `DB_PATH`.
+// - When `--mirror-home` IS given, the database path is ALWAYS
+//   `<mirror_home>/memory.db` -- `--env` is silently ignored for the
+//   filename (`default_db_path_for_home` hardcodes "memory.db"). Confirmed
+//   live: `seed --mirror-home X --env test` writes `X/memory.db`, not
+//   `X/memory_test.db`.
+// - When `--mirror-home` is absent and `--env` differs from the ambient
+//   `MEMORY_ENV` (or ambient is unset, defaulting "production" like Python's
+//   module-level MEMORY_ENV constant), the database path follows
+//   `db_path_for_env`: MEMORY_PROD_DIR (production only) > MEMORY_DIR > the
+//   resolved mirror home, with the env-appropriate filename -- but WITHOUT
+//   checking `DB_PATH` (that env var is only wired to the *ambient*
+//   environment in Python, cached once at import time).
+// - When `--mirror-home` is absent and `--env` matches the ambient
+//   `MEMORY_ENV` (or is omitted), the database path follows the SAME full
+//   generic chain every other command uses (`require_db_path()` ==
+//   `resolveDbPath`).
+//
+// `--db-path` is a TS-front-door-only convenience (Python's `seed` CLI has no
+// such flag), kept here for consistency with every other ported command --
+// it wins over everything, as documented in dbPath.ts.
+
+import { join } from "node:path";
+import { expandHome } from "#util/paths.ts";
+import { optionValue } from "./args.ts";
+import {
+  type DbPathEnv,
+  type DbPathIo,
+  dbNameForEnv,
+  MirrorHomeNotConfiguredError,
+  resolveDbPath,
+  resolveMirrorHome,
+} from "./dbPath.ts";
+
+export interface SeedPaths {
+  dbPath: string;
+  identityRoot: string;
+  mirrorHome: string;
+  env: string;
+}
+
+/**
+ * Resolve `seed`'s database path, identity root, mirror home, and effective
+ * env, mirroring the Python branches documented above exactly. Throws
+ * MirrorHomeNotConfiguredError when nothing resolves (mapped to exit 2 by the
+ * caller, matching every other command's unconfigured-home contract).
+ */
+export function resolveSeedPaths(
+  args: readonly string[],
+  env: DbPathEnv = process.env,
+  io: DbPathIo = {},
+): SeedPaths {
+  const explicitDbPath = optionValue(args, "--db-path");
+  const explicitMirrorHome = optionValue(args, "--mirror-home");
+  const envFlag = optionValue(args, "--env");
+  const ambientEnv = env.MEMORY_ENV || "production";
+  const effectiveEnv = envFlag || ambientEnv;
+
+  const mirrorHome = explicitMirrorHome
+    ? expandHome(explicitMirrorHome)
+    : resolveMirrorHome(env, io);
+  const identityRoot = join(mirrorHome, "identity");
+
+  if (explicitDbPath) {
+    return { dbPath: expandHome(explicitDbPath), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  if (explicitMirrorHome) {
+    // default_db_path_for_home: ALWAYS "memory.db", --env is not consulted.
+    return { dbPath: join(mirrorHome, "memory.db"), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  if (envFlag && envFlag !== ambientEnv) {
+    const dbName = dbNameForEnv(envFlag);
+    let dir: string;
+    if (envFlag === "production" && env.MEMORY_PROD_DIR) {
+      dir = expandHome(env.MEMORY_PROD_DIR);
+    } else if (env.MEMORY_DIR) {
+      dir = expandHome(env.MEMORY_DIR);
+    } else {
+      dir = mirrorHome;
+    }
+    return { dbPath: join(dir, dbName), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  // require_db_path(): by construction neither --db-path nor --mirror-home is
+  // present here, so this is exactly resolveDbPath's own DB_PATH ->
+  // MEMORY_PROD_DIR -> MEMORY_DIR -> resolved-mirror-home chain -- the same
+  // one every other command uses. Reused directly rather than re-implemented.
+  return { dbPath: resolveDbPath(args, env, io), identityRoot, mirrorHome, env: effectiveEnv };
+}
+
+export { MirrorHomeNotConfiguredError };

package/ts/src/frontDoor/soulRoute.ts

@@ -0,0 +1,433 @@
+// CV22.DS7.US6 plateau 6 — the `soul` front-door route.
+//
+// Dispatch only: every behavior it reaches was ported and graded in plateaus
+// 1-5. What this module owns is the argv shape, the exit codes, and the
+// refusals — Python's `cmd_*` wrappers print `Error: <message>` to stderr and
+// exit 1 for a ValueError, and argparse exits 2 for an unknown subcommand or a
+// missing required argument.
+//
+// The subcommands are allowlisted BY NAME by `routing.ts`, so a subcommand
+// Python grows later reaches Python instead of inheriting this route. That is
+// the `conversations append` lesson (RS009/CR055): a family claimed wholesale
+// answered an argv shape it had never implemented, exited 0, and discarded the
+// caller's data.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { persistStickyDefaults } from "#mirror/orchestration.ts";
+import { resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
+import { activateOperatingMode } from "#mode/operatingMode.ts";
+import { embeddingLedgerHook } from "#observability/ledgerHooks.ts";
+import { generateEmbeddingSafely } from "#providers/embedding.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { SOUL_HARVEST_TRANSPORT } from "#providers/transport.ts";
+import { applyIdentityIntegration, SoulApplyError } from "#soul/apply.ts";
+import {
+  persistHarvestSave,
+  planHarvestSave,
+  SoulHarvestError,
+  type TranscriptMessage,
+} from "#soul/harvest.ts";
+import {
+  composeSoulBeautyVoicePrompt,
+  composeSoulSelfVoicePrompt,
+  composeSoulWisdomVoicePrompt,
+} from "#soul/prompts.ts";
+import {
+  renderActiveRite,
+  renderClosingRite,
+  renderEnrichmentProposal,
+  renderFruitInMaturation,
+  renderHarvestedFruit,
+  renderIdentityChangeApplied,
+  renderIntegrationReview,
+  renderPossibleListenings,
+  type SoulListeningOption,
+  SoulSurfaceError,
+} from "#soul/render.ts";
+import {
+  clearFruitInMaturation,
+  clearHarvestedFruit,
+  getFruitInMaturation,
+  getHarvestedFruit,
+  harvestFruit,
+  resolveCliSoulSessionId,
+  SoulStateError,
+  setFruitInMaturation,
+} from "#soul/state.ts";
+import { renderSoulModeTransition } from "#soul/transition.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { pyStrip } from "#util/pythonText.ts";
+import { optionValue, stripOptionWithValue } from "./args.ts";
+
+/** Python's argparse subcommands, by name. Order is irrelevant; membership is not. */
+export const SOUL_SUBCOMMANDS = [
+  "load",
+  "listen",
+  "rite",
+  "close",
+  "review",
+  "propose",
+  "apply",
+  "fruit",
+  "harvest",
+  "prompt",
+] as const;
+
+const OPTIONS_WITH_VALUES = [
+  "--mirror-home",
+  "--db-path",
+  "--session-id",
+  "--matter",
+  "--self",
+  "--shadow",
+  "--wisdom",
+  "--beauty",
+  "--says",
+  "--listening-for",
+  "--question",
+  "--harvested",
+  "--echoes",
+  "--open",
+  "--integration",
+  "--origin",
+  "--journal",
+  "--ego",
+  "--persona",
+  "--key",
+  "--current",
+  "--proposed",
+  "--why",
+  "--confirm",
+  "--conversation-id",
+  "--journal-id",
+  "--journey",
+];
+
+function positionals(args: readonly string[]): string[] {
+  return OPTIONS_WITH_VALUES.reduce<string[]>(
+    (remaining, option) => stripOptionWithValue(remaining, option),
+    [...args],
+  );
+}
+
+function fail(message: string): number {
+  process.stderr.write(`Error: ${message}\n`);
+  return 1;
+}
+
+/** argparse's own exit for an unknown subcommand or a missing required argument. */
+function usageError(message: string): number {
+  process.stderr.write(`${message}\n`);
+  return 2;
+}
+
+export interface SoulRouteDeps {
+  readMessages: (db: Database, conversationId: string) => TranscriptMessage[];
+  /**
+   * The harvest journal's embedding (CV22.DS8.US3).
+   *
+   * Async because it is a real, billable provider round trip: `routing.ts`
+   * used to keep `harvest save` on Python unless a replay fixture was set, and
+   * nothing ever supplied one through the front door -- so the only leaf of
+   * the Soul command that crosses the provider seam could not complete on
+   * TypeScript at all. The route now resolves the family's provider and
+   * embeds through `generateEmbeddingSafely`, with the ledger hook attached.
+   */
+  embed: (db: WritableDatabase, text: string) => Promise<Uint8Array>;
+  newId: () => string;
+  nowIso: () => string;
+}
+
+export const defaultSoulRouteDeps: SoulRouteDeps = {
+  readMessages: (db, conversationId) =>
+    db
+      .prepare("SELECT role, content FROM messages WHERE conversation_id = ? ORDER BY rowid")
+      .all(conversationId) as unknown as TranscriptMessage[],
+  embed: async (db, text) => {
+    const family = await resolveFamilyProviders(process.env, SOUL_HARVEST_TRANSPORT);
+    if (!family?.embedding) {
+      // `routing.ts` reverts the family before the route is reached, so this
+      // is defense in depth rather than the operator-facing message.
+      throw new SoulHarvestError("soul harvest save requires an embedding provider");
+    }
+    // Through the wrapper, like every other embedding path: bounded retry of a
+    // transient empty payload, the AI-07 dimension guard, and one ledger row
+    // per round trip, priced (CR075's adjacent case).
+    const vector = await generateEmbeddingSafely(family.embedding, text, {
+      onAttempt: embeddingLedgerHook(db),
+    });
+    return new Uint8Array(new Float32Array(vector).buffer);
+  },
+  newId,
+  nowIso,
+};
+
+export async function runSoulRoute(
+  db: WritableDatabase,
+  argv: readonly string[],
+  deps: SoulRouteDeps = defaultSoulRouteDeps,
+): Promise<number> {
+  const rawArgs = argv.slice(1);
+  const args = positionals(rawArgs);
+  const sub = args[0];
+  const option = (name: string) => optionValue(rawArgs, name);
+
+  try {
+    switch (sub) {
+      case "load":
+        return runLoad(db, args[1] ?? null, option("--session-id"), deps);
+      case "listen":
+        return write(renderPossibleListenings(listeningOptions(option)));
+      case "rite": {
+        const voice = args[1];
+        if (!voice) return usageError("soul rite requires a voice");
+        return write(
+          renderActiveRite(voice, {
+            utterance: option("--says"),
+            listeningFor: option("--listening-for"),
+            question: option("--question"),
+          }),
+        );
+      }
+      case "close":
+        return write(
+          renderClosingRite({
+            harvested: option("--harvested"),
+            echoes: option("--echoes"),
+            remainsOpen: option("--open"),
+            integration: option("--integration"),
+          }),
+        );
+      case "review":
+        return write(
+          renderIntegrationReview({
+            // `--origin` and its legacy alias `--journal` share one argparse
+            // destination, so the LAST one on the command line wins -- not a
+            // fixed precedence between them.
+            journal: lastOptionValue(rawArgs, ["--origin", "--journal"]),
+            selfMaterial: option("--self"),
+            shadow: option("--shadow"),
+            ego: option("--ego"),
+            persona: option("--persona"),
+            leaveOpen: option("--open"),
+          }),
+        );
+      case "propose": {
+        const layer = args[1];
+        if (!layer) return usageError("soul propose requires a layer");
+        const key = resolveIdentityKey(layer, option("--key"));
+        return write(
+          renderEnrichmentProposal(layer, {
+            key,
+            origin: option("--origin") ?? "",
+            current: option("--current"),
+            proposed: option("--proposed") ?? "",
+            why: option("--why") ?? "",
+          }),
+        );
+      }
+      case "apply":
+        return runApply(db, args[1], option, deps);
+      case "fruit":
+        return runFruit(db, args[1], args[2] ?? null, option("--session-id"), deps);
+      case "harvest":
+        return await runHarvest(db, args[1], args[2] ?? null, option, deps);
+      case "prompt":
+        return runPrompt(db, args[1]);
+      default:
+        return usageError(`soul: unknown subcommand ${sub ?? ""}`);
+    }
+  } catch (error) {
+    if (
+      error instanceof SoulSurfaceError ||
+      error instanceof SoulStateError ||
+      error instanceof SoulApplyError ||
+      error instanceof SoulHarvestError
+    ) {
+      return fail(error.message);
+    }
+    throw error;
+  }
+}
+
+/** The value of whichever of `names` appears LAST in argv, as argparse resolves a shared dest. */
+function lastOptionValue(args: readonly string[], names: readonly string[]): string | null {
+  let value: string | null = null;
+  for (let index = 0; index < args.length; index += 1) {
+    if (names.includes(args[index] as string)) value = args[index + 1] ?? null;
+  }
+  return value;
+}
+
+function write(rendered: string): number {
+  process.stdout.write(`${rendered}\n`);
+  return 0;
+}
+
+function listeningOptions(option: (name: string) => string | null): SoulListeningOption[] {
+  const raw: [string, string | null][] = [
+    ["self", option("--self")],
+    ["shadow", option("--shadow")],
+    ["wisdom", option("--wisdom")],
+    ["beauty", option("--beauty")],
+  ];
+  return raw
+    .filter(([, description]) => description !== null && description.trim() !== "")
+    .map(([voice, description]) => ({ voice, description: (description as string).trim() }));
+}
+
+/** Port of `_resolve_identity_key`. */
+function resolveIdentityKey(layer: string, key: string | null): string {
+  if (layer === "self") return key || "soul";
+  if (layer === "shadow") return key || "profile";
+  if (layer === "ego") return key || "behavior";
+  if (layer === "persona") {
+    if (!key) throw new SoulApplyError("persona proposals require --key");
+    return key;
+  }
+  throw new SoulApplyError(`unsupported psyche layer: ${layer}`);
+}
+
+function runLoad(
+  db: WritableDatabase,
+  slug: string | null,
+  sessionId: string | null,
+  deps: SoulRouteDeps,
+): number {
+  const now = deps.nowIso();
+  if (slug) {
+    if (!getIdentityContent(db, "journey", slug)) {
+      process.stderr.write(`Error: journey '${slug}' not found.\n`);
+      return 1;
+    }
+    persistStickyDefaults(db, null, slug, now);
+  }
+  // `cmd_load` uses the OPERATING-MODE resolver, not the Soul one, and that
+  // resolver may return null -- in which case `activate_mode` writes the GLOBAL
+  // mode row instead of a session row. Falling back to `__global_soul_mode__`
+  // here would silently write to a different row than Python does.
+  const resolvedSessionId = resolveRuntimeSessionId(
+    db,
+    sessionId,
+    process.env.MIRROR_SESSION_ID ?? null,
+  );
+  activateOperatingMode(
+    db,
+    { mode: "Soul Mode", journey: slug, sessionId: resolvedSessionId },
+    now,
+  );
+  return write(renderSoulModeTransition(slug));
+}
+
+function runApply(
+  db: WritableDatabase,
+  layer: string | undefined,
+  option: (name: string) => string | null,
+  deps: SoulRouteDeps,
+): number {
+  if (!layer) return usageError("soul apply requires a layer");
+  const key = resolveIdentityKey(layer, option("--key"));
+  if (option("--confirm") !== "APPLY") {
+    return fail("identity update requires --confirm APPLY");
+  }
+  const content = pyStrip(option("--proposed") ?? "");
+  if (!content) return fail("identity content must not be empty");
+  applyIdentityIntegration(
+    db,
+    {
+      layer,
+      key,
+      content,
+      origin: option("--origin"),
+      conversationId: option("--conversation-id"),
+      journalId: option("--journal-id"),
+    },
+    { newId: deps.newId, nowIso: deps.nowIso() },
+  );
+  return write(renderIdentityChangeApplied(layer, { key, content }));
+}
+
+function runFruit(
+  db: WritableDatabase,
+  action: string | undefined,
+  fruit: string | null,
+  sessionId: string | null,
+  deps: SoulRouteDeps,
+): number {
+  const resolved = resolveCliSoulSessionId(db, sessionId, process.env.MIRROR_SESSION_ID ?? null);
+  if (action === "set") {
+    if (fruit === null) return usageError("soul fruit set requires a fruit");
+    const state = setFruitInMaturation(db, fruit, resolved, deps.nowIso());
+    return write(renderFruitInMaturation(state.fruit ?? ""));
+  }
+  if (action === "show") {
+    const state = getFruitInMaturation(db, resolved);
+    if (!state.fruit) return fail("No fruit in maturation.");
+    return write(renderFruitInMaturation(state.fruit));
+  }
+  if (action === "clear") {
+    clearFruitInMaturation(db, resolved, deps.nowIso());
+    process.stdout.write("Fruit in maturation cleared.\n");
+    return 0;
+  }
+  return usageError(`soul fruit: unknown action ${action ?? ""}`);
+}
+
+async function runHarvest(
+  db: WritableDatabase,
+  action: string | undefined,
+  fruit: string | null,
+  option: (name: string) => string | null,
+  deps: SoulRouteDeps,
+): Promise<number> {
+  const resolved = resolveCliSoulSessionId(
+    db,
+    option("--session-id"),
+    process.env.MIRROR_SESSION_ID ?? null,
+  );
+  if (action === "set") {
+    const state = harvestFruit(db, { fruit, sessionId: resolved }, deps.nowIso());
+    return write(renderHarvestedFruit(state.fruit ?? ""));
+  }
+  if (action === "show") {
+    const state = getHarvestedFruit(db, resolved);
+    if (!state.fruit) return fail("No harvested fruit.");
+    return write(renderHarvestedFruit(state.fruit));
+  }
+  if (action === "save") {
+    const state = getHarvestedFruit(db, resolved);
+    if (!state.fruit) return fail("No harvested fruit.");
+    // Compose, then embed, then persist. The fruit is cleared inside the
+    // persist step, so a failing embedding leaves it harvested for a retry
+    // rather than losing it to a provider outage -- Python's ordering.
+    const plan = planHarvestSave(db, resolved, (conversationId) =>
+      deps.readMessages(db, conversationId),
+    );
+    const embedding = await deps.embed(db, plan.embedText);
+    const result = persistHarvestSave(
+      db,
+      plan,
+      { sessionId: resolved, journey: option("--journey") },
+      { newId: deps.newId, nowIso: deps.nowIso(), embedding },
+    );
+    process.stdout.write(`Harvest saved to journal. ${result.memoryId}\n`);
+    return 0;
+  }
+  if (action === "decline") {
+    clearHarvestedFruit(db, resolved, deps.nowIso());
+    process.stdout.write("Harvest discarded without journal save.\n");
+    return 0;
+  }
+  return usageError(`soul harvest: unknown action ${action ?? ""}`);
+}
+
+function runPrompt(db: Database, voice: string | undefined): number {
+  // `print(prompt)` appends a newline to a template that already ends with one,
+  // so the shipped output ends with two. Stripping either is a divergence.
+  if (voice === "self") return write(composeSoulSelfVoicePrompt(db));
+  if (voice === "wisdom") return write(composeSoulWisdomVoicePrompt());
+  if (voice === "beauty") return write(composeSoulBeautyVoicePrompt());
+  process.stderr.write(`Error: unsupported Soul Mode prompt voice: ${voice ?? ""}\n`);
+  return 1;
+}