vora-ai 0.1.0

package/dist/server-startup-matrix-migration-CMLAopuE.js

@@ -0,0 +1,1255 @@
+import { m as pathExists } from "./utils-BiWzD1kh.js";
+import { n as listBundledPluginMetadata } from "./bundled-plugin-metadata-DuQVm9f5.js";
+import { r as runCommandWithTimeout } from "./exec-DNTgEe82.js";
+import { s as resolveStableNodePath } from "./runtime-paths-C22j-CNR.js";
+import { s as applyPathPrepend } from "./bootstrap-budget-lNGYv_xu.js";
+import { o as trimLogTail } from "./restart-sentinel-BEGeUiKE.js";
+import { i as autoMigrateLegacyMatrixState, n as hasPendingMatrixMigration, o as autoPrepareLegacyMatrixCrypto, r as maybeCreateMatrixMigrationSnapshot, t as hasActionableMatrixMigration } from "./matrix-migration-snapshot-BSPlCZpf.js";
+import { i as resolveControlUiDistIndexPathForRoot, r as resolveControlUiDistIndexHealth } from "./control-ui-assets-DbOOvjtb.js";
+import { a as isBetaTag, n as DEV_BRANCH, o as isStableTag, r as channelToNpmTag } from "./update-channels-d8te77R1.js";
+import { n as compareSemverStrings, s as detectPackageManager$1 } from "./update-check-DK2tfDQH.js";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+//#region src/infra/package-json.ts
+async function readPackageVersion(root) {
+	try {
+		const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+		const version = JSON.parse(raw)?.version?.trim();
+		return version ? version : null;
+	} catch {
+		return null;
+	}
+}
+async function readPackageName(root) {
+	try {
+		const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+		const name = JSON.parse(raw)?.name?.trim();
+		return name ? name : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/infra/package-tag.ts
+function normalizePackageTagInput(value, packageNames) {
+	const trimmed = value?.trim();
+	if (!trimmed) return null;
+	for (const packageName of packageNames) {
+		if (trimmed === packageName) return null;
+		const prefix = `${packageName}@`;
+		if (trimmed.startsWith(prefix)) {
+			const tag = trimmed.slice(prefix.length).trim();
+			return tag ? tag : null;
+		}
+	}
+	return trimmed;
+}
+//#endregion
+//#region src/plugins/public-artifacts.ts
+function assertUniqueValues(values, label) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const value of values) {
+		if (seen.has(value)) {
+			duplicates.add(value);
+			continue;
+		}
+		seen.add(value);
+	}
+	if (duplicates.size > 0) throw new Error(`Duplicate ${label}: ${Array.from(duplicates).join(", ")}`);
+	return values;
+}
+function getPublicArtifactBasename(relativePath) {
+	return relativePath.split("/").at(-1) ?? relativePath;
+}
+function buildBundledDistArtifactPath(dirName, artifact) {
+	return [
+		"dist",
+		"extensions",
+		dirName,
+		artifact
+	].join("/");
+}
+const BUNDLED_RUNTIME_SIDECAR_PATHS = assertUniqueValues(listBundledPluginMetadata().flatMap((entry) => (entry.runtimeSidecarArtifacts ?? []).map((artifact) => buildBundledDistArtifactPath(entry.dirName, artifact))).toSorted((left, right) => left.localeCompare(right)), "bundled runtime sidecar path");
+const EXTRA_GUARDED_EXTENSION_PUBLIC_SURFACE_BASENAMES = assertUniqueValues([
+	"action-runtime.runtime.js",
+	"action-runtime-api.js",
+	"allow-from.js",
+	"api.js",
+	"auth-presence.js",
+	"channel-config-api.js",
+	"index.js",
+	"login-qr-api.js",
+	"onboard.js",
+	"openai-codex-catalog.js",
+	"provider-catalog.js",
+	"session-key-api.js",
+	"setup-api.js",
+	"setup-entry.js",
+	"timeouts.js",
+	"x-search.js"
+], "extra guarded extension public surface basename");
+assertUniqueValues([...assertUniqueValues([...new Set(BUNDLED_RUNTIME_SIDECAR_PATHS.map(getPublicArtifactBasename))], "bundled runtime sidecar basename"), ...EXTRA_GUARDED_EXTENSION_PUBLIC_SURFACE_BASENAMES], "guarded extension public surface basename");
+//#endregion
+//#region src/infra/update-global.ts
+const PRIMARY_PACKAGE_NAME = "vora";
+const ALL_PACKAGE_NAMES = [PRIMARY_PACKAGE_NAME];
+const GLOBAL_RENAME_PREFIX = ".";
+const VORA_MAIN_PACKAGE_SPEC = "github:vora/vora#main";
+const NPM_GLOBAL_INSTALL_QUIET_FLAGS = [
+	"--no-fund",
+	"--no-audit",
+	"--loglevel=error"
+];
+const NPM_GLOBAL_INSTALL_OMIT_OPTIONAL_FLAGS = ["--omit=optional", ...NPM_GLOBAL_INSTALL_QUIET_FLAGS];
+function normalizePackageTarget(value) {
+	return value.trim();
+}
+function isMainPackageTarget(value) {
+	return normalizePackageTarget(value).toLowerCase() === "main";
+}
+function isExplicitPackageInstallSpec(value) {
+	const trimmed = normalizePackageTarget(value);
+	if (!trimmed) return false;
+	return trimmed.includes("://") || trimmed.includes("#") || /^(?:file|github|git\+ssh|git\+https|git\+http|git\+file|npm):/i.test(trimmed);
+}
+function resolveExpectedInstalledVersionFromSpec(packageName, spec) {
+	const normalizedPackageName = packageName.trim();
+	const normalizedSpec = normalizePackageTarget(spec);
+	if (!normalizedPackageName || !normalizedSpec.startsWith(`${normalizedPackageName}@`)) return null;
+	const rawVersion = normalizedSpec.slice(normalizedPackageName.length + 1).trim();
+	if (!rawVersion || rawVersion.includes("/") || rawVersion.includes(":") || rawVersion.includes("#") || /^(latest|beta|next|main)$/i.test(rawVersion)) return null;
+	return rawVersion;
+}
+async function collectInstalledGlobalPackageErrors(params) {
+	const errors = [];
+	const installedVersion = await readPackageVersion(params.packageRoot);
+	if (params.expectedVersion && installedVersion !== params.expectedVersion) errors.push(`expected installed version ${params.expectedVersion}, found ${installedVersion ?? "<missing>"}`);
+	for (const relativePath of BUNDLED_RUNTIME_SIDECAR_PATHS) if (!await pathExists(path.join(params.packageRoot, relativePath))) errors.push(`missing bundled runtime sidecar ${relativePath}`);
+	return errors;
+}
+function canResolveRegistryVersionForPackageTarget(value) {
+	const trimmed = normalizePackageTarget(value);
+	if (!trimmed) return true;
+	return !isMainPackageTarget(trimmed) && !isExplicitPackageInstallSpec(trimmed);
+}
+async function resolvePortableGitPathPrepend(env) {
+	if (process.platform !== "win32") return [];
+	const localAppData = env?.LOCALAPPDATA?.trim() || process.env.LOCALAPPDATA?.trim();
+	if (!localAppData) return [];
+	const portableGitRoot = path.join(localAppData, "Vora", "deps", "portable-git");
+	const candidates = [
+		path.join(portableGitRoot, "mingw64", "bin"),
+		path.join(portableGitRoot, "usr", "bin"),
+		path.join(portableGitRoot, "cmd"),
+		path.join(portableGitRoot, "bin")
+	];
+	const existing = [];
+	for (const candidate of candidates) if (await pathExists(candidate)) existing.push(candidate);
+	return existing;
+}
+function applyWindowsPackageInstallEnv(env) {
+	if (process.platform !== "win32") return;
+	env.NPM_CONFIG_UPDATE_NOTIFIER = "false";
+	env.NPM_CONFIG_FUND = "false";
+	env.NPM_CONFIG_AUDIT = "false";
+	env.NPM_CONFIG_SCRIPT_SHELL = "cmd.exe";
+	env.NODE_LLAMA_CPP_SKIP_DOWNLOAD = "1";
+}
+function resolveGlobalInstallSpec(params) {
+	const override = params.env?.VORA_UPDATE_PACKAGE_SPEC?.trim() || process.env.VORA_UPDATE_PACKAGE_SPEC?.trim();
+	if (override) return override;
+	const target = normalizePackageTarget(params.tag);
+	if (isMainPackageTarget(target)) return VORA_MAIN_PACKAGE_SPEC;
+	if (isExplicitPackageInstallSpec(target)) return target;
+	return `${params.packageName}@${target}`;
+}
+async function createGlobalInstallEnv(env) {
+	const pathPrepend = await resolvePortableGitPathPrepend(env);
+	if (pathPrepend.length === 0 && process.platform !== "win32") return env;
+	const merged = Object.fromEntries(Object.entries(env ?? process.env).filter(([, value]) => value != null).map(([key, value]) => [key, String(value)]));
+	applyPathPrepend(merged, pathPrepend);
+	applyWindowsPackageInstallEnv(merged);
+	return merged;
+}
+async function tryRealpath(targetPath) {
+	try {
+		return await fs.realpath(targetPath);
+	} catch {
+		return path.resolve(targetPath);
+	}
+}
+function resolveBunGlobalRoot() {
+	const bunInstall = process.env.BUN_INSTALL?.trim() || path.join(os.homedir(), ".bun");
+	return path.join(bunInstall, "install", "global", "node_modules");
+}
+async function resolveGlobalRoot(manager, runCommand, timeoutMs) {
+	if (manager === "bun") return resolveBunGlobalRoot();
+	const res = await runCommand(manager === "pnpm" ? [
+		"pnpm",
+		"root",
+		"-g"
+	] : [
+		"npm",
+		"root",
+		"-g"
+	], { timeoutMs }).catch(() => null);
+	if (!res || res.code !== 0) return null;
+	return res.stdout.trim() || null;
+}
+async function resolveGlobalPackageRoot(manager, runCommand, timeoutMs) {
+	const root = await resolveGlobalRoot(manager, runCommand, timeoutMs);
+	if (!root) return null;
+	return path.join(root, PRIMARY_PACKAGE_NAME);
+}
+async function detectGlobalInstallManagerForRoot(runCommand, pkgRoot, timeoutMs) {
+	const pkgReal = await tryRealpath(pkgRoot);
+	for (const { manager, argv } of [{
+		manager: "npm",
+		argv: [
+			"npm",
+			"root",
+			"-g"
+		]
+	}, {
+		manager: "pnpm",
+		argv: [
+			"pnpm",
+			"root",
+			"-g"
+		]
+	}]) {
+		const res = await runCommand(argv, { timeoutMs }).catch(() => null);
+		if (!res || res.code !== 0) continue;
+		const globalRoot = res.stdout.trim();
+		if (!globalRoot) continue;
+		const globalReal = await tryRealpath(globalRoot);
+		for (const name of ALL_PACKAGE_NAMES) {
+			const expectedReal = await tryRealpath(path.join(globalReal, name));
+			if (path.resolve(expectedReal) === path.resolve(pkgReal)) return manager;
+		}
+	}
+	const bunGlobalReal = await tryRealpath(resolveBunGlobalRoot());
+	for (const name of ALL_PACKAGE_NAMES) {
+		const bunExpectedReal = await tryRealpath(path.join(bunGlobalReal, name));
+		if (path.resolve(bunExpectedReal) === path.resolve(pkgReal)) return "bun";
+	}
+	return null;
+}
+async function detectGlobalInstallManagerByPresence(runCommand, timeoutMs) {
+	for (const manager of ["npm", "pnpm"]) {
+		const root = await resolveGlobalRoot(manager, runCommand, timeoutMs);
+		if (!root) continue;
+		for (const name of ALL_PACKAGE_NAMES) if (await pathExists(path.join(root, name))) return manager;
+	}
+	const bunRoot = resolveBunGlobalRoot();
+	for (const name of ALL_PACKAGE_NAMES) if (await pathExists(path.join(bunRoot, name))) return "bun";
+	return null;
+}
+function globalInstallArgs(manager, spec) {
+	if (manager === "pnpm") return [
+		"pnpm",
+		"add",
+		"-g",
+		spec
+	];
+	if (manager === "bun") return [
+		"bun",
+		"add",
+		"-g",
+		spec
+	];
+	return [
+		"npm",
+		"i",
+		"-g",
+		spec,
+		...NPM_GLOBAL_INSTALL_QUIET_FLAGS
+	];
+}
+function globalInstallFallbackArgs(manager, spec) {
+	if (manager !== "npm") return null;
+	return [
+		"npm",
+		"i",
+		"-g",
+		spec,
+		...NPM_GLOBAL_INSTALL_OMIT_OPTIONAL_FLAGS
+	];
+}
+async function cleanupGlobalRenameDirs(params) {
+	const removed = [];
+	const root = params.globalRoot.trim();
+	const name = params.packageName.trim();
+	if (!root || !name) return { removed };
+	const prefix = `${GLOBAL_RENAME_PREFIX}${name}-`;
+	let entries = [];
+	try {
+		entries = await fs.readdir(root);
+	} catch {
+		return { removed };
+	}
+	for (const entry of entries) {
+		if (!entry.startsWith(prefix)) continue;
+		const target = path.join(root, entry);
+		try {
+			if (!(await fs.lstat(target)).isDirectory()) continue;
+			await fs.rm(target, {
+				recursive: true,
+				force: true
+			});
+			removed.push(entry);
+		} catch {}
+	}
+	return { removed };
+}
+//#endregion
+//#region src/infra/update-runner.ts
+const DEFAULT_TIMEOUT_MS = 20 * 6e4;
+const MAX_LOG_CHARS = 8e3;
+const PREFLIGHT_MAX_COMMITS = 10;
+const START_DIRS = [
+	"cwd",
+	"argv1",
+	"process"
+];
+const DEFAULT_PACKAGE_NAME = "vora";
+const CORE_PACKAGE_NAMES = new Set([DEFAULT_PACKAGE_NAME]);
+function normalizeDir(value) {
+	if (!value) return null;
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	return path.resolve(trimmed);
+}
+function resolveNodeModulesBinPackageRoot(argv1) {
+	const normalized = path.resolve(argv1);
+	const parts = normalized.split(path.sep);
+	const binIndex = parts.lastIndexOf(".bin");
+	if (binIndex <= 0) return null;
+	if (parts[binIndex - 1] !== "node_modules") return null;
+	const binName = path.basename(normalized);
+	const nodeModulesDir = parts.slice(0, binIndex).join(path.sep);
+	return path.join(nodeModulesDir, binName);
+}
+function buildStartDirs(opts) {
+	const dirs = [];
+	const cwd = normalizeDir(opts.cwd);
+	if (cwd) dirs.push(cwd);
+	const argv1 = normalizeDir(opts.argv1);
+	if (argv1) {
+		dirs.push(path.dirname(argv1));
+		const packageRoot = resolveNodeModulesBinPackageRoot(argv1);
+		if (packageRoot) dirs.push(packageRoot);
+	}
+	const proc = normalizeDir(process.cwd());
+	if (proc) dirs.push(proc);
+	return Array.from(new Set(dirs));
+}
+async function readBranchName(runCommand, root, timeoutMs) {
+	const res = await runCommand([
+		"git",
+		"-C",
+		root,
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	], { timeoutMs }).catch(() => null);
+	if (!res || res.code !== 0) return null;
+	return res.stdout.trim() || null;
+}
+async function listGitTags(runCommand, root, timeoutMs, pattern = "v*") {
+	const res = await runCommand([
+		"git",
+		"-C",
+		root,
+		"tag",
+		"--list",
+		pattern,
+		"--sort=-v:refname"
+	], { timeoutMs }).catch(() => null);
+	if (!res || res.code !== 0) return [];
+	return res.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+async function resolveChannelTag(runCommand, root, timeoutMs, channel) {
+	const tags = await listGitTags(runCommand, root, timeoutMs);
+	if (channel === "beta") {
+		const betaTag = tags.find((tag) => isBetaTag(tag)) ?? null;
+		const stableTag = tags.find((tag) => isStableTag(tag)) ?? null;
+		if (!betaTag) return stableTag;
+		if (!stableTag) return betaTag;
+		const cmp = compareSemverStrings(betaTag, stableTag);
+		if (cmp != null && cmp < 0) return stableTag;
+		return betaTag;
+	}
+	return tags.find((tag) => isStableTag(tag)) ?? null;
+}
+async function resolveGitRoot(runCommand, candidates, timeoutMs) {
+	for (const dir of candidates) {
+		const res = await runCommand([
+			"git",
+			"-C",
+			dir,
+			"rev-parse",
+			"--show-toplevel"
+		], { timeoutMs }).catch(() => null);
+		if (!res) continue;
+		if (res.code === 0) {
+			const root = res.stdout.trim();
+			if (root) return root;
+		}
+	}
+	return null;
+}
+async function findPackageRoot(candidates) {
+	for (const dir of candidates) {
+		let current = dir;
+		for (let i = 0; i < 12; i += 1) {
+			const pkgPath = path.join(current, "package.json");
+			try {
+				const raw = await fs.readFile(pkgPath, "utf-8");
+				const name = JSON.parse(raw)?.name?.trim();
+				if (name && CORE_PACKAGE_NAMES.has(name)) return current;
+			} catch {}
+			const parent = path.dirname(current);
+			if (parent === current) break;
+			current = parent;
+		}
+	}
+	return null;
+}
+async function detectPackageManager(root) {
+	return await detectPackageManager$1(root) ?? "npm";
+}
+function managerPreferenceOrder(preferred) {
+	if (preferred === "pnpm") return [
+		"pnpm",
+		"npm",
+		"bun"
+	];
+	if (preferred === "bun") return [
+		"bun",
+		"npm",
+		"pnpm"
+	];
+	return [
+		"npm",
+		"pnpm",
+		"bun"
+	];
+}
+function managerVersionArgs(manager) {
+	if (manager === "pnpm") return ["pnpm", "--version"];
+	if (manager === "bun") return ["bun", "--version"];
+	return ["npm", "--version"];
+}
+async function isManagerAvailable(runCommand, manager, timeoutMs) {
+	try {
+		return (await runCommand(managerVersionArgs(manager), { timeoutMs })).code === 0;
+	} catch {
+		return false;
+	}
+}
+async function isCommandAvailable(runCommand, argv, timeoutMs) {
+	try {
+		return (await runCommand(argv, { timeoutMs })).code === 0;
+	} catch {
+		return false;
+	}
+}
+async function ensurePnpmAvailable(runCommand, timeoutMs) {
+	if (await isManagerAvailable(runCommand, "pnpm", timeoutMs)) return true;
+	if (!await isCommandAvailable(runCommand, ["corepack", "--version"], timeoutMs)) return false;
+	try {
+		if ((await runCommand(["corepack", "enable"], { timeoutMs })).code !== 0) return false;
+	} catch {
+		return false;
+	}
+	return await isManagerAvailable(runCommand, "pnpm", timeoutMs);
+}
+async function resolveAvailableManager(runCommand, root, timeoutMs) {
+	const preferred = await detectPackageManager(root);
+	if (preferred === "pnpm" && await ensurePnpmAvailable(runCommand, timeoutMs)) return {
+		manager: "pnpm",
+		fallback: false
+	};
+	for (const manager of managerPreferenceOrder(preferred)) if (await isManagerAvailable(runCommand, manager, timeoutMs)) return {
+		manager,
+		fallback: manager !== preferred
+	};
+	return {
+		manager: "npm",
+		fallback: preferred !== "npm"
+	};
+}
+async function runStep(opts) {
+	const { runCommand, name, argv, cwd, timeoutMs, env, progress, stepIndex, totalSteps } = opts;
+	const command = argv.join(" ");
+	const stepInfo = {
+		name,
+		command,
+		index: stepIndex,
+		total: totalSteps
+	};
+	progress?.onStepStart?.(stepInfo);
+	const started = Date.now();
+	const result = await runCommand(argv, {
+		cwd,
+		timeoutMs,
+		env
+	});
+	const durationMs = Date.now() - started;
+	const stderrTail = trimLogTail(result.stderr, MAX_LOG_CHARS);
+	progress?.onStepComplete?.({
+		...stepInfo,
+		durationMs,
+		exitCode: result.code,
+		stderrTail
+	});
+	return {
+		name,
+		command,
+		cwd,
+		durationMs,
+		exitCode: result.code,
+		stdoutTail: trimLogTail(result.stdout, MAX_LOG_CHARS),
+		stderrTail: trimLogTail(result.stderr, MAX_LOG_CHARS)
+	};
+}
+function managerScriptArgs(manager, script, args = []) {
+	if (manager === "pnpm") return [
+		"pnpm",
+		script,
+		...args
+	];
+	if (manager === "bun") return [
+		"bun",
+		"run",
+		script,
+		...args
+	];
+	if (args.length > 0) return [
+		"npm",
+		"run",
+		script,
+		"--",
+		...args
+	];
+	return [
+		"npm",
+		"run",
+		script
+	];
+}
+function managerInstallArgs(manager, opts) {
+	if (manager === "pnpm") return ["pnpm", "install"];
+	if (manager === "bun") return ["bun", "install"];
+	if (opts?.compatFallback) return [
+		"npm",
+		"install",
+		"--no-package-lock",
+		"--legacy-peer-deps"
+	];
+	return ["npm", "install"];
+}
+function normalizeTag(tag) {
+	return normalizePackageTagInput(tag, ["vora", DEFAULT_PACKAGE_NAME]) ?? "latest";
+}
+function mergeCommandEnvironments(baseEnv, overrideEnv) {
+	if (!baseEnv) return overrideEnv;
+	if (!overrideEnv) return baseEnv;
+	return {
+		...baseEnv,
+		...overrideEnv
+	};
+}
+async function runGatewayUpdate(opts = {}) {
+	const startedAt = Date.now();
+	const defaultCommandEnv = await createGlobalInstallEnv();
+	const runCommand = opts.runCommand ?? (async (argv, options) => {
+		const res = await runCommandWithTimeout(argv, {
+			...options,
+			env: mergeCommandEnvironments(defaultCommandEnv, options.env)
+		});
+		return {
+			stdout: res.stdout,
+			stderr: res.stderr,
+			code: res.code
+		};
+	});
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const progress = opts.progress;
+	const steps = [];
+	const candidates = buildStartDirs(opts);
+	let stepIndex = 0;
+	let gitTotalSteps = 0;
+	const step = (name, argv, cwd, env) => {
+		const currentIndex = stepIndex;
+		stepIndex += 1;
+		return {
+			runCommand,
+			name,
+			argv,
+			cwd,
+			timeoutMs,
+			env,
+			progress,
+			stepIndex: currentIndex,
+			totalSteps: gitTotalSteps
+		};
+	};
+	const pkgRoot = await findPackageRoot(candidates);
+	let gitRoot = await resolveGitRoot(runCommand, candidates, timeoutMs);
+	if (gitRoot && pkgRoot && path.resolve(gitRoot) !== path.resolve(pkgRoot)) gitRoot = null;
+	if (gitRoot && !pkgRoot) return {
+		status: "error",
+		mode: "unknown",
+		root: gitRoot,
+		reason: "not-vora-root",
+		steps: [],
+		durationMs: Date.now() - startedAt
+	};
+	if (gitRoot && pkgRoot && path.resolve(gitRoot) === path.resolve(pkgRoot)) {
+		const beforeSha = (await runCommand([
+			"git",
+			"-C",
+			gitRoot,
+			"rev-parse",
+			"HEAD"
+		], {
+			cwd: gitRoot,
+			timeoutMs
+		})).stdout.trim() || null;
+		const beforeVersion = await readPackageVersion(gitRoot);
+		const channel = opts.channel ?? "dev";
+		const branch = channel === "dev" ? await readBranchName(runCommand, gitRoot, timeoutMs) : null;
+		const needsCheckoutMain = channel === "dev" && branch !== "main";
+		gitTotalSteps = channel === "dev" ? needsCheckoutMain ? 11 : 10 : 9;
+		const buildGitErrorResult = (reason) => ({
+			status: "error",
+			mode: "git",
+			root: gitRoot,
+			reason,
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		});
+		const runGitCheckoutOrFail = async (name, argv) => {
+			const checkoutStep = await runStep(step(name, argv, gitRoot));
+			steps.push(checkoutStep);
+			if (checkoutStep.exitCode !== 0) return buildGitErrorResult("checkout-failed");
+			return null;
+		};
+		const statusCheck = await runStep(step("clean check", [
+			"git",
+			"-C",
+			gitRoot,
+			"status",
+			"--porcelain",
+			"--",
+			":!dist/control-ui/"
+		], gitRoot));
+		steps.push(statusCheck);
+		if (statusCheck.stdoutTail && statusCheck.stdoutTail.trim().length > 0) return {
+			status: "skipped",
+			mode: "git",
+			root: gitRoot,
+			reason: "dirty",
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+		if (channel === "dev") {
+			if (needsCheckoutMain) {
+				const failure = await runGitCheckoutOrFail(`git checkout ${DEV_BRANCH}`, [
+					"git",
+					"-C",
+					gitRoot,
+					"checkout",
+					DEV_BRANCH
+				]);
+				if (failure) return failure;
+			}
+			const upstreamStep = await runStep(step("upstream check", [
+				"git",
+				"-C",
+				gitRoot,
+				"rev-parse",
+				"--abbrev-ref",
+				"--symbolic-full-name",
+				"@{upstream}"
+			], gitRoot));
+			steps.push(upstreamStep);
+			if (upstreamStep.exitCode !== 0) return {
+				status: "skipped",
+				mode: "git",
+				root: gitRoot,
+				reason: "no-upstream",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const fetchStep = await runStep(step("git fetch", [
+				"git",
+				"-C",
+				gitRoot,
+				"fetch",
+				"--all",
+				"--prune",
+				"--tags"
+			], gitRoot));
+			steps.push(fetchStep);
+			const upstreamShaStep = await runStep(step("git rev-parse @{upstream}", [
+				"git",
+				"-C",
+				gitRoot,
+				"rev-parse",
+				"@{upstream}"
+			], gitRoot));
+			steps.push(upstreamShaStep);
+			const upstreamSha = upstreamShaStep.stdoutTail?.trim();
+			if (!upstreamShaStep.stdoutTail || !upstreamSha) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "no-upstream-sha",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const revListStep = await runStep(step("git rev-list", [
+				"git",
+				"-C",
+				gitRoot,
+				"rev-list",
+				`--max-count=${PREFLIGHT_MAX_COMMITS}`,
+				upstreamSha
+			], gitRoot));
+			steps.push(revListStep);
+			if (revListStep.exitCode !== 0) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "preflight-revlist-failed",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const candidates = (revListStep.stdoutTail ?? "").split("\n").map((line) => line.trim()).filter(Boolean);
+			if (candidates.length === 0) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "preflight-no-candidates",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const manager = await resolveAvailableManager(runCommand, gitRoot, timeoutMs);
+			const preflightRoot = await fs.mkdtemp(path.join(os.tmpdir(), "vora-update-preflight-"));
+			const worktreeDir = path.join(preflightRoot, "worktree");
+			const worktreeStep = await runStep(step("preflight worktree", [
+				"git",
+				"-C",
+				gitRoot,
+				"worktree",
+				"add",
+				"--detach",
+				worktreeDir,
+				upstreamSha
+			], gitRoot));
+			steps.push(worktreeStep);
+			if (worktreeStep.exitCode !== 0) {
+				await fs.rm(preflightRoot, {
+					recursive: true,
+					force: true
+				}).catch(() => {});
+				return {
+					status: "error",
+					mode: "git",
+					root: gitRoot,
+					reason: "preflight-worktree-failed",
+					before: {
+						sha: beforeSha,
+						version: beforeVersion
+					},
+					steps,
+					durationMs: Date.now() - startedAt
+				};
+			}
+			let selectedSha = null;
+			try {
+				for (const sha of candidates) {
+					const shortSha = sha.slice(0, 8);
+					const checkoutStep = await runStep(step(`preflight checkout (${shortSha})`, [
+						"git",
+						"-C",
+						worktreeDir,
+						"checkout",
+						"--detach",
+						sha
+					], worktreeDir));
+					steps.push(checkoutStep);
+					if (checkoutStep.exitCode !== 0) continue;
+					const depsStep = await runStep(step(`preflight deps install (${shortSha})`, managerInstallArgs(manager.manager, { compatFallback: manager.fallback && manager.manager === "npm" }), worktreeDir));
+					steps.push(depsStep);
+					if (depsStep.exitCode !== 0) continue;
+					const buildStep = await runStep(step(`preflight build (${shortSha})`, managerScriptArgs(manager.manager, "build"), worktreeDir));
+					steps.push(buildStep);
+					if (buildStep.exitCode !== 0) continue;
+					const lintStep = await runStep(step(`preflight lint (${shortSha})`, managerScriptArgs(manager.manager, "lint"), worktreeDir));
+					steps.push(lintStep);
+					if (lintStep.exitCode !== 0) continue;
+					selectedSha = sha;
+					break;
+				}
+			} finally {
+				const removeStep = await runStep(step("preflight cleanup", [
+					"git",
+					"-C",
+					gitRoot,
+					"worktree",
+					"remove",
+					"--force",
+					worktreeDir
+				], gitRoot));
+				steps.push(removeStep);
+				await runCommand([
+					"git",
+					"-C",
+					gitRoot,
+					"worktree",
+					"prune"
+				], {
+					cwd: gitRoot,
+					timeoutMs
+				}).catch(() => null);
+				await fs.rm(preflightRoot, {
+					recursive: true,
+					force: true
+				}).catch(() => {});
+			}
+			if (!selectedSha) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "preflight-no-good-commit",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const rebaseStep = await runStep(step("git rebase", [
+				"git",
+				"-C",
+				gitRoot,
+				"rebase",
+				selectedSha
+			], gitRoot));
+			steps.push(rebaseStep);
+			if (rebaseStep.exitCode !== 0) {
+				const abortResult = await runCommand([
+					"git",
+					"-C",
+					gitRoot,
+					"rebase",
+					"--abort"
+				], {
+					cwd: gitRoot,
+					timeoutMs
+				});
+				steps.push({
+					name: "git rebase --abort",
+					command: "git rebase --abort",
+					cwd: gitRoot,
+					durationMs: 0,
+					exitCode: abortResult.code,
+					stdoutTail: trimLogTail(abortResult.stdout, MAX_LOG_CHARS),
+					stderrTail: trimLogTail(abortResult.stderr, MAX_LOG_CHARS)
+				});
+				return {
+					status: "error",
+					mode: "git",
+					root: gitRoot,
+					reason: "rebase-failed",
+					before: {
+						sha: beforeSha,
+						version: beforeVersion
+					},
+					steps,
+					durationMs: Date.now() - startedAt
+				};
+			}
+		} else {
+			const fetchStep = await runStep(step("git fetch", [
+				"git",
+				"-C",
+				gitRoot,
+				"fetch",
+				"--all",
+				"--prune",
+				"--tags"
+			], gitRoot));
+			steps.push(fetchStep);
+			if (fetchStep.exitCode !== 0) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "fetch-failed",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const tag = await resolveChannelTag(runCommand, gitRoot, timeoutMs, channel);
+			if (!tag) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "no-release-tag",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const failure = await runGitCheckoutOrFail(`git checkout ${tag}`, [
+				"git",
+				"-C",
+				gitRoot,
+				"checkout",
+				"--detach",
+				tag
+			]);
+			if (failure) return failure;
+		}
+		const manager = await resolveAvailableManager(runCommand, gitRoot, timeoutMs);
+		const depsStep = await runStep(step("deps install", managerInstallArgs(manager.manager, { compatFallback: manager.fallback && manager.manager === "npm" }), gitRoot));
+		steps.push(depsStep);
+		if (depsStep.exitCode !== 0) return {
+			status: "error",
+			mode: "git",
+			root: gitRoot,
+			reason: "deps-install-failed",
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+		const buildStep = await runStep(step("build", managerScriptArgs(manager.manager, "build"), gitRoot));
+		steps.push(buildStep);
+		if (buildStep.exitCode !== 0) return {
+			status: "error",
+			mode: "git",
+			root: gitRoot,
+			reason: "build-failed",
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+		const uiBuildStep = await runStep(step("ui:build", managerScriptArgs(manager.manager, "ui:build"), gitRoot));
+		steps.push(uiBuildStep);
+		if (uiBuildStep.exitCode !== 0) return {
+			status: "error",
+			mode: "git",
+			root: gitRoot,
+			reason: "ui-build-failed",
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+		const doctorEntry = path.join(gitRoot, "vora.mjs");
+		if (!await fs.stat(doctorEntry).then(() => true).catch(() => false)) {
+			steps.push({
+				name: "vora doctor entry",
+				command: `verify ${doctorEntry}`,
+				cwd: gitRoot,
+				durationMs: 0,
+				exitCode: 1,
+				stderrTail: `missing ${doctorEntry}`
+			});
+			return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: "doctor-entry-missing",
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+		}
+		const doctorStep = await runStep(step("vora doctor", [
+			await resolveStableNodePath(process.execPath),
+			doctorEntry,
+			"doctor",
+			"--non-interactive",
+			"--fix"
+		], gitRoot, { VORA_UPDATE_IN_PROGRESS: "1" }));
+		steps.push(doctorStep);
+		if (!(await resolveControlUiDistIndexHealth({ root: gitRoot })).exists) {
+			const repairArgv = managerScriptArgs(manager.manager, "ui:build");
+			const started = Date.now();
+			const repairResult = await runCommand(repairArgv, {
+				cwd: gitRoot,
+				timeoutMs
+			});
+			const repairStep = {
+				name: "ui:build (post-doctor repair)",
+				command: repairArgv.join(" "),
+				cwd: gitRoot,
+				durationMs: Date.now() - started,
+				exitCode: repairResult.code,
+				stdoutTail: trimLogTail(repairResult.stdout, MAX_LOG_CHARS),
+				stderrTail: trimLogTail(repairResult.stderr, MAX_LOG_CHARS)
+			};
+			steps.push(repairStep);
+			if (repairResult.code !== 0) return {
+				status: "error",
+				mode: "git",
+				root: gitRoot,
+				reason: repairStep.name,
+				before: {
+					sha: beforeSha,
+					version: beforeVersion
+				},
+				steps,
+				durationMs: Date.now() - startedAt
+			};
+			const repairedUiIndexHealth = await resolveControlUiDistIndexHealth({ root: gitRoot });
+			if (!repairedUiIndexHealth.exists) {
+				const uiIndexPath = repairedUiIndexHealth.indexPath ?? resolveControlUiDistIndexPathForRoot(gitRoot);
+				steps.push({
+					name: "ui assets verify",
+					command: `verify ${uiIndexPath}`,
+					cwd: gitRoot,
+					durationMs: 0,
+					exitCode: 1,
+					stderrTail: `missing ${uiIndexPath}`
+				});
+				return {
+					status: "error",
+					mode: "git",
+					root: gitRoot,
+					reason: "ui-assets-missing",
+					before: {
+						sha: beforeSha,
+						version: beforeVersion
+					},
+					steps,
+					durationMs: Date.now() - startedAt
+				};
+			}
+		}
+		const failedStep = steps.find((s) => s.exitCode !== 0);
+		const afterShaStep = await runStep(step("git rev-parse HEAD (after)", [
+			"git",
+			"-C",
+			gitRoot,
+			"rev-parse",
+			"HEAD"
+		], gitRoot));
+		steps.push(afterShaStep);
+		const afterVersion = await readPackageVersion(gitRoot);
+		return {
+			status: failedStep ? "error" : "ok",
+			mode: "git",
+			root: gitRoot,
+			reason: failedStep ? failedStep.name : void 0,
+			before: {
+				sha: beforeSha,
+				version: beforeVersion
+			},
+			after: {
+				sha: afterShaStep.stdoutTail?.trim() ?? null,
+				version: afterVersion
+			},
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+	}
+	if (!pkgRoot) return {
+		status: "error",
+		mode: "unknown",
+		reason: `no root (${START_DIRS.join(",")})`,
+		steps: [],
+		durationMs: Date.now() - startedAt
+	};
+	const beforeVersion = await readPackageVersion(pkgRoot);
+	const globalManager = await detectGlobalInstallManagerForRoot(runCommand, pkgRoot, timeoutMs);
+	if (globalManager) {
+		const packageName = await readPackageName(pkgRoot) ?? DEFAULT_PACKAGE_NAME;
+		await cleanupGlobalRenameDirs({
+			globalRoot: path.dirname(pkgRoot),
+			packageName
+		});
+		const channel = opts.channel ?? "stable";
+		const tag = normalizeTag(opts.tag ?? channelToNpmTag(channel));
+		const steps = [];
+		const globalInstallEnv = await createGlobalInstallEnv();
+		const spec = resolveGlobalInstallSpec({
+			packageName,
+			tag,
+			env: globalInstallEnv
+		});
+		const updateStep = await runStep({
+			runCommand,
+			name: "global update",
+			argv: globalInstallArgs(globalManager, spec),
+			cwd: pkgRoot,
+			timeoutMs,
+			env: globalInstallEnv,
+			progress,
+			stepIndex: 0,
+			totalSteps: 1
+		});
+		steps.push(updateStep);
+		let finalStep = updateStep;
+		if (updateStep.exitCode !== 0) {
+			const fallbackArgv = globalInstallFallbackArgs(globalManager, spec);
+			if (fallbackArgv) {
+				const fallbackStep = await runStep({
+					runCommand,
+					name: "global update (omit optional)",
+					argv: fallbackArgv,
+					cwd: pkgRoot,
+					timeoutMs,
+					env: globalInstallEnv,
+					progress,
+					stepIndex: 0,
+					totalSteps: 1
+				});
+				steps.push(fallbackStep);
+				finalStep = fallbackStep;
+			}
+		}
+		const verifiedPackageRoot = await resolveGlobalPackageRoot(globalManager, runCommand, timeoutMs) ?? pkgRoot;
+		const verificationErrors = await collectInstalledGlobalPackageErrors({
+			packageRoot: verifiedPackageRoot,
+			expectedVersion: resolveExpectedInstalledVersionFromSpec(packageName, spec)
+		});
+		if (verificationErrors.length > 0) steps.push({
+			name: "global install verify",
+			command: `verify ${verifiedPackageRoot}`,
+			cwd: verifiedPackageRoot,
+			durationMs: 0,
+			exitCode: 1,
+			stderrTail: verificationErrors.join("\n")
+		});
+		const afterVersion = await readPackageVersion(verifiedPackageRoot);
+		const failedStep = finalStep.exitCode !== 0 ? finalStep : steps.find((step) => step.name === "global install verify" && step.exitCode !== 0) ?? null;
+		return {
+			status: failedStep ? "error" : "ok",
+			mode: globalManager,
+			root: verifiedPackageRoot,
+			reason: failedStep ? failedStep.name : void 0,
+			before: { version: beforeVersion },
+			after: { version: afterVersion },
+			steps,
+			durationMs: Date.now() - startedAt
+		};
+	}
+	return {
+		status: "skipped",
+		mode: "unknown",
+		root: pkgRoot,
+		reason: "not-git-install",
+		before: { version: beforeVersion },
+		steps: [],
+		durationMs: Date.now() - startedAt
+	};
+}
+//#endregion
+//#region src/gateway/server-startup-matrix-migration.ts
+async function runBestEffortMatrixMigrationStep(params) {
+	try {
+		await params.run();
+	} catch (err) {
+		params.log.warn?.(`${params.logPrefix?.trim() || "gateway"}: ${params.label} failed during Matrix migration; continuing startup: ${String(err)}`);
+	}
+}
+async function runStartupMatrixMigration(params) {
+	const env = params.env ?? process.env;
+	const createSnapshot = params.deps?.maybeCreateMatrixMigrationSnapshot ?? maybeCreateMatrixMigrationSnapshot;
+	const migrateLegacyState = params.deps?.autoMigrateLegacyMatrixState ?? autoMigrateLegacyMatrixState;
+	const prepareLegacyCrypto = params.deps?.autoPrepareLegacyMatrixCrypto ?? autoPrepareLegacyMatrixCrypto;
+	const trigger = params.trigger?.trim() || "gateway-startup";
+	const logPrefix = params.logPrefix?.trim() || "gateway";
+	const actionable = hasActionableMatrixMigration({
+		cfg: params.cfg,
+		env
+	});
+	if (!(actionable || hasPendingMatrixMigration({
+		cfg: params.cfg,
+		env
+	}))) return;
+	if (!actionable) {
+		params.log.info?.("matrix: migration remains in a warning-only state; no pre-migration snapshot was needed yet");
+		return;
+	}
+	try {
+		await createSnapshot({
+			trigger,
+			env,
+			log: params.log
+		});
+	} catch (err) {
+		params.log.warn?.(`${logPrefix}: failed creating a Matrix migration snapshot; skipping Matrix migration for now: ${String(err)}`);
+		return;
+	}
+	await runBestEffortMatrixMigrationStep({
+		label: "legacy Matrix state migration",
+		log: params.log,
+		logPrefix,
+		run: () => migrateLegacyState({
+			cfg: params.cfg,
+			env,
+			log: params.log
+		})
+	});
+	await runBestEffortMatrixMigrationStep({
+		label: "legacy Matrix encrypted-state preparation",
+		log: params.log,
+		logPrefix,
+		run: () => prepareLegacyCrypto({
+			cfg: params.cfg,
+			env,
+			log: params.log
+		})
+	});
+}
+//#endregion
+export { collectInstalledGlobalPackageErrors as a, detectGlobalInstallManagerForRoot as c, resolveGlobalInstallSpec as d, resolveGlobalPackageRoot as f, readPackageVersion as h, cleanupGlobalRenameDirs as i, globalInstallArgs as l, readPackageName as m, runGatewayUpdate as n, createGlobalInstallEnv as o, normalizePackageTagInput as p, canResolveRegistryVersionForPackageTarget as r, detectGlobalInstallManagerByPresence as s, runStartupMatrixMigration as t, resolveExpectedInstalledVersionFromSpec as u };