codemem 0.22.4 → 0.24.0

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-import { DEFAULT_COORDINATOR_DB_PATH, MemoryStore, ObserverClient, RawEventSweeper, SyncRetentionRunner, VERSION, applyBootstrapSnapshot, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildRawEventEnvelopeFromHook, connect, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorImportInviteAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, ensureDeviceIdentity, exportMemories, fetchAllSnapshotPages, fingerprintPublicKey, getRawEventStatus, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, loadPublicKey, loadSqliteVec, planReplicationOpsAgePrune, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCoordinatorSyncConfig, readImportPayload, requestJson, resolveDbPath, resolveProject, retryRawEventFailures, runSyncDaemon, runSyncPass, schema, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
-import { Command } from "commander";
+import { DEFAULT_COORDINATOR_DB_PATH, MemoryStore, ObserverClient, RawEventSweeper, SyncRetentionRunner, VERSION, applyBootstrapSnapshot, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildRawEventEnvelopeFromHook, compareMemoryRoleReports, connect, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, ensureDeviceIdentity, exportMemories, fetchAllSnapshotPages, fingerprintPublicKey, getExtractionBenchmarkProfile, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSessionExtractionEval, getSessionExtractionEvalScenario, getWorkspaceCodememConfigPath, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, loadObserverConfig, loadPublicKey, loadSqliteVec, planReplicationOpsAgePrune, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, retryRawEventFailures, runSyncDaemon, runSyncPass, schema, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
+import { Command, Option } from "commander";
 import omelette from "omelette";
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
+import { serve } from "@hono/node-server";
 import { homedir, networkInterfaces } from "node:os";
 import { dirname, join } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import net from "node:net";
-import { serve } from "@hono/node-server";
 import { desc, eq } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 //#region src/help-style.ts
@@ -30,6 +30,52 @@ var helpStyle = {
 	styleArgumentText: (str) => styleText("yellow", str)
 };
 //#endregion
+//#region src/shared-options.ts
+/** Add -d/--db-path and hidden --db alias to a command. */
+function addDbOption(cmd) {
+	cmd.addOption(new Option("-d, --db-path <path>", "database path (overrides $CODEMEM_DB)"));
+	cmd.addOption(new Option("--db <path>", "database path").hideHelp());
+	return cmd;
+}
+/** Resolve the db path from parsed opts that may have --db or --db-path. */
+function resolveDbOpt(opts) {
+	return opts.dbPath ?? opts.db;
+}
+/** Add -c/--config to a command. */
+function addConfigOption(cmd) {
+	cmd.addOption(new Option("-c, --config <path>", "config file path (overrides $CODEMEM_CONFIG)"));
+	return cmd;
+}
+/** Add -j/--json to a command. */
+function addJsonOption(cmd) {
+	cmd.addOption(new Option("-j, --json", "output as JSON"));
+	return cmd;
+}
+/** Add --host and --port for the viewer/serve service. */
+function addViewerHostOptions(cmd, defaults = {}) {
+	cmd.option("--host <host>", "viewer host", defaults.host ?? "127.0.0.1");
+	cmd.option("--port <port>", "viewer port", defaults.port ?? "38888");
+	return cmd;
+}
+/** Add hidden --user/--system Typer-era compatibility flags. */
+function addLegacyServiceFlags(cmd) {
+	cmd.addOption(new Option("--user", "accepted for compatibility").default(true).hideHelp());
+	cmd.addOption(new Option("--system", "accepted for compatibility").hideHelp());
+	return cmd;
+}
+/** Emit a deprecation warning to stderr. */
+function emitDeprecationWarning(oldForm, newForm) {
+	console.error(`Warning: '${oldForm}' is deprecated, use '${newForm}' instead.`);
+}
+/** Print a structured JSON error to stdout and set the exit code. */
+function emitJsonError(errorCode, message, exitCode = 1) {
+	console.log(JSON.stringify({
+		error: errorCode,
+		message
+	}));
+	process.exitCode = exitCode;
+}
+//#endregion
 //#region src/commands/claude-hook-ingest.ts
 /**
 * codemem claude-hook-ingest — read a single Claude Code hook payload
@@ -43,6 +89,13 @@ var helpStyle = {
 *   echo '{"hook_event_name":"Stop","session_id":"...","last_assistant_message":"..."}' \
 *     | codemem claude-hook-ingest
 */
+function emitStructuredError$1(errorCode, message) {
+	console.log(JSON.stringify({
+		error: errorCode,
+		message
+	}));
+	process.exitCode = 1;
+}
 /** Try to POST the hook payload to the running viewer server. */
 async function tryHttpIngest(payload, host, port) {
 	const url = `http://${host}:${port}/api/claude-hooks`;
@@ -130,55 +183,823 @@ async function ingestClaudeHookPayload(payload, opts, deps = {}) {
 	const httpIngest = deps.httpIngest ?? tryHttpIngest;
 	const directIngest = deps.directIngest ?? directEnqueue;
 	const resolveDb = deps.resolveDb ?? resolveDbPath;
-	const httpResult = await httpIngest(payload, opts.host, opts.port);
+	const port = typeof opts.port === "number" ? opts.port : Number.parseInt(opts.port, 10);
+	const httpResult = await httpIngest(payload, opts.host, port);
 	if (httpResult.ok) return {
 		inserted: httpResult.inserted,
 		skipped: httpResult.skipped,
 		via: "http"
 	};
 	return {
-		...directIngest(payload, resolveDb(opts.db ?? opts.dbPath)),
+		...directIngest(payload, resolveDb(resolveDbOpt(opts))),
 		via: "direct"
 	};
 }
-var claudeHookIngestCommand = new Command("claude-hook-ingest").configureHelp(helpStyle).description("Ingest Claude hook payload: HTTP first, direct DB fallback").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "viewer server host", "127.0.0.1").option("--port <port>", "viewer server port", "38888").action(async (opts) => {
+var claudeHookCmd = new Command("claude-hook-ingest").configureHelp(helpStyle).description("Ingest Claude hook payload: HTTP first, direct DB fallback");
+addDbOption(claudeHookCmd);
+addViewerHostOptions(claudeHookCmd);
+var claudeHookIngestCommand = claudeHookCmd.action(async (opts) => {
 	let raw;
 	try {
 		raw = readFileSync(0, "utf8").trim();
 	} catch {
-		process.exitCode = 1;
+		emitStructuredError$1("read_error", "failed to read stdin");
 		return;
 	}
 	if (!raw) {
-		process.exitCode = 1;
+		emitStructuredError$1("read_error", "empty stdin");
 		return;
 	}
 	let payload;
 	try {
 		const parsed = JSON.parse(raw);
 		if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			emitStructuredError$1("parse_error", "payload must be a JSON object");
+			return;
+		}
+		payload = parsed;
+	} catch {
+		emitStructuredError$1("parse_error", "invalid JSON");
+		return;
+	}
+	try {
+		const result = await ingestClaudeHookPayload(payload, opts);
+		console.log(JSON.stringify(result));
+	} catch (err) {
+		emitStructuredError$1("ingest_error", err instanceof Error ? err.message : String(err));
+	}
+});
+//#endregion
+//#region src/commands/claude-hook-inject.ts
+var DEFAULT_VIEWER_HOST = "127.0.0.1";
+var DEFAULT_VIEWER_PORT = 38888;
+var DEFAULT_MAX_CHARS = 16e3;
+var DEFAULT_HTTP_MAX_TIME_S = 2;
+function emitJson(value) {
+	console.log(JSON.stringify(value));
+}
+function envNotDisabled(value) {
+	const normalized = String(value ?? "").trim().toLowerCase();
+	return normalized !== "0" && normalized !== "false" && normalized !== "off";
+}
+function parsePositiveInt(value, fallback) {
+	const parsed = Number.parseInt(String(value ?? ""), 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+	return parsed;
+}
+function continueResult(additionalContext) {
+	if (!additionalContext) return { continue: true };
+	return {
+		continue: true,
+		hookSpecificOutput: { additionalContext }
+	};
+}
+function truncateAdditionalContext(text, maxChars) {
+	const normalized = text.trim();
+	if (!normalized) return "";
+	if (!Number.isFinite(maxChars) || maxChars <= 0 || normalized.length <= maxChars) return normalized;
+	return normalized.slice(0, maxChars);
+}
+function extractInjectContext(payload) {
+	return String(payload.prompt ?? "").trim() || null;
+}
+function resolveInjectProject(payload) {
+	return resolveHookProject(typeof payload.cwd === "string" ? payload.cwd : null, payload.project);
+}
+async function buildLocalPack(context, project, dbPath) {
+	const store = new MemoryStore(dbPath);
+	try {
+		const limit = parsePositiveInt(process.env.CODEMEM_INJECT_LIMIT, 8);
+		const budget = parsePositiveInt(process.env.CODEMEM_INJECT_TOKEN_BUDGET, 800);
+		const filters = {};
+		if (project) filters.project = project;
+		const pack = await store.buildMemoryPackAsync(context, limit, budget, filters);
+		return String(pack.pack_text ?? "").trim();
+	} finally {
+		store.close();
+	}
+}
+async function tryHttpPack(context, project, maxTimeMs = DEFAULT_HTTP_MAX_TIME_S * 1e3) {
+	const host = process.env.CODEMEM_VIEWER_HOST || DEFAULT_VIEWER_HOST;
+	const port = parsePositiveInt(process.env.CODEMEM_VIEWER_PORT, DEFAULT_VIEWER_PORT);
+	const url = new URL(`http://${host}:${port}/api/pack`);
+	url.searchParams.set("context", context);
+	url.searchParams.set("limit", String(parsePositiveInt(process.env.CODEMEM_INJECT_LIMIT, 8)));
+	url.searchParams.set("token_budget", String(parsePositiveInt(process.env.CODEMEM_INJECT_TOKEN_BUDGET, 800)));
+	if (project) url.searchParams.set("project", project);
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), maxTimeMs);
+	try {
+		const res = await fetch(url, { signal: controller.signal });
+		if (!res.ok) return "";
+		const body = await res.json();
+		return String(body.pack_text ?? "").trim();
+	} catch {
+		return "";
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+async function buildClaudeHookInjection(payload, opts, deps = {}) {
+	if (!envNotDisabled(process.env.CODEMEM_INJECT_CONTEXT || "1")) return continueResult();
+	const context = extractInjectContext(payload);
+	if (!context) return continueResult();
+	const buildPack = deps.buildLocalPack ?? buildLocalPack;
+	const httpPack = deps.httpPack ?? tryHttpPack;
+	const resolveDb = deps.resolveDb ?? resolveDbPath;
+	const project = resolveInjectProject(payload);
+	const maxChars = parsePositiveInt(process.env.CODEMEM_INJECT_MAX_CHARS, DEFAULT_MAX_CHARS);
+	const httpMaxTimeMs = parsePositiveInt(process.env.CODEMEM_INJECT_HTTP_MAX_TIME_S, DEFAULT_HTTP_MAX_TIME_S) * 1e3;
+	let additionalContext = "";
+	try {
+		additionalContext = await buildPack(context, project, resolveDb(resolveDbOpt(opts)));
+	} catch {
+		additionalContext = "";
+	}
+	if (!additionalContext && envNotDisabled(process.env.CODEMEM_INJECT_HTTP_FALLBACK || "1")) additionalContext = await httpPack(context, project, httpMaxTimeMs);
+	return continueResult(truncateAdditionalContext(additionalContext, maxChars));
+}
+var claudeHookInjectCmd = new Command("claude-hook-inject").configureHelp(helpStyle).description("Return Claude hook additionalContext from local pack generation");
+addDbOption(claudeHookInjectCmd);
+var claudeHookInjectCommand = claudeHookInjectCmd.action(async (opts) => {
+	let raw = "";
+	for await (const chunk of process.stdin) raw += String(chunk);
+	const trimmed = raw.trim();
+	if (!trimmed) {
+		emitJson(continueResult());
+		return;
+	}
+	let payload;
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			emitJson({
+				error: "parse_error",
+				message: "payload must be a JSON object"
+			});
 			process.exitCode = 1;
 			return;
 		}
 		payload = parsed;
 	} catch {
+		emitJson({
+			error: "parse_error",
+			message: "invalid JSON"
+		});
 		process.exitCode = 1;
 		return;
 	}
-	const port = Number.parseInt(opts.port, 10);
-	const host = opts.host;
+	emitJson(await buildClaudeHookInjection(payload, opts));
+});
+//#endregion
+//#region src/commands/config.ts
+function parseIntegerOption(value, flagName) {
+	if (value == null) return void 0;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) throw new Error(`Invalid ${flagName}: ${value}`);
+	return Number.parseInt(trimmed, 10);
+}
+function buildWorkspaceConfigPatch(opts) {
+	const patch = {};
+	if (opts.syncEnabled === true) patch.sync_enabled = true;
+	if (opts.syncEnabled === false) patch.sync_enabled = false;
+	if (opts.syncHost?.trim()) patch.sync_host = opts.syncHost.trim();
+	const syncPort = parseIntegerOption(opts.syncPort, "--sync-port");
+	if (syncPort != null) patch.sync_port = syncPort;
+	const syncInterval = parseIntegerOption(opts.syncIntervalS, "--sync-interval-s");
+	if (syncInterval != null) patch.sync_interval_s = syncInterval;
+	if (opts.coordinatorUrl?.trim()) patch.sync_coordinator_url = opts.coordinatorUrl.trim();
+	if (opts.coordinatorGroup?.trim()) patch.sync_coordinator_group = opts.coordinatorGroup.trim();
+	return patch;
+}
+function mergeWorkspaceConfig(existingConfig, patch) {
+	return {
+		...existingConfig,
+		...patch
+	};
+}
+function runWorkspaceConfigCommand(opts) {
+	if (opts.enableSync && opts.disableSync) throw new Error("Use only one of --enable-sync or --disable-sync");
+	const workspaceId = opts.workspaceId;
+	if (!workspaceId) throw new Error("workspace-id is required");
+	const configPath = getWorkspaceCodememConfigPath(workspaceId);
+	const existingConfig = existsSync(configPath) ? readCodememConfigFileAtPath(configPath) : readCodememConfigFile();
+	const patch = buildWorkspaceConfigPatch({
+		workspaceId,
+		syncEnabled: opts.enableSync ? true : opts.disableSync ? false : void 0,
+		syncHost: opts.syncHost,
+		syncPort: opts.syncPort,
+		syncIntervalS: opts.syncIntervalS,
+		coordinatorUrl: opts.coordinatorUrl,
+		coordinatorGroup: opts.coordinatorGroup,
+		json: opts.json
+	});
+	if (Object.keys(patch).length === 0) throw new Error("Provide at least one config field to update");
+	const nextConfig = mergeWorkspaceConfig(existingConfig, patch);
+	return {
+		workspace_id: workspaceId,
+		config_path: writeCodememConfigFile(nextConfig, configPath),
+		updated_keys: Object.keys(patch).sort(),
+		config: nextConfig
+	};
+}
+var configCommand = new Command("config").configureHelp(helpStyle).description("Manage codemem configuration");
+var workspaceCmd = new Command("workspace").configureHelp(helpStyle).description("Create or update workspace-scoped codemem config").argument("[workspace-id]", "workspace identifier").option("--enable-sync", "set sync_enabled=true").option("--disable-sync", "set sync_enabled=false").option("--sync-host <host>", "set sync_host").option("--sync-port <port>", "set sync_port").option("--sync-interval-s <seconds>", "set sync_interval_s").option("--coordinator-url <url>", "set sync_coordinator_url").option("--coordinator-group <group>", "set sync_coordinator_group");
+workspaceCmd.addOption(new Option("--workspace-id <id>", "workspace identifier (use positional instead)").hideHelp());
+addJsonOption(workspaceCmd);
+workspaceCmd.action((workspaceIdArg, opts) => {
 	try {
-		const result = await ingestClaudeHookPayload(payload, {
-			host,
-			port,
-			db: opts.db,
-			dbPath: opts.dbPath
+		const workspaceId = workspaceIdArg || opts.workspaceId;
+		if (!workspaceId) {
+			console.error("Error: missing required argument 'workspace-id'");
+			process.exitCode = 2;
+			return;
+		}
+		const result = runWorkspaceConfigCommand({
+			...opts,
+			workspaceId
 		});
-		console.log(JSON.stringify(result));
-	} catch {
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		console.log(`Updated workspace config: ${result.config_path}`);
+		console.log(`Updated keys: ${result.updated_keys.join(", ")}`);
+	} catch (err) {
+		if (opts.json) console.log(JSON.stringify({
+			error: "config_error",
+			message: err instanceof Error ? err.message : String(err)
+		}));
+		else console.error(err instanceof Error ? err.message : String(err));
 		process.exitCode = 1;
 	}
 });
+configCommand.addCommand(workspaceCmd);
+function formatWhereHuman(result) {
+	const lines = [];
+	const allEntries = [result.resolved, ...result.fallbackChain];
+	const sourceOrder = {
+		"cli-flag": 0,
+		"env-codemem-config": 1,
+		"env-runtime-root": 2,
+		"env-workspace-id": 3,
+		"legacy-global": 4
+	};
+	allEntries.sort((a, b) => (sourceOrder[a.source] ?? 99) - (sourceOrder[b.source] ?? 99));
+	for (const entry of allEntries) {
+		const marker = entry === result.resolved ? ">>>" : "   ";
+		const existsLabel = entry.exists ? "exists" : "missing";
+		lines.push(`${marker} [${entry.source}] ${entry.path}`);
+		lines.push(`       ${entry.reason} (${existsLabel})`);
+	}
+	return lines.join("\n");
+}
+var whereCmd = new Command("where").configureHelp(helpStyle).description("show resolved config file path");
+addConfigOption(whereCmd);
+addJsonOption(whereCmd);
+whereCmd.action((opts) => {
+	try {
+		const result = resolveCodememConfigPath(opts.config, "read");
+		if (opts.json) console.log(JSON.stringify(result, null, 2));
+		else console.log(formatWhereHuman(result));
+	} catch (err) {
+		if (opts.json) console.log(JSON.stringify({
+			error: "config_error",
+			message: err instanceof Error ? err.message : String(err)
+		}));
+		else console.error(err instanceof Error ? err.message : String(err));
+		process.exitCode = 1;
+	}
+});
+configCommand.addCommand(whereCmd);
+//#endregion
+//#region src/commands/coordinator.ts
+/**
+* Coordinator CLI commands — manage coordinator invites, join requests, and relay server.
+*
+* Extracted from sync.ts to give coordinator admin its own top-level group
+* per cli-design-conventions.md (operator/admin surfaces belong in their own group).
+*
+* buildCoordinatorCommand() is a factory that creates a fresh command tree.
+* This allows both the canonical top-level `coordinator` and the deprecated
+* `sync coordinator` alias to have independent Commander instances (Commander
+* re-parents commands on addCommand, so sharing instances between two parents
+* is not possible).
+*/
+function readCoordinatorPublicKey(opts) {
+	const inline = String(opts.publicKey ?? "").trim();
+	const filePath = String(opts.publicKeyFile ?? "").trim();
+	if (inline && filePath) throw new Error("Use only one of --public-key or --public-key-file");
+	if (filePath) {
+		const text = readFileSync(filePath, "utf8").trim();
+		if (!text) throw new Error(`Public key file is empty: ${filePath}`);
+		return text;
+	}
+	if (!inline) throw new Error("Public key required via --public-key or --public-key-file");
+	return inline;
+}
+/**
+* Build a fresh coordinator command tree. Each call returns independent
+* Commander instances so the tree can be mounted under multiple parents.
+*/
+function buildCoordinatorCommand() {
+	const cmd = new Command("coordinator").configureHelp(helpStyle).description("Manage coordinator invites, join requests, and relay server");
+	const groupCreateCmd = new Command("group-create").configureHelp(helpStyle).description("Create a coordinator group in the local store").argument("<group>", "group id").option("--name <name>", "display name override");
+	addDbOption(groupCreateCmd);
+	addJsonOption(groupCreateCmd);
+	groupCreateCmd.action(async (groupId, opts) => {
+		try {
+			const group = await coordinatorCreateGroupAction({
+				groupId,
+				displayName: opts.name?.trim() || null,
+				dbPath: resolveDbOpt(opts) ?? null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(group, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator group-create");
+			p.log.success(`Group ready: ${groupId.trim()}`);
+			p.outro(String(group.display_name ?? group.group_id ?? groupId.trim()));
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("group_create_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(groupCreateCmd);
+	const listGroupsCmd = new Command("list-groups").configureHelp(helpStyle).description("List coordinator groups from the local store");
+	addDbOption(listGroupsCmd);
+	addJsonOption(listGroupsCmd);
+	listGroupsCmd.action(async (opts) => {
+		try {
+			const groups = await coordinatorListGroupsAction({ dbPath: resolveDbOpt(opts) ?? null });
+			if (opts.json) {
+				console.log(JSON.stringify(groups, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator list-groups");
+			if (groups.length === 0) {
+				p.outro("No coordinator groups found");
+				return;
+			}
+			for (const group of groups) p.log.message(`- ${String(group.group_id ?? "")}${group.display_name ? ` (${String(group.display_name)})` : ""}`);
+			p.outro(`${groups.length} group(s)`);
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("list_groups_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(listGroupsCmd);
+	const enrollDeviceCmd = new Command("enroll-device").configureHelp(helpStyle).description("Enroll a device in a local coordinator group").argument("<group>", "group id").argument("<device-id>", "device id").option("--fingerprint <fingerprint>", "device fingerprint").option("--public-key <key>", "device public key").option("--public-key-file <path>", "path to device public key").option("--name <name>", "display name");
+	addDbOption(enrollDeviceCmd);
+	addJsonOption(enrollDeviceCmd);
+	enrollDeviceCmd.action(async (groupId, deviceId, opts) => {
+		try {
+			const publicKey = readCoordinatorPublicKey(opts);
+			const fingerprint = String(opts.fingerprint ?? "").trim();
+			if (!fingerprint) {
+				if (opts.json) {
+					emitJsonError("usage_error", "Fingerprint required via --fingerprint", 2);
+					return;
+				}
+				p.log.error("Fingerprint required via --fingerprint");
+				process.exitCode = 1;
+				return;
+			}
+			if (fingerprintPublicKey(publicKey) !== fingerprint) {
+				if (opts.json) {
+					emitJsonError("fingerprint_mismatch", "Fingerprint does not match the provided public key");
+					return;
+				}
+				p.log.error("Fingerprint does not match the provided public key");
+				process.exitCode = 1;
+				return;
+			}
+			const enrollment = await coordinatorEnrollDeviceAction({
+				groupId,
+				deviceId,
+				fingerprint,
+				publicKey,
+				displayName: opts.name?.trim() || null,
+				dbPath: resolveDbOpt(opts) ?? null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(enrollment, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator enroll-device");
+			p.log.success(`Enrolled ${deviceId.trim()} in ${groupId.trim()}`);
+			p.outro(String(enrollment.display_name ?? enrollment.device_id ?? deviceId.trim()));
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("enroll_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(enrollDeviceCmd);
+	const listDevicesCmd = new Command("list-devices").configureHelp(helpStyle).description("List enrolled devices in a local coordinator group").argument("<group>", "group id").option("--include-disabled", "include disabled devices");
+	addDbOption(listDevicesCmd);
+	addJsonOption(listDevicesCmd);
+	listDevicesCmd.action(async (groupId, opts) => {
+		try {
+			const rows = await coordinatorListDevicesAction({
+				groupId,
+				includeDisabled: opts.includeDisabled === true,
+				dbPath: resolveDbOpt(opts) ?? null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(rows, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator list-devices");
+			if (rows.length === 0) {
+				p.outro(`No enrolled devices for ${groupId.trim()}`);
+				return;
+			}
+			for (const row of rows) {
+				const label = String(row.display_name ?? row.device_id ?? "").trim() || String(row.device_id ?? "");
+				const enabled = Number(row.enabled ?? 1) === 1 ? "enabled" : "disabled";
+				p.log.message(`- ${label} (${String(row.device_id ?? "")}) ${enabled}`);
+			}
+			p.outro(`${rows.length} device(s)`);
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("list_devices_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(listDevicesCmd);
+	const renameDeviceCmd = new Command("rename-device").configureHelp(helpStyle).description("Rename an enrolled device in the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id").requiredOption("--name <name>", "display name");
+	addDbOption(renameDeviceCmd);
+	addJsonOption(renameDeviceCmd);
+	renameDeviceCmd.action(async (groupId, deviceId, opts) => {
+		try {
+			const result = await coordinatorRenameDeviceAction({
+				groupId,
+				deviceId,
+				displayName: opts.name.trim(),
+				dbPath: resolveDbOpt(opts) ?? null
+			});
+			if (!result) {
+				if (opts.json) {
+					emitJsonError("device_not_found", `Device not found: ${deviceId.trim()}`);
+					return;
+				}
+				p.log.error(`Device not found: ${deviceId.trim()}`);
+				process.exitCode = 1;
+				return;
+			}
+			if (opts.json) {
+				console.log(JSON.stringify(result, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator rename-device");
+			p.log.success(`Renamed ${deviceId.trim()} in ${groupId.trim()}`);
+			p.outro(String(result.display_name ?? result.device_id ?? deviceId.trim()));
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("rename_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(renameDeviceCmd);
+	const disableDeviceCmd = new Command("disable-device").configureHelp(helpStyle).description("Disable an enrolled device in the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id");
+	addDbOption(disableDeviceCmd);
+	addJsonOption(disableDeviceCmd);
+	disableDeviceCmd.action(async (groupId, deviceId, opts) => {
+		try {
+			if (!await coordinatorDisableDeviceAction({
+				groupId,
+				deviceId,
+				dbPath: resolveDbOpt(opts) ?? null
+			})) {
+				if (opts.json) {
+					emitJsonError("device_not_found", `Device not found: ${deviceId.trim()}`);
+					return;
+				}
+				p.log.error(`Device not found: ${deviceId.trim()}`);
+				process.exitCode = 1;
+				return;
+			}
+			if (opts.json) {
+				console.log(JSON.stringify({
+					ok: true,
+					group_id: groupId.trim(),
+					device_id: deviceId.trim()
+				}, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator disable-device");
+			p.log.success(`Disabled ${deviceId.trim()} in ${groupId.trim()}`);
+			p.outro("disabled");
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("disable_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(disableDeviceCmd);
+	const removeDeviceCmd = new Command("remove-device").configureHelp(helpStyle).description("Remove an enrolled device from the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id");
+	addDbOption(removeDeviceCmd);
+	addJsonOption(removeDeviceCmd);
+	removeDeviceCmd.action(async (groupId, deviceId, opts) => {
+		try {
+			if (!await coordinatorRemoveDeviceAction({
+				groupId,
+				deviceId,
+				dbPath: resolveDbOpt(opts) ?? null
+			})) {
+				if (opts.json) {
+					emitJsonError("device_not_found", `Device not found: ${deviceId.trim()}`);
+					return;
+				}
+				p.log.error(`Device not found: ${deviceId.trim()}`);
+				process.exitCode = 1;
+				return;
+			}
+			if (opts.json) {
+				console.log(JSON.stringify({
+					ok: true,
+					group_id: groupId.trim(),
+					device_id: deviceId.trim()
+				}, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator remove-device");
+			p.log.success(`Removed ${deviceId.trim()} from ${groupId.trim()}`);
+			p.outro("removed");
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("remove_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(removeDeviceCmd);
+	const coordServeCmd = new Command("serve").configureHelp(helpStyle).description("Run the coordinator relay HTTP server").option("--coordinator-host <host>", "bind host").option("--coordinator-port <port>", "bind port");
+	coordServeCmd.addOption(new Option("-d, --db-path <path>", "coordinator database path"));
+	coordServeCmd.addOption(new Option("--db <path>", "coordinator database path").hideHelp());
+	coordServeCmd.addOption(new Option("--host <host>", "bind host").hideHelp());
+	coordServeCmd.addOption(new Option("--port <port>", "bind port").hideHelp());
+	coordServeCmd.action(async (opts) => {
+		const host = String(opts.coordinatorHost ?? opts.host ?? "127.0.0.1").trim() || "127.0.0.1";
+		const port = Number.parseInt(String(opts.coordinatorPort ?? opts.port ?? "7347"), 10);
+		const dbPath = resolveDbOpt(opts) ?? DEFAULT_COORDINATOR_DB_PATH;
+		const app = createBetterSqliteCoordinatorApp({ dbPath });
+		p.intro("codemem coordinator serve");
+		p.log.success(`Coordinator listening at http://${host}:${port}`);
+		p.log.info(`DB: ${dbPath}`);
+		serve({
+			fetch: app.fetch,
+			hostname: host,
+			port
+		});
+	});
+	cmd.addCommand(coordServeCmd);
+	const listBootstrapGrantsCmd = new Command("list-bootstrap-grants").configureHelp(helpStyle).description("List bootstrap grants for a coordinator group").argument("<group>", "group id").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override");
+	addDbOption(listBootstrapGrantsCmd);
+	addJsonOption(listBootstrapGrantsCmd);
+	listBootstrapGrantsCmd.action(async (groupId, opts) => {
+		try {
+			const rows = await coordinatorListBootstrapGrantsAction({
+				groupId,
+				dbPath: resolveDbOpt(opts) ?? null,
+				remoteUrl: opts.remoteUrl?.trim() || null,
+				adminSecret: opts.adminSecret?.trim() || null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(rows, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator list-bootstrap-grants");
+			if (rows.length === 0) {
+				p.outro(`No bootstrap grants for ${groupId.trim()}`);
+				return;
+			}
+			for (const row of rows) p.log.message(`- ${row.grant_id} seed=${row.seed_device_id} worker=${row.worker_device_id} expires=${row.expires_at} revoked=${row.revoked_at ?? "no"}`);
+			p.outro(`${rows.length} bootstrap grant(s)`);
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("list_bootstrap_grants_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(listBootstrapGrantsCmd);
+	const revokeBootstrapGrantCmd = new Command("revoke-bootstrap-grant").configureHelp(helpStyle).description("Revoke a bootstrap grant").argument("<grant-id>", "bootstrap grant id").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override");
+	addDbOption(revokeBootstrapGrantCmd);
+	addJsonOption(revokeBootstrapGrantCmd);
+	revokeBootstrapGrantCmd.action(async (grantId, opts) => {
+		try {
+			if (!await coordinatorRevokeBootstrapGrantAction({
+				grantId,
+				dbPath: resolveDbOpt(opts) ?? null,
+				remoteUrl: opts.remoteUrl?.trim() || null,
+				adminSecret: opts.adminSecret?.trim() || null
+			})) {
+				if (opts.json) {
+					emitJsonError("grant_not_found", `Bootstrap grant not found: ${grantId.trim()}`);
+					return;
+				}
+				p.log.error(`Bootstrap grant not found: ${grantId.trim()}`);
+				process.exitCode = 1;
+				return;
+			}
+			if (opts.json) {
+				console.log(JSON.stringify({
+					ok: true,
+					grant_id: grantId.trim()
+				}, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator revoke-bootstrap-grant");
+			p.log.success(`Revoked ${grantId.trim()}`);
+			p.outro("revoked");
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("revoke_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(revokeBootstrapGrantCmd);
+	const createInviteCmd = new Command("create-invite").configureHelp(helpStyle).description("Create a coordinator team invite").argument("[group]", "group id").option("--group <group>", "group id").option("--coordinator-url <url>", "coordinator URL override").option("--policy <policy>", "invite policy", "auto_admit").option("--ttl-hours <hours>", "invite TTL hours", "24").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override");
+	addDbOption(createInviteCmd);
+	addJsonOption(createInviteCmd);
+	createInviteCmd.action(async (groupArg, opts) => {
+		try {
+			const ttlHours = Number.parseInt(String(opts.ttlHours ?? "24"), 10);
+			const groupId = String(opts.group ?? "").trim() || String(groupArg ?? "").trim();
+			const result = await coordinatorCreateInviteAction({
+				groupId,
+				coordinatorUrl: opts.coordinatorUrl?.trim() || null,
+				policy: String(opts.policy ?? "auto_admit").trim(),
+				ttlHours,
+				createdBy: null,
+				dbPath: resolveDbOpt(opts) ?? null,
+				remoteUrl: opts.remoteUrl?.trim() || null,
+				adminSecret: opts.adminSecret?.trim() || null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(result, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator create-invite");
+			p.log.success(`Invite created for ${groupId}`);
+			if (typeof result.link === "string") p.log.message(`- link: ${result.link}`);
+			if (typeof result.encoded === "string") p.log.message(`- invite: ${result.encoded}`);
+			for (const warning of Array.isArray(result.warnings) ? result.warnings : []) p.log.warn(String(warning));
+			p.outro("Invite ready");
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("create_invite_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(createInviteCmd);
+	const importInviteCmd = new Command("import-invite").configureHelp(helpStyle).description("Import a coordinator invite").argument("<invite>", "invite value or link").option("--keys-dir <path>", "keys directory");
+	addDbOption(importInviteCmd);
+	addConfigOption(importInviteCmd);
+	addJsonOption(importInviteCmd);
+	importInviteCmd.action(async (invite, opts) => {
+		try {
+			const result = await coordinatorImportInviteAction({
+				inviteValue: invite,
+				dbPath: resolveDbOpt(opts) ?? null,
+				keysDir: opts.keysDir ?? null,
+				configPath: opts.config ?? null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(result, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator import-invite");
+			p.log.success(`Invite imported for ${result.group_id}`);
+			p.log.message(`- coordinator: ${result.coordinator_url}`);
+			p.log.message(`- status: ${result.status}`);
+			p.outro("Coordinator config updated");
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("import_invite_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(importInviteCmd);
+	const listJoinRequestsCmd = new Command("list-join-requests").configureHelp(helpStyle).description("List pending coordinator join requests").argument("[group]", "group id").option("--group <group>", "group id").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override");
+	addDbOption(listJoinRequestsCmd);
+	addJsonOption(listJoinRequestsCmd);
+	listJoinRequestsCmd.action(async (groupArg, opts) => {
+		try {
+			const groupId = String(opts.group ?? "").trim() || String(groupArg ?? "").trim();
+			const rows = await coordinatorListJoinRequestsAction({
+				groupId,
+				dbPath: resolveDbOpt(opts) ?? null,
+				remoteUrl: opts.remoteUrl?.trim() || null,
+				adminSecret: opts.adminSecret?.trim() || null
+			});
+			if (opts.json) {
+				console.log(JSON.stringify(rows, null, 2));
+				return;
+			}
+			p.intro("codemem coordinator list-join-requests");
+			if (rows.length === 0) {
+				p.outro(`No pending join requests for ${groupId}`);
+				return;
+			}
+			for (const row of rows) {
+				const displayName = row.display_name || row.device_id;
+				p.log.message(`- ${displayName} (${row.device_id}) request_id=${row.request_id}`);
+			}
+			p.outro(`${rows.length} pending join request(s)`);
+		} catch (err) {
+			if (opts.json) {
+				emitJsonError("list_join_requests_failed", err instanceof Error ? err.message : String(err));
+				return;
+			}
+			p.log.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	});
+	cmd.addCommand(listJoinRequestsCmd);
+	function addReviewJoinRequestCommand(name, approve) {
+		const reviewCmd = new Command(name).configureHelp(helpStyle).description(`${approve ? "Approve" : "Deny"} a coordinator join request`).argument("<request-id>", "join request id").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override");
+		addDbOption(reviewCmd);
+		addJsonOption(reviewCmd);
+		reviewCmd.action(async (requestId, opts) => {
+			try {
+				const request = await coordinatorReviewJoinRequestAction({
+					requestId: requestId.trim(),
+					approve,
+					reviewedBy: null,
+					dbPath: resolveDbOpt(opts) ?? null,
+					remoteUrl: opts.remoteUrl?.trim() || null,
+					adminSecret: opts.adminSecret?.trim() || null
+				});
+				if (!request) {
+					if (opts.json) {
+						emitJsonError("join_request_not_found", `Join request not found: ${requestId.trim()}`);
+						return;
+					}
+					p.log.error(`Join request not found: ${requestId.trim()}`);
+					process.exitCode = 1;
+					return;
+				}
+				if (opts.json) {
+					console.log(JSON.stringify(request, null, 2));
+					return;
+				}
+				p.intro(`codemem coordinator ${name}`);
+				p.log.success(`${approve ? "Approved" : "Denied"} join request ${requestId.trim()}`);
+				p.outro(String(request.status ?? "updated"));
+			} catch (err) {
+				if (opts.json) {
+					emitJsonError("review_failed", err instanceof Error ? err.message : String(err));
+					return;
+				}
+				p.log.error(err instanceof Error ? err.message : String(err));
+				process.exitCode = 1;
+			}
+		});
+		cmd.addCommand(reviewCmd);
+	}
+	addReviewJoinRequestCommand("approve-join-request", true);
+	addReviewJoinRequestCommand("deny-join-request", false);
+	return cmd;
+}
+/** Canonical top-level coordinator command for registration in index.ts. */
+var coordinatorCommand = buildCoordinatorCommand();
 //#endregion
 //#region src/commands/db.ts
 function formatBytes(bytes) {
@@ -210,18 +1031,28 @@ function estimateReplicationOpsBytes(db) {
 	}
 }
 var dbCommand = new Command("db").configureHelp(helpStyle).description("Database maintenance");
-dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("Create or verify the SQLite database and schema").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
-	const result = initDatabase(opts.db ?? opts.dbPath);
+var initCmd = new Command("init").configureHelp(helpStyle).description("Create or verify the SQLite database and schema");
+addDbOption(initCmd);
+initCmd.action((opts) => {
+	const result = initDatabase(resolveDbOpt(opts));
 	p.intro("codemem db init");
 	p.log.success(`Database ready: ${result.path}`);
 	p.outro(`Size: ${result.sizeBytes.toLocaleString()} bytes`);
-})).addCommand(new Command("vacuum").configureHelp(helpStyle).description("Run VACUUM on the SQLite database").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
-	const result = vacuumDatabase(opts.db ?? opts.dbPath);
+});
+dbCommand.addCommand(initCmd);
+var vacuumCmd = new Command("vacuum").configureHelp(helpStyle).description("Run VACUUM on the SQLite database");
+addDbOption(vacuumCmd);
+vacuumCmd.action((opts) => {
+	const result = vacuumDatabase(resolveDbOpt(opts));
 	p.intro("codemem db vacuum");
 	p.log.success(`Vacuumed: ${result.path}`);
 	p.outro(`Size: ${result.sizeBytes.toLocaleString()} bytes`);
-})).addCommand(new Command("prune-replication-ops").configureHelp(helpStyle).description("Prune replication op history with approximate oldest-first retention, dry-run, and progress reporting").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--dry-run", "show current size/targets without deleting").option("--max-age-days <days>", "retention age threshold in days", "30").option("--max-size-mb <mb>", "target replication log budget in MB", "512").option("--batch-ops <n>", "max ops deleted per batch", "5000").option("--batch-runtime-ms <ms>", "max runtime per batch in ms", "2000").option("--vacuum", "run VACUUM explicitly after prune completes").action((opts) => {
-	const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
+});
+dbCommand.addCommand(vacuumCmd);
+var pruneReplCmd = new Command("prune-replication-ops").configureHelp(helpStyle).description("Prune replication op history with approximate oldest-first retention, dry-run, and progress reporting").option("--dry-run", "show current size/targets without deleting").option("--max-age-days <days>", "retention age threshold in days", "30").option("--max-size-mb <mb>", "target replication log budget in MB", "512").option("--batch-ops <n>", "max ops deleted per batch", "5000").option("--batch-runtime-ms <ms>", "max runtime per batch in ms", "2000").option("--vacuum", "run VACUUM explicitly after prune completes");
+addDbOption(pruneReplCmd);
+pruneReplCmd.action((opts) => {
+	const dbPath = resolveDbPath(resolveDbOpt(opts));
 	const db = connect(dbPath);
 	let dbOpen = true;
 	try {
@@ -267,8 +1098,13 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		if (dbOpen) db.close();
 	}
-})).addCommand(new Command("raw-events-status").configureHelp(helpStyle).description("Show pending raw-event backlog by source stream").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max rows to show", "25").option("--json", "output as JSON").action((opts) => {
-	const result = getRawEventStatus(opts.db ?? opts.dbPath, Number.parseInt(opts.limit, 10) || 25);
+});
+dbCommand.addCommand(pruneReplCmd);
+var rawEventsStatusCmd = new Command("raw-events-status").configureHelp(helpStyle).description("Show pending raw-event backlog by source stream").option("-n, --limit <n>", "max rows to show", "25");
+addDbOption(rawEventsStatusCmd);
+addJsonOption(rawEventsStatusCmd);
+rawEventsStatusCmd.action((opts) => {
+	const result = getRawEventStatus(resolveDbOpt(opts), Number.parseInt(opts.limit, 10) || 25);
 	if (opts.json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
@@ -281,12 +1117,21 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	}
 	for (const item of result.items) p.log.message(`${item.source}:${item.stream_id} pending=${Math.max(0, item.last_received_event_seq - item.last_flushed_event_seq)} received=${item.last_received_event_seq} flushed=${item.last_flushed_event_seq} project=${item.project ?? ""}`);
 	p.outro("done");
-})).addCommand(new Command("raw-events-retry").configureHelp(helpStyle).description("Requeue failed raw-event flush batches").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max failed batches to requeue", "25").action((opts) => {
-	const result = retryRawEventFailures(opts.db ?? opts.dbPath, Number.parseInt(opts.limit, 10) || 25);
+});
+dbCommand.addCommand(rawEventsStatusCmd);
+var rawEventsRetryCmd = new Command("raw-events-retry").configureHelp(helpStyle).description("Requeue failed raw-event flush batches").option("-n, --limit <n>", "max failed batches to requeue", "25");
+addDbOption(rawEventsRetryCmd);
+rawEventsRetryCmd.action((opts) => {
+	const result = retryRawEventFailures(resolveDbOpt(opts), Number.parseInt(opts.limit, 10) || 25);
 	p.intro("codemem db raw-events-retry");
 	p.outro(`Requeued ${result.retried.toLocaleString()} failed batch(es)`);
-})).addCommand(new Command("raw-events-gate").configureHelp(helpStyle).description("Validate raw-event reliability thresholds (non-zero exit on failure)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--min-flush-success-rate <rate>", "minimum flush success rate", "0.95").option("--max-dropped-event-rate <rate>", "maximum dropped event rate", "0.05").option("--min-session-boundary-accuracy <rate>", "minimum session boundary accuracy", "0.9").option("--window-hours <hours>", "lookback window in hours", "24").option("--json", "output as JSON").action((opts) => {
-	const result = rawEventsGate(opts.db ?? opts.dbPath, {
+});
+dbCommand.addCommand(rawEventsRetryCmd);
+var rawEventsGateCmd = new Command("raw-events-gate").configureHelp(helpStyle).description("Validate raw-event reliability thresholds (non-zero exit on failure)").option("--min-flush-success-rate <rate>", "minimum flush success rate", "0.95").option("--max-dropped-event-rate <rate>", "maximum dropped event rate", "0.05").option("--min-session-boundary-accuracy <rate>", "minimum session boundary accuracy", "0.9").option("--window-hours <hours>", "lookback window in hours", "24");
+addDbOption(rawEventsGateCmd);
+addJsonOption(rawEventsGateCmd);
+rawEventsGateCmd.action((opts) => {
+	const result = rawEventsGate(resolveDbOpt(opts), {
 		minFlushSuccessRate: Number.parseFloat(opts.minFlushSuccessRate),
 		maxDroppedEventRate: Number.parseFloat(opts.maxDroppedEventRate),
 		minSessionBoundaryAccuracy: Number.parseFloat(opts.minSessionBoundaryAccuracy),
@@ -310,8 +1155,12 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 		p.outro("reliability gate FAILED");
 		process.exitCode = 1;
 	}
-})).addCommand(new Command("rename-project").configureHelp(helpStyle).description("Rename a project across sessions and related tables").argument("<old-name>", "current project name").argument("<new-name>", "new project name").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--apply", "apply changes (default is dry-run)").action((oldName, newName, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+dbCommand.addCommand(rawEventsGateCmd);
+var renameProjectCmd = new Command("rename-project").configureHelp(helpStyle).description("Rename a project across sessions and related tables").argument("<old-name>", "current project name").argument("<new-name>", "new project name").option("--apply", "apply changes (default is dry-run)");
+addDbOption(renameProjectCmd);
+renameProjectCmd.action((oldName, newName, opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const dryRun = !opts.apply;
 		const suffixPattern = `%/${oldName.replace(/%/g, "\\%").replace(/_/g, "\\_")}`;
@@ -338,8 +1187,12 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		store.close();
 	}
-})).addCommand(new Command("normalize-projects").configureHelp(helpStyle).description("Normalize path-like project identifiers to their basename").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--apply", "apply changes (default is dry-run)").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+dbCommand.addCommand(renameProjectCmd);
+var normalizeProjectsCmd = new Command("normalize-projects").configureHelp(helpStyle).description("Normalize path-like project identifiers to their basename").option("--apply", "apply changes (default is dry-run)");
+addDbOption(normalizeProjectsCmd);
+normalizeProjectsCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const dryRun = !opts.apply;
 		const tables = ["sessions", "raw_event_sessions"];
@@ -379,8 +1232,13 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		store.close();
 	}
-})).addCommand(new Command("size-report").configureHelp(helpStyle).description("Show SQLite file size and major storage consumers").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "number of largest tables/indexes to show", "12").option("--json", "output as JSON").action((opts) => {
-	const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
+});
+dbCommand.addCommand(normalizeProjectsCmd);
+var sizeReportCmd = new Command("size-report").configureHelp(helpStyle).description("Show SQLite file size and major storage consumers").option("--limit <n>", "number of largest tables/indexes to show", "12");
+addDbOption(sizeReportCmd);
+addJsonOption(sizeReportCmd);
+sizeReportCmd.action((opts) => {
+	const dbPath = resolveDbPath(resolveDbOpt(opts));
 	const db = connect(dbPath);
 	try {
 		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 12);
@@ -389,10 +1247,10 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 		const freePages = db.prepare("SELECT freelist_count FROM pragma_freelist_count").get();
 		const pageSize = db.prepare("PRAGMA page_size").get();
 		const tables = db.prepare(`SELECT name, SUM(pgsize) as size_bytes
-							 FROM dbstat
-							 GROUP BY name
-							 ORDER BY size_bytes DESC
-							 LIMIT ?`).all(limit);
+				 FROM dbstat
+				 GROUP BY name
+				 ORDER BY size_bytes DESC
+				 LIMIT ?`).all(limit);
 		if (opts.json) {
 			console.log(JSON.stringify({
 				file_size_bytes: fileSizeBytes,
@@ -419,8 +1277,13 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		db.close();
 	}
-})).addCommand(new Command("backfill-tags").configureHelp(helpStyle).description("Populate tags_text for memories where tags are empty").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max memories to check").option("--since <iso>", "only memories created at/after this ISO timestamp").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "backfill across all projects").option("--inactive", "include inactive memories").option("--dry-run", "preview updates without writing").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+dbCommand.addCommand(sizeReportCmd);
+var backfillTagsCmd = new Command("backfill-tags").configureHelp(helpStyle).description("Populate tags_text for memories where tags are empty").option("--limit <n>", "max memories to check").option("--since <iso>", "only memories created at/after this ISO timestamp").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "backfill across all projects").option("--inactive", "include inactive memories").option("--dry-run", "preview updates without writing");
+addDbOption(backfillTagsCmd);
+addJsonOption(backfillTagsCmd);
+backfillTagsCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = parseOptionalPositiveInt$1(opts.limit);
 		const project = opts.allProjects === true ? null : opts.project?.trim() || process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), null);
@@ -445,8 +1308,13 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		store.close();
 	}
-})).addCommand(new Command("prune-observations").configureHelp(helpStyle).description("Deactivate low-signal observations (does not delete rows)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max observations to check").option("--dry-run", "preview deactivations without writing").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+dbCommand.addCommand(backfillTagsCmd);
+var pruneObsCmd = new Command("prune-observations").configureHelp(helpStyle).description("Deactivate low-signal observations (does not delete rows)").option("--limit <n>", "max observations to check").option("--dry-run", "preview deactivations without writing");
+addDbOption(pruneObsCmd);
+addJsonOption(pruneObsCmd);
+pruneObsCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = parseOptionalPositiveInt$1(opts.limit);
 		const result = deactivateLowSignalObservations(store.db, limit ?? null, opts.dryRun === true);
@@ -463,8 +1331,13 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		store.close();
 	}
-})).addCommand(new Command("prune-memories").configureHelp(helpStyle).description("Deactivate low-signal memories across selected kinds").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max memories to check").option("--kinds <csv>", "comma-separated memory kinds (default set when omitted)").option("--dry-run", "preview deactivations without writing").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+dbCommand.addCommand(pruneObsCmd);
+var pruneMemCmd = new Command("prune-memories").configureHelp(helpStyle).description("Deactivate low-signal memories across selected kinds").option("--limit <n>", "max memories to check").option("--kinds <csv>", "comma-separated memory kinds (default set when omitted)").option("--dry-run", "preview deactivations without writing");
+addDbOption(pruneMemCmd);
+addJsonOption(pruneMemCmd);
+pruneMemCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = parseOptionalPositiveInt$1(opts.limit);
 		const kinds = parseKindsCsv(opts.kinds);
@@ -486,7 +1359,8 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("C
 	} finally {
 		store.close();
 	}
-}));
+});
+dbCommand.addCommand(pruneMemCmd);
 //#endregion
 //#region src/commands/embed.ts
 function parseOptionalPositiveInt(value) {
@@ -503,8 +1377,11 @@ function resolveEmbedProjectScope(cwd, projectOpt, allProjects) {
 	if (envProject) return envProject;
 	return resolveProject(cwd, null);
 }
-var embedCommand = new Command("embed").configureHelp(helpStyle).description("Backfill semantic embeddings").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max memories to check").option("--since <iso>", "only memories created at/after this ISO timestamp").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "embed across all projects").option("--inactive", "include inactive memories").option("--dry-run", "preview work without writing vectors").option("--json", "output as JSON").action(async (opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var embedCmd = new Command("embed").configureHelp(helpStyle).description("Backfill semantic embeddings").option("--limit <n>", "max memories to check").option("--since <iso>", "only memories created at/after this ISO timestamp").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "embed across all projects").option("--inactive", "include inactive memories").option("--dry-run", "preview work without writing vectors");
+addDbOption(embedCmd);
+addJsonOption(embedCmd);
+var embedCommand = embedCmd.action(async (opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = parseOptionalPositiveInt(opts.limit);
 		const project = resolveEmbedProjectScope(process.cwd(), opts.project, opts.allProjects);
@@ -547,7 +1424,7 @@ function resolveSessionStreamId(payload) {
 		if (text) values.set(key, text);
 	}
 	if (values.size === 0) return null;
-	if (new Set(values.values()).size > 1) throw new Error("conflicting session id fields");
+	if (new Set(values.values()).size > 1) return null;
 	for (const key of SESSION_ID_KEYS) {
 		const value = values.get(key);
 		if (value) return value;
@@ -563,39 +1440,61 @@ async function readStdinJson() {
 	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("payload must be an object");
 	return parsed;
 }
-var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(helpStyle).description("Enqueue one raw event from stdin into the durable queue").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
-	const payload = await readStdinJson();
-	const sessionId = resolveSessionStreamId(payload);
-	if (!sessionId) throw new Error("session id required");
-	if (sessionId.startsWith("msg_")) throw new Error("invalid session id");
-	const eventType = typeof payload.event_type === "string" ? payload.event_type.trim() : "";
-	if (!eventType) throw new Error("event_type required");
-	const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
-	const project = typeof payload.project === "string" ? payload.project : null;
-	const startedAt = typeof payload.started_at === "string" ? payload.started_at : null;
-	const tsWallMs = Number.isFinite(Number(payload.ts_wall_ms)) ? Math.floor(Number(payload.ts_wall_ms)) : null;
-	const tsMonoMs = Number.isFinite(Number(payload.ts_mono_ms)) ? Number(payload.ts_mono_ms) : null;
-	const eventId = typeof payload.event_id === "string" ? payload.event_id.trim() : "";
-	const eventPayload = payload.payload && typeof payload.payload === "object" && !Array.isArray(payload.payload) ? stripPrivateObj(payload.payload) : {};
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+function emitStructuredError(errorCode, message) {
+	console.log(JSON.stringify({
+		error: errorCode,
+		message
+	}));
+	process.exitCode = 1;
+}
+var enqueueCmd = new Command("enqueue-raw-event").configureHelp(helpStyle).description("Enqueue one raw event from stdin into the durable queue");
+addDbOption(enqueueCmd);
+var enqueueRawEventCommand = enqueueCmd.action(async (opts) => {
 	try {
-		store.updateRawEventSessionMeta({
-			opencodeSessionId: sessionId,
-			source: "opencode",
-			cwd,
-			project,
-			startedAt,
-			lastSeenTsWallMs: tsWallMs
-		});
-		store.recordRawEventsBatch(sessionId, [{
-			event_id: eventId,
-			event_type: eventType,
-			payload: eventPayload,
-			ts_wall_ms: tsWallMs,
-			ts_mono_ms: tsMonoMs
-		}]);
-	} finally {
-		store.close();
+		const payload = await readStdinJson();
+		const sessionId = resolveSessionStreamId(payload);
+		if (!sessionId) {
+			emitStructuredError("validation_error", "session id required");
+			return;
+		}
+		if (sessionId.startsWith("msg_")) {
+			emitStructuredError("validation_error", "invalid session id");
+			return;
+		}
+		const eventType = typeof payload.event_type === "string" ? payload.event_type.trim() : "";
+		if (!eventType) {
+			emitStructuredError("validation_error", "event_type required");
+			return;
+		}
+		const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
+		const project = typeof payload.project === "string" ? payload.project : null;
+		const startedAt = typeof payload.started_at === "string" ? payload.started_at : null;
+		const tsWallMs = Number.isFinite(Number(payload.ts_wall_ms)) ? Math.floor(Number(payload.ts_wall_ms)) : null;
+		const tsMonoMs = Number.isFinite(Number(payload.ts_mono_ms)) ? Number(payload.ts_mono_ms) : null;
+		const eventId = typeof payload.event_id === "string" ? payload.event_id.trim() : "";
+		const eventPayload = payload.payload && typeof payload.payload === "object" && !Array.isArray(payload.payload) ? stripPrivateObj(payload.payload) : {};
+		const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
+		try {
+			store.updateRawEventSessionMeta({
+				opencodeSessionId: sessionId,
+				source: "opencode",
+				cwd,
+				project,
+				startedAt,
+				lastSeenTsWallMs: tsWallMs
+			});
+			store.recordRawEventsBatch(sessionId, [{
+				event_id: eventId,
+				event_type: eventType,
+				payload: eventPayload,
+				ts_wall_ms: tsWallMs,
+				ts_mono_ms: tsMonoMs
+			}]);
+		} finally {
+			store.close();
+		}
+	} catch (err) {
+		emitStructuredError("enqueue_error", err instanceof Error ? err.message : String(err));
 	}
 });
 //#endregion
@@ -603,9 +1502,11 @@ var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(help
 function expandUserPath(value) {
 	return value.startsWith("~/") ? join(homedir(), value.slice(2)) : value;
 }
-var exportMemoriesCommand = new Command("export-memories").configureHelp(helpStyle).description("Export memories to a JSON file for sharing or backup").argument("<output>", "output file path (use '-' for stdout)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--project <project>", "filter by project (defaults to git repo root)").option("--all-projects", "export all projects").option("--include-inactive", "include deactivated memories").option("--since <iso>", "only export memories created after this ISO timestamp").action((output, opts) => {
+var cmd$2 = new Command("export-memories").configureHelp(helpStyle).description("Export memories to a JSON file for sharing or backup").argument("<output>", "output file path (use '-' for stdout)").option("--project <project>", "filter by project (defaults to git repo root)").option("--all-projects", "export all projects").option("--include-inactive", "include deactivated memories").option("--since <iso>", "only export memories created after this ISO timestamp");
+addDbOption(cmd$2);
+cmd$2.action((output, opts) => {
 	const payload = exportMemories({
-		dbPath: resolveDbPath(opts.db ?? opts.dbPath),
+		dbPath: resolveDbPath(resolveDbOpt(opts)),
 		project: opts.project,
 		allProjects: opts.allProjects,
 		includeInactive: opts.includeInactive,
@@ -628,31 +1529,49 @@ var exportMemoriesCommand = new Command("export-memories").configureHelp(helpSty
 	].join("\n"));
 	p.outro("done");
 });
+var exportMemoriesCommand = cmd$2;
 //#endregion
 //#region src/commands/import-memories.ts
-var importMemoriesCommand = new Command("import-memories").configureHelp(helpStyle).description("Import memories from an exported JSON file").argument("<inputFile>", "input JSON file (use '-' for stdin)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--remap-project <path>", "remap all projects to this path on import").option("--dry-run", "preview import without writing").action((inputFile, opts) => {
+var cmd$1 = new Command("import-memories").configureHelp(helpStyle).description("Import memories from an exported JSON file").argument("<inputFile>", "input JSON file (use '-' for stdin)").option("--remap-project <path>", "remap all projects to this path on import").option("--dry-run", "preview import without writing");
+addDbOption(cmd$1);
+addJsonOption(cmd$1);
+cmd$1.action((inputFile, opts) => {
 	let payload;
 	try {
 		payload = readImportPayload(inputFile);
 	} catch (error) {
-		p.log.error(error instanceof Error ? error.message : "Invalid import file");
-		process.exitCode = 1;
+		const message = error instanceof Error ? error.message : "Invalid import file";
+		if (opts.json) emitJsonError("invalid_input", message);
+		else {
+			p.log.error(message);
+			process.exitCode = 1;
+		}
 		return;
 	}
-	p.intro("codemem import-memories");
-	p.log.info([
-		`Export version: ${payload.version}`,
-		`Exported at:    ${payload.exported_at}`,
-		`Sessions:       ${payload.sessions.length.toLocaleString()}`,
-		`Memories:       ${payload.memory_items.length.toLocaleString()}`,
-		`Summaries:      ${payload.session_summaries.length.toLocaleString()}`,
-		`Prompts:        ${payload.user_prompts.length.toLocaleString()}`
-	].join("\n"));
+	if (!opts.json) {
+		p.intro("codemem import-memories");
+		p.log.info([
+			`Export version: ${payload.version}`,
+			`Exported at:    ${payload.exported_at}`,
+			`Sessions:       ${payload.sessions.length.toLocaleString()}`,
+			`Memories:       ${payload.memory_items.length.toLocaleString()}`,
+			`Summaries:      ${payload.session_summaries.length.toLocaleString()}`,
+			`Prompts:        ${payload.user_prompts.length.toLocaleString()}`
+		].join("\n"));
+	}
 	const result = importMemories(payload, {
-		dbPath: resolveDbPath(opts.db ?? opts.dbPath),
+		dbPath: resolveDbPath(resolveDbOpt(opts)),
 		remapProject: opts.remapProject,
 		dryRun: opts.dryRun
 	});
+	if (opts.json) {
+		console.log(JSON.stringify({
+			sessions: result.sessions,
+			memory_items: result.memory_items,
+			skipped: result.dryRun
+		}));
+		return;
+	}
 	if (result.dryRun) {
 		p.outro("dry run complete");
 		return;
@@ -665,25 +1584,53 @@ var importMemoriesCommand = new Command("import-memories").configureHelp(helpSty
 	].join("\n"));
 	p.outro("done");
 });
+var importMemoriesCommand = cmd$1;
 //#endregion
 //#region src/commands/mcp.ts
-var mcpCommand = new Command("mcp").configureHelp(helpStyle).description("Start the MCP stdio server").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
-	const dbPath = opts.db ?? opts.dbPath;
+var mcpCmd = new Command("mcp").configureHelp(helpStyle).description("Start the MCP stdio server");
+addDbOption(mcpCmd);
+var mcpCommand = mcpCmd.action(async (opts) => {
+	const dbPath = resolveDbOpt(opts);
 	if (dbPath) process.env.CODEMEM_DB = dbPath;
-	await import("@codemem/mcp");
+	try {
+		await import("@codemem/mcp");
+	} catch (err) {
+		console.error(`Failed to start MCP server: ${err instanceof Error ? err.message : String(err)}`);
+		process.exitCode = 1;
+	}
 });
 //#endregion
+//#region src/commands/pack-shared.ts
+function collectWorkingSetFile(value, previous) {
+	return [...previous, value];
+}
+function buildPackRequestOptions(opts, ctx = {}) {
+	const limit = Number.parseInt(opts.limit ?? "10", 10) || 10;
+	const budgetRaw = opts.tokenBudget ?? opts.budget;
+	const budget = budgetRaw ? Number.parseInt(budgetRaw, 10) : void 0;
+	const filters = {};
+	if (!opts.allProjects) {
+		const defaultProject = ctx.envProject?.trim() || null;
+		const resolveProjectFn = ctx.resolveProjectFn ?? resolveProject;
+		const cwd = ctx.cwd ?? process.cwd();
+		const project = defaultProject || resolveProjectFn(cwd, opts.project ?? null);
+		if (project) filters.project = project;
+	}
+	if ((opts.workingSetFile?.length ?? 0) > 0) filters.working_set_paths = opts.workingSetFile;
+	return {
+		limit,
+		budget,
+		filters
+	};
+}
+//#endregion
 //#region src/commands/memory.ts
 /**
-* Memory management CLI commands — show, forget, remember.
+* Memory management CLI commands — show, forget, remember, inject.
 *
 * Ports codemem/commands/memory_cmds.py (show_cmd, forget_cmd, remember_cmd).
-* Compact and inject are deferred — compact requires the summarizer pipeline,
-* and inject is just pack_text output which the existing pack command covers.
+* Inject is deprecated in favor of `codemem pack`.
 */
-function collectWorkingSetFile$1(value, previous) {
-	return [...previous, value];
-}
 /** Parse a strict positive integer, rejecting prefixes like "12abc". */
 function parseStrictPositiveId(value) {
 	if (!/^\d+$/.test(value.trim())) return null;
@@ -693,19 +1640,35 @@ function parseStrictPositiveId(value) {
 function showMemoryAction(idStr, opts) {
 	const memoryId = parseStrictPositiveId(idStr);
 	if (memoryId === null) {
-		p.log.error(`Invalid memory ID: ${idStr}`);
-		process.exitCode = 1;
+		if (opts.json) emitJsonError("invalid_id", `Invalid memory ID: ${idStr}`);
+		else {
+			p.log.error(`Invalid memory ID: ${idStr}`);
+			process.exitCode = 1;
+		}
 		return;
 	}
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const item = store.get(memoryId);
 		if (!item) {
-			p.log.error(`Memory ${memoryId} not found`);
-			process.exitCode = 1;
+			if (opts.json) emitJsonError("not_found", `Memory ${memoryId} not found`);
+			else {
+				p.log.error(`Memory ${memoryId} not found`);
+				process.exitCode = 1;
+			}
 			return;
 		}
-		console.log(JSON.stringify(item, null, 2));
+		if (opts.json) console.log(JSON.stringify(item, null, 2));
+		else {
+			console.log(`#${item.id} [${item.kind}] ${item.title}`);
+			if (item.subtitle) console.log(`  ${item.subtitle}`);
+			console.log(`  created: ${item.created_at}  confidence: ${item.confidence}`);
+			if (item.tags_text) console.log(`  tags: ${item.tags_text}`);
+			if (item.body_text) {
+				const preview = item.body_text.length > 300 ? `${item.body_text.slice(0, 300)}…` : item.body_text;
+				console.log(`\n${preview}`);
+			}
+		}
 	} finally {
 		store.close();
 	}
@@ -713,20 +1676,27 @@ function showMemoryAction(idStr, opts) {
 function forgetMemoryAction(idStr, opts) {
 	const memoryId = parseStrictPositiveId(idStr);
 	if (memoryId === null) {
-		p.log.error(`Invalid memory ID: ${idStr}`);
-		process.exitCode = 1;
+		if (opts.json) emitJsonError("invalid_id", `Invalid memory ID: ${idStr}`);
+		else {
+			p.log.error(`Invalid memory ID: ${idStr}`);
+			process.exitCode = 1;
+		}
 		return;
 	}
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		store.forget(memoryId);
-		p.log.success(`Memory ${memoryId} marked inactive`);
+		if (opts.json) console.log(JSON.stringify({
+			id: memoryId,
+			status: "forgotten"
+		}));
+		else p.log.success(`Memory ${memoryId} marked inactive`);
 	} finally {
 		store.close();
 	}
 }
 async function rememberMemoryAction(opts) {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	let sessionId = null;
 	try {
 		const project = resolveProject(process.cwd(), opts.project ?? null);
@@ -740,7 +1710,8 @@ async function rememberMemoryAction(opts) {
 		const memId = store.remember(sessionId, opts.kind, opts.title, opts.body, .5, opts.tags);
 		await store.flushPendingVectorWrites();
 		store.endSession(sessionId, { manual: true });
-		p.log.success(`Stored memory ${memId}`);
+		if (opts.json) console.log(JSON.stringify({ id: memId }));
+		else p.log.success(`Stored memory ${memId}`);
 	} catch (err) {
 		if (sessionId !== null) try {
 			store.endSession(sessionId, {
@@ -748,46 +1719,504 @@ async function rememberMemoryAction(opts) {
 				error: true
 			});
 		} catch {}
-		throw err;
+		const message = err instanceof Error ? err.message : String(err);
+		if (opts.json) emitJsonError("remember_failed", message);
+		else {
+			p.log.error(`Failed to store memory: ${message}`);
+			process.exitCode = 1;
+		}
 	} finally {
 		store.close();
 	}
 }
 function createShowMemoryCommand() {
-	return new Command("show").configureHelp(helpStyle).description("Print a memory item as JSON").argument("<id>", "memory ID").option("--db <path>", "database path").option("--db-path <path>", "database path").action(showMemoryAction);
+	const cmd = new Command("show").configureHelp(helpStyle).description("Show a memory item").argument("<id>", "memory ID");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action(showMemoryAction);
+	return cmd;
 }
 function createForgetMemoryCommand() {
-	return new Command("forget").configureHelp(helpStyle).description("Deactivate a memory item").argument("<id>", "memory ID").option("--db <path>", "database path").option("--db-path <path>", "database path").action(forgetMemoryAction);
+	const cmd = new Command("forget").configureHelp(helpStyle).description("Deactivate a memory item").argument("<id>", "memory ID");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action(forgetMemoryAction);
+	return cmd;
 }
 function createRememberMemoryCommand() {
-	return new Command("remember").configureHelp(helpStyle).description("Manually add a memory item").requiredOption("-k, --kind <kind>", "memory kind (discovery, decision, feature, bugfix, etc.)").requiredOption("-t, --title <title>", "memory title").requiredOption("-b, --body <body>", "memory body text").option("--tags <tags...>", "tags (space-separated)").option("--project <project>", "project name (defaults to git repo root)").option("--db <path>", "database path").option("--db-path <path>", "database path").action(rememberMemoryAction);
+	const cmd = new Command("remember").configureHelp(helpStyle).description("Manually add a memory item").requiredOption("-k, --kind <kind>", "memory kind (discovery, decision, feature, bugfix, etc.)").requiredOption("-t, --title <title>", "memory title").requiredOption("-b, --body <body>", "memory body text").option("--tags <tags...>", "tags (space-separated)").option("--project <project>", "project name (defaults to git repo root)");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action(rememberMemoryAction);
+	return cmd;
+}
+function createInjectMemoryCommand() {
+	const cmd = new Command("inject").configureHelp(helpStyle).description("Build raw memory context text for manual prompt injection").argument("<context>", "context string to search for").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--token-budget <tokens>", "token budget").option("--working-set-file <path>", "recently modified file path used as ranking hint", collectWorkingSetFile, []).option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").allowUnknownOption(true).allowExcessArguments(true);
+	addDbOption(cmd);
+	cmd.action(async (context, opts) => {
+		emitDeprecationWarning("codemem memory inject", "codemem pack");
+		const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
+		try {
+			const { limit, budget, filters } = buildPackRequestOptions(opts, { envProject: process.env.CODEMEM_PROJECT });
+			const pack = await store.buildMemoryPackAsync(context, limit, budget, filters);
+			console.log(pack.pack_text ?? "");
+		} finally {
+			store.close();
+		}
+	});
+	return cmd;
+}
+function createMemoryRoleReportCommand() {
+	const cmd = new Command("role-report").configureHelp(helpStyle).description("Analyze inferred memory roles in a DB snapshot").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "analyze across all projects").option("--probe <query>", "run a retrieval probe query against the snapshot", (value, prev) => [...prev, value], []).option("--scenario <id>", "run a named injection-first eval scenario pack (can be repeated)", (value, prev) => [...prev, value], []).option("--inactive", "include inactive memories");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action((opts) => {
+		const project = opts.allProjects === true ? null : opts.project?.trim() || process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), null);
+		const invalidScenario = (opts.scenario ?? []).find((id) => getInjectionEvalScenarioPack(id) == null);
+		if (invalidScenario) throw new Error(`Unknown eval scenario pack: ${invalidScenario}`);
+		const probes = [...opts.probe ?? [], ...getInjectionEvalScenarioPrompts(opts.scenario ?? [])];
+		const result = getMemoryRoleReport(resolveDbOpt(opts), {
+			project,
+			allProjects: opts.allProjects === true,
+			includeInactive: opts.inactive === true,
+			probes
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		p.intro("codemem memory role-report");
+		p.log.info([
+			`Memories: ${result.totals.memories}`,
+			`Active: ${result.totals.active}`,
+			`Sessions: ${result.totals.sessions}`
+		].join("\n"));
+		p.log.info("Counts by role:");
+		for (const [role, count] of Object.entries(result.counts_by_role)) p.log.message(`  ${role.padEnd(10)} ${String(count)}`);
+		p.log.info("Counts by mapping:");
+		p.log.message(`  mapped      ${result.counts_by_mapping.mapped}`);
+		p.log.message(`  unmapped    ${result.counts_by_mapping.unmapped}`);
+		p.log.info("Summary lineages:");
+		p.log.message(`  session_summary         ${result.summary_lineages.session_summary}`);
+		p.log.message(`  legacy_metadata_summary ${result.summary_lineages.legacy_metadata_summary}`);
+		p.log.message(`  summary_mapped          ${result.summary_mapping.mapped}`);
+		p.log.message(`  summary_unmapped        ${result.summary_mapping.unmapped}`);
+		p.log.info("Project quality:");
+		for (const [bucket, count] of Object.entries(result.project_quality)) p.log.message(`  ${bucket.padEnd(12)} ${String(count)}`);
+		p.log.info("Session classes:");
+		for (const [bucket, count] of Object.entries(result.session_class_buckets)) p.log.message(`  ${bucket.padEnd(20)} ${String(count)}`);
+		p.log.info("Summary dispositions:");
+		for (const [bucket, count] of Object.entries(result.summary_disposition_buckets)) p.log.message(`  ${bucket.padEnd(20)} ${String(count)}`);
+		if (result.probe_results.length > 0) {
+			p.log.info("Probe results:");
+			for (const probe of result.probe_results) {
+				p.log.message(`  query: ${probe.query}`);
+				if (probe.scenario_id) p.log.message(`    scenario: ${probe.scenario_id} (${probe.scenario_category ?? "unknown"})${probe.scenario_title ? ` — ${probe.scenario_title}` : ""}`);
+				p.log.message(`    mode: ${probe.mode}`);
+				p.log.message(`    top roles: durable=${probe.top_role_counts.durable} recap=${probe.top_role_counts.recap} ephemeral=${probe.top_role_counts.ephemeral} general=${probe.top_role_counts.general}`);
+				p.log.message(`    top mapping: mapped=${probe.top_mapping_counts.mapped} unmapped=${probe.top_mapping_counts.unmapped}`);
+				p.log.message(`    burden: recap_share=${probe.top_burden.recap_share.toFixed(2)} unmapped_share=${probe.top_burden.unmapped_share.toFixed(2)} recap_unmapped_share=${probe.top_burden.recap_unmapped_share.toFixed(2)}`);
+				if (probe.simulated_demoted_unmapped_recap) p.log.message(`    simulated demote-unmapped-recap burden: recap_share=${probe.simulated_demoted_unmapped_recap.top_burden.recap_share.toFixed(2)} unmapped_share=${probe.simulated_demoted_unmapped_recap.top_burden.unmapped_share.toFixed(2)} recap_unmapped_share=${probe.simulated_demoted_unmapped_recap.top_burden.recap_unmapped_share.toFixed(2)}`);
+				if (probe.simulated_demoted_unmapped_recap_and_ephemeral) p.log.message(`    simulated demote-unmapped-recap+ephemeral burden: recap_share=${probe.simulated_demoted_unmapped_recap_and_ephemeral.top_burden.recap_share.toFixed(2)} unmapped_share=${probe.simulated_demoted_unmapped_recap_and_ephemeral.top_burden.unmapped_share.toFixed(2)} recap_unmapped_share=${probe.simulated_demoted_unmapped_recap_and_ephemeral.top_burden.recap_unmapped_share.toFixed(2)}`);
+				if (probe.scenario_score) p.log.message(`    scenario score: mode_match=${probe.scenario_score.mode_match ? "yes" : "no"} top1_primary=${probe.scenario_score.primary_in_top1 ? "yes" : "no"} top3_primary=${probe.scenario_score.primary_in_top3_count} top1_anti=${probe.scenario_score.anti_signal_in_top1 ? "yes" : "no"} primary=${probe.scenario_score.primary_match_count} anti=${probe.scenario_score.anti_signal_count} recap=${probe.scenario_score.recap_count} unmapped_recap=${probe.scenario_score.unmapped_recap_count} chatter=${probe.scenario_score.administrative_chatter_count} net=${probe.scenario_score.score}`);
+				for (const item of probe.items.slice(0, 5)) p.log.message(`    [${item.id}] (${item.kind}/${item.role}/${item.mapping}/${item.session_class}/${item.summary_disposition}) ${item.title} — ${item.role_reason}`);
+			}
+		}
+		p.outro("done");
+	});
+	return cmd;
+}
+function createMemoryRoleCompareCommand() {
+	const cmd = new Command("role-compare").configureHelp(helpStyle).description("Compare inferred memory-role and probe metrics across two DB snapshots").argument("<baseline_db>", "baseline sqlite database path").argument("<candidate_db>", "candidate sqlite database path").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "analyze across all projects").option("--probe <query>", "run a retrieval probe query against both snapshots", (value, prev) => [...prev, value], []).option("--scenario <id>", "run a named injection-first eval scenario pack (can be repeated)", (value, prev) => [...prev, value], []).option("--inactive", "include inactive memories");
+	addJsonOption(cmd);
+	cmd.action((baselineDb, candidateDb, opts) => {
+		const project = opts.allProjects === true ? null : opts.project?.trim() || process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), null);
+		const invalidScenario = (opts.scenario ?? []).find((id) => getInjectionEvalScenarioPack(id) == null);
+		if (invalidScenario) throw new Error(`Unknown eval scenario pack: ${invalidScenario}`);
+		const probes = [...opts.probe ?? [], ...getInjectionEvalScenarioPrompts(opts.scenario ?? [])];
+		const result = compareMemoryRoleReports(baselineDb, candidateDb, {
+			project,
+			allProjects: opts.allProjects === true,
+			includeInactive: opts.inactive === true,
+			probes
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		p.intro("codemem memory role-compare");
+		p.log.info([
+			`Baseline sessions: ${result.baseline.totals.sessions}`,
+			`Candidate sessions: ${result.candidate.totals.sessions}`,
+			`Delta sessions: ${result.delta.totals.sessions}`,
+			`Mapped delta: ${result.delta.counts_by_mapping.mapped}`,
+			`Unmapped delta: ${result.delta.counts_by_mapping.unmapped}`,
+			`Summary mapped delta: ${result.delta.summary_mapping.mapped}`,
+			`Summary unmapped delta: ${result.delta.summary_mapping.unmapped}`
+		].join("\n"));
+		p.log.info("Role deltas:");
+		for (const [role, count] of Object.entries(result.delta.counts_by_role)) p.log.message(`  ${role.padEnd(10)} ${String(count)}`);
+		p.log.info("Session class deltas:");
+		for (const [bucket, count] of Object.entries(result.delta.session_class_buckets)) p.log.message(`  ${bucket.padEnd(20)} ${String(count)}`);
+		p.log.info("Summary disposition deltas:");
+		for (const [bucket, count] of Object.entries(result.delta.summary_disposition_buckets)) p.log.message(`  ${bucket.padEnd(20)} ${String(count)}`);
+		if (result.probe_comparisons.length > 0) {
+			p.log.info("Probe comparisons:");
+			for (const probe of result.probe_comparisons) {
+				p.log.message(`  query: ${probe.query}`);
+				p.log.message(`    modes: baseline=${probe.baseline_mode ?? "-"} candidate=${probe.candidate_mode ?? "-"}`);
+				p.log.message(`    overlap: shared_top_keys=${probe.shared_item_keys.length} baseline_top=${probe.baseline_item_ids.slice(0, 5).join(",") || "-"} candidate_top=${probe.candidate_item_ids.slice(0, 5).join(",") || "-"}`);
+				if (probe.delta_top_burden) p.log.message(`    burden delta: recap_share=${probe.delta_top_burden.recap_share.toFixed(2)} unmapped_share=${probe.delta_top_burden.unmapped_share.toFixed(2)} recap_unmapped_share=${probe.delta_top_burden.recap_unmapped_share.toFixed(2)}`);
+				if (probe.delta_top_mapping_counts) p.log.message(`    mapping delta: mapped=${probe.delta_top_mapping_counts.mapped} unmapped=${probe.delta_top_mapping_counts.unmapped}`);
+				if (probe.baseline_scenario_score || probe.candidate_scenario_score) p.log.message(`    scenario scores: baseline=${probe.baseline_scenario_score?.score ?? "-"} candidate=${probe.candidate_scenario_score?.score ?? "-"}`);
+				if (probe.delta_scenario_score) p.log.message(`    scenario delta: mode_match=${probe.delta_scenario_score.mode_match ?? "-"} top1_primary=${probe.delta_scenario_score.primary_in_top1 ?? "-"} top3_primary=${probe.delta_scenario_score.primary_in_top3_count ?? "-"} top1_anti=${probe.delta_scenario_score.anti_signal_in_top1 ?? "-"} primary=${probe.delta_scenario_score.primary_match_count ?? "-"} anti=${probe.delta_scenario_score.anti_signal_count ?? "-"} recap=${probe.delta_scenario_score.recap_count ?? "-"} unmapped_recap=${probe.delta_scenario_score.unmapped_recap_count ?? "-"} chatter=${probe.delta_scenario_score.administrative_chatter_count ?? "-"} net=${probe.delta_scenario_score.score ?? "-"}`);
+			}
+		}
+		p.outro("done");
+	});
+	return cmd;
+}
+function createMemoryExtractionReportCommand() {
+	const cmd = new Command("extraction-report").configureHelp(helpStyle).description("Score extracted memories for a session against a built-in extraction eval rubric").option("--session-id <id>", "session ID to evaluate").option("--batch-id <id>", "raw-event flush batch ID to evaluate").requiredOption("--scenario <id>", "built-in extraction eval scenario ID").option("--inactive", "include inactive memories");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action((opts) => {
+		const sessionIdInput = opts.sessionId?.trim() ?? "";
+		const batchIdInput = opts.batchId?.trim() ?? "";
+		const hasSessionId = sessionIdInput.length > 0;
+		const hasBatchId = batchIdInput.length > 0;
+		if (hasSessionId === hasBatchId) throw new Error("Provide exactly one of --session-id or --batch-id");
+		const sessionId = hasSessionId ? parseStrictPositiveId(sessionIdInput) : null;
+		if (hasSessionId && sessionId === null) throw new Error(`Invalid session ID: ${sessionIdInput || opts.sessionId}`);
+		const batchId = hasBatchId ? parseStrictPositiveId(batchIdInput) : null;
+		if (hasBatchId && batchId === null) throw new Error(`Invalid batch ID: ${batchIdInput || opts.batchId}`);
+		const scenarioId = opts.scenario?.trim() ?? "";
+		const scenario = getSessionExtractionEvalScenario(scenarioId);
+		if (!scenario) throw new Error(`Unknown extraction eval scenario: ${scenarioId || opts.scenario}`);
+		const result = batchId != null ? getSessionExtractionEval(resolveDbOpt(opts), {
+			batchId,
+			scenarioId: scenario.id,
+			includeInactive: opts.inactive === true
+		}) : getSessionExtractionEval(resolveDbOpt(opts), {
+			sessionId,
+			scenarioId: scenario.id,
+			includeInactive: opts.inactive === true
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		p.intro("codemem memory extraction-report");
+		p.log.info([
+			`Scenario: ${result.scenario.id} — ${result.scenario.title}`,
+			`Target: ${result.target.type}${result.target.batchId != null ? ` #${result.target.batchId}` : ""}`,
+			`Session: ${result.session.id} (${result.session.project ?? "no-project"})`,
+			`Session class: ${result.session.sessionClass}`,
+			`Summary disposition: ${result.session.summaryDisposition}`
+		].join("\n"));
+		p.log.info([
+			`Pass: ${result.pass ? "yes" : "no"}`,
+			`Summary count: ${result.counts.summaries}`,
+			`Observation count: ${result.counts.observations}`,
+			`Summary thread coverage: ${result.coverage.summaryThreadCoverage}`,
+			`Observation thread coverage: ${result.coverage.observationThreadCoverage}`,
+			`Total thread coverage: ${result.coverage.totalThreadCoverage}`,
+			`Duplicate observation threads: ${result.coverage.duplicateObservationThreads}`
+		].join("\n"));
+		if (result.failureReasons.length > 0) {
+			p.log.warn("Failure reasons:");
+			for (const reason of result.failureReasons) p.log.message(`  - ${reason}`);
+		}
+		p.log.info("Thread coverage:");
+		for (const thread of result.threads) p.log.message(`  ${thread.id.padEnd(22)} summary=${thread.summaryMatch ? "yes" : "no"} observations=${thread.observationMatch ? "yes" : "no"}`);
+		p.outro("done");
+	});
+	return cmd;
+}
+function createMemoryExtractionReplayCommand() {
+	const cmd = new Command("extraction-replay").configureHelp(helpStyle).description("Re-run the observer on a historical flush batch without persisting, then score the fresh output").requiredOption("--batch-id <id>", "raw-event flush batch ID to replay").option("--transcript-budget <chars>", "override replay transcript budget in characters (replay only)").option("--observer-tier-routing", "use replay-only benchmark-backed observer tier routing").option("--observer-temperature <value>", "override observer temperature for replay only").option("--openai-responses", "use OpenAI Responses API for replay only").option("--reasoning-effort <level>", "set OpenAI reasoning.effort for replay only (responses path)").option("--reasoning-summary <mode>", "set OpenAI reasoning.summary for replay only (responses path)").option("--max-output-tokens <n>", "override OpenAI max_output_tokens for replay only (responses path)").requiredOption("--scenario <id>", "built-in extraction eval scenario ID");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action(async (opts) => {
+		const batchIdInput = opts.batchId?.trim() ?? "";
+		const batchId = parseStrictPositiveId(batchIdInput);
+		if (batchId === null) throw new Error(`Invalid batch ID: ${batchIdInput || opts.batchId}`);
+		const scenarioId = opts.scenario?.trim() ?? "";
+		const scenario = getSessionExtractionEvalScenario(scenarioId);
+		if (!scenario) throw new Error(`Unknown extraction eval scenario: ${scenarioId || opts.scenario}`);
+		const transcriptBudgetInput = opts.transcriptBudget?.trim() ?? "";
+		const transcriptBudget = transcriptBudgetInput.length > 0 ? parseStrictPositiveId(transcriptBudgetInput) : null;
+		if (transcriptBudgetInput.length > 0 && transcriptBudget === null) throw new Error(`Invalid transcript budget: ${transcriptBudgetInput || opts.transcriptBudget}`);
+		const observerTemperatureInput = opts.observerTemperature?.trim() ?? "";
+		let observerTemperature;
+		if (observerTemperatureInput.length > 0) {
+			const parsed = Number(observerTemperatureInput);
+			if (!Number.isFinite(parsed)) throw new Error(`Invalid observer temperature: ${observerTemperatureInput || opts.observerTemperature}`);
+			observerTemperature = parsed;
+		}
+		const maxOutputTokensInput = opts.maxOutputTokens?.trim() ?? "";
+		const maxOutputTokens = maxOutputTokensInput.length > 0 ? parseStrictPositiveId(maxOutputTokensInput) : null;
+		if (maxOutputTokensInput.length > 0 && maxOutputTokens === null) throw new Error(`Invalid max output tokens: ${maxOutputTokensInput || opts.maxOutputTokens}`);
+		const observerConfig = loadObserverConfig();
+		const observerConfigWithOverrides = {
+			...observerConfig,
+			observerTemperature: observerTemperature ?? observerConfig.observerTemperature,
+			observerOpenAIUseResponses: opts.openaiResponses === true,
+			observerReasoningEffort: opts.reasoningEffort?.trim() || null,
+			observerReasoningSummary: opts.reasoningSummary?.trim() || null,
+			observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxTokens
+		};
+		const observer = new ObserverClient(observerConfigWithOverrides);
+		const result = opts.observerTierRouting === true ? await replayBatchExtractionWithTierRouting(resolveDbOpt(opts), observerConfigWithOverrides, {
+			batchId,
+			scenarioId: scenario.id,
+			transcriptBudget: transcriptBudget ?? void 0
+		}) : await replayBatchExtraction(resolveDbOpt(opts), observer, {
+			batchId,
+			scenarioId: scenario.id,
+			transcriptBudget: transcriptBudget ?? void 0
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		p.intro("codemem memory extraction-replay");
+		p.log.info([
+			`Scenario: ${result.scenario.id} — ${result.scenario.title}`,
+			`Batch: ${result.target.batchId}`,
+			`Session: ${result.target.sessionId}`,
+			`Observer: ${result.observer.provider}/${result.observer.model}`,
+			`Tier: ${result.observer.tier ?? "manual"}`,
+			`OpenAI Responses: ${result.observer.openaiUseResponses ? "yes" : "no"}`,
+			`Reasoning effort: ${result.observer.reasoningEffort ?? "none"}`,
+			`Classification: ${result.classification.status}`,
+			`Pass: ${result.evaluation.pass ? "yes" : "no"}`
+		].join("\n"));
+		if (result.classification.reason) p.log.message(`Classification reason: ${result.classification.reason}`);
+		if (result.evaluation.failureReasons.length > 0) {
+			p.log.warn("Failure reasons:");
+			for (const reason of result.evaluation.failureReasons) p.log.message(`  - ${reason}`);
+		}
+		p.log.info([
+			`Fresh summaries: ${result.evaluation.counts.summaries}`,
+			`Fresh observations: ${result.evaluation.counts.observations}`,
+			`Summary thread coverage: ${result.evaluation.coverage.summaryThreadCoverage}`,
+			`Observation thread coverage: ${result.evaluation.coverage.observationThreadCoverage}`,
+			`Total thread coverage: ${result.evaluation.coverage.totalThreadCoverage}`
+		].join("\n"));
+		p.outro("done");
+	});
+	return cmd;
+}
+function createMemoryExtractionBenchmarkCommand() {
+	const cmd = new Command("extraction-benchmark").configureHelp(helpStyle).description("Run the formal extraction replay benchmark set and print a cost/quality scoreboard").requiredOption("--benchmark <id>", "benchmark profile id").option("--observer-provider <provider>", "override observer provider for this benchmark run").option("--observer-model <model>", "override observer model for this benchmark run").option("--observer-tier-routing", "use replay-only benchmark-backed observer tier routing").option("--openai-responses", "use OpenAI Responses API for this benchmark run").option("--reasoning-effort <level>", "set OpenAI reasoning.effort for this benchmark run (responses path)").option("--reasoning-summary <mode>", "set OpenAI reasoning.summary for this benchmark run (responses path)").option("--max-output-tokens <n>", "override OpenAI max_output_tokens for this benchmark run (responses path)").option("--observer-temperature <value>", "override observer temperature for this benchmark run").option("--transcript-budget <chars>", "override replay transcript budget in characters for this benchmark run");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action(async (opts) => {
+		const benchmarkId = opts.benchmark?.trim() ?? "";
+		const benchmark = getExtractionBenchmarkProfile(benchmarkId);
+		if (!benchmark) throw new Error(`Unknown extraction benchmark: ${benchmarkId || opts.benchmark}`);
+		const transcriptBudgetInput = opts.transcriptBudget?.trim() ?? "";
+		const transcriptBudget = transcriptBudgetInput.length > 0 ? parseStrictPositiveId(transcriptBudgetInput) : null;
+		if (transcriptBudgetInput.length > 0 && transcriptBudget === null) throw new Error(`Invalid transcript budget: ${transcriptBudgetInput || opts.transcriptBudget}`);
+		const observerTemperatureInput = opts.observerTemperature?.trim() ?? "";
+		let observerTemperature;
+		if (observerTemperatureInput.length > 0) {
+			const parsed = Number(observerTemperatureInput);
+			if (!Number.isFinite(parsed)) throw new Error(`Invalid observer temperature: ${observerTemperatureInput || opts.observerTemperature}`);
+			observerTemperature = parsed;
+		}
+		const maxOutputTokensInput = opts.maxOutputTokens?.trim() ?? "";
+		const maxOutputTokens = maxOutputTokensInput.length > 0 ? parseStrictPositiveId(maxOutputTokensInput) : null;
+		if (maxOutputTokensInput.length > 0 && maxOutputTokens === null) throw new Error(`Invalid max output tokens: ${maxOutputTokensInput || opts.maxOutputTokens}`);
+		const observerConfig = loadObserverConfig();
+		const observerConfigWithOverrides = {
+			...observerConfig,
+			observerProvider: opts.observerProvider?.trim() || observerConfig.observerProvider,
+			observerModel: opts.observerModel?.trim() || observerConfig.observerModel,
+			observerTemperature: observerTemperature ?? observerConfig.observerTemperature,
+			observerOpenAIUseResponses: opts.openaiResponses === true,
+			observerReasoningEffort: opts.reasoningEffort?.trim() || null,
+			observerReasoningSummary: opts.reasoningSummary?.trim() || null,
+			observerMaxOutputTokens: maxOutputTokens ?? observerConfig.observerMaxTokens
+		};
+		const observer = new ObserverClient(observerConfigWithOverrides);
+		const runs = [];
+		for (const batch of benchmark.batches) {
+			const scenarioId = batch.scenarioId ?? benchmark.scenarioId;
+			const result = opts.observerTierRouting === true ? await replayBatchExtractionWithTierRouting(resolveDbOpt(opts), observerConfigWithOverrides, {
+				batchId: batch.batchId,
+				scenarioId,
+				transcriptBudget: transcriptBudget ?? void 0
+			}) : await replayBatchExtraction(resolveDbOpt(opts), observer, {
+				batchId: batch.batchId,
+				scenarioId,
+				transcriptBudget: transcriptBudget ?? void 0
+			});
+			runs.push({
+				batchId: batch.batchId,
+				sessionId: batch.sessionId,
+				label: batch.label,
+				purpose: batch.purpose,
+				complexity: batch.complexity,
+				scenarioId,
+				expectedTier: batch.expectedTier ?? null,
+				analysis: {
+					eventSpan: result.analysis.eventSpan,
+					promptCount: result.analysis.promptCount,
+					toolCount: result.analysis.toolCount,
+					transcriptLength: result.analysis.transcriptLength
+				},
+				status: result.classification.status,
+				reason: result.classification.reason,
+				tier: result.observer.tier ?? "manual",
+				provider: result.observer.provider,
+				model: result.observer.model,
+				openaiUseResponses: result.observer.openaiUseResponses,
+				reasoningEffort: result.observer.reasoningEffort,
+				reasoningSummary: result.observer.reasoningSummary,
+				maxOutputTokens: result.observer.maxOutputTokens,
+				temperature: result.observer.temperature,
+				summaries: result.evaluation.counts.summaries,
+				observations: result.evaluation.counts.observations,
+				repairApplied: result.observer.repairApplied
+			});
+		}
+		const summary = {
+			total: runs.length,
+			shapeQualityTotal: runs.filter((run) => run.purpose === "shape_quality").length,
+			shapeQualityPasses: runs.filter((run) => run.purpose === "shape_quality" && run.status === "pass").length,
+			shapeQualityFails: runs.filter((run) => run.purpose === "shape_quality" && run.status === "shape_fail").length,
+			expectedTierTotal: runs.filter((run) => run.expectedTier != null).length,
+			expectedTierMatches: runs.filter((run) => run.expectedTier != null && run.expectedTier === run.tier).length,
+			robustnessNoOutput: runs.filter((run) => run.status === "observer_no_output").length
+		};
+		const uniqueObserverKeys = Array.from(new Set(runs.map((run) => `${run.provider}::${run.model}::${run.openaiUseResponses ? "responses" : "chat"}`)));
+		const observerSummary = opts.observerTierRouting === true ? {
+			provider: uniqueObserverKeys.length === 1 ? runs[0]?.provider ?? observer.provider : "mixed",
+			model: uniqueObserverKeys.length === 1 ? runs[0]?.model ?? observer.model : "mixed",
+			tierRouting: true,
+			openaiUseResponses: uniqueObserverKeys.length === 1 ? runs[0]?.openaiUseResponses ?? observer.openaiUseResponses : null,
+			reasoningEffort: uniqueObserverKeys.length === 1 ? runs[0]?.reasoningEffort ?? observer.reasoningEffort : "mixed",
+			reasoningSummary: uniqueObserverKeys.length === 1 ? runs[0]?.reasoningSummary ?? observer.reasoningSummary : "mixed",
+			maxOutputTokens: uniqueObserverKeys.length === 1 ? runs[0]?.maxOutputTokens ?? observer.maxOutputTokens : null,
+			temperature: uniqueObserverKeys.length === 1 ? runs[0]?.temperature ?? observer.temperature : null,
+			transcriptBudget: transcriptBudget ?? null,
+			selectedObservers: uniqueObserverKeys
+		} : {
+			provider: observer.provider,
+			model: observer.model,
+			tierRouting: false,
+			openaiUseResponses: observer.openaiUseResponses,
+			reasoningEffort: observer.reasoningEffort,
+			reasoningSummary: observer.reasoningSummary,
+			maxOutputTokens: observer.maxOutputTokens,
+			temperature: observer.temperature,
+			transcriptBudget: transcriptBudget ?? null,
+			selectedObservers: uniqueObserverKeys
+		};
+		const output = {
+			benchmark: {
+				id: benchmark.id,
+				title: benchmark.title,
+				scenarioId: benchmark.scenarioId
+			},
+			observer: observerSummary,
+			summary,
+			runs
+		};
+		if (opts.json) {
+			console.log(JSON.stringify(output, null, 2));
+			return;
+		}
+		p.intro("codemem memory extraction-benchmark");
+		p.log.info([
+			`Benchmark: ${benchmark.id} — ${benchmark.title}`,
+			`Observer: ${observerSummary.provider}/${observerSummary.model}`,
+			`Tier routing: ${opts.observerTierRouting === true ? "yes" : "no"}`,
+			`OpenAI Responses: ${observerSummary.openaiUseResponses === null ? "mixed" : observerSummary.openaiUseResponses ? "yes" : "no"}`,
+			`Reasoning effort: ${observerSummary.reasoningEffort ?? "none"}`,
+			`Reasoning summary: ${observerSummary.reasoningSummary ?? "none"}`,
+			`Max output tokens: ${observerSummary.maxOutputTokens ?? "mixed"}`,
+			`Temperature: ${observerSummary.temperature ?? "mixed"}`,
+			`Transcript budget override: ${transcriptBudget ?? "default"}`,
+			`Shape-quality passes: ${summary.shapeQualityPasses}/${summary.shapeQualityTotal}`,
+			`Shape-quality fails: ${summary.shapeQualityFails}`,
+			`Expected-tier matches: ${summary.expectedTierMatches}/${summary.expectedTierTotal}`,
+			`Observer no-output cases: ${summary.robustnessNoOutput}`
+		].join("\n"));
+		for (const run of runs) p.log.message(`  [${run.batchId}] ${run.status.padEnd(18)} ${run.complexity.padEnd(10)} tier=${run.tier.padEnd(6)} expected=${(run.expectedTier ?? "n/a").padEnd(6)} span=${String(run.analysis.eventSpan).padEnd(3)} prompts=${run.analysis.promptCount} tools=${String(run.analysis.toolCount).padEnd(2)} transcript=${run.analysis.transcriptLength} ${run.provider}/${run.model}${run.openaiUseResponses ? " [responses]" : ""} summaries=${run.summaries} observations=${run.observations} repair=${run.repairApplied ? "yes" : "no"} — ${run.label}`);
+		p.outro("done");
+	});
+	return cmd;
 }
-function createInjectMemoryCommand() {
-	return new Command("inject").configureHelp(helpStyle).description("Build raw memory context text for manual prompt injection").argument("<context>", "context string to search for").option("--db <path>", "database path").option("--db-path <path>", "database path").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--token-budget <tokens>", "token budget").option("--working-set-file <path>", "recently modified file path used as ranking hint", collectWorkingSetFile$1, []).option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").allowUnknownOption(true).allowExcessArguments(true).action(async (context, opts) => {
-		const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
-		try {
-			const limit = Number.parseInt(opts.limit ?? "10", 10) || 10;
-			const budgetRaw = opts.tokenBudget ?? opts.budget;
-			const budget = budgetRaw ? Number.parseInt(budgetRaw, 10) : void 0;
-			const filters = {};
-			if (!opts.allProjects) {
-				const project = process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), opts.project ?? null);
-				if (project) filters.project = project;
-			}
-			if ((opts.workingSetFile?.length ?? 0) > 0) filters.working_set_paths = opts.workingSetFile;
-			const pack = await store.buildMemoryPackAsync(context, limit, budget, filters);
-			console.log(pack.pack_text ?? "");
-		} finally {
-			store.close();
+function createMemoryRelinkReportCommand() {
+	const cmd = new Command("relink-report").configureHelp(helpStyle).description("Analyze dry-run raw-event session relinking and compaction opportunities").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "analyze across all projects").option("--limit <n>", "max groups to print", "25");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action((opts) => {
+		const project = opts.allProjects === true ? null : opts.project?.trim() || process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), null);
+		const limit = Number.parseInt(opts.limit ?? "25", 10) || 25;
+		const result = getRawEventRelinkReport(resolveDbOpt(opts), {
+			project,
+			allProjects: opts.allProjects === true,
+			limit
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
 		}
+		p.intro("codemem memory relink-report");
+		p.log.info([
+			`Recoverable sessions: ${result.totals.recoverable_sessions}`,
+			`Distinct stable ids: ${result.totals.distinct_stable_ids}`,
+			`Groups with multiple sessions: ${result.totals.groups_with_multiple_sessions}`,
+			`Groups with mapped session: ${result.totals.groups_with_mapped_session}`,
+			`Groups without mapped session: ${result.totals.groups_without_mapped_session}`,
+			`Active memories in groups: ${result.totals.active_memories}`,
+			`Repointable active memories: ${result.totals.repointable_active_memories}`
+		].join("\n"));
+		p.log.info("Top relink groups:");
+		for (const group of result.groups) p.log.message(`  ${group.stable_id} -> canonical ${group.canonical_session_id} | local=${group.local_sessions} mapped=${group.mapped_sessions} unmapped=${group.unmapped_sessions} active=${group.active_memories} repointable=${group.repointable_active_memories}`);
+		p.outro("done");
 	});
+	return cmd;
 }
-function createCompactMemoryCommand() {
-	return new Command("compact").configureHelp(helpStyle).description("Deferred command guidance for memory compaction").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--session-id <id>", "session ID").option("--limit <n>", "max sessions to compact", "10").allowUnknownOption(true).allowExcessArguments(true).action(() => {
-		p.log.warn("`codemem memory compact` is not implemented in the TypeScript CLI yet.");
-		p.log.info("Current workaround: rely on automatic ingestion; for manual context use `codemem memory inject <context>`.");
-		process.exitCode = 2;
+function createMemoryRelinkPlanCommand() {
+	const cmd = new Command("relink-plan").configureHelp(helpStyle).description("Emit dry-run raw-event relink remediation actions").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "analyze across all projects").option("--limit <n>", "max groups to include", "25");
+	addDbOption(cmd);
+	addJsonOption(cmd);
+	cmd.action((opts) => {
+		const project = opts.allProjects === true ? null : opts.project?.trim() || process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), null);
+		const limit = Number.parseInt(opts.limit ?? "25", 10) || 25;
+		const result = getRawEventRelinkPlan(resolveDbOpt(opts), {
+			project,
+			allProjects: opts.allProjects === true,
+			limit
+		});
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		p.intro("codemem memory relink-plan");
+		p.log.info([
+			`Groups: ${result.totals.groups}`,
+			`Eligible groups: ${result.totals.eligible_groups}`,
+			`Skipped groups: ${result.totals.skipped_groups}`,
+			`Actions: ${result.totals.actions}`,
+			`Bridge creations: ${result.totals.bridge_creations}`,
+			`Memory repoints: ${result.totals.memory_repoints}`,
+			`Session compactions: ${result.totals.session_compactions}`
+		].join("\n"));
+		p.log.info("Planned actions:");
+		for (const action of result.actions.slice(0, 15)) p.log.message(`  ${action.action} ${action.stable_id} -> canonical ${action.canonical_session_id} | sessions=${action.session_ids.join(",") || "-"} memories=${action.memory_count} reason=${action.reason}`);
+		if (result.skipped_groups.length > 0) {
+			p.log.info("Skipped groups:");
+			for (const group of result.skipped_groups.slice(0, 10)) p.log.message(`  ${group.stable_id} | blockers=${group.blockers.join(",")}`);
+		}
+		p.outro("done");
 	});
+	return cmd;
 }
 var showMemoryCommand = createShowMemoryCommand();
 var forgetMemoryCommand = createForgetMemoryCommand();
@@ -797,24 +2226,22 @@ memoryCommand.addCommand(createShowMemoryCommand());
 memoryCommand.addCommand(createForgetMemoryCommand());
 memoryCommand.addCommand(createRememberMemoryCommand());
 memoryCommand.addCommand(createInjectMemoryCommand());
-memoryCommand.addCommand(createCompactMemoryCommand());
+memoryCommand.addCommand(createMemoryRoleReportCommand());
+memoryCommand.addCommand(createMemoryRoleCompareCommand());
+memoryCommand.addCommand(createMemoryExtractionReportCommand());
+memoryCommand.addCommand(createMemoryExtractionReplayCommand());
+memoryCommand.addCommand(createMemoryExtractionBenchmarkCommand());
+memoryCommand.addCommand(createMemoryRelinkReportCommand());
+memoryCommand.addCommand(createMemoryRelinkPlanCommand());
 //#endregion
 //#region src/commands/pack.ts
-function collectWorkingSetFile(value, previous) {
-	return [...previous, value];
-}
-var packCommand = new Command("pack").configureHelp(helpStyle).description("Build a context-aware memory pack").argument("<context>", "context string to search for").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--token-budget <tokens>", "token budget").option("--working-set-file <path>", "recently modified file path used as ranking hint", collectWorkingSetFile, []).option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--json", "output as JSON").action(async (context, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var packCmd = new Command("pack").configureHelp(helpStyle).description("Build a context-aware memory pack").argument("<context>", "context string to search for").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--token-budget <tokens>", "token budget").option("--working-set-file <path>", "recently modified file path used as ranking hint", collectWorkingSetFile, []).option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects");
+addDbOption(packCmd);
+addJsonOption(packCmd);
+var packCommand = packCmd.action(async (context, opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
-		const limit = Number.parseInt(opts.limit, 10) || 10;
-		const budgetRaw = opts.tokenBudget ?? opts.budget;
-		const budget = budgetRaw ? Number.parseInt(budgetRaw, 10) : void 0;
-		const filters = {};
-		if (!opts.allProjects) {
-			const project = process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), opts.project ?? null);
-			if (project) filters.project = project;
-		}
-		if ((opts.workingSetFile?.length ?? 0) > 0) filters.working_set_paths = opts.workingSetFile;
+		const { limit, budget, filters } = buildPackRequestOptions(opts, { envProject: process.env.CODEMEM_PROJECT });
 		const result = await store.buildMemoryPackAsync(context, limit, budget, filters);
 		if (opts.json) {
 			console.log(JSON.stringify(result, null, 2));
@@ -837,8 +2264,11 @@ var packCommand = new Command("pack").configureHelp(helpStyle).description("Buil
 });
 //#endregion
 //#region src/commands/recent.ts
-var recentCommand = new Command("recent").configureHelp(helpStyle).description("Show recent memories").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var cmd = new Command("recent").configureHelp(helpStyle).description("Show recent memories").option("--limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind");
+addDbOption(cmd);
+addJsonOption(cmd);
+cmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 5);
 		const filters = {};
@@ -848,15 +2278,20 @@ var recentCommand = new Command("recent").configureHelp(helpStyle).description("
 			if (project) filters.project = project;
 		}
 		const items = store.recent(limit, filters);
-		for (const item of items) console.log(`#${item.id} [${item.kind}] ${item.title}`);
+		if (opts.json) console.log(JSON.stringify(items));
+		else for (const item of items) console.log(`#${item.id} [${item.kind}] ${item.title}`);
 	} finally {
 		store.close();
 	}
 });
+var recentCommand = cmd;
 //#endregion
 //#region src/commands/search.ts
-var searchCommand = new Command("search").configureHelp(helpStyle).description("Search memories by query").argument("<query>", "search query").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind").option("--json", "output as JSON").action((query, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var searchCmd = new Command("search").configureHelp(helpStyle).description("Search memories by query").argument("<query>", "search query").option("-n, --limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind");
+addDbOption(searchCmd);
+addJsonOption(searchCmd);
+var searchCommand = searchCmd.action((query, opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 5);
 		const filters = {};
@@ -900,6 +2335,10 @@ function timeSince(isoDate) {
 }
 //#endregion
 //#region src/commands/serve-invocation.ts
+/**
+* Parse and validate a port string. Throws a user-friendly message (no stack trace)
+* that callers in serve.ts catch at the action boundary.
+*/
 function parsePort(rawPort) {
 	const port = Number.parseInt(rawPort, 10);
 	if (!Number.isFinite(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${rawPort}`);
@@ -908,10 +2347,11 @@ function parsePort(rawPort) {
 function resolveLegacyServeInvocation(opts) {
 	if (opts.stop && opts.restart) throw new Error("Use only one of --stop or --restart");
 	if (opts.foreground && opts.background) throw new Error("Use only one of --background or --foreground");
-	const dbPath = opts.db ?? opts.dbPath ?? null;
+	const dbPath = resolveDbOpt(opts) ?? null;
 	return {
 		mode: opts.stop ? "stop" : opts.restart ? "restart" : "start",
 		dbPath,
+		configPath: opts.config ?? null,
 		host: opts.host,
 		port: parsePort(opts.port),
 		background: opts.restart ? true : opts.background ? true : false
@@ -926,7 +2366,8 @@ function resolveServeInvocation(action, opts) {
 function resolveStartServeInvocation(opts) {
 	return {
 		mode: "start",
-		dbPath: opts.db ?? opts.dbPath ?? null,
+		dbPath: resolveDbOpt(opts) ?? null,
+		configPath: opts.config ?? null,
 		host: opts.host,
 		port: parsePort(opts.port),
 		background: !opts.foreground
@@ -935,7 +2376,8 @@ function resolveStartServeInvocation(opts) {
 function resolveStopRestartInvocation(mode, opts) {
 	return {
 		mode,
-		dbPath: opts.db ?? opts.dbPath ?? null,
+		dbPath: resolveDbOpt(opts) ?? null,
+		configPath: opts.config ?? null,
 		host: opts.host,
 		port: parsePort(opts.port),
 		background: mode === "restart"
@@ -1182,14 +2624,19 @@ async function startBackgroundViewer(invocation) {
 		return;
 	}
 	const scriptPath = process.argv[1];
-	if (!scriptPath) throw new Error("Unable to resolve CLI entrypoint for background launch");
+	if (!scriptPath) {
+		p.log.error("Unable to resolve CLI entrypoint for background launch");
+		process.exitCode = 1;
+		return;
+	}
 	const child = spawn(process.execPath, buildForegroundRunnerArgs(scriptPath, invocation), {
 		cwd: process.cwd(),
 		detached: true,
 		stdio: "ignore",
 		env: {
 			...process.env,
-			...invocation.dbPath ? { CODEMEM_DB: invocation.dbPath } : {}
+			...invocation.dbPath ? { CODEMEM_DB: invocation.dbPath } : {},
+			...invocation.configPath ? { CODEMEM_CONFIG: invocation.configPath } : {}
 		}
 	});
 	child.unref();
@@ -1205,6 +2652,7 @@ async function startForegroundViewer(invocation) {
 	const { createApp, createSyncApp, closeStore, getStore } = await import("@codemem/server");
 	const { serve } = await import("@hono/node-server");
 	if (invocation.dbPath) process.env.CODEMEM_DB = invocation.dbPath;
+	if (invocation.configPath) process.env.CODEMEM_CONFIG = invocation.configPath;
 	warnIfViewerExposed(invocation.host, invocation.port);
 	if (await isPortOpen(invocation.host, invocation.port)) {
 		p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
@@ -1229,7 +2677,7 @@ async function startForegroundViewer(invocation) {
 	sweeper.start();
 	const syncAbort = new AbortController();
 	const retentionAbort = new AbortController();
-	const syncConfig = readCoordinatorSyncConfig(readCodememConfigFile());
+	const syncConfig = readCoordinatorSyncConfig(invocation.configPath ? readCodememConfigFileAtPath(invocation.configPath) : readCodememConfigFile());
 	const syncEnabled = syncConfig.syncEnabled;
 	const retentionRunner = new SyncRetentionRunner({
 		dbPath: resolveDbPath(invocation.dbPath ?? void 0),
@@ -1408,17 +2856,31 @@ async function runServeInvocation(invocation) {
 		});
 	}
 }
-function addSharedServeOptions(command) {
-	return command.option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "bind host", "127.0.0.1").option("--port <port>", "bind port", "38888");
-}
-var serveCommand = addSharedServeOptions(new Command("serve").configureHelp(helpStyle).description("Run or manage the viewer").argument("[action]", "lifecycle action (start|stop|restart)")).option("--background", "run viewer in background").option("--foreground", "run viewer in foreground").option("--stop", "stop background viewer").option("--restart", "restart background viewer").action(async (action, opts) => {
-	const normalizedAction = action === void 0 ? void 0 : action === "start" || action === "stop" || action === "restart" ? action : null;
-	if (normalizedAction === null) {
-		p.log.error(`Unknown serve action: ${action}`);
+var serveCmd = new Command("serve").configureHelp(helpStyle).description("Run or manage the viewer").argument("[action]", "lifecycle action (start|stop|restart)");
+addDbOption(serveCmd);
+addConfigOption(serveCmd);
+addViewerHostOptions(serveCmd);
+serveCmd.addOption(new Option("--background", "run viewer in background").hideHelp());
+serveCmd.addOption(new Option("--foreground", "run viewer in foreground").hideHelp());
+serveCmd.addOption(new Option("--stop", "stop background viewer").hideHelp());
+serveCmd.addOption(new Option("--restart", "restart background viewer").hideHelp());
+var serveCommand = serveCmd.action(async (action, opts) => {
+	try {
+		if (opts.stop) emitDeprecationWarning("--stop", "codemem serve stop");
+		if (opts.restart) emitDeprecationWarning("--restart", "codemem serve restart");
+		if (opts.background) emitDeprecationWarning("--background", "codemem serve start");
+		if (opts.foreground) emitDeprecationWarning("--foreground", "codemem serve start --foreground");
+		const normalizedAction = action === void 0 ? void 0 : action === "start" || action === "stop" || action === "restart" ? action : null;
+		if (normalizedAction === null) {
+			p.log.error(`Unknown serve action: ${action}`);
+			process.exitCode = 1;
+			return;
+		}
+		await runServeInvocation(resolveServeInvocation(normalizedAction, opts));
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
 		process.exitCode = 1;
-		return;
 	}
-	await runServeInvocation(resolveServeInvocation(normalizedAction, opts));
 });
 //#endregion
 //#region src/commands/setup-config.ts
@@ -1673,8 +3135,11 @@ function fmtTokens(n) {
 	if (n >= 1e3) return `~${(n / 1e3).toFixed(0)}K`;
 	return `${n}`;
 }
-var statsCommand = new Command("stats").configureHelp(helpStyle).description("Show database statistics").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var statsCmd = new Command("stats").configureHelp(helpStyle).description("Show database statistics");
+addDbOption(statsCmd);
+addJsonOption(statsCmd);
+var statsCommand = statsCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const result = store.stats();
 		if (opts.json) {
@@ -1728,7 +3193,9 @@ function buildServeLifecycleArgs(action, opts, scriptPath, execArgv = []) {
 	if (action === "start") args.push("--restart");
 	else if (action === "stop") args.push("--stop");
 	else args.push("--restart");
-	if (opts.db ?? opts.dbPath) args.push("--db-path", opts.db ?? opts.dbPath ?? "");
+	const dbResolved = resolveDbOpt(opts);
+	if (dbResolved) args.push("--db-path", dbResolved);
+	if (opts.config) args.push("--config", opts.config);
 	if (opts.host) args.push("--host", opts.host);
 	if (opts.port) args.push("--port", opts.port);
 	return args;
@@ -1752,10 +3219,22 @@ function collectAdvertiseAddresses(explicitAddress, configuredHost, port, interf
 /**
 * Sync CLI commands — enable/disable/status/peers/connect.
 */
+function readCliConfig(configPath) {
+	return configPath ? readCodememConfigFileAtPath(configPath) : readCodememConfigFile();
+}
+function writeCliConfig(config, configPath) {
+	return writeCodememConfigFile(config, configPath || void 0);
+}
 function parseAttemptsLimit(value) {
 	if (!/^\d+$/.test(value.trim())) throw new Error(`Invalid --limit: ${value}`);
 	return Number.parseInt(value, 10);
 }
+function parsePositiveIntegerOption(value, flagName) {
+	if (value == null) return void 0;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) throw new Error(`Invalid ${flagName}: ${value}`);
+	return Number.parseInt(trimmed, 10);
+}
 function resolvePeerMatch(db, peerRef) {
 	const trimmed = peerRef.trim();
 	if (!trimmed) return null;
@@ -1771,18 +3250,6 @@ function resolvePeerMatch(db, peerRef) {
 	if (byName.length > 1) return "ambiguous";
 	return byName[0] ?? null;
 }
-function readCoordinatorPublicKey(opts) {
-	const inline = String(opts.publicKey ?? "").trim();
-	const filePath = String(opts.publicKeyFile ?? "").trim();
-	if (inline && filePath) throw new Error("Use only one of --public-key or --public-key-file");
-	if (filePath) {
-		const text = readFileSync(filePath, "utf8").trim();
-		if (!text) throw new Error(`Public key file is empty: ${filePath}`);
-		return text;
-	}
-	if (!inline) throw new Error("Public key required via --public-key or --public-key-file");
-	return inline;
-}
 async function portOpen(host, port) {
 	return new Promise((resolve) => {
 		const socket = net.createConnection({
@@ -1828,12 +3295,13 @@ function parseStoredAddressEndpoint(value) {
 async function runServeLifecycle(action, opts) {
 	if (opts.user === false || opts.system === true) p.log.warn("TS sync lifecycle currently manages the local viewer process, not separate user/system services.");
 	if (action === "start") {
-		if (readCodememConfigFile().sync_enabled !== true) {
+		if (readCoordinatorSyncConfig(readCliConfig(opts.config)).syncEnabled !== true) {
 			p.log.error("Sync is disabled. Run `codemem sync enable` first.");
 			process.exitCode = 1;
 			return;
 		}
 	}
+	const dbResolved = resolveDbOpt(opts);
 	const args = buildServeLifecycleArgs(action, opts, process.argv[1] ?? "", process.execArgv);
 	await new Promise((resolve, reject) => {
 		const child = spawn(process.execPath, args, {
@@ -1841,7 +3309,8 @@ async function runServeLifecycle(action, opts) {
 			stdio: "inherit",
 			env: {
 				...process.env,
-				...opts.db ?? opts.dbPath ? { CODEMEM_DB: opts.db ?? opts.dbPath } : {}
+				...dbResolved ? { CODEMEM_DB: dbResolved } : {},
+				...opts.config ? { CODEMEM_CONFIG: opts.config } : {}
 			}
 		});
 		child.once("error", reject);
@@ -1852,8 +3321,11 @@ async function runServeLifecycle(action, opts) {
 	});
 }
 var syncCommand = new Command("sync").configureHelp(helpStyle).description("Sync configuration and peer management");
-syncCommand.addCommand(new Command("attempts").configureHelp(helpStyle).description("Show recent sync attempts").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--limit <n>", "max attempts", "10").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var attemptsCmd = new Command("attempts").configureHelp(helpStyle).description("Show recent sync attempts").option("--limit <n>", "max attempts", "10");
+addDbOption(attemptsCmd);
+addJsonOption(attemptsCmd);
+attemptsCmd.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const d = drizzle(store.db, { schema });
 		const limit = parseAttemptsLimit(opts.limit);
@@ -1873,19 +3345,30 @@ syncCommand.addCommand(new Command("attempts").configureHelp(helpStyle).descript
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("start").configureHelp(helpStyle).description("Start sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
-	await runServeLifecycle("start", opts);
-}));
-syncCommand.addCommand(new Command("stop").configureHelp(helpStyle).description("Stop sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
-	await runServeLifecycle("stop", opts);
-}));
-syncCommand.addCommand(new Command("restart").configureHelp(helpStyle).description("Restart sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
-	await runServeLifecycle("restart", opts);
-}));
-syncCommand.addCommand(new Command("once").configureHelp(helpStyle).description("Run a single sync pass").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--peer <peer>", "peer device id or name").action(async (opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+syncCommand.addCommand(attemptsCmd);
+function addDeprecatedLifecycleCommand(action) {
+	const cmd = new Command(action).configureHelp(helpStyle).description(`[deprecated] ${action} sync daemon — use 'codemem serve ${action}'`);
+	addDbOption(cmd);
+	addConfigOption(cmd);
+	addViewerHostOptions(cmd);
+	addLegacyServiceFlags(cmd);
+	cmd.action(async (opts) => {
+		emitDeprecationWarning(`codemem sync ${action}`, `codemem serve ${action}`);
+		await runServeLifecycle(action, opts);
+	});
+	syncCommand.addCommand(cmd, { hidden: true });
+}
+addDeprecatedLifecycleCommand("start");
+addDeprecatedLifecycleCommand("stop");
+addDeprecatedLifecycleCommand("restart");
+var onceCmd = new Command("once").configureHelp(helpStyle).description("Run a single sync pass").option("--peer <peer>", "peer device id or name");
+addDbOption(onceCmd);
+addJsonOption(onceCmd);
+onceCmd.action(async (opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
+		const keysDir = process.env.CODEMEM_KEYS_DIR?.trim() || void 0;
 		syncPassPreflight(store.db);
 		const d = drizzle(store.db, { schema });
 		const rows = opts.peer ? (() => {
@@ -1893,6 +3376,10 @@ syncCommand.addCommand(new Command("once").configureHelp(helpStyle).description(
 			if (deviceMatches.length > 0) return deviceMatches;
 			const nameMatches = d.select({ peer_device_id: schema.syncPeers.peer_device_id }).from(schema.syncPeers).where(eq(schema.syncPeers.name, opts.peer)).all();
 			if (nameMatches.length > 1) {
+				if (opts.json) {
+					emitJsonError("ambiguous_peer", `Peer name is ambiguous: ${opts.peer}`);
+					return [];
+				}
 				p.log.error(`Peer name is ambiguous: ${opts.peer}`);
 				process.exitCode = 1;
 				return [];
@@ -1900,31 +3387,59 @@ syncCommand.addCommand(new Command("once").configureHelp(helpStyle).description(
 			return nameMatches;
 		})() : d.select({ peer_device_id: schema.syncPeers.peer_device_id }).from(schema.syncPeers).all();
 		if (rows.length === 0) {
+			if (process.exitCode) return;
+			if (opts.json) {
+				emitJsonError("no_peers", "No peers available for sync");
+				return;
+			}
 			p.log.warn("No peers available for sync");
 			process.exitCode = 1;
 			return;
 		}
 		let hadFailure = false;
+		const results = [];
 		for (const row of rows) {
-			const result = await runSyncPass(store.db, row.peer_device_id);
+			const result = await runSyncPass(store.db, row.peer_device_id, { keysDir });
 			if (!result.ok) hadFailure = true;
-			console.log(formatSyncOnceResult(row.peer_device_id, result));
+			results.push({
+				peer_device_id: row.peer_device_id,
+				ok: result.ok,
+				...result.error ? { error: result.error } : {}
+			});
+			if (!opts.json) console.log(formatSyncOnceResult(row.peer_device_id, result));
 		}
+		if (opts.json) console.log(JSON.stringify({
+			ok: !hadFailure,
+			results
+		}, null, 2));
 		if (hadFailure) process.exitCode = 1;
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description("Print pairing payload or accept a peer payload").option("--accept <json>", "accept pairing payload JSON from another device").option("--accept-file <path>", "accept pairing payload from file path, or '-' for stdin").option("--payload-only", "when generating pairing payload, print JSON only").option("--name <name>", "label for the peer").option("--address <host:port>", "override peer address (host:port)").option("--include <projects>", "outbound-only allowlist for accepted peer").option("--exclude <projects>", "outbound-only blocklist for accepted peer").option("--all", "with --accept, push all projects to that peer").option("--default", "with --accept, use default/global push filters").option("--db-path <path>", "database path").action(async (opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.dbPath));
+});
+syncCommand.addCommand(onceCmd);
+var pairCmd = new Command("pair").configureHelp(helpStyle).description("Print pairing payload or accept a peer payload").option("--accept <json>", "accept pairing payload JSON from another device").option("--accept-file <path>", "accept pairing payload from file path, or '-' for stdin").option("--payload-only", "when generating pairing payload, print JSON only").option("--name <name>", "label for the peer").option("--address <host:port>", "override peer address (host:port)").option("--include <projects>", "outbound-only allowlist for accepted peer").option("--exclude <projects>", "outbound-only blocklist for accepted peer").option("--all", "with --accept, push all projects to that peer").option("--default", "with --accept, use default/global push filters");
+addDbOption(pairCmd);
+addConfigOption(pairCmd);
+addJsonOption(pairCmd);
+pairCmd.action(async (opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const acceptModeRequested = opts.accept != null || opts.acceptFile != null;
 		if (opts.payloadOnly && acceptModeRequested) {
+			if (opts.json) {
+				emitJsonError("usage_error", "--payload-only cannot be combined with --accept or --accept-file", 2);
+				return;
+			}
 			p.log.error("--payload-only cannot be combined with --accept or --accept-file");
 			process.exitCode = 1;
 			return;
 		}
 		if (opts.accept && opts.acceptFile) {
+			if (opts.json) {
+				emitJsonError("usage_error", "Use only one of --accept or --accept-file", 2);
+				return;
+			}
 			p.log.error("Use only one of --accept or --accept-file");
 			process.exitCode = 1;
 			return;
@@ -1941,27 +3456,48 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 				process.stdin.on("error", reject);
 			}) : readFileSync(opts.acceptFile, "utf8");
 		} catch (error) {
-			p.log.error(error instanceof Error ? `Failed to read pairing payload from ${opts.acceptFile}: ${error.message}` : `Failed to read pairing payload from ${opts.acceptFile}`);
+			const msg = error instanceof Error ? `Failed to read pairing payload from ${opts.acceptFile}: ${error.message}` : `Failed to read pairing payload from ${opts.acceptFile}`;
+			if (opts.json) {
+				emitJsonError("read_error", msg);
+				return;
+			}
+			p.log.error(msg);
 			process.exitCode = 1;
 			return;
 		}
 		if (acceptModeRequested && !(acceptText ?? "").trim()) {
+			if (opts.json) {
+				emitJsonError("usage_error", "Empty pairing payload; provide JSON via --accept or --accept-file", 2);
+				return;
+			}
 			p.log.error("Empty pairing payload; provide JSON via --accept or --accept-file");
 			process.exitCode = 1;
 			return;
 		}
 		if (!acceptText && (opts.include || opts.exclude || opts.all || opts.default)) {
+			if (opts.json) {
+				emitJsonError("usage_error", "Project filters are outbound-only and must be set on the device running --accept", 2);
+				return;
+			}
 			p.log.error("Project filters are outbound-only and must be set on the device running --accept");
 			process.exitCode = 1;
 			return;
 		}
 		if (acceptText?.trim()) {
 			if (opts.all && opts.default) {
+				if (opts.json) {
+					emitJsonError("usage_error", "Use only one of --all or --default", 2);
+					return;
+				}
 				p.log.error("Use only one of --all or --default");
 				process.exitCode = 1;
 				return;
 			}
 			if ((opts.all || opts.default) && (opts.include || opts.exclude)) {
+				if (opts.json) {
+					emitJsonError("usage_error", "--include/--exclude cannot be combined with --all/--default", 2);
+					return;
+				}
 				p.log.error("--include/--exclude cannot be combined with --all/--default");
 				process.exitCode = 1;
 				return;
@@ -1970,7 +3506,12 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 			try {
 				payload = JSON.parse(acceptText);
 			} catch (error) {
-				p.log.error(error instanceof Error ? `Invalid pairing payload: ${error.message}` : "Invalid pairing payload");
+				const msg = error instanceof Error ? `Invalid pairing payload: ${error.message}` : "Invalid pairing payload";
+				if (opts.json) {
+					emitJsonError("invalid_payload", msg);
+					return;
+				}
+				p.log.error(msg);
 				process.exitCode = 1;
 				return;
 			}
@@ -1979,11 +3520,20 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 			const publicKey = String(payload.public_key || "").trim();
 			const resolvedAddresses = opts.address?.trim() ? [opts.address.trim()] : Array.isArray(payload.addresses) ? payload.addresses.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim()) : [];
 			if (!deviceId || !fingerprint || !publicKey || resolvedAddresses.length === 0) {
-				p.log.error("Pairing payload missing device_id, fingerprint, public_key, or addresses");
+				const msg = "Pairing payload missing device_id, fingerprint, public_key, or addresses";
+				if (opts.json) {
+					emitJsonError("invalid_payload", msg);
+					return;
+				}
+				p.log.error(msg);
 				process.exitCode = 1;
 				return;
 			}
 			if (fingerprintPublicKey(publicKey) !== fingerprint) {
+				if (opts.json) {
+					emitJsonError("fingerprint_mismatch", "Pairing payload fingerprint mismatch");
+					return;
+				}
 				p.log.error("Pairing payload fingerprint mismatch");
 				process.exitCode = 1;
 				return;
@@ -2001,6 +3551,13 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 				include: opts.all ? [] : parseProjectList(opts.include),
 				exclude: opts.all ? [] : parseProjectList(opts.exclude)
 			});
+			if (opts.json) {
+				console.log(JSON.stringify({
+					ok: true,
+					peer_device_id: deviceId
+				}));
+				return;
+			}
 			p.log.success(`Paired with ${deviceId}`);
 			return;
 		}
@@ -2008,24 +3565,28 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 		const [deviceId, fingerprint] = ensureDeviceIdentity(store.db, { keysDir });
 		const publicKey = loadPublicKey(keysDir);
 		if (!publicKey) {
+			if (opts.json) {
+				emitJsonError("missing_key", "Public key missing");
+				return;
+			}
 			p.log.error("Public key missing");
 			process.exitCode = 1;
 			return;
 		}
-		const config = readCodememConfigFile();
+		const config = readCliConfig(opts.config);
 		const explicitAddress = opts.address?.trim();
 		const configuredHost = typeof config.sync_host === "string" ? config.sync_host : null;
 		const configuredPort = typeof config.sync_port === "number" ? config.sync_port : 7337;
 		const addresses = collectAdvertiseAddresses(explicitAddress ?? null, configuredHost, configuredPort, networkInterfaces());
-		const payload = {
+		const payloadObj = {
 			device_id: deviceId,
 			fingerprint,
 			public_key: publicKey,
 			address: addresses[0] ?? "",
 			addresses
 		};
-		const payloadText = JSON.stringify(payload);
-		if (opts.payloadOnly) {
+		const payloadText = JSON.stringify(payloadObj);
+		if (opts.payloadOnly || opts.json) {
 			process.stdout.write(`${payloadText}\n`);
 			return;
 		}
@@ -2042,10 +3603,15 @@ syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description(
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("doctor").configureHelp(helpStyle).description("Diagnose common sync setup and connectivity issues").option("--db <path>", "database path").option("--db-path <path>", "database path").action(async (opts) => {
-	const config = readCodememConfigFile();
-	const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
+});
+syncCommand.addCommand(pairCmd);
+var doctorCmd = new Command("doctor").configureHelp(helpStyle).description("Diagnose common sync setup and connectivity issues");
+addDbOption(doctorCmd);
+addConfigOption(doctorCmd);
+addJsonOption(doctorCmd);
+doctorCmd.action(async (opts) => {
+	const config = readCliConfig(opts.config);
+	const dbPath = resolveDbPath(resolveDbOpt(opts));
 	const store = new MemoryStore(dbPath);
 	try {
 		const d = drizzle(store.db, { schema });
@@ -2061,47 +3627,70 @@ syncCommand.addCommand(new Command("doctor").configureHelp(helpStyle).descriptio
 		const syncHost = typeof config.sync_host === "string" ? config.sync_host : "0.0.0.0";
 		const syncPort = typeof config.sync_port === "number" ? config.sync_port : 7337;
 		const viewerBinding = readViewerBinding(dbPath);
+		const reachable = viewerBinding ? await portOpen(viewerBinding.host, viewerBinding.port) : false;
+		if (!reachable) issues.push("daemon not running");
+		if (!device) issues.push("identity missing");
+		if (daemonState?.last_error && (!daemonState.last_ok_at || daemonState.last_ok_at < (daemonState.last_error_at ?? ""))) issues.push("daemon error");
+		if (peers.length === 0) issues.push("no peers");
+		if (!config.sync_enabled) issues.push("sync is disabled");
+		const peerDetails = [];
+		for (const peer of peers) {
+			const addresses = peer.addresses_json ? JSON.parse(peer.addresses_json) : [];
+			const endpoint = parseStoredAddressEndpoint(addresses[0] ?? "");
+			const reach = endpoint ? await portOpen(endpoint.host, endpoint.port) ? "ok" : "unreachable" : "unknown";
+			const pinned = Boolean(peer.pinned_fingerprint);
+			const hasKey = Boolean(peer.public_key);
+			peerDetails.push({
+				peer_device_id: peer.peer_device_id,
+				addresses: addresses.length,
+				reachable: reach,
+				pinned,
+				has_public_key: hasKey
+			});
+			if (reach !== "ok") issues.push(`peer ${peer.peer_device_id} unreachable`);
+			if (!pinned || !hasKey) issues.push(`peer ${peer.peer_device_id} not pinned`);
+		}
+		if (opts.json) {
+			console.log(JSON.stringify({
+				enabled: config.sync_enabled === true,
+				listen: `${syncHost}:${syncPort}`,
+				mdns: process.env.CODEMEM_SYNC_MDNS ? "env-configured" : "default/off",
+				daemon: reachable ? "running" : "not running",
+				identity: device?.device_id ?? null,
+				daemon_error: daemonState?.last_error ?? null,
+				peers: peerDetails,
+				issues: [...new Set(issues)],
+				ok: issues.length === 0
+			}));
+			return;
+		}
 		console.log("Sync doctor");
 		console.log(`- Enabled: ${config.sync_enabled === true}`);
 		console.log(`- Listen: ${syncHost}:${syncPort}`);
 		console.log(`- mDNS: ${process.env.CODEMEM_SYNC_MDNS ? "env-configured" : "default/off"}`);
-		const reachable = viewerBinding ? await portOpen(viewerBinding.host, viewerBinding.port) : false;
 		console.log(`- Daemon: ${reachable ? "running" : "not running"}`);
-		if (!reachable) issues.push("daemon not running");
-		if (!device) {
-			console.log("- Identity: missing (run `codemem sync enable`)");
-			issues.push("identity missing");
-		} else console.log(`- Identity: ${device.device_id}`);
-		if (daemonState?.last_error && (!daemonState.last_ok_at || daemonState.last_ok_at < (daemonState.last_error_at ?? ""))) {
-			console.log(`- Daemon error: ${daemonState.last_error} (at ${daemonState.last_error_at ?? "unknown"})`);
-			issues.push("daemon error");
-		}
-		if (peers.length === 0) {
-			console.log("- Peers: none (pair a device first)");
-			issues.push("no peers");
-		} else {
+		if (!device) console.log("- Identity: missing (run `codemem sync enable`)");
+		else console.log(`- Identity: ${device.device_id}`);
+		if (daemonState?.last_error && (!daemonState.last_ok_at || daemonState.last_ok_at < (daemonState.last_error_at ?? ""))) console.log(`- Daemon error: ${daemonState.last_error} (at ${daemonState.last_error_at ?? "unknown"})`);
+		if (peers.length === 0) console.log("- Peers: none (pair a device first)");
+		else {
 			console.log(`- Peers: ${peers.length}`);
-			for (const peer of peers) {
-				const addresses = peer.addresses_json ? JSON.parse(peer.addresses_json) : [];
-				const endpoint = parseStoredAddressEndpoint(addresses[0] ?? "");
-				const reach = endpoint ? await portOpen(endpoint.host, endpoint.port) ? "ok" : "unreachable" : "unknown";
-				const pinned = Boolean(peer.pinned_fingerprint);
-				const hasKey = Boolean(peer.public_key);
-				console.log(`  - ${peer.peer_device_id}: addresses=${addresses.length} reach=${reach} pinned=${pinned} public_key=${hasKey}`);
-				if (reach !== "ok") issues.push(`peer ${peer.peer_device_id} unreachable`);
-				if (!pinned || !hasKey) issues.push(`peer ${peer.peer_device_id} not pinned`);
-			}
+			for (const detail of peerDetails) console.log(`  - ${detail.peer_device_id}: addresses=${detail.addresses} reach=${detail.reachable} pinned=${detail.pinned} public_key=${detail.has_public_key}`);
 		}
-		if (!config.sync_enabled) issues.push("sync is disabled");
 		if (issues.length > 0) console.log(`WARN: ${[...new Set(issues)].slice(0, 3).join(", ")}`);
 		else console.log("OK: sync looks healthy");
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("status").configureHelp(helpStyle).description("Show sync configuration and peer summary").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--json", "output as JSON").action((opts) => {
-	const config = readCodememConfigFile();
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+syncCommand.addCommand(doctorCmd);
+var statusCmd = new Command("status").configureHelp(helpStyle).description("Show sync configuration and peer summary");
+addDbOption(statusCmd);
+addConfigOption(statusCmd);
+addJsonOption(statusCmd);
+statusCmd.action((opts) => {
+	const config = readCliConfig(opts.config);
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const d = drizzle(store.db, { schema });
 		const deviceRow = d.select({
@@ -2151,17 +3740,41 @@ syncCommand.addCommand(new Command("status").configureHelp(helpStyle).descriptio
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("enable").configureHelp(helpStyle).description("Enable sync and initialize device identity").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "sync listen host").option("--port <port>", "sync listen port").option("--interval <seconds>", "sync interval in seconds").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+syncCommand.addCommand(statusCmd);
+var enableCmd = new Command("enable").configureHelp(helpStyle).description("Enable sync and initialize device identity").option("--sync-host <host>", "sync listen host").option("--sync-port <port>", "sync listen port").option("--interval <seconds>", "sync interval in seconds");
+addDbOption(enableCmd);
+addConfigOption(enableCmd);
+addJsonOption(enableCmd);
+enableCmd.addOption(new Option("--host <host>", "sync listen host").hideHelp());
+enableCmd.addOption(new Option("--port <port>", "sync listen port").hideHelp());
+enableCmd.action((opts) => {
+	if (opts.host && !opts.syncHost) emitDeprecationWarning("--host on sync enable", "--sync-host");
+	if (opts.port && !opts.syncPort) emitDeprecationWarning("--port on sync enable", "--sync-port");
+	const effectiveHost = opts.syncHost ?? opts.host;
+	const effectivePort = opts.syncPort ?? opts.port;
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const [deviceId, fingerprint] = ensureDeviceIdentity(store.db);
-		const config = readCodememConfigFile();
+		const config = readCliConfig(opts.config);
 		config.sync_enabled = true;
-		if (opts.host) config.sync_host = opts.host;
-		if (opts.port) config.sync_port = Number.parseInt(opts.port, 10);
-		if (opts.interval) config.sync_interval_s = Number.parseInt(opts.interval, 10);
-		writeCodememConfigFile(config);
+		if (effectiveHost) config.sync_host = effectiveHost;
+		const syncPort = parsePositiveIntegerOption(effectivePort, "--sync-port");
+		const syncInterval = parsePositiveIntegerOption(opts.interval, "--interval");
+		if (syncPort != null) config.sync_port = syncPort;
+		if (syncInterval != null) config.sync_interval_s = syncInterval;
+		writeCliConfig(config, opts.config);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: true,
+				device_id: deviceId,
+				fingerprint,
+				host: config.sync_host ?? "0.0.0.0",
+				port: config.sync_port ?? 7337,
+				interval_s: config.sync_interval_s ?? 120
+			}));
+			return;
+		}
 		p.intro("codemem sync enable");
 		p.log.success([
 			`Device ID:   ${deviceId}`,
@@ -2174,16 +3787,23 @@ syncCommand.addCommand(new Command("enable").configureHelp(helpStyle).descriptio
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("disable").configureHelp(helpStyle).description("Disable sync without deleting keys or peers").action(() => {
-	const config = readCodememConfigFile();
+});
+syncCommand.addCommand(enableCmd);
+var disableCmd = new Command("disable").configureHelp(helpStyle).description("Disable sync without deleting keys or peers");
+addConfigOption(disableCmd);
+disableCmd.action((opts) => {
+	const config = readCliConfig(opts.config);
 	config.sync_enabled = false;
-	writeCodememConfigFile(config);
+	writeCliConfig(config, opts.config);
 	p.intro("codemem sync disable");
 	p.outro("Sync disabled — restart `codemem serve` to take effect");
-}));
-var peersCommand = new Command("peers").configureHelp(helpStyle).description("List known sync peers").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+});
+syncCommand.addCommand(disableCmd);
+var peersCommand = new Command("peers").configureHelp(helpStyle).description("List known sync peers");
+addDbOption(peersCommand);
+addJsonOption(peersCommand);
+peersCommand.action((opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const peers = drizzle(store.db, { schema }).select({
 			peer_device_id: schema.syncPeers.peer_device_id,
@@ -2211,17 +3831,28 @@ var peersCommand = new Command("peers").configureHelp(helpStyle).description("Li
 		store.close();
 	}
 });
-peersCommand.addCommand(new Command("remove").configureHelp(helpStyle).description("Remove a sync peer by device id or exact name").argument("<peer>", "peer device id or exact name").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--json", "output as JSON").action((peerRef, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var peersRemoveCmd = new Command("remove").configureHelp(helpStyle).description("Remove a sync peer by device id or exact name").argument("<peer>", "peer device id or exact name");
+addDbOption(peersRemoveCmd);
+addJsonOption(peersRemoveCmd);
+peersRemoveCmd.action((peerRef, opts) => {
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
 		const d = drizzle(store.db, { schema });
 		const match = resolvePeerMatch(d, peerRef);
 		if (match === "ambiguous") {
+			if (opts.json) {
+				emitJsonError("ambiguous_peer", `Peer name is ambiguous: ${peerRef.trim()}`);
+				return;
+			}
 			p.log.error(`Peer name is ambiguous: ${peerRef.trim()}`);
 			process.exitCode = 1;
 			return;
 		}
 		if (!match) {
+			if (opts.json) {
+				emitJsonError("peer_not_found", `Peer not found: ${peerRef.trim()}`);
+				return;
+			}
 			p.log.error(`Peer not found: ${peerRef.trim()}`);
 			process.exitCode = 1;
 			return;
@@ -2243,29 +3874,37 @@ peersCommand.addCommand(new Command("remove").configureHelp(helpStyle).descripti
 	} finally {
 		store.close();
 	}
-}));
+});
+peersCommand.addCommand(peersRemoveCmd);
 syncCommand.addCommand(peersCommand);
-syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).description("Fast-bootstrap memories from a peer (full snapshot transfer)").requiredOption("--peer <device-id>", "peer device ID to bootstrap from").option("--page-size <n>", "items per snapshot page (default: 2000)", "2000").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--keys-dir <path>", "keys directory").option("--force", "skip dirty-local-state safety check").option("--json", "output as JSON").action(async (opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+var bootstrapCmd = new Command("bootstrap").configureHelp(helpStyle).description("Fast-bootstrap memories from a peer (full snapshot transfer)").argument("[peer-device-id]", "peer device ID to bootstrap from").option("--bootstrap-grant <grant-id>", "bootstrap grant id for seed-authorized bootstrap").option("--page-size <n>", "items per snapshot page (default: 2000)", "2000").option("--keys-dir <path>", "keys directory").option("--force", "skip dirty-local-state safety check");
+addDbOption(bootstrapCmd);
+addJsonOption(bootstrapCmd);
+bootstrapCmd.addOption(new Option("--peer <device-id>", "peer device ID").hideHelp());
+bootstrapCmd.action(async (peerArg, opts) => {
+	const peerDeviceId = (peerArg || opts.peer || "").trim();
+	if (!peerDeviceId) {
+		if (opts.json) {
+			emitJsonError("usage_error", "missing required argument: <peer-device-id>", 2);
+			return;
+		}
+		p.log.error("missing required argument: <peer-device-id>");
+		process.exitCode = 2;
+		return;
+	}
+	const store = new MemoryStore(resolveDbPath(resolveDbOpt(opts)));
 	try {
-		const peerDeviceId = opts.peer.trim();
 		const pageSize = Math.max(1, Number.parseInt(opts.pageSize, 10) || 2e3);
 		const keysDir = opts.keysDir ?? void 0;
 		const peer = drizzle(store.db, { schema }).select().from(schema.syncPeers).where(eq(schema.syncPeers.peer_device_id, peerDeviceId)).get();
 		if (!peer) {
-			if (opts.json) console.log(JSON.stringify({
-				ok: false,
-				error: "peer not found"
-			}));
+			if (opts.json) emitJsonError("peer_not_found", `Peer ${peerDeviceId} not found in sync_peers.`);
 			else p.log.error(`Peer ${peerDeviceId} not found in sync_peers.`);
 			process.exitCode = 1;
 			return;
 		}
 		if (!peer.pinned_fingerprint) {
-			if (opts.json) console.log(JSON.stringify({
-				ok: false,
-				error: "peer not pinned"
-			}));
+			if (opts.json) emitJsonError("peer_not_pinned", `Peer ${peerDeviceId} has no pinned fingerprint. Accept it first.`);
 			else p.log.error(`Peer ${peerDeviceId} has no pinned fingerprint. Accept it first.`);
 			process.exitCode = 1;
 			return;
@@ -2273,11 +3912,7 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 		if (!opts.force) {
 			const dirty = hasUnsyncedSharedMemoryChanges(store.db);
 			if (dirty.dirty) {
-				if (opts.json) console.log(JSON.stringify({
-					ok: false,
-					error: "local_unsynced_changes",
-					count: dirty.count
-				}));
+				if (opts.json) emitJsonError("local_unsynced_changes", `${dirty.count} unsynced shared memory change(s) would be lost. Use --force to override.`);
 				else p.log.error(`${dirty.count} unsynced shared memory change(s) would be lost. Use --force to override.`);
 				process.exitCode = 1;
 				return;
@@ -2286,17 +3921,14 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 		const [deviceId] = ensureDeviceIdentity(store.db, { keysDir });
 		const addresses = JSON.parse(String(peer.addresses_json ?? "[]"));
 		if (!addresses.length) {
-			if (opts.json) console.log(JSON.stringify({
-				ok: false,
-				error: "no peer addresses"
-			}));
+			if (opts.json) emitJsonError("no_peer_addresses", "Peer has no known addresses. Run a sync first or add addresses.");
 			else p.log.error("Peer has no known addresses. Run a sync first or add addresses.");
 			process.exitCode = 1;
 			return;
 		}
 		let boundary = null;
 		let baseUrl = "";
-		let lastAddressError = "";
+		const addressResults = [];
 		for (const address of addresses) {
 			const candidate = buildBaseUrl(address);
 			if (!candidate) continue;
@@ -2306,16 +3938,23 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 				method: "GET",
 				url: statusUrl,
 				bodyBytes: Buffer.alloc(0),
+				bootstrapGrantId: opts.bootstrapGrant,
 				keysDir
 			});
 			try {
 				const [code, payload] = await requestJson("GET", statusUrl, { headers });
 				if (code !== 200 || !payload) {
-					lastAddressError = `${candidate}: status ${code}`;
+					addressResults.push({
+						address: candidate,
+						result: `status ${code}`
+					});
 					continue;
 				}
 				if (payload.fingerprint !== peer.pinned_fingerprint) {
-					lastAddressError = `${candidate}: fingerprint mismatch`;
+					addressResults.push({
+						address: candidate,
+						result: "fingerprint mismatch"
+					});
 					continue;
 				}
 				const reset = payload.sync_reset;
@@ -2326,18 +3965,30 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 						baseline_cursor: typeof reset.baseline_cursor === "string" ? reset.baseline_cursor : null
 					};
 					baseUrl = candidate;
+					addressResults.push({
+						address: candidate,
+						result: "ok"
+					});
 					break;
 				}
-				lastAddressError = `${candidate}: missing sync_reset boundary`;
+				addressResults.push({
+					address: candidate,
+					result: "missing sync_reset boundary"
+				});
 			} catch (err) {
-				lastAddressError = `${candidate}: ${err instanceof Error ? err.message : String(err)}`;
+				addressResults.push({
+					address: candidate,
+					result: err instanceof Error ? err.message : String(err)
+				});
 			}
 		}
 		if (!boundary || !baseUrl) {
-			const detail = lastAddressError ? `peer unreachable or missing reset boundary (${lastAddressError})` : "peer unreachable or missing reset boundary";
+			const summary = addressResults.map((r) => `${r.address}: ${r.result}`).join("; ");
+			const detail = summary ? `no reachable peer with valid reset boundary. Tried: ${summary}` : "peer unreachable or missing reset boundary";
 			if (opts.json) console.log(JSON.stringify({
 				ok: false,
-				error: detail
+				error: detail,
+				addresses: addressResults
 			}));
 			else p.log.error(detail);
 			process.exitCode = 1;
@@ -2357,6 +4008,7 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 		};
 		const { items } = await fetchAllSnapshotPages(baseUrl, resetInfo, deviceId, {
 			keysDir,
+			bootstrapGrantId: opts.bootstrapGrant,
 			pageSize
 		});
 		const result = applyBootstrapSnapshot(store.db, peerDeviceId, items, resetInfo);
@@ -2375,266 +4027,27 @@ syncCommand.addCommand(new Command("bootstrap").configureHelp(helpStyle).descrip
 	} finally {
 		store.close();
 	}
-}));
-syncCommand.addCommand(new Command("connect").configureHelp(helpStyle).description("Configure coordinator URL for cloud sync").argument("<url>", "coordinator URL (e.g. https://coordinator.example.com)").option("--group <group>", "sync group ID").action((url, opts) => {
-	const config = readCodememConfigFile();
+});
+syncCommand.addCommand(bootstrapCmd);
+var connectCmd = new Command("connect").configureHelp(helpStyle).description("Configure coordinator URL for cloud sync").argument("<url>", "coordinator URL (e.g. https://coordinator.example.com)").option("--group <group>", "sync group ID");
+addConfigOption(connectCmd);
+connectCmd.action((url, opts) => {
+	const config = readCliConfig(opts.config);
 	config.sync_coordinator_url = url.trim();
 	if (opts.group) config.sync_coordinator_group = opts.group.trim();
-	writeCodememConfigFile(config);
+	writeCliConfig(config, opts.config);
 	p.intro("codemem sync connect");
 	p.log.success(`Coordinator: ${url.trim()}`);
 	if (opts.group) p.log.info(`Group: ${opts.group.trim()}`);
 	p.outro("Restart `codemem serve` to activate coordinator sync");
-}));
-var coordinatorCommand = new Command("coordinator").configureHelp(helpStyle).description("Manage coordinator invites, join requests, and relay server");
-coordinatorCommand.addCommand(new Command("group-create").configureHelp(helpStyle).description("Create a coordinator group in the local store").argument("<group>", "group id").option("--name <name>", "display name override").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, opts) => {
-	const group = await coordinatorCreateGroupAction({
-		groupId,
-		displayName: opts.name?.trim() || null,
-		dbPath: opts.db ?? opts.dbPath ?? null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(group, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator group-create");
-	p.log.success(`Group ready: ${groupId.trim()}`);
-	p.outro(String(group.display_name ?? group.group_id ?? groupId.trim()));
-}));
-coordinatorCommand.addCommand(new Command("list-groups").configureHelp(helpStyle).description("List coordinator groups from the local store").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (opts) => {
-	const groups = await coordinatorListGroupsAction({ dbPath: opts.db ?? opts.dbPath ?? null });
-	if (opts.json) {
-		console.log(JSON.stringify(groups, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator list-groups");
-	if (groups.length === 0) {
-		p.outro("No coordinator groups found");
-		return;
-	}
-	for (const group of groups) p.log.message(`- ${String(group.group_id ?? "")}${group.display_name ? ` (${String(group.display_name)})` : ""}`);
-	p.outro(`${groups.length} group(s)`);
-}));
-coordinatorCommand.addCommand(new Command("enroll-device").configureHelp(helpStyle).description("Enroll a device in a local coordinator group").argument("<group>", "group id").argument("<device-id>", "device id").option("--fingerprint <fingerprint>", "device fingerprint").option("--public-key <key>", "device public key").option("--public-key-file <path>", "path to device public key").option("--name <name>", "display name").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, deviceId, opts) => {
-	const publicKey = readCoordinatorPublicKey(opts);
-	const fingerprint = String(opts.fingerprint ?? "").trim();
-	if (!fingerprint) {
-		p.log.error("Fingerprint required via --fingerprint");
-		process.exitCode = 1;
-		return;
-	}
-	if (fingerprintPublicKey(publicKey) !== fingerprint) {
-		p.log.error("Fingerprint does not match the provided public key");
-		process.exitCode = 1;
-		return;
-	}
-	const enrollment = await coordinatorEnrollDeviceAction({
-		groupId,
-		deviceId,
-		fingerprint,
-		publicKey,
-		displayName: opts.name?.trim() || null,
-		dbPath: opts.db ?? opts.dbPath ?? null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(enrollment, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator enroll-device");
-	p.log.success(`Enrolled ${deviceId.trim()} in ${groupId.trim()}`);
-	p.outro(String(enrollment.display_name ?? enrollment.device_id ?? deviceId.trim()));
-}));
-coordinatorCommand.addCommand(new Command("list-devices").configureHelp(helpStyle).description("List enrolled devices in a local coordinator group").argument("<group>", "group id").option("--include-disabled", "include disabled devices").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, opts) => {
-	const rows = await coordinatorListDevicesAction({
-		groupId,
-		includeDisabled: opts.includeDisabled === true,
-		dbPath: opts.db ?? opts.dbPath ?? null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(rows, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator list-devices");
-	if (rows.length === 0) {
-		p.outro(`No enrolled devices for ${groupId.trim()}`);
-		return;
-	}
-	for (const row of rows) {
-		const label = String(row.display_name ?? row.device_id ?? "").trim() || String(row.device_id ?? "");
-		const enabled = Number(row.enabled ?? 1) === 1 ? "enabled" : "disabled";
-		p.log.message(`- ${label} (${String(row.device_id ?? "")}) ${enabled}`);
-	}
-	p.outro(`${rows.length} device(s)`);
-}));
-coordinatorCommand.addCommand(new Command("rename-device").configureHelp(helpStyle).description("Rename an enrolled device in the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id").requiredOption("--name <name>", "display name").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, deviceId, opts) => {
-	const result = await coordinatorRenameDeviceAction({
-		groupId,
-		deviceId,
-		displayName: opts.name.trim(),
-		dbPath: opts.db ?? opts.dbPath ?? null
-	});
-	if (!result) {
-		p.log.error(`Device not found: ${deviceId.trim()}`);
-		process.exitCode = 1;
-		return;
-	}
-	if (opts.json) {
-		console.log(JSON.stringify(result, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator rename-device");
-	p.log.success(`Renamed ${deviceId.trim()} in ${groupId.trim()}`);
-	p.outro(String(result.display_name ?? result.device_id ?? deviceId.trim()));
-}));
-coordinatorCommand.addCommand(new Command("disable-device").configureHelp(helpStyle).description("Disable an enrolled device in the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, deviceId, opts) => {
-	if (!await coordinatorDisableDeviceAction({
-		groupId,
-		deviceId,
-		dbPath: opts.db ?? opts.dbPath ?? null
-	})) {
-		p.log.error(`Device not found: ${deviceId.trim()}`);
-		process.exitCode = 1;
-		return;
-	}
-	if (opts.json) {
-		console.log(JSON.stringify({
-			ok: true,
-			group_id: groupId.trim(),
-			device_id: deviceId.trim()
-		}, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator disable-device");
-	p.log.success(`Disabled ${deviceId.trim()} in ${groupId.trim()}`);
-	p.outro("disabled");
-}));
-coordinatorCommand.addCommand(new Command("remove-device").configureHelp(helpStyle).description("Remove an enrolled device from the local coordinator store").argument("<group>", "group id").argument("<device-id>", "device id").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--json", "output as JSON").action(async (groupId, deviceId, opts) => {
-	if (!await coordinatorRemoveDeviceAction({
-		groupId,
-		deviceId,
-		dbPath: opts.db ?? opts.dbPath ?? null
-	})) {
-		p.log.error(`Device not found: ${deviceId.trim()}`);
-		process.exitCode = 1;
-		return;
-	}
-	if (opts.json) {
-		console.log(JSON.stringify({
-			ok: true,
-			group_id: groupId.trim(),
-			device_id: deviceId.trim()
-		}, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator remove-device");
-	p.log.success(`Removed ${deviceId.trim()} from ${groupId.trim()}`);
-	p.outro("removed");
-}));
-coordinatorCommand.addCommand(new Command("serve").configureHelp(helpStyle).description("Run the coordinator relay HTTP server").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--host <host>", "bind host", "127.0.0.1").option("--port <port>", "bind port", "7347").action(async (opts) => {
-	const host = String(opts.host ?? "127.0.0.1").trim() || "127.0.0.1";
-	const port = Number.parseInt(String(opts.port ?? "7347"), 10);
-	const dbPath = opts.db ?? opts.dbPath ?? DEFAULT_COORDINATOR_DB_PATH;
-	const app = createBetterSqliteCoordinatorApp({ dbPath });
-	p.intro("codemem sync coordinator serve");
-	p.log.success(`Coordinator listening at http://${host}:${port}`);
-	p.log.info(`DB: ${dbPath}`);
-	serve({
-		fetch: app.fetch,
-		hostname: host,
-		port
-	});
-}));
-coordinatorCommand.addCommand(new Command("create-invite").configureHelp(helpStyle).description("Create a coordinator team invite").argument("[group]", "group id").option("--group <group>", "group id").option("--coordinator-url <url>", "coordinator URL override").option("--policy <policy>", "invite policy", "auto_admit").option("--ttl-hours <hours>", "invite TTL hours", "24").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override").option("--json", "output as JSON").action(async (groupArg, opts) => {
-	const ttlHours = Number.parseInt(String(opts.ttlHours ?? "24"), 10);
-	const groupId = String(opts.group ?? "").trim() || String(groupArg ?? "").trim();
-	const result = await coordinatorCreateInviteAction({
-		groupId,
-		coordinatorUrl: opts.coordinatorUrl?.trim() || null,
-		policy: String(opts.policy ?? "auto_admit").trim(),
-		ttlHours,
-		createdBy: null,
-		dbPath: opts.db ?? opts.dbPath ?? null,
-		remoteUrl: opts.remoteUrl?.trim() || null,
-		adminSecret: opts.adminSecret?.trim() || null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(result, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator create-invite");
-	p.log.success(`Invite created for ${groupId}`);
-	if (typeof result.link === "string") p.log.message(`- link: ${result.link}`);
-	if (typeof result.encoded === "string") p.log.message(`- invite: ${result.encoded}`);
-	for (const warning of Array.isArray(result.warnings) ? result.warnings : []) p.log.warn(String(warning));
-	p.outro("Invite ready");
-}));
-coordinatorCommand.addCommand(new Command("import-invite").configureHelp(helpStyle).description("Import a coordinator invite").argument("<invite>", "invite value or link").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--keys-dir <path>", "keys directory").option("--config <path>", "config path").option("--json", "output as JSON").action(async (invite, opts) => {
-	const result = await coordinatorImportInviteAction({
-		inviteValue: invite,
-		dbPath: opts.db ?? opts.dbPath ?? null,
-		keysDir: opts.keysDir ?? null,
-		configPath: opts.config ?? null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(result, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator import-invite");
-	p.log.success(`Invite imported for ${result.group_id}`);
-	p.log.message(`- coordinator: ${result.coordinator_url}`);
-	p.log.message(`- status: ${result.status}`);
-	p.outro("Coordinator config updated");
-}));
-coordinatorCommand.addCommand(new Command("list-join-requests").configureHelp(helpStyle).description("List pending coordinator join requests").argument("[group]", "group id").option("--group <group>", "group id").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override").option("--json", "output as JSON").action(async (groupArg, opts) => {
-	const groupId = String(opts.group ?? "").trim() || String(groupArg ?? "").trim();
-	const rows = await coordinatorListJoinRequestsAction({
-		groupId,
-		dbPath: opts.db ?? opts.dbPath ?? null,
-		remoteUrl: opts.remoteUrl?.trim() || null,
-		adminSecret: opts.adminSecret?.trim() || null
-	});
-	if (opts.json) {
-		console.log(JSON.stringify(rows, null, 2));
-		return;
-	}
-	p.intro("codemem sync coordinator list-join-requests");
-	if (rows.length === 0) {
-		p.outro(`No pending join requests for ${groupId}`);
-		return;
-	}
-	for (const row of rows) {
-		const displayName = row.display_name || row.device_id;
-		p.log.message(`- ${displayName} (${row.device_id}) request_id=${row.request_id}`);
-	}
-	p.outro(`${rows.length} pending join request(s)`);
-}));
-function addReviewJoinRequestCommand(name, approve) {
-	coordinatorCommand.addCommand(new Command(name).configureHelp(helpStyle).description(`${approve ? "Approve" : "Deny"} a coordinator join request`).argument("<request-id>", "join request id").option("--db <path>", "coordinator database path").option("--db-path <path>", "coordinator database path").option("--remote-url <url>", "remote coordinator URL override").option("--admin-secret <secret>", "remote coordinator admin secret override").option("--json", "output as JSON").action(async (requestId, opts) => {
-		const request = await coordinatorReviewJoinRequestAction({
-			requestId: requestId.trim(),
-			approve,
-			reviewedBy: null,
-			dbPath: opts.db ?? opts.dbPath ?? null,
-			remoteUrl: opts.remoteUrl?.trim() || null,
-			adminSecret: opts.adminSecret?.trim() || null
-		});
-		if (!request) {
-			p.log.error(`Join request not found: ${requestId.trim()}`);
-			process.exitCode = 1;
-			return;
-		}
-		if (opts.json) {
-			console.log(JSON.stringify(request, null, 2));
-			return;
-		}
-		p.intro(`codemem sync coordinator ${name}`);
-		p.log.success(`${approve ? "Approved" : "Denied"} join request ${requestId.trim()}`);
-		p.outro(String(request.status ?? "updated"));
-	}));
-}
-addReviewJoinRequestCommand("approve-join-request", true);
-addReviewJoinRequestCommand("deny-join-request", false);
-syncCommand.addCommand(coordinatorCommand);
+});
+syncCommand.addCommand(connectCmd);
+var syncCoordinatorAlias = buildCoordinatorCommand();
+syncCoordinatorAlias.hook("preAction", (_thisCmd, actionCmd) => {
+	const subName = actionCmd.name();
+	emitDeprecationWarning(`codemem sync coordinator ${subName}`, `codemem coordinator ${subName}`);
+});
+syncCommand.addCommand(syncCoordinatorAlias);
 //#endregion
 //#region src/commands/version.ts
 var versionCommand = new Command("version").configureHelp(helpStyle).description("Print codemem version").action(() => {
@@ -2655,24 +4068,24 @@ var versionCommand = new Command("version").configureHelp(helpStyle).description
 var completion = omelette("codemem <command>");
 completion.on("command", ({ reply }) => {
 	reply([
+		"claude-hook-inject",
 		"claude-hook-ingest",
+		"config",
+		"coordinator",
 		"db",
 		"embed",
+		"enqueue-raw-event",
 		"export-memories",
-		"forget",
-		"memory",
 		"import-memories",
-		"setup",
-		"show",
-		"sync",
-		"stats",
+		"mcp",
+		"memory",
+		"pack",
 		"recent",
-		"remember",
 		"search",
-		"pack",
 		"serve",
-		"mcp",
-		"enqueue-raw-event",
+		"setup",
+		"stats",
+		"sync",
 		"version",
 		"help",
 		"--help",
@@ -2706,8 +4119,33 @@ if (hasRootFlag("--cleanup-completion")) {
 	completion.cleanupShellInitFile();
 	process.exit(0);
 }
+{
+	const memExport = new Command("export").description("Export memories to a JSON file for sharing or backup").argument("<output>", "output file path (use '-' for stdout)").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--project <project>", "filter by project").option("--all-projects", "export all projects").option("--include-inactive", "include deactivated memories").option("--since <iso>", "only export memories created after this ISO timestamp").configureHelp(helpStyle).allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+		const idx = process.argv.indexOf("export");
+		const tail = idx >= 0 ? process.argv.slice(idx + 1) : [];
+		await exportMemoriesCommand.parseAsync([
+			"node",
+			"export-memories",
+			...tail
+		]);
+	});
+	const memImport = new Command("import").description("Import memories from an exported JSON file").argument("<inputFile>", "input JSON file (use '-' for stdin)").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--remap-project <path>", "remap all projects to this path on import").option("--dry-run", "preview import without writing").configureHelp(helpStyle).allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+		const idx = process.argv.indexOf("import");
+		const tail = idx >= 0 ? process.argv.slice(idx + 1) : [];
+		await importMemoriesCommand.parseAsync([
+			"node",
+			"import-memories",
+			...tail
+		]);
+	});
+	memoryCommand.addCommand(memExport);
+	memoryCommand.addCommand(memImport);
+}
 program.addCommand(serveCommand);
+program.addCommand(configCommand);
+program.addCommand(coordinatorCommand);
 program.addCommand(mcpCommand);
+program.addCommand(claudeHookInjectCommand);
 program.addCommand(claudeHookIngestCommand);
 program.addCommand(dbCommand);
 program.addCommand(exportMemoriesCommand);
@@ -2717,9 +4155,9 @@ program.addCommand(embedCommand);
 program.addCommand(recentCommand);
 program.addCommand(searchCommand);
 program.addCommand(packCommand);
-program.addCommand(showMemoryCommand);
-program.addCommand(forgetMemoryCommand);
-program.addCommand(rememberMemoryCommand);
+program.addCommand(showMemoryCommand, { hidden: true });
+program.addCommand(forgetMemoryCommand, { hidden: true });
+program.addCommand(rememberMemoryCommand, { hidden: true });
 program.addCommand(memoryCommand);
 program.addCommand(syncCommand);
 program.addCommand(setupCommand);