codemem 0.30.0-alpha.2 → 0.30.0-alpha.4

package/dist/index.js

@@ -3118,11 +3118,22 @@ cmd$1.action((inputFile, opts) => {
 			`Prompts:        ${payload.user_prompts.length.toLocaleString()}`
 		].join("\n"));
 	}
-	const result = importMemories(payload, {
-		dbPath: resolveDbPath(resolveDbOpt(opts)),
-		remapProject: opts.remapProject,
-		dryRun: opts.dryRun
-	});
+	let result;
+	try {
+		result = importMemories(payload, {
+			dbPath: resolveDbPath(resolveDbOpt(opts)),
+			remapProject: opts.remapProject,
+			dryRun: opts.dryRun
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Import failed";
+		if (opts.json) emitJsonError("import_failed", message);
+		else {
+			p.log.error(message);
+			process.exitCode = 1;
+		}
+		return;
+	}
 	if (opts.json) {
 		console.log(JSON.stringify({
 			sessions: result.sessions,
@@ -3145,11 +3156,193 @@ cmd$1.action((inputFile, opts) => {
 });
 var importMemoriesCommand = cmd$1;
 //#endregion
+//#region src/maintenance-worker-runtime.ts
+var defaultLogger = {
+	step: (message) => console.error(message),
+	warn: (message) => console.error(`Warning: ${message}`),
+	error: (message) => console.error(`Error: ${message}`)
+};
+function readWorkerSyncConfig(configPath) {
+	return readCoordinatorSyncConfig(configPath ? readCodememConfigFileAtPath(configPath) : readCodememConfigFile());
+}
+function createSequentialBackfillCoordinator(store, jobPlans, options) {
+	const pollIntervalMs = 1e3;
+	let activeRunner = null;
+	let activePlan = null;
+	let activePollTimer = null;
+	let nextJobIndex = 0;
+	let stopped = false;
+	const clearPollTimer = () => {
+		if (!activePollTimer) return;
+		clearTimeout(activePollTimer);
+		activePollTimer = null;
+	};
+	const schedulePoll = (fn) => {
+		clearPollTimer();
+		activePollTimer = setTimeout(fn, pollIntervalMs);
+		if (typeof activePollTimer === "object" && "unref" in activePollTimer) activePollTimer.unref();
+	};
+	const startNextJob = () => {
+		clearPollTimer();
+		if (stopped || options.signal?.aborted) return;
+		while (nextJobIndex < jobPlans.length) {
+			const plan = jobPlans[nextJobIndex++];
+			if (!plan) continue;
+			if (!plan.isPending(store.db)) continue;
+			activePlan = plan;
+			activeRunner = plan.createRunner();
+			options.logger.step(`${plan.name} backfill started`);
+			activeRunner.start();
+			schedulePoll(waitForCurrentJob);
+			return;
+		}
+		options.logger.step("All backfill jobs complete");
+	};
+	const waitForCurrentJob = () => {
+		if (stopped || options.signal?.aborted || !activePlan || !activeRunner) return;
+		const job = getMaintenanceJob(store.db, activePlan.kind);
+		if (!activePlan.isPending(store.db)) {
+			const finishedPlan = activePlan;
+			const finishedRunner = activeRunner;
+			activePlan = null;
+			activeRunner = null;
+			finishedRunner.stop().finally(() => {
+				if (!stopped && !options.signal?.aborted) {
+					options.logger.step(`${finishedPlan.name} backfill complete`);
+					startNextJob();
+				}
+			});
+			return;
+		}
+		if (job?.status === "failed") {
+			const failedPlan = activePlan;
+			const failedRunner = activeRunner;
+			activePlan = null;
+			activeRunner = null;
+			failedRunner.stop().finally(() => {
+				if (!stopped && !options.signal?.aborted) {
+					options.logger.warn(`${failedPlan.name} backfill failed and will be retried on a later startup`);
+					startNextJob();
+				}
+			});
+			return;
+		}
+		schedulePoll(waitForCurrentJob);
+	};
+	return {
+		start: () => {
+			if (stopped || options.signal?.aborted) return;
+			const pendingCount = jobPlans.filter((plan) => plan.isPending(store.db)).length;
+			if (pendingCount === 0) return;
+			options.logger.step(`${pendingCount} backfill job(s) pending — starting sequential runners`);
+			startNextJob();
+		},
+		stop: async () => {
+			stopped = true;
+			clearPollTimer();
+			const runner = activeRunner;
+			activeRunner = null;
+			activePlan = null;
+			if (runner) await runner.stop();
+		}
+	};
+}
+function startMaintenanceWorkerRuntime(options = {}) {
+	const logger = options.logger ?? defaultLogger;
+	const dbPath = resolveDbPath(options.dbPath ?? void 0);
+	const store = new MemoryStore(dbPath);
+	const syncConfig = readWorkerSyncConfig(options.configPath);
+	const runners = [];
+	const walCheckpointTimer = setInterval(() => {
+		try {
+			store.db.pragma("wal_checkpoint(TRUNCATE)");
+		} catch (error) {
+			logger.warn(`WAL checkpoint failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}, 300 * 1e3);
+	walCheckpointTimer.unref();
+	if (!isEmbeddingDisabled()) runners.push(new VectorModelMigrationRunner({
+		dbPath,
+		signal: options.signal,
+		idleIntervalMs: 5e3
+	}));
+	runners.push(createSequentialBackfillCoordinator(store, [
+		{
+			name: "Sharing-domain",
+			kind: SCOPE_BACKFILL_JOB,
+			isPending: hasPendingScopeBackfill,
+			createRunner: () => new ScopeBackfillRunner({
+				dbPath,
+				signal: options.signal
+			})
+		},
+		{
+			name: "Dedup-key",
+			kind: DEDUP_KEY_BACKFILL_JOB,
+			isPending: hasPendingDedupKeyBackfill,
+			createRunner: () => new DedupKeyBackfillRunner({
+				dbPath,
+				signal: options.signal
+			})
+		},
+		{
+			name: "Session-context",
+			kind: SESSION_CONTEXT_BACKFILL_JOB,
+			isPending: hasPendingSessionContextBackfill,
+			createRunner: () => new SessionContextBackfillRunner({
+				dbPath,
+				signal: options.signal
+			})
+		},
+		{
+			name: "Ref",
+			kind: REF_BACKFILL_JOB,
+			isPending: hasPendingRefBackfill,
+			createRunner: () => new RefBackfillRunner({
+				dbPath,
+				signal: options.signal
+			})
+		},
+		{
+			name: "Session-summary dedup",
+			kind: SUMMARY_DEDUP_BACKFILL_JOB,
+			isPending: hasPendingSummaryDedupBackfill,
+			createRunner: () => new SummaryDedupBackfillRunner({
+				dbPath,
+				deviceId: store.deviceId,
+				signal: options.signal
+			})
+		}
+	], {
+		signal: options.signal,
+		logger
+	}));
+	if (syncConfig.syncRetentionEnabled) runners.push(new SyncRetentionRunner({
+		dbPath,
+		signal: options.signal
+	}));
+	for (const runner of runners) runner.start();
+	logger.step("Maintenance worker started");
+	return {
+		start: () => {
+			for (const runner of runners) runner.start();
+		},
+		stop: async () => {
+			clearInterval(walCheckpointTimer);
+			for (const runner of [...runners].reverse()) await runner.stop();
+			store.close();
+		}
+	};
+}
+//#endregion
 //#region src/commands/maintenance.ts
 var maintenanceCmd = new Command("maintenance").configureHelp(helpStyle).description("Inspect background maintenance / backfill jobs");
 var statusCmd$1 = new Command("status").configureHelp(helpStyle).description("Print current status of all maintenance jobs");
 addDbOption(statusCmd$1);
 addJsonOption(statusCmd$1);
+var workerCmd = new Command("worker").configureHelp(helpStyle).description("Run maintenance worker plumbing");
+addDbOption(workerCmd);
+addConfigOption(workerCmd);
 statusCmd$1.action((opts) => {
 	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
@@ -3163,7 +3356,48 @@ statusCmd$1.action((opts) => {
 		store.close();
 	}
 });
+async function runMaintenanceWorkerCommand(opts) {
+	const dbPath = resolveDbPath(resolveDbOpt(opts));
+	if (opts.config) process.env.CODEMEM_CONFIG = opts.config;
+	process.env.CODEMEM_DB = dbPath;
+	const abort = new AbortController();
+	const runtime = startMaintenanceWorkerRuntime({
+		dbPath,
+		configPath: opts.config ?? null,
+		signal: abort.signal
+	});
+	const keepAlive = setInterval(() => void 0, 6e4);
+	let stopping = false;
+	const shutdown = async () => {
+		if (stopping) return;
+		stopping = true;
+		abort.abort();
+		clearInterval(keepAlive);
+		const forceExit = setTimeout(() => {
+			process.exit(1);
+		}, 3e4);
+		try {
+			await runtime.stop();
+			process.exit(0);
+		} finally {
+			clearTimeout(forceExit);
+		}
+	};
+	await new Promise((resolve, reject) => {
+		process.once("SIGINT", () => void shutdown().then(resolve, reject));
+		process.once("SIGTERM", () => void shutdown().then(resolve, reject));
+	});
+}
+workerCmd.action(async (opts) => {
+	try {
+		await runMaintenanceWorkerCommand(opts);
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+});
 maintenanceCmd.addCommand(statusCmd$1);
+maintenanceCmd.addCommand(workerCmd, { hidden: true });
 var maintenanceCommand = maintenanceCmd;
 function printJobsTable(jobs) {
 	p.intro("codemem maintenance");
@@ -3343,6 +3577,14 @@ function forgetMemoryAction(idStr, opts) {
 	}
 	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
+		if (!store.get(memoryId)) {
+			if (opts.json) emitJsonError("not_found", `Memory ${memoryId} not found`);
+			else {
+				p.log.error(`Memory ${memoryId} not found`);
+				process.exitCode = 1;
+			}
+			return;
+		}
 		store.forget(memoryId);
 		if (opts.json) console.log(JSON.stringify({
 			id: memoryId,
@@ -3353,6 +3595,19 @@ function forgetMemoryAction(idStr, opts) {
 		store.close();
 	}
 }
+function rollbackManualMemory(store, sessionId, memoryId) {
+	store.db.transaction(() => {
+		const row = store.db.prepare("SELECT import_key FROM memory_items WHERE id = ?").get(memoryId);
+		store.db.prepare("DELETE FROM memory_vectors WHERE memory_id = ?").run(memoryId);
+		store.db.prepare("DELETE FROM memory_file_refs WHERE memory_id = ?").run(memoryId);
+		store.db.prepare("DELETE FROM memory_concept_refs WHERE memory_id = ?").run(memoryId);
+		store.db.prepare("DELETE FROM replication_ops WHERE entity_type = 'memory_item' AND (entity_id = ? OR entity_id = ?)").run(row?.import_key ?? "", String(memoryId));
+		store.db.prepare("DELETE FROM memory_items WHERE id = ?").run(memoryId);
+		store.db.prepare(`DELETE FROM sessions
+				 WHERE id = ?
+				   AND NOT EXISTS (SELECT 1 FROM memory_items WHERE session_id = ?)`).run(sessionId, sessionId);
+	})();
+}
 async function rememberMemoryAction(opts) {
 	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	let sessionId = null;
@@ -3366,8 +3621,14 @@ async function rememberMemoryAction(opts) {
 			metadata: { manual: true }
 		});
 		const memId = store.remember(sessionId, opts.kind, opts.title, opts.body, .5, opts.tags);
-		await store.flushPendingVectorWrites();
+		if (!store.get(memId)) {
+			await store.flushPendingVectorWrites();
+			rollbackManualMemory(store, sessionId, memId);
+			sessionId = null;
+			throw new Error("unauthorized_scope");
+		}
 		store.endSession(sessionId, { manual: true });
+		await store.flushPendingVectorWrites();
 		if (opts.json) console.log(JSON.stringify({ id: memId }));
 		else p.log.success(`Stored memory ${memId}`);
 	} catch (err) {
@@ -4149,7 +4410,7 @@ function warnIfViewerExposed(host, port) {
 function isLikelyViewerCommand(command) {
 	const lowered = command.toLowerCase();
 	if (!/\bserve\s+start\b/.test(lowered)) return false;
-	return lowered.includes("codemem") || lowered.includes("packages/cli/dist/index.js") || lowered.includes("/cli/dist/index.js");
+	return lowered.includes("codemem") || lowered.includes("packages/cli/dist/index.js") || lowered.includes("/cli/dist/index.js") || lowered.includes("packages/cli/src/index.ts");
 }
 function prepareViewerDatabase(dbPath) {
 	return initDatabase(dbPath ?? void 0).path;
@@ -4199,6 +4460,44 @@ function isTrustedViewerPid(pid, target, listenerPid) {
 function pidFilePath(dbPath) {
 	return join(dirname(dbPath), "viewer.pid");
 }
+function maintenanceWorkerPidFilePath(dbPath) {
+	return join(dirname(dbPath), "maintenance-worker.pid");
+}
+function readMaintenanceWorkerPidRecord(dbPath) {
+	const pidPath = maintenanceWorkerPidFilePath(dbPath);
+	if (!existsSync(pidPath)) return null;
+	const raw = readFileSync(pidPath, "utf-8").trim();
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "number" && Number.isFinite(parsed) && parsed > 0) return {
+			pid: Math.trunc(parsed),
+			dbPath: null
+		};
+		if (typeof parsed === "object" && parsed !== null && typeof parsed.pid === "number" && Number.isFinite(parsed.pid) && parsed.pid > 0) return {
+			pid: Math.trunc(parsed.pid),
+			dbPath: typeof parsed.dbPath === "string" ? resolveDbPath(parsed.dbPath) : null
+		};
+	} catch {
+		const parsed = Number.parseInt(raw, 10);
+		if (Number.isFinite(parsed) && parsed > 0) return {
+			pid: parsed,
+			dbPath: null
+		};
+	}
+	return null;
+}
+function isLikelyMaintenanceWorkerCommand(command) {
+	const lowered = command.toLowerCase();
+	if (!/\bmaintenance\s+worker\b/.test(lowered)) return false;
+	return lowered.includes("codemem") || lowered.includes("packages/cli/dist/index.js") || lowered.includes("/cli/dist/index.js") || lowered.includes("packages/cli/src/index.ts");
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function commandHasExactDbPath(command, dbPath) {
+	const escapedPath = escapeRegExp(resolveDbPath(dbPath));
+	return new RegExp(`(?:^|\\s)--db-path(?:=|\\s+)${escapedPath}(?:\\s|$)`).test(command);
+}
 function readViewerPidRecord(dbPath) {
 	const pidPath = pidFilePath(dbPath);
 	if (!existsSync(pidPath)) return null;
@@ -4289,6 +4588,44 @@ async function waitForProcessExit(pid, timeoutMs = 3e4) {
 	}
 	return !isProcessRunning(pid);
 }
+async function terminateProcessPid(pid, timeouts = {}) {
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {
+		return true;
+	}
+	if (await waitForProcessExit(pid, timeouts.gracefulMs ?? 3e4)) return true;
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch {
+		return true;
+	}
+	return waitForProcessExit(pid, timeouts.forceMs ?? 5e3);
+}
+async function terminateTrustedViewerPid(pid, timeouts = {}) {
+	return terminateProcessPid(pid, timeouts);
+}
+async function terminateTrustedMaintenanceWorker(dbPath, timeouts = {}) {
+	const pidPath = maintenanceWorkerPidFilePath(dbPath);
+	const record = readMaintenanceWorkerPidRecord(dbPath);
+	if (!record) return true;
+	const expectedDbPath = resolveDbPath(dbPath);
+	if (record.dbPath && record.dbPath !== expectedDbPath) return false;
+	if (!isProcessRunning(record.pid)) {
+		try {
+			rmSync(pidPath);
+		} catch {}
+		return true;
+	}
+	const command = readProcessCommand(record.pid);
+	if (!command || !isLikelyMaintenanceWorkerCommand(command)) return false;
+	if (record.dbPath !== expectedDbPath || !commandHasExactDbPath(command, expectedDbPath)) return false;
+	const stopped = await terminateProcessPid(record.pid, timeouts);
+	if (stopped) try {
+		rmSync(pidPath);
+	} catch {}
+	return stopped;
+}
 async function waitForPortRelease(host, port, timeoutMs = 1e4) {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
@@ -4298,21 +4635,13 @@ async function waitForPortRelease(host, port, timeoutMs = 1e4) {
 	return false;
 }
 async function stopExistingViewer(dbPath, target) {
-	const terminatePid = async (pid) => {
-		try {
-			process.kill(pid, "SIGTERM");
-			return await waitForProcessExit(pid);
-		} catch {
-			return true;
-		}
-	};
 	const pidPath = pidFilePath(dbPath);
 	const record = readViewerPidRecord(dbPath);
 	const viewerPidFromStats = await lookupViewerPidFromStats(target.host, target.port);
 	const listenerPid = lookupListeningPid(target.host, target.port);
 	const viewerPid = pickViewerPidCandidate(viewerPidFromStats, listenerPid);
 	if (viewerPid && isTrustedViewerPid(viewerPid, target, listenerPid)) {
-		if (!await terminatePid(viewerPid)) return {
+		if (!await terminateTrustedViewerPid(viewerPid)) return {
 			stopped: false,
 			pid: viewerPid
 		};
@@ -4328,12 +4657,19 @@ async function stopExistingViewer(dbPath, target) {
 		stopped: false,
 		pid: null
 	};
-	if (await respondsLikeCodememViewer(record)) {
-		if (!await terminatePid(record.pid)) return {
+	const recordListenerPid = lookupListeningPid(record.host, record.port);
+	if (await respondsLikeCodememViewer(record) && isTrustedViewerPid(record.pid, {
+		host: record.host,
+		port: record.port
+	}, recordListenerPid)) {
+		if (!await terminateTrustedViewerPid(record.pid)) return {
 			stopped: false,
 			pid: record.pid
 		};
-	}
+	} else return {
+		stopped: false,
+		pid: null
+	};
 	try {
 		rmSync(pidPath);
 	} catch {}
@@ -4357,6 +4693,56 @@ function buildForegroundRunnerArgs(scriptPath, invocation, execArgv = process.ex
 	if (invocation.dbPath) args.push("--db-path", invocation.dbPath);
 	return args;
 }
+function buildMaintenanceWorkerArgs(scriptPath, invocation, execArgv = process.execArgv) {
+	const args = [
+		...execArgv,
+		scriptPath,
+		"maintenance",
+		"worker"
+	];
+	if (invocation.dbPath) args.push("--db-path", invocation.dbPath);
+	if (invocation.configPath) args.push("--config", invocation.configPath);
+	return args;
+}
+function startMaintenanceWorkerProcess(invocation) {
+	const scriptPath = process.argv[1];
+	if (!scriptPath) {
+		p.log.warn("Unable to resolve CLI entrypoint for maintenance worker launch");
+		return null;
+	}
+	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
+	const child = spawn(process.execPath, buildMaintenanceWorkerArgs(scriptPath, invocation), {
+		cwd: process.cwd(),
+		stdio: "ignore",
+		env: {
+			...process.env,
+			CODEMEM_DB: dbPath,
+			...invocation.configPath ? { CODEMEM_CONFIG: invocation.configPath } : {}
+		}
+	});
+	child.unref();
+	if (child.pid) {
+		writeFileSync(maintenanceWorkerPidFilePath(dbPath), JSON.stringify({
+			pid: child.pid,
+			dbPath
+		}), "utf-8");
+		p.log.step(`Maintenance worker started (pid ${child.pid})`);
+	}
+	return child;
+}
+async function stopMaintenanceWorkerProcess(child, dbPath) {
+	if (child?.pid && isProcessRunning(child.pid)) await terminateProcessPid(child.pid, {
+		gracefulMs: 5e3,
+		forceMs: 5e3
+	});
+	else await terminateTrustedMaintenanceWorker(dbPath, {
+		gracefulMs: 5e3,
+		forceMs: 5e3
+	});
+	try {
+		rmSync(maintenanceWorkerPidFilePath(dbPath));
+	} catch {}
+}
 function isSqliteVecLoadFailure(error) {
 	if (!(error instanceof Error)) return false;
 	const text = error.message.toLowerCase();
@@ -4404,88 +4790,6 @@ async function startBackgroundViewer(invocation) {
 	p.intro("codemem viewer");
 	p.outro(`Viewer started in background (pid ${child.pid}) at http://${invocation.host}:${invocation.port}`);
 }
-function createSequentialBackfillCoordinator(store, jobPlans, signal) {
-	const pollIntervalMs = 1e3;
-	let activeRunner = null;
-	let activePlan = null;
-	let activePollTimer = null;
-	let nextJobIndex = 0;
-	let stopped = false;
-	const clearPollTimer = () => {
-		if (!activePollTimer) return;
-		clearTimeout(activePollTimer);
-		activePollTimer = null;
-	};
-	const schedulePoll = (fn) => {
-		clearPollTimer();
-		activePollTimer = setTimeout(fn, pollIntervalMs);
-		if (typeof activePollTimer === "object" && "unref" in activePollTimer) activePollTimer.unref();
-	};
-	const waitForCurrentJob = () => {
-		if (stopped || signal?.aborted || !activePlan || !activeRunner) return;
-		const job = getMaintenanceJob(store.db, activePlan.kind);
-		if (!activePlan.isPending(store.db)) {
-			const finishedPlan = activePlan;
-			const finishedRunner = activeRunner;
-			activePlan = null;
-			activeRunner = null;
-			finishedRunner.stop().finally(() => {
-				if (!stopped && !signal?.aborted) {
-					p.log.step(`${finishedPlan.name} backfill complete`);
-					startNextJob();
-				}
-			});
-			return;
-		}
-		if (job?.status === "failed") {
-			const failedPlan = activePlan;
-			const failedRunner = activeRunner;
-			activePlan = null;
-			activeRunner = null;
-			failedRunner.stop().finally(() => {
-				if (!stopped && !signal?.aborted) {
-					p.log.warn(`${failedPlan.name} backfill failed and will be retried on a later startup`);
-					startNextJob();
-				}
-			});
-			return;
-		}
-		schedulePoll(waitForCurrentJob);
-	};
-	const startNextJob = () => {
-		clearPollTimer();
-		if (stopped || signal?.aborted) return;
-		while (nextJobIndex < jobPlans.length) {
-			const plan = jobPlans[nextJobIndex++];
-			if (!plan) continue;
-			if (!plan.isPending(store.db)) continue;
-			activePlan = plan;
-			activeRunner = plan.createRunner();
-			p.log.step(`${plan.name} backfill started`);
-			activeRunner.start();
-			schedulePoll(waitForCurrentJob);
-			return;
-		}
-		p.log.step("All backfill jobs complete");
-	};
-	return {
-		start: () => {
-			if (stopped || signal?.aborted) return;
-			const pendingCount = jobPlans.filter((plan) => plan.isPending(store.db)).length;
-			if (pendingCount === 0) return;
-			p.log.step(`${pendingCount} backfill job(s) pending — starting sequential runners`);
-			startNextJob();
-		},
-		stop: async () => {
-			stopped = true;
-			clearPollTimer();
-			const runner = activeRunner;
-			activeRunner = null;
-			activePlan = null;
-			if (runner) await runner.stop();
-		}
-	};
-}
 async function startForegroundViewer(invocation) {
 	const { createApp, createSyncApp, closeStore, getStore } = await import("@codemem/server");
 	const { serve } = await import("@hono/node-server");
@@ -4514,67 +4818,13 @@ async function startForegroundViewer(invocation) {
 	const sweeper = new RawEventSweeper(store, { observer });
 	sweeper.start();
 	const syncAbort = new AbortController();
-	const retentionAbort = new AbortController();
-	const backfillAbort = new AbortController();
 	const syncConfig = readCoordinatorSyncConfig(invocation.configPath ? readCodememConfigFileAtPath(invocation.configPath) : readCodememConfigFile());
 	const syncEnabled = syncConfig.syncEnabled;
 	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
-	const retentionRunner = new SyncRetentionRunner({
-		dbPath,
-		signal: retentionAbort.signal
-	});
-	const vectorMigrationRunner = new VectorModelMigrationRunner({
-		dbPath,
-		signal: backfillAbort.signal
-	});
-	const backfillCoordinator = createSequentialBackfillCoordinator(store, [
-		{
-			name: "Sharing-domain",
-			kind: SCOPE_BACKFILL_JOB,
-			isPending: hasPendingScopeBackfill,
-			createRunner: () => new ScopeBackfillRunner({
-				dbPath,
-				signal: backfillAbort.signal
-			})
-		},
-		{
-			name: "Dedup-key",
-			kind: DEDUP_KEY_BACKFILL_JOB,
-			isPending: hasPendingDedupKeyBackfill,
-			createRunner: () => new DedupKeyBackfillRunner({
-				dbPath,
-				signal: backfillAbort.signal
-			})
-		},
-		{
-			name: "Session-context",
-			kind: SESSION_CONTEXT_BACKFILL_JOB,
-			isPending: hasPendingSessionContextBackfill,
-			createRunner: () => new SessionContextBackfillRunner({
-				dbPath,
-				signal: backfillAbort.signal
-			})
-		},
-		{
-			name: "Ref",
-			kind: REF_BACKFILL_JOB,
-			isPending: hasPendingRefBackfill,
-			createRunner: () => new RefBackfillRunner({
-				dbPath,
-				signal: backfillAbort.signal
-			})
-		},
-		{
-			name: "Session-summary dedup",
-			kind: SUMMARY_DEDUP_BACKFILL_JOB,
-			isPending: hasPendingSummaryDedupBackfill,
-			createRunner: () => new SummaryDedupBackfillRunner({
-				dbPath,
-				deviceId: store.deviceId,
-				signal: backfillAbort.signal
-			})
-		}
-	], backfillAbort.signal);
+	if (!await terminateTrustedMaintenanceWorker(dbPath, {
+		gracefulMs: 1e3,
+		forceMs: 5e3
+	})) p.log.warn("Existing maintenance worker is not trusted or did not stop; starting viewer anyway");
 	const syncRuntimeStatus = {
 		phase: syncEnabled ? "starting" : "disabled",
 		detail: syncEnabled ? "Waiting for viewer startup to finish" : "Sync is disabled"
@@ -4587,6 +4837,7 @@ async function startForegroundViewer(invocation) {
 	};
 	const app = createApp(appOpts);
 	const pidPath = pidFilePath(dbPath);
+	let maintenanceWorker = null;
 	let syncServer = null;
 	let syncListenerReady = false;
 	if (syncEnabled) {
@@ -4617,15 +4868,7 @@ async function startForegroundViewer(invocation) {
 		p.log.success(`Listening on http://${info.address}:${info.port}`);
 		p.log.info(`Database: ${preparedDb}`);
 		p.log.step("Raw event sweeper started");
-		if (!isEmbeddingDisabled()) {
-			vectorMigrationRunner.start();
-			p.log.step("Vector maintenance runner started");
-		}
-		backfillCoordinator.start();
-		if (syncConfig.syncRetentionEnabled) {
-			retentionRunner.start();
-			p.log.step("Retention maintenance runner started");
-		}
+		maintenanceWorker = startMaintenanceWorkerProcess(invocation);
 		if (syncEnabled) {
 			const syncStartDelayMs = 3e3;
 			p.log.step(`Sync daemon will start in background (${syncStartDelayMs / 1e3}s delay)`);
@@ -4667,24 +4910,11 @@ async function startForegroundViewer(invocation) {
 		else p.log.error(err.message);
 		process.exit(1);
 	});
-	const walCheckpointTimer = setInterval(() => {
-		try {
-			store.db.pragma("wal_checkpoint(TRUNCATE)");
-		} catch (err) {
-			p.log.warn(`WAL checkpoint failed: ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}, 300 * 1e3);
-	walCheckpointTimer.unref();
 	const shutdown = async () => {
 		p.outro("shutting down");
-		clearInterval(walCheckpointTimer);
 		syncAbort.abort();
-		retentionAbort.abort();
-		backfillAbort.abort();
+		await stopMaintenanceWorkerProcess(maintenanceWorker, dbPath);
 		await sweeper.stop();
-		await vectorMigrationRunner.stop();
-		await retentionRunner.stop();
-		await backfillCoordinator.stop();
 		await new Promise((resolve) => {
 			let remaining = syncServer ? 2 : 1;
 			const done = () => {
@@ -4701,9 +4931,15 @@ async function startForegroundViewer(invocation) {
 	};
 	const forceShutdown = () => {
 		setTimeout(() => {
+			if (maintenanceWorker?.pid && isProcessRunning(maintenanceWorker.pid)) try {
+				process.kill(maintenanceWorker.pid, "SIGKILL");
+			} catch {}
 			try {
 				rmSync(pidPath);
 			} catch {}
+			try {
+				rmSync(maintenanceWorkerPidFilePath(dbPath));
+			} catch {}
 			closeStore();
 			process.exit(1);
 		}, 3e4).unref();
@@ -4736,8 +4972,13 @@ async function runServeInvocation(invocation) {
 			port: invocation.port
 		});
 		if (result.stopped) {
+			const workerStopped = await terminateTrustedMaintenanceWorker(dbPath, {
+				gracefulMs: 5e3,
+				forceMs: 5e3
+			});
 			p.intro("codemem viewer");
 			p.log.success(`Stopped viewer${result.pid ? ` (pid ${result.pid})` : ""}`);
+			if (!workerStopped) p.log.warn("Maintenance worker pidfile exists but did not match trusted worker command");
 			if (invocation.mode === "stop") {
 				p.outro("done");
 				return;
@@ -4749,7 +4990,12 @@ async function runServeInvocation(invocation) {
 			process.exitCode = 1;
 			return;
 		} else if (invocation.mode === "stop") {
+			const workerStopped = await terminateTrustedMaintenanceWorker(dbPath, {
+				gracefulMs: 5e3,
+				forceMs: 5e3
+			});
 			p.intro("codemem viewer");
+			if (!workerStopped) p.log.warn("Maintenance worker pidfile exists but did not match trusted worker command");
 			p.outro("No background viewer found");
 			return;
 		}