mirror-mind 0.0.1 → 0.33.0

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

package/ts/src/frontDoor/stdinSource.ts

@@ -0,0 +1,37 @@
+// Where a stdin-reading route gets its payload (CV21.DS2.US8).
+//
+// Two of the conversation logger's subcommands read a hook payload from
+// stdin: `user-prompt` and `stop`. Until US8 the Claude hook entries did not
+// touch fd 0 and let the route read it. Now an entry reads the payload first,
+// to detect the runtime it is in (`runtimeDetection.ts`), and fd 0 cannot be
+// read twice. So the entry hands the payload over here, and the route takes
+// it before falling back to fd 0.
+//
+// A one-shot handoff rather than an argument because the hooks run the front
+// door in-process (`runFrontDoor`), through the same `main(argv)` every other
+// caller uses, and a payload does not belong in argv: argv is what `ps`
+// shows, and what the Gemini hooks already put a prompt into is the exception
+// this seam avoids repeating.
+
+import { readFileSync } from "node:fs";
+
+let provided: string | null = null;
+
+/** Hand a payload to the next stdin-reading route in this process. */
+export function provideStdin(text: string): void {
+  provided = text;
+}
+
+/** The provided payload, once; else fd 0 to its end; "" when there is none. */
+export function takeStdin(): string {
+  if (provided !== null) {
+    const text = provided;
+    provided = null;
+    return text;
+  }
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}

package/ts/src/frontDoor/tasksImportSyncRoute.ts

@@ -0,0 +1,110 @@
+// Front-door `tasks import|sync|sync-config` write handlers (CV22.DS7.US2
+// slice 3c). The testable core of routing these subcommands to the TS core,
+// mirroring `memory.cli.tasks_cmd`'s `cmd_import`/`cmd_sync`/`cmd_sync_config`.
+
+import { existsSync } from "node:fs";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { listIdentityByLayer } from "#identity/identityRead.ts";
+import { getSyncFile, JOURNEY_LAYER, setSyncFile } from "#journey/journeySyncFile.ts";
+import {
+  importTasksFromJourneyPath,
+  type SyncResult,
+  syncTasksFromFile,
+} from "#tasks/taskImportSync.ts";
+import type { Task } from "#tasks/taskStore.ts";
+import { normalizeProjectPath } from "#util/paths.ts";
+
+/** Journeys to operate on for `tasks import [journey]`: the explicit one, or every known journey (key order). */
+export function resolveImportJourneys(db: Database, explicitJourney: string | null): string[] {
+  if (explicitJourney) return [explicitJourney];
+  return listIdentityByLayer(db, JOURNEY_LAYER).map((row) => row.key);
+}
+
+/** One journey's import result, included in rendering only when it created at least one task. */
+export interface ImportJourneyResult {
+  journey: string;
+  created: Task[];
+}
+
+/**
+ * `tasks import [journey]`: import pending tasks for each resolved journey.
+ * Matches Python's `if created:` filter -- a journey with zero imports never
+ * appears in the render, but still contributes to nothing (not an error).
+ */
+export function applyTasksImport(
+  db: WritableDatabase,
+  explicitJourney: string | null,
+): ImportJourneyResult[] {
+  const journeys = resolveImportJourneys(db, explicitJourney);
+  const results: ImportJourneyResult[] = [];
+  for (const journey of journeys) {
+    const created = importTasksFromJourneyPath(db, journey);
+    if (created.length > 0) {
+      results.push({ journey, created });
+    }
+  }
+  return results;
+}
+
+/** Journeys to operate on for `tasks sync [journey]`: the explicit one (regardless of sync-file config), or every journey WITH a sync file configured. */
+export function resolveSyncJourneys(db: Database, explicitJourney: string | null): string[] {
+  if (explicitJourney) return [explicitJourney];
+  return listIdentityByLayer(db, JOURNEY_LAYER)
+    .map((row) => row.key)
+    .filter((key) => getSyncFile(db, key) !== null);
+}
+
+export type SyncJourneyOutcome =
+  | { kind: "no_sync_file"; journey: string }
+  | { kind: "synced"; journey: string; syncFile: string; result: SyncResult }
+  | { kind: "error"; journey: string; message: string };
+
+/**
+ * `tasks sync`'s per-journey step: re-checks the sync file (an explicit
+ * journey may have none configured -- Python's own per-iteration check, not a
+ * whole-command precondition), then syncs, catching ANY error the same way
+ * Python's two `except` clauses collapse to the identical print.
+ */
+export function applyTasksSyncForJourney(
+  db: WritableDatabase,
+  journey: string,
+): SyncJourneyOutcome {
+  const syncFile = getSyncFile(db, journey);
+  if (!syncFile) return { kind: "no_sync_file", journey };
+  try {
+    const result = syncTasksFromFile(db, journey);
+    return { kind: "synced", journey, syncFile, result };
+  } catch (error) {
+    return {
+      kind: "error",
+      journey,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export interface SyncConfigOutcome {
+  journey: string;
+  resolvedPath: string;
+  fileExisted: boolean;
+}
+
+/**
+ * `tasks sync-config <journey> <file>`: normalize the path (the same
+ * expanduser+resolve `normalizeProjectPath` already ports for `journey
+ * set-path`), record whether it currently exists (a warning, not a failure),
+ * and configure it. Throws `JourneyNotFoundError` for an unknown journey --
+ * Python's `cmd_sync_config` does not catch this either (see
+ * `journeySyncFile.ts`'s module doc).
+ */
+export function applyTasksSyncConfig(
+  db: WritableDatabase,
+  journey: string,
+  rawFilePath: string,
+  nowIso: string,
+): SyncConfigOutcome {
+  const resolvedPath = normalizeProjectPath(rawFilePath);
+  const fileExisted = existsSync(resolvedPath);
+  setSyncFile(db, journey, resolvedPath, nowIso);
+  return { journey, resolvedPath, fileExisted };
+}

package/ts/src/frontDoor/tasksWriteRoute.ts

@@ -0,0 +1,101 @@
+// Front-door `tasks add|done|doing|block|delete` write handlers (CV22.DS7.US2
+// slice 3a). The testable core of routing these subcommands to the TS core:
+// each function takes an already-open `WritableDatabase` plus injected
+// id/now (the DS4 determinism-injection idiom) and returns a result the
+// `render/tasks.ts` module turns into Python-identical stdout.
+//
+// `tasks import`/`sync`/`sync-config` (which also depend on the journey
+// sync-file/project-path metadata subsystem) and `week plan`/`save` (LLM-gated,
+// reassigned to US5) are NOT here -- see the plan's slice breakdown.
+
+import type { WritableDatabase } from "#db/database.ts";
+import {
+  completeTask,
+  createTask,
+  deleteTaskById,
+  resolveTaskByIdOrPrefix,
+  type Task,
+  updateTaskStatus,
+} from "#tasks/taskStore.ts";
+
+/** Fields accepted by `tasks add`, mirroring the Python CLI's flags. */
+export interface AddTaskParams {
+  title: string;
+  journey?: string | null;
+  due?: string | null;
+  stage?: string | null;
+}
+
+/** `tasks add`: create the task and return it for rendering. */
+export function applyTasksAdd(
+  db: WritableDatabase,
+  params: AddTaskParams,
+  id: string,
+  nowIso: string,
+): Task {
+  return createTask(
+    db,
+    { title: params.title, journey: params.journey, dueDate: params.due, stage: params.stage },
+    id,
+    nowIso,
+  );
+}
+
+/** The Python-visible status a `done|doing|block` command applies. */
+export type TaskStatusTarget = "doing" | "blocked" | "done";
+
+export type StatusChangeOutcome =
+  | { kind: "changed"; task: Task; newStatus: TaskStatusTarget }
+  | { kind: "ambiguous"; idOrPrefix: string; matches: Task[] }
+  | { kind: "not_found"; idOrPrefix: string };
+
+/**
+ * `tasks done|doing|block`: resolve the id/prefix via the ONE shared resolver,
+ * apply the status change, and report the outcome. `done` completes the task
+ * (status + completed_at); `doing`/`blocked` only change status -- matching
+ * Python's `if new_status == "done": complete_task(...) else: update_task(...)`.
+ */
+export function applyTasksStatusChange(
+  db: WritableDatabase,
+  idOrPrefix: string,
+  newStatus: TaskStatusTarget,
+  nowIso: string,
+): StatusChangeOutcome {
+  const resolved = resolveTaskByIdOrPrefix(db, idOrPrefix);
+  if (resolved.kind === "not_found") return { kind: "not_found", idOrPrefix };
+  if (resolved.kind === "ambiguous") {
+    return { kind: "ambiguous", idOrPrefix, matches: resolved.matches };
+  }
+
+  if (newStatus === "done") {
+    completeTask(db, resolved.task.id, nowIso);
+  } else {
+    updateTaskStatus(db, resolved.task.id, newStatus, nowIso);
+  }
+
+  const task: Task = {
+    ...resolved.task,
+    status: newStatus,
+    updated_at: nowIso,
+    completed_at: newStatus === "done" ? nowIso : resolved.task.completed_at,
+  };
+  return { kind: "changed", task, newStatus };
+}
+
+export type DeleteOutcome =
+  | { kind: "deleted"; task: Task }
+  | { kind: "not_found"; idOrPrefix: string };
+
+/**
+ * `tasks delete`: resolve via the SAME shared resolver as status-change, but
+ * fold "ambiguous" into "not_found" -- Python's `cmd_delete` only branches on
+ * `len(matches) == 1`, treating both zero AND multiple matches as "not found".
+ * This is the deliberate asymmetry the plan calls out; it is expressed here,
+ * in presentation, not inside the shared resolver.
+ */
+export function applyTasksDelete(db: WritableDatabase, idOrPrefix: string): DeleteOutcome {
+  const resolved = resolveTaskByIdOrPrefix(db, idOrPrefix);
+  if (resolved.kind !== "found") return { kind: "not_found", idOrPrefix };
+  deleteTaskById(db, resolved.task.id);
+  return { kind: "deleted", task: resolved.task };
+}