codemem 0.40.2 → 0.41.0

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, REF_BACKFILL_JOB, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, clonePromptPackAttempt, compareMemoryRoleReports, connect, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getAttributionDiagnostics, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, planReplicationOpsAgePrune, projectMatchesFilter, promptPackArtifactFingerprint, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, recordPromptPackArtifacts, recordPromptPackTerminal, recordRetrievalSurface, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, resolveRetrievalSession, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, tryUpdateRetrievalDelivery, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
+import { DEDUP_KEY_BACKFILL_JOB, DEFAULT_COORDINATOR_DB_PATH, DedupKeyBackfillRunner, DeviceIdentityError, MUTATING_TOOL_NAMES, MemoryStore, ObserverClient, REF_BACKFILL_JOB, RawEventSweeper, RefBackfillRunner, SCOPE_BACKFILL_JOB, SESSION_CONTEXT_BACKFILL_JOB, SUMMARY_DEDUP_BACKFILL_JOB, ScopeBackfillRunner, SessionContextBackfillRunner, SummaryDedupBackfillRunner, SyncRetentionRunner, VERSION, VectorModelMigrationRunner, aiBackfillStructuredContent, applyBootstrapSnapshot, applyDistillRule, backfillMemoryDedupKeys, backfillNarrativeFromBody, backfillTagsText, backfillVectors, buildAuthHeaders, buildBaseUrl, buildDistillReport, buildRawEventEnvelopeFromCodexHook, buildRawEventEnvelopeFromHook, clonePromptPackAttempt, collectOperationalStatus, compareMemoryRoleReports, connect, connectReadOnly, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnrollDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorUpdateScopeAction, createBetterSqliteCoordinatorApp, deactivateLowSignalMemories, deactivateLowSignalObservations, dedupNearDuplicateMemories, detectInstallKind, draftDistillRule, ensureDeviceIdentity, ensureSchemaBootstrapped, estimateExtractionModelCost, exportMemories, extractApplyPatchPaths, fetchAllSnapshotPages, fingerprintPublicKey, flushRawEvents, formatHostPort, getAttributionDiagnostics, getExtractionBenchmarkProfile, getExtractionModelPricing, getInjectionEvalScenarioPack, getInjectionEvalScenarioPrompts, getMaintenanceJob, getMemoryArtifactReport, getMemoryRoleReport, getRawEventRelinkPlan, getRawEventRelinkReport, getRawEventStatus, getSemanticIndexDiagnostics, getSessionExtractionEval, getSessionExtractionEvalScenario, getUpdateStatus, getWorkspaceCodememConfigPath, hasPendingDedupKeyBackfill, hasPendingRefBackfill, hasPendingScopeBackfill, hasPendingSessionContextBackfill, hasPendingSummaryDedupBackfill, hasUnsyncedSharedMemoryChanges, importMemories, initDatabase, isEmbeddingDisabled, isStableReleaseVersion, judgeDistillReport, listMaintenanceJobs, listPerPeerScopeSyncState, listRetentionScopeIds, loadObserverConfig, loadPublicKey, loadSqliteVec, mdnsEnabled, planReplicationOpsAgePrune, probeCodememViewerLiveness, probeCodememViewerLiveness as probeCodememViewerLiveness$1, projectMatchesFilter, promptPackArtifactFingerprint, pruneReplicationOpsUntilCaughtUp, rawEventsGate, readCodememConfigFile, readCodememConfigFileAtPath, readCoordinatorSyncConfig, readImportPayload, recordPromptPackArtifacts, recordPromptPackTerminal, recordRetrievalSurface, renderUnifiedDiff, replayBatchExtraction, replayBatchExtractionWithTierRouting, requestJson, resolveCodememConfigPath, resolveDbPath, resolveHookProject, resolveProject, resolveProjectRoot, resolveRetrievalSession, retryRawEventFailures, runSyncDaemon, runSyncPass, scanSecretsRetroactive, schema, scoreExtractionBenchmarkOutput, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, tryUpdateRetrievalDelivery, updatePeerAddresses, vacuumDatabase, viewerUrl, writeCodememConfigFile } from "@codemem/core";
 import { Command, Option } from "commander";
 import omelette from "omelette";
 import { randomInt, randomUUID } from "node:crypto";
@@ -13,6 +13,7 @@ import { execFileSync, spawn, spawnSync } from "node:child_process";
 import net from "node:net";
 import { desc, eq } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/better-sqlite3";
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
 //#region src/help-style.ts
 /**
 * Shared Commander help style configuration.
@@ -1482,7 +1483,7 @@ var EMPTY_PACK$1 = {
 	packTokens: 0
 };
 var DEFAULT_VIEWER_HOST$1 = "127.0.0.1";
-var DEFAULT_VIEWER_PORT$1 = 38888;
+var DEFAULT_VIEWER_PORT$2 = 38888;
 var DEFAULT_MAX_CHARS$1 = 16e3;
 var DEFAULT_HTTP_MAX_TIME_S$1 = 2;
 function emitJson$1(value) {
@@ -1551,7 +1552,7 @@ async function tryHttpPack$1(context, project, maxTimeMs = DEFAULT_HTTP_MAX_TIME
 		packTokens: 0
 	};
 	const host = process.env.CODEMEM_VIEWER_HOST || DEFAULT_VIEWER_HOST$1;
-	const port = parsePositiveInt$2(process.env.CODEMEM_VIEWER_PORT, DEFAULT_VIEWER_PORT$1);
+	const port = parsePositiveInt$2(process.env.CODEMEM_VIEWER_PORT, DEFAULT_VIEWER_PORT$2);
 	const url = new URL(`http://${host}:${port}/api/pack`);
 	url.searchParams.set("context", context);
 	url.searchParams.set("limit", String(parsePositiveInt$2(process.env.CODEMEM_INJECT_LIMIT, 8)));
@@ -2182,7 +2183,7 @@ var EMPTY_PACK = {
 	packTokens: 0
 };
 var DEFAULT_VIEWER_HOST = "127.0.0.1";
-var DEFAULT_VIEWER_PORT = 38888;
+var DEFAULT_VIEWER_PORT$1 = 38888;
 var DEFAULT_MAX_CHARS = 16e3;
 var DEFAULT_HTTP_MAX_TIME_S = 2;
 var CODEMEM_CONTEXT_HEADER = `## codemem memory context
@@ -2256,7 +2257,7 @@ async function buildLocalPack(context, project, dbPath) {
 }
 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$1(process.env.CODEMEM_VIEWER_PORT, DEFAULT_VIEWER_PORT);
+	const port = parsePositiveInt$1(process.env.CODEMEM_VIEWER_PORT, DEFAULT_VIEWER_PORT$1);
 	const url = new URL(`http://${host}:${port}/api/pack`);
 	url.searchParams.set("context", context);
 	url.searchParams.set("limit", String(parsePositiveInt$1(process.env.CODEMEM_INJECT_LIMIT, 8)));
@@ -4267,6 +4268,7 @@ function expandUserPath(value) {
 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) => {
+	if (output !== "-" && invokedAsTopLevelAlias("export-memories")) emitDeprecationWarning("codemem export-memories", "codemem memory export");
 	const payload = exportMemories({
 		dbPath: resolveDbPath(resolveDbOpt(opts)),
 		project: opts.project,
@@ -4298,6 +4300,7 @@ var cmd$1 = new Command("import-memories").configureHelp(helpStyle).description(
 addDbOption(cmd$1);
 addJsonOption(cmd$1);
 cmd$1.action((inputFile, opts) => {
+	if (!opts.json && invokedAsTopLevelAlias("import-memories")) emitDeprecationWarning("codemem import-memories", "codemem memory import");
 	let payload;
 	try {
 		payload = readImportPayload(inputFile);
@@ -6040,6 +6043,90 @@ function timeSince(isoDate) {
 	return `${Math.floor(days / 30)}mo ago`;
 }
 //#endregion
+//#region src/viewer-runtime.ts
+function isValidPid(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isValidPort(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535;
+}
+function parseViewerPidRecord(raw) {
+	if (raw == null) return { state: "missing" };
+	const trimmed = raw.trim();
+	if (!trimmed) return { state: "malformed" };
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (isValidPid(parsed)) return {
+			state: "legacy",
+			pid: parsed
+		};
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { state: "malformed" };
+		const candidate = parsed;
+		if (!isValidPid(candidate.pid) || typeof candidate.host !== "string" || !candidate.host.trim() || !isValidPort(candidate.port)) return { state: "malformed" };
+		return {
+			state: "valid",
+			record: {
+				pid: candidate.pid,
+				host: candidate.host.trim(),
+				port: candidate.port
+			}
+		};
+	} catch {
+		if (!/^\d+$/.test(trimmed)) return { state: "malformed" };
+		const pid = Number(trimmed);
+		return isValidPid(pid) ? {
+			state: "legacy",
+			pid
+		} : { state: "malformed" };
+	}
+}
+function isLoopbackHost(host) {
+	const normalized = host.trim().toLowerCase().replace(/^\[(.*)\]$/, "$1");
+	const ipv4Parts = normalized.split(".");
+	const isIpv4Loopback = ipv4Parts.length >= 1 && ipv4Parts.length <= 4 && ipv4Parts[0] === "127" && ipv4Parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255);
+	return normalized === "localhost" || normalized === "::1" || normalized === "0:0:0:0:0:0:0:1" || isIpv4Loopback;
+}
+async function observeViewerRuntime(parsed, deps, defaultTarget = {
+	host: "127.0.0.1",
+	port: 38888
+}) {
+	if (parsed.state === "malformed") return {
+		state: "unknown",
+		attention_code: "viewer_pid_malformed"
+	};
+	const record = parsed.state === "valid" ? parsed.record : parsed.state === "legacy" ? {
+		...defaultTarget,
+		pid: parsed.pid
+	} : defaultTarget;
+	if (!isLoopbackHost(record.host)) return {
+		state: "unknown",
+		pid: record.pid,
+		attention_code: "viewer_non_loopback"
+	};
+	if (record.pid && deps.isProcessRunning(record.pid) === false) return {
+		state: "stopped",
+		pid: record.pid
+	};
+	const probe = await probeCodememViewerLiveness(record, deps);
+	if (probe.state === "live") return probe.degraded ? {
+		state: "running",
+		pid: record.pid,
+		attention_code: "viewer_not_ready"
+	} : record.pid ? {
+		state: "running",
+		pid: record.pid
+	} : { state: "running" };
+	if (probe.reason === "unreachable") return {
+		state: "unreachable",
+		pid: record.pid
+	};
+	return {
+		state: "unknown",
+		pid: record.pid,
+		attention_code: probe.reason === "wrong_service" ? "viewer_wrong_service" : "viewer_unexpected_response"
+	};
+}
+//#endregion
 //#region src/commands/serve-invocation.ts
 /**
 * Parse and validate a port string. Throws a user-friendly message (no stack trace)
@@ -6102,8 +6189,7 @@ function isLocalHost(host) {
 	return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1" || normalized === "0.0.0.0" || normalized === "::";
 }
 function isLoopbackOnlyHost(host) {
-	const normalized = host.trim().toLowerCase();
-	return normalized === "localhost" || /^127(?:\.\d{1,3}){0,3}$/.test(normalized) || normalized === "::1" || normalized === "0:0:0:0:0:0:0:1";
+	return isLoopbackHost(host);
 }
 function warnIfViewerExposed(host, port) {
 	if (isLoopbackOnlyHost(host)) return;
@@ -6203,22 +6289,13 @@ function commandHasExactDbPath(command, dbPath) {
 function readViewerPidRecord(dbPath) {
 	const pidPath = pidFilePath(dbPath);
 	if (!existsSync(pidPath)) return null;
-	const raw = readFileSync(pidPath, "utf-8").trim();
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed.pid === "number" && typeof parsed.host === "string" && typeof parsed.port === "number") return {
-			pid: parsed.pid,
-			host: parsed.host,
-			port: parsed.port
-		};
-	} catch {
-		const pid = Number.parseInt(raw, 10);
-		if (Number.isFinite(pid) && pid > 0) return {
-			pid,
-			host: "127.0.0.1",
-			port: 38888
-		};
-	}
+	const parsed = parseViewerPidRecord(readFileSync(pidPath, "utf-8"));
+	if (parsed.state === "valid") return parsed.record;
+	if (parsed.state === "legacy") return {
+		pid: parsed.pid,
+		host: "127.0.0.1",
+		port: 38888
+	};
 	return null;
 }
 function normalizeViewerHost(host) {
@@ -6242,23 +6319,18 @@ function isProcessRunning(pid) {
 		return false;
 	}
 }
-async function respondsLikeCodememViewer(record) {
-	try {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), 1e3);
-		const res = await fetch(`http://${record.host}:${record.port}/api/stats`, { signal: controller.signal });
-		clearTimeout(timer);
-		return res.ok;
-	} catch {
-		return false;
-	}
+async function respondsLikeCodememViewer(record, fetchImpl = fetch) {
+	return (await probeCodememViewerLiveness$1(record, {
+		fetch: fetchImpl,
+		timeoutMs: 1e3
+	})).state === "live";
 }
 async function lookupViewerPidFromStats(host, port) {
 	try {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), 1e3);
-		const res = await fetch(`http://${host}:${port}/api/stats`, { signal: controller.signal });
-		clearTimeout(timer);
+		const res = await fetch(viewerUrl({
+			host,
+			port
+		}, "/api/stats"), { signal: AbortSignal.timeout(1e3) });
 		if (!res.ok) return null;
 		return extractViewerPid(await res.json());
 	} catch {
@@ -6467,11 +6539,14 @@ async function runServeCoordinatorMaintenance(store, dependencies) {
 	const enrollmentIssues = coordinatorEnrollment.issues ?? 0;
 	const recipientPolicies = await dependencies.reconcileRecipientPolicyProjects(store, { limit: 3 });
 	if (projectShares.failed > 0) throw new Error(`share operation maintenance failed for ${projectShares.failed} of ${projectShares.processed} operations`);
-	if (coordinatorEnrollment.failedGroups > 0 || enrollmentIssues > 0) {
+	if (coordinatorEnrollment.failedGroups > 0) {
 		const groupLabel = coordinatorEnrollment.failedGroups === 1 ? "group" : "groups";
 		const issueLabel = enrollmentIssues === 1 ? "issue" : "issues";
-		throw new Error(`coordinator enrollment maintenance failed for ${coordinatorEnrollment.failedGroups} ${groupLabel} with ${enrollmentIssues} reconciliation ${issueLabel}`);
+		const failures = coordinatorEnrollment.failures ?? [];
+		const failureDetail = failures.length ? ` [${failures.slice(0, 3).map((failure) => `${failure.groupId}:${failure.stage}:${failure.code}`).join(", ")}${failures.length > 3 ? `, +${failures.length - 3} more` : ""}]` : "";
+		throw new Error(`coordinator enrollment maintenance failed for ${coordinatorEnrollment.failedGroups} ${groupLabel} with ${enrollmentIssues} reconciliation ${issueLabel}${failureDetail}`);
 	}
+	if (enrollmentIssues > 0) throw new Error(`coordinator enrollment reconciliation found ${enrollmentIssues} ${enrollmentIssues === 1 ? "issue" : "issues"}`);
 	if (recipientPolicies.failed > 0) throw new Error(`recipient policy maintenance failed for ${recipientPolicies.failed} of ${recipientPolicies.processed} projects`);
 	return {
 		projectShares,
@@ -7290,6 +7365,341 @@ var statsCommand = statsCmd.action((opts) => {
 	}
 });
 //#endregion
+//#region src/commands/status.ts
+var MAX_ATTENTION = 20;
+var DEFAULT_VIEWER_PORT = 38888;
+var RECENT_FAILURE_WINDOW_MS = 1440 * 60 * 1e3;
+var OBSERVER_IDENTITY_KEYS = [
+	"observer_provider",
+	"observer_model",
+	"observer_runtime",
+	"observer_base_url",
+	"observer_simple_provider",
+	"observer_simple_model",
+	"observer_rich_provider",
+	"observer_rich_model"
+];
+var defaultDependencies = {
+	now: () => /* @__PURE__ */ new Date(),
+	exists: existsSync,
+	readText: (path) => {
+		try {
+			return readFileSync(path, "utf8");
+		} catch {
+			return null;
+		}
+	},
+	readConfig: (path) => path ? readCodememConfigFileAtPath(path) : readCodememConfigFile(),
+	resolveDbPath,
+	connectReadOnly,
+	collectDatabase: collectOperationalStatus,
+	embeddingDisabled: isEmbeddingDisabled,
+	fetch,
+	isProcessRunning: (pid) => {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "EPERM") return null;
+			return false;
+		}
+	},
+	env: process.env,
+	writeStdout: (text) => console.log(text),
+	writeStderr: (text) => console.error(text),
+	setExitCode: (code) => {
+		process.exitCode = code;
+	}
+};
+function boolValue(value) {
+	if (typeof value === "boolean") return value;
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	if ([
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes(normalized)) return true;
+	if ([
+		"0",
+		"false",
+		"no",
+		"off"
+	].includes(normalized)) return false;
+	return null;
+}
+function syncEnabled(config, env) {
+	return boolValue(env.CODEMEM_SYNC_ENABLED) ?? boolValue(config.sync_enabled) ?? false;
+}
+function observerConfigured(config, env) {
+	const fileConfigured = OBSERVER_IDENTITY_KEYS.some((key) => {
+		const value = config[key];
+		return typeof value === "string" && value.trim() !== "";
+	});
+	const envConfigured = OBSERVER_IDENTITY_KEYS.some((key) => {
+		const value = env[`CODEMEM_${key.toUpperCase()}`];
+		return typeof value === "string" && value.trim() !== "";
+	});
+	return fileConfigured || envConfigured;
+}
+function viewerDefaultTarget(env) {
+	const host = env.CODEMEM_VIEWER_HOST?.trim() || "127.0.0.1";
+	const parsedPort = Number.parseInt(env.CODEMEM_VIEWER_PORT ?? "", 10);
+	return {
+		host,
+		port: Number.isFinite(parsedPort) && parsedPort > 0 && parsedPort <= 65535 ? parsedPort : DEFAULT_VIEWER_PORT
+	};
+}
+function boundAttention(items) {
+	return items.slice(0, MAX_ATTENTION).map((item) => ({
+		code: item.code.replace(/[^a-z0-9_]/gi, "_").slice(0, 64),
+		severity: item.severity,
+		message: item.message.slice(0, 500)
+	}));
+}
+function projectSync(enabled, snapshot, attention) {
+	if (!enabled) return "disabled";
+	if (!snapshot) return "unknown";
+	if (snapshot.sync.daemon_error || snapshot.sync.needs_attention) {
+		attention.push({
+			code: "sync_daemon_error",
+			severity: "error",
+			message: "Sync requires attention; run `codemem sync doctor`"
+		});
+		return "error";
+	}
+	if (snapshot.sync.peer_errors > 0) {
+		attention.push({
+			code: "sync_degraded",
+			severity: "warning",
+			message: "Sync has recent peer failures; run `codemem sync status`"
+		});
+		return "degraded";
+	}
+	if (!snapshot.sync.available) return "unknown";
+	return "healthy";
+}
+function addDatabaseAttention(state, attention) {
+	if (state === "missing") attention.push({
+		code: "database_missing",
+		severity: "error",
+		message: "Database does not exist"
+	});
+	else if (state === "unavailable") attention.push({
+		code: "database_unavailable",
+		severity: "error",
+		message: "Database could not be read"
+	});
+}
+function addRuntimeAttention(runtime, attention) {
+	if (runtime.state === "stopped") {
+		attention.push({
+			code: "viewer_stopped",
+			severity: "warning",
+			message: "Viewer is stopped; run `codemem serve start` if needed"
+		});
+		return;
+	}
+	if (runtime.state === "unreachable") {
+		attention.push({
+			code: "viewer_unreachable",
+			severity: "warning",
+			message: "Viewer did not answer its local health check"
+		});
+		return;
+	}
+	if (runtime.attention_code) attention.push({
+		code: runtime.attention_code,
+		severity: "warning",
+		message: {
+			viewer_pid_malformed: "Viewer PID record is malformed",
+			viewer_non_loopback: "Viewer PID record is not loopback; no request was made",
+			viewer_not_ready: "Viewer is running but its database is not ready",
+			viewer_unexpected_response: "Viewer returned an unexpected local health response",
+			viewer_wrong_service: "Local health endpoint did not identify codemem viewer"
+		}[runtime.attention_code]
+	});
+}
+function projectDatabaseSubsystems(snapshot, configuredObserver, attention) {
+	if (!snapshot) return {
+		maintenance: { state: "unknown" },
+		semantic_index: { state: "unknown" },
+		raw_events: {
+			state: "unknown",
+			pending: 0
+		},
+		observer: { state: configuredObserver ? "unknown" : "unconfigured" }
+	};
+	if (snapshot.maintenance.state === "failed") attention.push({
+		code: "maintenance_failed",
+		severity: "error",
+		message: "Maintenance has failed jobs; run `codemem maintenance status`"
+	});
+	else if (snapshot.maintenance.state === "running") attention.push({
+		code: "maintenance_running",
+		severity: "warning",
+		message: "Maintenance work is in progress"
+	});
+	if (snapshot.semantic_index.state === "failed") attention.push({
+		code: "semantic_index_failed",
+		severity: "error",
+		message: "Semantic index maintenance failed; run `codemem maintenance status`"
+	});
+	else if (snapshot.semantic_index.state === "pending") attention.push({
+		code: "semantic_index_pending",
+		severity: "warning",
+		message: "Semantic index maintenance is pending"
+	});
+	else if (snapshot.semantic_index.state === "degraded") attention.push({
+		code: "semantic_index_degraded",
+		severity: "warning",
+		message: "Semantic search is unavailable; keyword search remains available"
+	});
+	const pending = Math.max(0, Math.trunc(snapshot.raw_events.pending));
+	let rawState = snapshot.raw_events.available ? "healthy" : "unknown";
+	if (snapshot.raw_events.failed_batches > 0) {
+		rawState = "failing";
+		attention.push({
+			code: "raw_events_failing",
+			severity: "error",
+			message: "Raw-event ingestion exhausted retries recently; run `codemem db raw-events-gate`"
+		});
+	} else if (pending > 0) {
+		rawState = "backlogged";
+		attention.push({
+			code: "raw_events_backlogged",
+			severity: "warning",
+			message: `${pending} raw events pending; run \`codemem db raw-events-status\``
+		});
+	}
+	let observerState = "unconfigured";
+	if (configuredObserver) observerState = snapshot.observer.available ? "idle" : "unknown";
+	if (configuredObserver && snapshot.observer.failed_batches > 0) {
+		observerState = "failed";
+		attention.push({
+			code: "observer_failed",
+			severity: "error",
+			message: "Observer exhausted retries recently; run `codemem db raw-events-gate`"
+		});
+	} else if (configuredObserver && snapshot.observer.backoff_batches > 0) {
+		observerState = "backoff";
+		attention.push({
+			code: "observer_backoff",
+			severity: "warning",
+			message: "Observer has retryable failures; run `codemem db raw-events-status`"
+		});
+	}
+	return {
+		maintenance: { state: snapshot.maintenance.state },
+		semantic_index: { state: snapshot.semantic_index.state },
+		raw_events: {
+			state: rawState,
+			pending
+		},
+		observer: { state: observerState }
+	};
+}
+async function collectStatusReport(opts, deps = defaultDependencies) {
+	const checkedAt = deps.now();
+	const config = deps.readConfig(opts.config);
+	const dbPath = deps.resolveDbPath(resolveDbOpt(opts));
+	let databaseState = "missing";
+	let snapshot = null;
+	if (deps.exists(dbPath)) {
+		let db = null;
+		try {
+			db = deps.connectReadOnly(dbPath, { warn: opts.json ? () => {} : deps.writeStderr });
+		} catch {
+			databaseState = "unavailable";
+		}
+		if (db) try {
+			snapshot = deps.collectDatabase(db, {
+				embeddingDisabled: deps.embeddingDisabled(),
+				recentFailureCutoff: (/* @__PURE__ */ new Date(checkedAt.getTime() - RECENT_FAILURE_WINDOW_MS)).toISOString()
+			});
+			databaseState = "ready";
+		} finally {
+			db.close();
+		}
+	}
+	const pidPath = join(dirname(dbPath), "viewer.pid");
+	const runtime = await observeViewerRuntime(parseViewerPidRecord(deps.exists(pidPath) ? deps.readText(pidPath) : null), {
+		fetch: deps.fetch,
+		isProcessRunning: deps.isProcessRunning
+	}, viewerDefaultTarget(deps.env));
+	const attention = [];
+	addDatabaseAttention(databaseState, attention);
+	addRuntimeAttention(runtime, attention);
+	const sync = projectSync(syncEnabled(config, deps.env), snapshot, attention);
+	const subsystems = projectDatabaseSubsystems(snapshot, observerConfigured(config, deps.env), attention);
+	const ok = !attention.some((item) => item.severity === "error");
+	const boundedAttention = boundAttention(attention);
+	return {
+		checked_at: checkedAt.toISOString(),
+		ok,
+		version: VERSION,
+		database: { state: databaseState },
+		runtime: runtime.pid ? {
+			viewer: runtime.state,
+			pid: runtime.pid
+		} : { viewer: runtime.state },
+		sync: { state: sync },
+		...subsystems,
+		attention: boundedAttention
+	};
+}
+function renderStatusReport(report) {
+	const lines = [
+		`codemem status ${report.ok ? "OK" : "ATTENTION"}`,
+		`Database:       ${report.database.state}`,
+		`Viewer:         ${report.runtime.viewer}${report.runtime.pid ? ` (pid ${report.runtime.pid})` : ""}`,
+		`Sync:           ${report.sync.state}`,
+		`Maintenance:    ${report.maintenance.state}`,
+		`Semantic index: ${report.semantic_index.state}`,
+		`Raw events:     ${report.raw_events.state}${report.raw_events.pending > 0 ? ` (${report.raw_events.pending} pending)` : ""}`,
+		`Observer:       ${report.observer.state}`
+	];
+	if (report.attention.length > 0) lines.push("Attention:", ...report.attention.map((item) => `- ${item.severity}: ${item.message}`));
+	return lines.join("\n");
+}
+function createStatusCommand(overrides = {}) {
+	const deps = {
+		...defaultDependencies,
+		...overrides
+	};
+	const command = new Command("status").configureHelp(helpStyle).description("Show local operational status").allowUnknownOption(true).allowExcessArguments(true);
+	addDbOption(command);
+	addConfigOption(command);
+	addJsonOption(command);
+	return command.action(async (opts, actionCommand) => {
+		if (actionCommand.args.length > 0) {
+			const message = "status accepts only documented options and no positional arguments";
+			if (opts.json) deps.writeStdout(JSON.stringify({
+				error: "usage_error",
+				message
+			}));
+			else deps.writeStderr(message);
+			deps.setExitCode(2);
+			return;
+		}
+		try {
+			const report = await collectStatusReport(opts, deps);
+			deps.writeStdout(opts.json ? JSON.stringify(report) : renderStatusReport(report));
+			deps.setExitCode(0);
+		} catch {
+			const error = {
+				error: "status_failed",
+				message: "Unable to collect operational status"
+			};
+			if (opts.json) deps.writeStdout(JSON.stringify(error));
+			else deps.writeStderr(error.message);
+			deps.setExitCode(1);
+		}
+	});
+}
+var statusCommand = createStatusCommand();
+//#endregion
 //#region src/commands/sync-helpers.ts
 function formatSyncAttempt(row) {
 	const status = row.ok ? "ok" : "error";
@@ -7523,6 +7933,7 @@ onceCmd.action(async (opts) => {
 		for (const row of rows) {
 			const result = await runSyncPass(store.db, row.peer_device_id, {
 				keysDir,
+				dbPath: store.dbPath,
 				scanner: store.scanner
 			});
 			if (!result.ok) hadFailure = true;
@@ -7738,6 +8149,15 @@ pairCmd.action(async (opts) => {
 		console.log("For machine-friendly output next time, run:");
 		console.log("  codemem sync pair --payload-only");
 		console.log("On the accepting device, --include/--exclude control both what it sends and what it accepts from that peer.");
+	} catch (error) {
+		const code = error instanceof DeviceIdentityError ? error.code : "pairing_failed";
+		const message = error instanceof Error ? error.message : "Pairing failed";
+		if (opts.json) {
+			emitJsonError(code, message);
+			return;
+		}
+		p.log.error(message);
+		process.exitCode = 1;
 	} finally {
 		store.close();
 	}
@@ -7762,12 +8182,19 @@ doctorCmd.action(async (opts) => {
 			public_key: schema.syncPeers.public_key
 		}).from(schema.syncPeers).all();
 		const issues = [];
+		let identityError = null;
 		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 (device) try {
+			ensureDeviceIdentity(store.db, { keysDir: process.env.CODEMEM_KEYS_DIR?.trim() || void 0 });
+		} catch (error) {
+			identityError = error instanceof Error ? error.message : "device_identity_unavailable";
+			issues.push(identityError);
+		}
 		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");
@@ -7799,6 +8226,7 @@ doctorCmd.action(async (opts) => {
 				mdns_source: mdnsSource,
 				daemon: reachable ? "running" : "not running",
 				identity: device?.device_id ?? null,
+				identity_error: identityError,
 				daemon_error: daemonState?.last_error ?? null,
 				peers: peerDetails,
 				issues: [...new Set(issues)],
@@ -7812,7 +8240,10 @@ doctorCmd.action(async (opts) => {
 		console.log(`- mDNS: ${mdnsLabel}`);
 		console.log(`- Daemon: ${reachable ? "running" : "not running"}`);
 		if (!device) console.log("- Identity: missing (run `codemem sync enable`)");
-		else console.log(`- Identity: ${device.device_id}`);
+		else {
+			console.log(`- Identity: ${device.device_id}`);
+			if (identityError) console.log(`- Identity error: ${identityError}`);
+		}
 		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 {
@@ -7821,6 +8252,15 @@ doctorCmd.action(async (opts) => {
 		}
 		if (issues.length > 0) console.log(`WARN: ${[...new Set(issues)].slice(0, 3).join(", ")}`);
 		else console.log("OK: sync looks healthy");
+	} catch (error) {
+		const code = error instanceof DeviceIdentityError ? error.code : "doctor_failed";
+		const message = error instanceof Error ? error.message : "Sync diagnostics failed";
+		if (opts.json) {
+			emitJsonError(code, message);
+			return;
+		}
+		p.log.error(message);
+		process.exitCode = 1;
 	} finally {
 		store.close();
 	}
@@ -8118,6 +8558,7 @@ bootstrapCmd.action(async (peerArg, opts) => {
 			const statusUrl = `${candidate}/v1/status`;
 			const headers = buildAuthHeaders({
 				deviceId,
+				dbPath: store.dbPath,
 				method: "GET",
 				url: statusUrl,
 				bodyBytes: Buffer.alloc(0),
@@ -8191,6 +8632,7 @@ bootstrapCmd.action(async (peerArg, opts) => {
 		};
 		const { items } = await fetchAllSnapshotPages(baseUrl, resetInfo, deviceId, {
 			keysDir,
+			dbPath: store.dbPath,
 			bootstrapGrantId: opts.bootstrapGrant,
 			pageSize
 		});
@@ -8207,6 +8649,15 @@ bootstrapCmd.action(async (peerArg, opts) => {
 			p.outro(result.ok ? "Bootstrap complete" : "Bootstrap failed");
 		}
 		if (!result.ok) process.exitCode = 1;
+	} catch (error) {
+		const code = error instanceof DeviceIdentityError ? error.code : "bootstrap_failed";
+		const message = error instanceof Error ? error.message : "Bootstrap failed";
+		if (opts.json) {
+			emitJsonError(code, message);
+			return;
+		}
+		p.log.error(message);
+		process.exitCode = 1;
 	} finally {
 		store.close();
 	}
@@ -8230,13 +8681,411 @@ syncCoordinatorAlias.hook("preAction", (_thisCmd, actionCmd) => {
 	const subName = actionCmd.name();
 	emitDeprecationWarning(`codemem sync coordinator ${subName}`, `codemem coordinator ${subName}`);
 });
-syncCommand.addCommand(syncCoordinatorAlias);
+syncCommand.addCommand(syncCoordinatorAlias, { hidden: true });
+//#endregion
+//#region src/commands/update.ts
+var INSTALL_TIMEOUT_MS = 300 * 1e3;
+var VERIFY_TIMEOUT_MS = 3e4;
+var PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+var UPDATE_LOCK_FILE = "update-install.lock";
+var UpdateInstallLockedError = class extends Error {};
+function updateInstallLockPath() {
+	return join(process.env.HOME?.trim() || homedir(), ".codemem", UPDATE_LOCK_FILE);
+}
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+async function removeStaleInstallLock(lockPath) {
+	try {
+		const [rawPid, lockStat] = await Promise.all([readFile(lockPath, "utf8"), stat(lockPath)]);
+		const pid = Number.parseInt(rawPid.trim(), 10);
+		if (Number.isSafeInteger(pid) && pid > 0) {
+			if (isProcessAlive(pid)) return false;
+		} else if (Date.now() - lockStat.mtimeMs <= 33e4) return false;
+		await unlink(lockPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function acquireInstallLock() {
+	const lockPath = updateInstallLockPath();
+	await mkdir(dirname(lockPath), {
+		recursive: true,
+		mode: 448
+	});
+	for (let attempt = 0; attempt < 2; attempt += 1) try {
+		const handle = await open(lockPath, "wx", 384);
+		await handle.writeFile(`${process.pid}\n`, "utf8");
+		return async () => {
+			await handle.close().catch(() => void 0);
+			await unlink(lockPath).catch(() => void 0);
+		};
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		if (attempt > 0 || !await removeStaleInstallLock(lockPath)) throw new UpdateInstallLockedError("another codemem update installation is already running");
+	}
+	throw new UpdateInstallLockedError("another codemem update installation is already running");
+}
+function runCommand(command, args, timeoutMs, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			detached: process.platform !== "win32",
+			shell: false,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			windowsVerbatimArguments: options.windowsVerbatimArguments
+		});
+		let settled = false;
+		let timedOut = false;
+		let stdout = "";
+		let stderr = "";
+		let timer;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(result);
+		};
+		const terminate = (signal) => {
+			if (process.platform === "win32" && child.pid) {
+				const systemRoot = process.env.SystemRoot?.trim();
+				if (systemRoot && isAbsolute(systemRoot)) {
+					spawnSync(join(systemRoot, "System32", "taskkill.exe"), [
+						"/PID",
+						String(child.pid),
+						"/T",
+						"/F"
+					], {
+						stdio: "ignore",
+						windowsHide: true
+					});
+					return;
+				}
+			}
+			if (process.platform !== "win32" && child.pid) try {
+				process.kill(-child.pid, signal);
+				return;
+			} catch {}
+			child.kill(signal);
+		};
+		timer = setTimeout(() => {
+			timedOut = true;
+			terminate("SIGTERM");
+			setTimeout(() => terminate("SIGKILL"), 5e3).unref();
+		}, timeoutMs);
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			if (!settled) reject(error);
+		});
+		child.once("close", (code) => finish({
+			exitCode: code ?? 1,
+			stdout,
+			stderr: timedOut ? "command timed out" : stderr
+		}));
+	});
+}
+async function resolveWindowsShim(name) {
+	const systemRoot = process.env.SystemRoot?.trim();
+	if (!systemRoot || !isAbsolute(systemRoot)) throw new Error("Windows SystemRoot is unavailable");
+	const result = await runCommand(join(systemRoot, "System32", "where.exe"), [name], 1e4, { cwd: join(systemRoot, "System32") });
+	const shim = result.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => isAbsolute(value));
+	if (result.exitCode !== 0 || !shim) throw new Error(`unable to resolve ${name} from PATH`);
+	return shim;
+}
+function windowsCommandLine(shim, args) {
+	return `""${shim}" ${args.join(" ")}"`;
+}
+async function resolveInstallCommand() {
+	if (process.platform !== "win32") return {
+		command: "npm",
+		args: []
+	};
+	const systemRoot = process.env.SystemRoot?.trim();
+	if (!systemRoot || !isAbsolute(systemRoot)) throw new Error("Windows SystemRoot is unavailable");
+	return {
+		command: join(systemRoot, "System32", "cmd.exe"),
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			await resolveWindowsShim("npm.cmd")
+		],
+		cwd: join(systemRoot, "System32")
+	};
+}
+async function resolveVerificationCommand() {
+	if (process.platform !== "win32") return {
+		command: "codemem",
+		args: []
+	};
+	const systemRoot = process.env.SystemRoot?.trim();
+	if (!systemRoot || !isAbsolute(systemRoot)) throw new Error("Windows SystemRoot is unavailable");
+	return {
+		command: join(systemRoot, "System32", "cmd.exe"),
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			await resolveWindowsShim("codemem.cmd")
+		],
+		cwd: join(systemRoot, "System32")
+	};
+}
+function failInstall(options, code, message) {
+	if (options.json) emitJsonError(code, message);
+	else {
+		console.error(message);
+		process.exitCode = 1;
+	}
+}
+function cacheQualifier(stale) {
+	return stale ? " (cached result)" : "";
+}
+function renderStatusWarning(error) {
+	return error ? ` Warning: ${error}` : "";
+}
+function renderHumanStatus(status) {
+	const warning = renderStatusWarning(status.error);
+	if (status.update_available) return `Update available${cacheQualifier(status.stale)}: ${status.current_version} → ${status.latest_version}. ${status.recommended_action}${warning}`;
+	if (!isStableReleaseVersion(status.current_version)) return `Unable to compare current version ${status.current_version} with ${status.latest_version}. ${status.recommended_action}${warning}`;
+	return `${status.current_version} is up to date${cacheQualifier(status.stale)}.${warning}`;
+}
+var checkCommand = addJsonOption(new Command("check").description("Check for a newer stable codemem release")).addOption(new Option("-r, --refresh", "bypass the six-hour release cache")).configureHelp(helpStyle).action(async (options) => {
+	try {
+		const status = await getUpdateStatus({
+			currentVersion: VERSION,
+			installKind: detectInstallKind({
+				entryPath: process.argv[1] ?? "",
+				env: process.env
+			}),
+			refresh: options.refresh
+		});
+		if (status.latest_version === null) {
+			const message = status.error ?? "release status is unavailable";
+			if (options.json) emitJsonError("update_check_unavailable", message);
+			else {
+				console.error(`Unable to check for updates: ${message}`);
+				process.exitCode = 1;
+			}
+			return;
+		}
+		if (options.json) {
+			console.log(JSON.stringify(status));
+			return;
+		}
+		console.log(renderHumanStatus(status));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "release status is unavailable";
+		if (options.json) emitJsonError("update_check_unavailable", message);
+		else {
+			console.error(`Unable to check for updates: ${message}`);
+			process.exitCode = 1;
+		}
+	}
+});
+var installCommand = addJsonOption(new Command("install").description("Install an eligible stable codemem update")).configureHelp(helpStyle).action(async (options) => {
+	let releaseInstallLock = null;
+	try {
+		const status = await getUpdateStatus({
+			currentVersion: VERSION,
+			installKind: detectInstallKind({
+				entryPath: process.argv[1] ?? "",
+				env: process.env
+			}),
+			refresh: true
+		});
+		if (!status.auto_update_eligible || !status.latest_version) {
+			failInstall(options, "update_install_refused", status.recommended_action);
+			return;
+		}
+		const targetVersion = status.latest_version;
+		if (!isStableReleaseVersion(targetVersion)) {
+			failInstall(options, "update_install_refused", "release version is not a stable semantic version");
+			return;
+		}
+		releaseInstallLock = await acquireInstallLock();
+		const npm = await resolveInstallCommand();
+		const installation = await runCommand(npm.command, process.platform === "win32" ? [...npm.args.slice(0, 3), windowsCommandLine(npm.args[3] ?? "", [
+			"install",
+			"-g",
+			"--registry",
+			PUBLIC_NPM_REGISTRY,
+			`codemem@${targetVersion}`
+		])] : [
+			"install",
+			"-g",
+			"--registry",
+			PUBLIC_NPM_REGISTRY,
+			`codemem@${targetVersion}`
+		], INSTALL_TIMEOUT_MS, {
+			cwd: npm.cwd,
+			windowsVerbatimArguments: process.platform === "win32"
+		});
+		if (installation.exitCode !== 0) {
+			failInstall(options, "update_install_failed", installation.stderr.trim() || "npm installation failed");
+			return;
+		}
+		const codemem = await resolveVerificationCommand();
+		const verification = await runCommand(codemem.command, process.platform === "win32" ? [...codemem.args.slice(0, 3), windowsCommandLine(codemem.args[3] ?? "", ["version"])] : ["version"], VERIFY_TIMEOUT_MS, {
+			cwd: codemem.cwd,
+			windowsVerbatimArguments: process.platform === "win32"
+		});
+		if (verification.exitCode !== 0 || verification.stdout.trim() !== targetVersion) {
+			failInstall(options, "update_verification_failed", "installed version verification failed");
+			return;
+		}
+		const result = {
+			previous_version: VERSION,
+			installed_version: targetVersion
+		};
+		if (options.json) console.log(JSON.stringify(result));
+		else console.log(`Updated codemem from ${VERSION} to ${targetVersion}.`);
+	} catch (error) {
+		failInstall(options, error instanceof UpdateInstallLockedError ? "update_install_locked" : "update_install_failed", error instanceof Error ? error.message : "update installation failed");
+	} finally {
+		await releaseInstallLock?.();
+	}
+});
+var updateCommand = new Command("update").description("Inspect and manage codemem updates").configureHelp(helpStyle).addCommand(checkCommand).addCommand(installCommand);
 //#endregion
 //#region src/commands/version.ts
 var versionCommand = new Command("version").configureHelp(helpStyle).description("Print codemem version").action(() => {
 	console.log(VERSION);
 });
 //#endregion
+//#region src/command-tree.ts
+/**
+* Assembled root command tree — single source of truth shared by the runtime
+* entrypoint (`index.ts`) and the command-tree parity tests.
+*
+* `index.ts` stays the only module with import-time side effects (omelette
+* completion init, `program.parse()`); everything here is side-effect free
+* until `registerRootCommands` is called.
+*/
+var ROOT_COMPLETION_COMMANDS = [
+	"claude-hook-file-context",
+	"claude-hook-inject",
+	"claude-hook-ingest",
+	"codex-hook-inject",
+	"codex-hook-ingest",
+	"config",
+	"coordinator",
+	"db",
+	"distill",
+	"embed",
+	"enqueue-raw-event",
+	"export-memories",
+	"import-memories",
+	"maintenance",
+	"mcp",
+	"memory",
+	"pack",
+	"recent",
+	"search",
+	"serve",
+	"setup",
+	"stats",
+	"status",
+	"sync",
+	"update",
+	"version",
+	"help",
+	"--help",
+	"--version"
+];
+/**
+* True when the CLI process was invoked through the named top-level
+* compatibility alias (first non-flag token of the real argv). Forwarding
+* wrappers such as `memory export` re-parse the alias command with synthetic
+* argv, so this stays false for canonical invocations.
+*/
+function invokedAsTopLevelAlias(name, argv = process.argv.slice(2)) {
+	for (const token of argv) {
+		if (token === "--") return false;
+		if (!token.startsWith("-")) return token === name;
+	}
+	return false;
+}
+function registerMemoryGroupWrappers() {
+	if (memoryCommand.commands.some((command) => command.name() === "export")) return;
+	const forwardedTail = (subcommand) => {
+		const argv = process.argv.slice(2);
+		const groupIdx = argv.indexOf("memory");
+		const searchFrom = groupIdx >= 0 ? groupIdx + 1 : 0;
+		const subIdx = argv.indexOf(subcommand, searchFrom);
+		return subIdx >= 0 ? argv.slice(subIdx + 1) : [];
+	};
+	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 () => {
+		await exportMemoriesCommand.parseAsync([
+			"node",
+			"export-memories",
+			...forwardedTail("export")
+		]);
+	});
+	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 () => {
+		await importMemoriesCommand.parseAsync([
+			"node",
+			"import-memories",
+			...forwardedTail("import")
+		]);
+	});
+	memoryCommand.addCommand(memExport);
+	memoryCommand.addCommand(memImport);
+}
+/** Register every root command (visible and hidden) on the given program. */
+function registerRootCommands(program) {
+	registerMemoryGroupWrappers();
+	program.addCommand(serveCommand);
+	program.addCommand(configCommand);
+	program.addCommand(coordinatorCommand);
+	program.addCommand(mcpCommand);
+	program.addCommand(claudeHookInjectCommand);
+	program.addCommand(claudeHookIngestCommand);
+	program.addCommand(claudeHookFileContextCommand);
+	program.addCommand(codexHookInjectCommand);
+	program.addCommand(codexHookIngestCommand);
+	program.addCommand(dbCommand);
+	program.addCommand(distillCommand);
+	program.addCommand(exportMemoriesCommand);
+	program.addCommand(importMemoriesCommand);
+	program.addCommand(statsCommand);
+	program.addCommand(statusCommand);
+	program.addCommand(maintenanceCommand);
+	program.addCommand(embedCommand);
+	program.addCommand(recentCommand);
+	program.addCommand(searchCommand);
+	program.addCommand(packCommand);
+	program.addCommand(promptPackLedgerCommand, { hidden: true });
+	program.addCommand(showMemoryCommand, { hidden: true });
+	program.addCommand(forgetMemoryCommand, { hidden: true });
+	program.addCommand(rememberMemoryCommand, { hidden: true });
+	program.addCommand(memoryCommand);
+	program.addCommand(syncCommand);
+	program.addCommand(setupCommand);
+	program.addCommand(enqueueRawEventCommand);
+	program.addCommand(updateCommand);
+	program.addCommand(versionCommand);
+	return program;
+}
+//#endregion
 //#region src/index.ts
 /**
 * @codemem/cli — CLI entry point.
@@ -8250,34 +9099,7 @@ var versionCommand = new Command("version").configureHelp(helpStyle).description
 */
 var completion = omelette("codemem <command>");
 completion.on("command", ({ reply }) => {
-	reply([
-		"claude-hook-file-context",
-		"claude-hook-inject",
-		"claude-hook-ingest",
-		"codex-hook-inject",
-		"codex-hook-ingest",
-		"config",
-		"coordinator",
-		"db",
-		"distill",
-		"embed",
-		"enqueue-raw-event",
-		"export-memories",
-		"import-memories",
-		"mcp",
-		"memory",
-		"pack",
-		"recent",
-		"search",
-		"serve",
-		"setup",
-		"stats",
-		"sync",
-		"version",
-		"help",
-		"--help",
-		"--version"
-	]);
+	reply([...ROOT_COMPLETION_COMMANDS]);
 });
 completion.init();
 function hasRootFlag(flag) {
@@ -8306,59 +9128,7 @@ if (hasRootFlag("--cleanup-completion")) {
 	completion.cleanupShellInitFile();
 	process.exit(0);
 }
-{
-	const forwardedTail = (subcommand) => {
-		const argv = process.argv.slice(2);
-		const groupIdx = argv.indexOf("memory");
-		const searchFrom = groupIdx >= 0 ? groupIdx + 1 : 0;
-		const subIdx = argv.indexOf(subcommand, searchFrom);
-		return subIdx >= 0 ? argv.slice(subIdx + 1) : [];
-	};
-	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 () => {
-		await exportMemoriesCommand.parseAsync([
-			"node",
-			"export-memories",
-			...forwardedTail("export")
-		]);
-	});
-	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 () => {
-		await importMemoriesCommand.parseAsync([
-			"node",
-			"import-memories",
-			...forwardedTail("import")
-		]);
-	});
-	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(claudeHookFileContextCommand);
-program.addCommand(codexHookInjectCommand);
-program.addCommand(codexHookIngestCommand);
-program.addCommand(dbCommand);
-program.addCommand(distillCommand);
-program.addCommand(exportMemoriesCommand);
-program.addCommand(importMemoriesCommand);
-program.addCommand(statsCommand);
-program.addCommand(maintenanceCommand);
-program.addCommand(embedCommand);
-program.addCommand(recentCommand);
-program.addCommand(searchCommand);
-program.addCommand(packCommand);
-program.addCommand(promptPackLedgerCommand, { hidden: true });
-program.addCommand(showMemoryCommand, { hidden: true });
-program.addCommand(forgetMemoryCommand, { hidden: true });
-program.addCommand(rememberMemoryCommand, { hidden: true });
-program.addCommand(memoryCommand);
-program.addCommand(syncCommand);
-program.addCommand(setupCommand);
-program.addCommand(enqueueRawEventCommand);
-program.addCommand(versionCommand);
+registerRootCommands(program);
 program.parse();
 //#endregion
 export {};