mulmoclaude 2.3.0 → 2.4.1

package/server/events/pub-sub/handshakeAuth.ts

@@ -0,0 +1,9 @@
+import { isAuthorizedToken } from "@mulmoclaude/common/token-guard";
+import { isRecord } from "../../utils/types.js";
+
+// `auth` is whatever the socket.io client put in `io({ auth })`. Only a record
+// whose `token` passes the shared bearer rule connects; a server with no token
+// yet refuses everything, as `bearerAuth` does for HTTP.
+export function isAuthorizedPubSubHandshake(auth: unknown, expectedToken: string | null): boolean {
+  return isRecord(auth) && isAuthorizedToken(auth.token, expectedToken);
+}

package/server/events/pub-sub/index.ts

@@ -1,26 +1,59 @@
 import http from "http";
-import { Server as IOServer } from "socket.io";
+import { Server as IOServer, type Socket } from "socket.io";
 
+import { UNAUTHORIZED_MESSAGE } from "@mulmoclaude/common/token-guard";
 import { log } from "../../system/logger/index.js";
+import { isAuthorizedPubSubHandshake } from "./handshakeAuth.js";
 
 export interface IPubSub {
   /** Publish data to all clients subscribed to this channel. */
   publish: (channel: string, data: unknown) => void;
 }
 
+export interface PubSubOptions {
+  /** The bearer token a handshake must present. `null` while the server
+   *  has none yet, which refuses every handshake. */
+  tokenProvider: () => string | null;
+}
+
 const logRoomError =
   (action: string, channel: string) =>
   (err: unknown): void => {
     log.warn("pubsub", `socket room ${action} failed`, { channel, error: String(err) });
   };
 
+// `join`/`leave` return `void | Promise<void>`: the in-memory adapter runs
+// synchronously and returns undefined, while a clustered adapter goes over
+// the wire. Nothing here depends on the result, but the promise branch
+// still needs a terminal handler — a bare `void` would turn an adapter
+// failure into an unhandled rejection. `Promise.resolve` normalises both.
+function bindRoomEvents(socket: Socket): void {
+  socket.on("subscribe", (channel: unknown) => {
+    if (typeof channel === "string") Promise.resolve(socket.join(channel)).catch(logRoomError("subscribe", channel));
+  });
+  socket.on("unsubscribe", (channel: unknown) => {
+    if (typeof channel === "string") Promise.resolve(socket.leave(channel)).catch(logRoomError("unsubscribe", channel));
+  });
+}
+
+// A refused handshake leaves the engine.io connection open, and that one
+// connection can keep sending CONNECT packets; one line per connection keeps
+// a misconfigured relay diagnosable without letting a loop fill the log.
+const warnedConnections = new WeakSet<object>();
+
+function warnRefusedOnce(socket: Socket): void {
+  if (warnedConnections.has(socket.conn)) return;
+  warnedConnections.add(socket.conn);
+  log.warn("pubsub", "handshake refused: bearer token missing or invalid", { address: socket.handshake.address });
+}
+
 // Channel names are treated as socket.io rooms — one room per
 // channel. Subscribe/unsubscribe is plain `socket.join` /
 // `socket.leave`. Publish broadcasts to the room. Reconnect /
 // heartbeat / multi-transport fallback are handled by socket.io
 // itself, which is why we switched off raw ws.
 
-export function createPubSub(server: http.Server): IPubSub {
+export function createPubSub(server: http.Server, options: PubSubOptions): IPubSub {
   const ioServer = new IOServer(server, {
     path: "/ws/pubsub",
     // Server binds to 127.0.0.1 only, so CORS is moot — but
@@ -36,20 +69,20 @@ export function createPubSub(server: http.Server): IPubSub {
     transports: ["websocket"],
   });
 
-  ioServer.on("connection", (socket) => {
-    // `join`/`leave` return `void | Promise<void>`: the in-memory adapter runs
-    // synchronously and returns undefined, while a clustered adapter goes over
-    // the wire. Nothing here depends on the result, but the promise branch
-    // still needs a terminal handler — a bare `void` would turn an adapter
-    // failure into an unhandled rejection. `Promise.resolve` normalises both.
-    socket.on("subscribe", (channel: unknown) => {
-      if (typeof channel === "string") Promise.resolve(socket.join(channel)).catch(logRoomError("subscribe", channel));
-    });
-    socket.on("unsubscribe", (channel: unknown) => {
-      if (typeof channel === "string") Promise.resolve(socket.leave(channel)).catch(logRoomError("unsubscribe", channel));
-    });
+  // Same token every `/api/*` call presents (#3433). A refused handshake
+  // destroys the client socket, so socket.io does not retry it — the SPA
+  // reads that as "reload for a fresh token" rather than spinning.
+  ioServer.use((socket, next) => {
+    if (isAuthorizedPubSubHandshake(socket.handshake.auth, options.tokenProvider())) {
+      next();
+      return;
+    }
+    warnRefusedOnce(socket);
+    next(new Error(UNAUTHORIZED_MESSAGE));
   });
 
+  ioServer.on("connection", bindRoomEvents);
+
   return {
     publish(channel: string, data: unknown): void {
       ioServer.to(channel).emit("data", { channel, data });

package/server/index.ts

@@ -84,7 +84,6 @@ import { announceShadowedEnv, SHADOWED_ENV_KEYS_VAR } from "./system/shadowedEnv
 import { announceOptionalDeps } from "./system/announceOptionalDeps.js";
 import { announceGeminiKey } from "./system/announceGeminiKey.js";
 import { currentLaunchRouteFacts } from "./system/geminiKeyGuidance.js";
-import { migrateLegacyBillingPresets } from "./workspace/billing-migration.js";
 import { APP_VERSION } from "./system/appVersion.js";
 import { createChatService } from "@mulmobridge/chat-service";
 import { readSessionJsonl, readSessionMeta } from "./utils/files/session-io.js";
@@ -109,8 +108,7 @@ import { preflightUserServers, logPreflightResult } from "./agent/mcpPreflight.j
 import { loadMcpConfig, loadSettings } from "./system/config.js";
 import { getVoiceInputStatus, stopWhisperSidecar, warmupVoiceInput } from "./system/whisper/index.js";
 import { initWorkspace, workspacePath } from "./workspace/workspace.js";
-import { runMemoryMigrationOnce } from "./workspace/memory/run.js";
-import { runTopicMigrationOnce } from "./workspace/memory/topic-run.js";
+import { startMemoryMigrations } from "./workspace/memory/startup.js";
 import { migrateCookingRecipesFromPlugin } from "./workspace/cooking-recipes/migrate.js";
 import { env, isAblated, isGeminiAvailable } from "./system/env.js";
 import { buildSandboxStatus } from "./api/sandboxStatus.js";
@@ -242,27 +240,21 @@ warnIfCspExtended();
 //
 // Both runners are idempotent: legacy no-ops when the source file
 // is gone, topic no-ops when the workspace already uses the topic
-// format or staging is already pending review. The agent can serve
-// traffic while the chain runs.
-//
-// `.then(noop, noop)` keeps the floating-promises rule happy
-// without smuggling in a `void` (banned by sonarjs/void-use). Each
-// runner logs its own failures; the chain's outer rejection
-// handler is therefore a hard backstop only.
+// format, and retries the swap when staging is left from a crash. The agent can serve
+// traffic while the chain runs, but the journal waits for it
+// (`memoryMigrationsSettled`) so its extractor can't append to a
+// `memory.md` that is mid-migration.
 //
 // CLEANUP 2026-07-01: this whole chain is one-shot migration code
 // for #1029 + #1070. After every active workspace has flipped to
 // the topic format, delete the chain plus the runners under
-// `server/workspace/memory/` (run.ts / migrate.ts /
+// `server/workspace/memory/` (startup.ts + the journal's wait on it / run.ts / migrate.ts /
 // llm-classifier.ts / topic-run.ts / topic-migrate.ts /
 // topic-cluster.ts / topic-swap.ts) and the
 // `scripts/memory-swap-topic-staging.ts` helper. Topic-format
 // reading / writing (`topic-types.ts`, `topic-io.ts`,
 // `topic-detect.ts`) plus the topic branch in `prompt.ts` stays.
-const noop = (): void => {};
-runMemoryMigrationOnce(workspacePath)
-  .then(() => runTopicMigrationOnce(workspacePath))
-  .then(noop, noop);
+startMemoryMigrations(workspacePath);
 
 // Recipe-book plugin → `mc-cooking-coach` skill migration (#1286).
 // Boot-time idempotent copy from the plugin's `files.data` scope
@@ -1081,13 +1073,6 @@ async function initBootDiagnostics(): Promise<void> {
   // inside the request. No-op when voice input is off / not ready.
   warmupVoiceInput(bootSettings);
 
-  // --- Billing-suite migration ---
-  // The invoicing collections moved from bundled `mc-*` presets to
-  // help-file recipes. Remove any lingering starred `mc-*` billing
-  // skill from `.claude/skills/` (records preserved) and fire a
-  // one-time bell. No-op once the dirs are gone. Never throws.
-  migrateLegacyBillingPresets();
-
   // --- Collection completion watchers ---
   // Mount `fs.watch` over every discovered collection's dataDir so
   // schemas with `completionField` fire / clear bell notifications
@@ -1548,7 +1533,7 @@ process.on("SIGTERM", () => {
     // (CodeRabbit review on PR #1196). Both `createPubSub` and
     // `initNotifier` are sync, so wiring them up here costs nothing
     // and closes the window.
-    const earlyPubsub = createPubSub(httpServer);
+    const earlyPubsub = createPubSub(httpServer, { tokenProvider: getCurrentToken });
     initNotifier({
       publish: (channel, payload) => earlyPubsub.publish(channel, payload),
     });

package/server/plugins/dev-watcher.ts

@@ -6,7 +6,7 @@
 // chokidar to avoid pulling another runtime dependency. Recursive
 // watching is reliable on macOS / Linux / Windows starting from Node
 // 20.12 (Linux had race conditions and crash-on-delete bugs in earlier
-// 20.x patches), which engines.node (>=22.19) clears comfortably.
+// 20.x patches), which engines.node clears comfortably.
 //
 // The publish + warnServerSideChange callbacks are injected so tests
 // can exercise the debounce + classification logic without booting the

package/server/prompts/system/system.md

@@ -19,9 +19,8 @@ All data lives in the workspace directory as plain files:
 - `conversations/chat/` — chat session history (one .jsonl per session)
 - `conversations/memory/` — distilled user facts as topic files (`<type>/<topic>.md`); see the Memory section below for the index and read rules.
 - `conversations/summaries/` — journal output (daily / topics / archive)
-- `data/contacts/` — address book entries
 - `data/wiki/` — personal knowledge wiki (index.md, pages/, sources/, log.md)
-- `data/scheduler/` — scheduled tasks
+- `config/scheduler/tasks.json` — scheduled tasks (Automations)
 - `artifacts/documents/`, `artifacts/images/`, `artifacts/html/`, `artifacts/charts/`, `artifacts/spreadsheets/`, `artifacts/stories/` — LLM-generated output
 - `config/` — settings.json, mcp.json, roles/, helps/
 - `github/` — git-cloned repositories. Clone here, not /tmp/. If the dir already exists with the same remote, `git pull` to update. If a different remote, ask the user for a new dir name.

package/server/utils/launcher/preflight.d.mts

@@ -1,17 +1,20 @@
 // Type declarations for preflight.mjs.
 
-export interface NodeVersionRequirement {
+export interface NodeVersion {
   major: number;
   minor: number;
+  patch: number;
 }
 
-export const REQUIRED_NODE: NodeVersionRequirement;
+export const REQUIRED_NODE: readonly NodeVersion[];
 
-export function parseNodeVersion(raw: string): NodeVersionRequirement | null;
+export function parseNodeVersion(raw: string): NodeVersion | null;
 
-export function isNodeVersionSupported(raw: string, required?: NodeVersionRequirement): boolean;
+export function isNodeVersionSupported(raw: string, required?: readonly NodeVersion[]): boolean;
 
-export function formatRequiredNode(required?: NodeVersionRequirement): string;
+export function formatRequiredNode(required?: readonly NodeVersion[]): string;
+
+export function formatEnginesRange(required?: readonly NodeVersion[]): string;
 
 export interface CommandProbeOptions {
   env?: Record<string, string | undefined>;

package/server/utils/launcher/preflight.mjs

@@ -9,7 +9,13 @@ import { execFileSync } from "node:child_process";
 
 // Mirrors `engines.node` in packages/mulmoclaude/package.json.
 // test/utils/launcher/test_preflight.ts fails if the two drift.
-export const REQUIRED_NODE = { major: 22, minor: 19 };
+// One floor per supported major; the last also admits every later major,
+// and a major with no floor of its own (23, 25) is unsupported.
+export const REQUIRED_NODE = [
+  { major: 22, minor: 22, patch: 2 },
+  { major: 24, minor: 15, patch: 0 },
+  { major: 26, minor: 0, patch: 0 },
+];
 
 // These probes run a local binary that reads its own package metadata;
 // anything past a few seconds means it is wedged, not slow.
@@ -22,30 +28,50 @@ const COMMAND_PROBE_TIMEOUT_MS = 5000;
  * Returns null for anything unparseable rather than guessing — an
  * unknown version must not silently pass the requirement.
  * @param {string} raw
- * @returns {{ major: number, minor: number } | null}
+ * @returns {import("./preflight.d.mts").NodeVersion | null}
  */
 export function parseNodeVersion(raw) {
   if (typeof raw !== "string") return null;
-  const match = /^v?(\d+)\.(\d+)\./.exec(raw.trim());
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
   if (!match) return null;
-  return { major: Number(match[1]), minor: Number(match[2]) };
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+function compareVersions(left, right) {
+  return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+
+function floorFor(found, required) {
+  const newest = required[required.length - 1];
+  if (found.major > newest.major) return newest;
+  return required.find((floor) => floor.major === found.major);
 }
 
 /**
  * @param {string} raw
- * @param {{ major: number, minor: number }} [required]
+ * @param {readonly import("./preflight.d.mts").NodeVersion[]} [required]
  * @returns {boolean}
  */
 export function isNodeVersionSupported(raw, required = REQUIRED_NODE) {
   const found = parseNodeVersion(raw);
   if (found === null) return false;
-  if (found.major !== required.major) return found.major > required.major;
-  return found.minor >= required.minor;
+  const floor = floorFor(found, required);
+  return floor !== undefined && compareVersions(found, floor) >= 0;
+}
+
+function formatVersion({ major, minor, patch }) {
+  return `${major}.${minor}.${patch}`;
 }
 
 /** Human-readable form of a requirement, for the {required} placeholder. */
 export function formatRequiredNode(required = REQUIRED_NODE) {
-  return `${required.major}.${required.minor}`;
+  return required.map(formatVersion).join(" / ");
+}
+
+/** The same requirement as an `engines.node` range. */
+export function formatEnginesRange(required = REQUIRED_NODE) {
+  const carets = required.slice(0, -1).map((floor) => `^${formatVersion(floor)}`);
+  return [...carets, `>=${formatVersion(required[required.length - 1])}`].join(" || ");
 }
 
 /**

package/server/workspace/journal/index.ts

@@ -18,6 +18,7 @@ import { buildIndexMarkdown, type IndexTopicEntry, type IndexDailyEntry } from "
 import { runClaudeCli, ClaudeCliNotFoundError, type Summarize, type JournalSummaryModel } from "./archivist-cli.js";
 import { extractFirstH1 } from "@mulmoclaude/markdown-utils/markdown/extractFirstH1";
 import { log } from "../../system/logger/index.js";
+import { memoryMigrationsSettled } from "../memory/startup.js";
 import { journalMode as resolveJournalMode, loadSettings, type JournalMode } from "../../system/config.js";
 
 export { extractFirstH1 };
@@ -57,6 +58,8 @@ export async function maybeRunJournal(opts: MaybeRunJournalOptions = {}): Promis
   if (mode === "off") return;
   running = true;
   try {
+    // Waiting under the lock makes triggers that arrive meanwhile return instead of queueing a second pass.
+    await memoryMigrationsSettled();
     await runJournalPass(opts, mode);
   } catch (err) {
     if (err instanceof ClaudeCliNotFoundError) {

package/server/workspace/journal/memoryExtractor.ts

@@ -7,6 +7,7 @@ import { WORKSPACE_FILES } from "../paths.js";
 import { writeFileAtomic } from "../../utils/files/atomic.js";
 import { log } from "../../system/logger/index.js";
 import { ClaudeCliNotFoundError } from "./archivist-cli.js";
+import { hasTopicFormat } from "../memory/topic-detect.js";
 
 const EXTRACTION_SYSTEM_PROMPT = `You are a personal-fact extractor. Given a batch of chat excerpts between a user and an AI assistant, extract ONLY durable facts about the USER — things that would still be true next week.
 
@@ -39,6 +40,11 @@ export interface MemoryExtractionDeps {
 }
 
 export async function extractAndAppendMemory(deps: MemoryExtractionDeps): Promise<number> {
+  // Same predicate the prompt reader uses: in topic format memory.md is never read, so writing it only grows a dead file.
+  if (hasTopicFormat(deps.workspaceRoot)) {
+    log.debug("memory-extractor", "topic-format workspace, skipping legacy memory.md extraction");
+    return 0;
+  }
   const memoryPath = path.join(deps.workspaceRoot, WORKSPACE_FILES.memory);
   const existingMemory = existsSync(memoryPath) ? readFileSync(memoryPath, "utf-8") : "";
 

package/server/workspace/memory/legacy-fold.ts

@@ -0,0 +1,34 @@
+// Bullets from a leftover `conversations/memory.md` that the atomic → topic cluster must include, or they drop out of
+// the prompt at the swap (#3460). By the time topic migration clusters, a present `memory.md` is never going to be
+// handled by the #1029 migration: it sits beside `.backup`, or is under its placeholder threshold.
+
+import type { MemoryCandidate } from "./migrate.js";
+import type { MemoryEntry, MemoryType } from "./types.js";
+
+// Nothing classifies these bullets; the clusterer files them by the type it is given.
+export const FOLDED_LEGACY_TYPE: MemoryType = "fact";
+
+const FOLDED_NAME_MAX_CHARS = 80;
+
+function dedupeKey(text: string): string {
+  return text.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/** Turn legacy bullets into cluster input, skipping any already present as an atomic entry body or earlier bullet. */
+export function legacyFoldEntries(candidates: readonly MemoryCandidate[], atomicEntries: readonly MemoryEntry[]): MemoryEntry[] {
+  const seen = new Set(atomicEntries.map((entry) => dedupeKey(entry.body)));
+  const folded: MemoryEntry[] = [];
+  candidates.forEach((candidate, index) => {
+    const key = dedupeKey(candidate.body);
+    if (key.length === 0 || seen.has(key)) return;
+    seen.add(key);
+    folded.push({
+      type: FOLDED_LEGACY_TYPE,
+      name: candidate.body.slice(0, FOLDED_NAME_MAX_CHARS),
+      description: candidate.section || "from conversations/memory.md",
+      body: candidate.body,
+      slug: `${FOLDED_LEGACY_TYPE}_legacy-${index}`,
+    });
+  });
+  return folded;
+}

package/server/workspace/memory/legacy-migration-gate.ts

@@ -0,0 +1,27 @@
+// Decides whether the one-shot `memory.md` → atomic migration (#1029) may run, from facts the
+// caller has already read off disk. Pure so every skip reason can be tested without a workspace.
+
+// The init placeholder we used to write was smaller than this; a file this small has no facts.
+export const LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES = 64;
+
+export interface LegacyMemoryState {
+  /** Size of `conversations/memory.md`, or null when the file is absent. */
+  legacySizeBytes: number | null;
+  /** `memory.md.backup` exists — the marker a previous migration completed. */
+  backupExists: boolean;
+  /** The workspace already uses the topic layout (#1070). */
+  topicFormat: boolean;
+}
+
+export type LegacyMigrationSkipReason = "no-legacy-file" | "topic-format" | "placeholder" | "already-migrated";
+
+export type LegacyMigrationGate = { run: true } | { run: false; reason: LegacyMigrationSkipReason };
+
+export function decideLegacyMigration(state: LegacyMemoryState): LegacyMigrationGate {
+  if (state.legacySizeBytes === null) return { run: false, reason: "no-legacy-file" };
+  // Atomic files written into a topic `memory/` are never read and never re-clustered.
+  if (state.topicFormat) return { run: false, reason: "topic-format" };
+  if (state.legacySizeBytes < LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES) return { run: false, reason: "placeholder" };
+  if (state.backupExists) return { run: false, reason: "already-migrated" };
+  return { run: true };
+}

package/server/workspace/memory/llm-classifier.ts

@@ -18,10 +18,8 @@ import type { MemoryClassification, MemoryCandidate, MemoryClassifier } from "./
 import { isMemoryType } from "./types.js";
 import { extractFirstObject, stripFenceAndWhitespace } from "./llm-json.js";
 
-import { ClaudeCliNotFoundError, type Summarize } from "../journal/archivist-cli.js";
-import { errorMessage } from "../../utils/errors.js";
+import type { Summarize } from "../journal/archivist-cli.js";
 import { isRecord } from "../../utils/types.js";
-import { log } from "../../system/logger/index.js";
 
 const SYSTEM_PROMPT = `You are classifying a single bullet from a personal-memory file into one of four types.
 
@@ -46,26 +44,10 @@ interface DepsForLlmClassifier {
 }
 
 export function makeLlmMemoryClassifier(deps: DepsForLlmClassifier): MemoryClassifier {
+  // A failed call throws (CLI missing, quota, auth, timeout) so the migration can tell it apart from
+  // the LLM deliberately answering `null` — only the latter is a real skip.
   return async (candidate: MemoryCandidate) => {
-    const userPrompt = buildUserPrompt(candidate);
-    let raw: string;
-    try {
-      raw = await deps.summarize(SYSTEM_PROMPT, userPrompt);
-    } catch (err) {
-      // Let `ClaudeCliNotFoundError` escape so the caller can abort
-      // the whole migration. Without this, every candidate runs
-      // through the classifier, gets `null` back, and migrateLegacyMemory
-      // produces an empty result + (pre-#1091) renames the legacy file
-      // to `.backup`. Even with #1091 the user pays N classifier
-      // failures (each spawns claude) before realising the CLI is
-      // missing (#1061 review).
-      if (err instanceof ClaudeCliNotFoundError) throw err;
-      log.warn("memory", "llm classifier: summarize threw", {
-        preview: candidate.body.slice(0, 80),
-        error: errorMessage(err),
-      });
-      return null;
-    }
+    const raw = await deps.summarize(SYSTEM_PROMPT, buildUserPrompt(candidate));
     return parseClassifierVerdict(raw);
   };
 }

package/server/workspace/memory/migrate.ts

@@ -58,8 +58,13 @@ export interface MigrationResult {
    *  surface to the user. The migration continues past write errors
    *  so a single bad entry doesn't strand the whole batch. */
   writeErrors: number;
+  /** Candidates whose classifier call failed. Any failure aborts before writing or renaming,
+   *  so `memory.md` stays readable and the next start retries. */
+  classifierFailures: number;
 }
 
+type ClassifyOutcome = { kind: "classified"; classification: MemoryClassification } | { kind: "skipped" } | { kind: "failed" };
+
 // Number of in-flight `classify` calls. Each call spawns the Claude
 // CLI, so there's a real cost to going wide; 4 is empirically a
 // sweet spot — well above the 1-at-a-time baseline (~10× faster on
@@ -85,13 +90,35 @@ export async function migrateLegacyMemory(workspaceRoot: string, classify: Memor
     candidateCount: candidates.length,
     concurrency: CLASSIFY_CONCURRENCY,
   });
-  const classifications = await classifyInParallel(classify, candidates);
+  const outcomes = await classifyInParallel(classify, candidates);
 
   const result = emptyResult(false);
+  result.classifierFailures = outcomes.filter((outcome) => outcome.kind === "failed").length;
+  if (result.classifierFailures > 0) {
+    log.warn("memory", "migration: classifier failed, leaving memory.md in place for the next start", {
+      classifierFailures: result.classifierFailures,
+      candidateCount: candidates.length,
+    });
+    return result;
+  }
+  await writeClassifiedEntries(workspaceRoot, candidates, outcomes, result);
+
+  await regenerateIndex(workspaceRoot);
+  await renameToBackup(sourcePath);
+  return result;
+}
+
+async function writeClassifiedEntries(
+  workspaceRoot: string,
+  candidates: readonly MemoryCandidate[],
+  outcomes: readonly ClassifyOutcome[],
+  result: MigrationResult,
+): Promise<void> {
   const usedSlugs = new Set<string>();
 
   for (const [index, candidate] of candidates.entries()) {
-    const classification = classifications[index];
+    const outcome = outcomes[index];
+    const classification = outcome?.kind === "classified" ? outcome.classification : null;
     if (!classification) {
       result.skippedByClassifier += 1;
     } else {
@@ -119,32 +146,35 @@ export async function migrateLegacyMemory(workspaceRoot: string, classify: Memor
       });
     }
   }
-
-  await regenerateIndex(workspaceRoot);
-  await renameToBackup(sourcePath);
-  return result;
 }
 
 // Classify candidates with bounded concurrency. Workers pull
 // indices off a shared cursor and write into a pre-allocated array
 // so `result[i]` matches `candidates[i]`. Each await falls inside
-// `safeClassify`, which already swallows individual classifier
-// throws (logging once); a concurrent failure can therefore not
-// poison the rest of the batch.
-async function classifyInParallel(classify: MemoryClassifier, candidates: readonly MemoryCandidate[]): Promise<(MemoryClassification | null)[]> {
-  // `Array.from`, not `new Array(n).fill(null)`: `fill` on the `any[]` that
-  // `new Array(n)` produces keeps the element type `any`. Both build the same
-  // dense array of nulls.
-  const results: (MemoryClassification | null)[] = Array.from({ length: candidates.length }, () => null);
+// `safeClassify`, which turns an individual classifier throw into a
+// `failed` outcome (logging once); a concurrent failure can therefore
+// not poison the rest of the batch.
+async function classifyInParallel(classify: MemoryClassifier, candidates: readonly MemoryCandidate[]): Promise<ClassifyOutcome[]> {
+  const results: ClassifyOutcome[] = Array.from({ length: candidates.length }, (): ClassifyOutcome => ({ kind: "skipped" }));
   let nextIndex = 0;
+  // One failure already aborts the migration, so stop spending classifier calls on the rest.
+  let failed = false;
   const worker = async (): Promise<void> => {
-    while (true) {
+    while (!failed) {
       const index = nextIndex;
       nextIndex += 1;
       const candidate = candidates[index];
       // Absent element == the shared cursor ran past the end.
       if (candidate === undefined) return;
-      results[index] = await safeClassify(classify, candidate);
+      let outcome: ClassifyOutcome;
+      try {
+        outcome = await safeClassify(classify, candidate);
+      } catch (err) {
+        failed = true;
+        throw err;
+      }
+      results[index] = outcome;
+      if (outcome.kind === "failed") failed = true;
     }
   };
   const workers = Array.from({ length: Math.min(CLASSIFY_CONCURRENCY, candidates.length) }, () => worker());
@@ -158,6 +188,7 @@ function emptyResult(noop: boolean): MigrationResult {
     written: { preference: 0, interest: 0, fact: 0, reference: 0 },
     skippedByClassifier: 0,
     writeErrors: 0,
+    classifierFailures: 0,
   };
 }
 
@@ -167,7 +198,7 @@ function emptyResult(noop: boolean): MigrationResult {
 // rides along as `section` so the classifier can use it as context.
 // Parsing is character-driven (no regex) to keep sonar happy and to
 // make the bullet-vs-header classification obvious from the code.
-function parseCandidates(raw: string): MemoryCandidate[] {
+export function parseCandidates(raw: string): MemoryCandidate[] {
   const lines = raw.split("\n");
   let section = "";
   const out: MemoryCandidate[] = [];
@@ -200,11 +231,11 @@ function extractBullet(line: string): string | null {
   return body.length > 0 ? body : null;
 }
 
-async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandidate): Promise<MemoryClassification | null> {
+async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandidate): Promise<ClassifyOutcome> {
   try {
     const verdict = await classify(candidate);
-    if (verdict && isMemoryType(verdict.type)) return verdict;
-    return null;
+    if (verdict && isMemoryType(verdict.type)) return { kind: "classified", classification: verdict };
+    return { kind: "skipped" };
   } catch (err) {
     // Startup-wide failures (CLI missing) MUST escape so
     // `runMemoryMigrationOnce` can log once + leave the legacy file
@@ -216,7 +247,7 @@ async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandida
       preview: candidate.body.slice(0, 80),
       error: errorMessage(err),
     });
-    return null;
+    return { kind: "failed" };
   }
 }