@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/dist/account-alias-DOHN1RSH.js

@@ -0,0 +1,973 @@
+import { h as ReviewCliInstallStampSchema } from "./src-DnwdaQ2r.js";
+import { G as readStoreAuth, Z as StoreClient } from "./review-agent-traces-DNJFYzc8.js";
+import { A as devReviewHome, N as writeFileAtomicAsync, O as withFileLock, P as writePrivateJsonAtomic } from "./s3-config-CAxhO9u_.js";
+import { B as installHarnessHooks, C as disableTraceMachine, E as traceMachineStatus, F as listTraceRepositoryRoots, G as traceScope, I as traceRepositoryStatus, N as disableAllTraceRepositories, P as enableTraceRepository, R as AGENT_TRACE_HOOK_AGENTS, S as configureTraceMachine, T as traceMachineEnabled, V as removeAgentTraceHook, n as reviewDesktopStateDir, z as describeTraceHookOwners } from "./review-home-paths-6zZH-1c9.js";
+import { i as readReviewPackageVersion } from "./package-paths-B6-zxvIO.js";
+import { n as isFile, t as isDirectory } from "./fs-utils-BMPLt0cr.js";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, lstat, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { valid } from "semver";
+//#region src/cursor-deeplink.ts
+/** Cursor's one-click MCP install link for Whiteboard's server. */
+function cursorInstallDeeplink(launch) {
+	const config = Buffer.from(JSON.stringify({
+		command: launch.command,
+		args: launch.args
+	})).toString("base64");
+	return `cursor://anysphere.cursor-deeplink/mcp/install?name=whiteboard&config=${encodeURIComponent(config)}`;
+}
+//#endregion
+//#region src/connect-prompts.ts
+/** The macOS and Linux launch form; the Claude and Cursor plugins must match it byte for byte, and the Codex plugin's bin/whiteboard-mcp runs the same command. */
+const REVIEW_MCP_LAUNCH = {
+	command: "sh",
+	args: ["-c", "exec \"$HOME/.local/bin/whiteboard\" mcp"]
+};
+/**
+* Windows has no sh, and Node-based harnesses cannot start a .cmd file
+* directly. cmd finds whiteboard.cmd on PATH, whether the first-run step or
+* the installer put it there.
+*/
+const WINDOWS_MCP_LAUNCH = {
+	command: "cmd",
+	args: [
+		"/d",
+		"/c",
+		"whiteboard",
+		"mcp"
+	]
+};
+const FFF_INSTALL_URL = "https://raw.githubusercontent.com/dmtrKovalenko/fff/v0.11.0/install-mcp.sh";
+const PI_FFF_PACKAGE = "npm:@ff-labs/pi-fff";
+const PI_WHITEBOARD_PACKAGE = "npm:@dev.fast/pi-whiteboard";
+function reviewMcpLaunch(hasShim, platform = process.platform) {
+	if (platform === "win32") return {
+		command: WINDOWS_MCP_LAUNCH.command,
+		args: [...WINDOWS_MCP_LAUNCH.args]
+	};
+	return hasShim ? {
+		command: REVIEW_MCP_LAUNCH.command,
+		args: [...REVIEW_MCP_LAUNCH.args]
+	} : {
+		command: "whiteboard",
+		args: ["mcp"]
+	};
+}
+function shellQuote(value) {
+	return "'" + value.replaceAll("'", "'\"'\"'") + "'";
+}
+function numbered(steps) {
+	return steps.map((step, index) => `${index + 1}. ${step}`);
+}
+function fffSteps(input, target) {
+	if (!input.traceEnabled) return [];
+	if (target === "pi" || target === "omp") return [`Run: ${target} install ${PI_FFF_PACKAGE}`];
+	const binary = shellQuote(input.fffBinaryPath);
+	const root = shellQuote(input.fffCorpusRoot);
+	return [`Unless \`${target} mcp get fff\` finds an existing server, run:\n\n\`\`\`sh\n[ -x ${binary} ] || curl -fsSL ${FFF_INSTALL_URL} | bash\n${target === "claude" ? "claude mcp add -s user" : "codex mcp add"} fff -- ${binary} ${root}\n\`\`\``];
+}
+/** The Claude plugin's sh launch cannot start on Windows, so register the server directly. */
+const CLAUDE_WINDOWS_MCP_ADD = `claude mcp add -s user whiteboard -- ${WINDOWS_MCP_LAUNCH.command} ${WINDOWS_MCP_LAUNCH.args.join(" ")}`;
+/** Copilot CLI loads the Claude plugin, so on Windows it too registers the server directly. */
+const COPILOT_WINDOWS_MCP_ADD = `copilot mcp add whiteboard -- ${WINDOWS_MCP_LAUNCH.command} ${WINDOWS_MCP_LAUNCH.args.join(" ")}`;
+function pluginSteps(target, platform) {
+	switch (target) {
+		case "claude":
+			if (platform === "win32") return [`Run:\n\n\`\`\`sh\nclaude plugin uninstall whiteboard@devfast # its launch cannot start on Windows, if installed\nclaude mcp remove -s user whiteboard # old registration, if any\n${CLAUDE_WINDOWS_MCP_ADD}\n\`\`\``];
+			return ["Run:\n\n```sh\nclaude plugin marketplace add devdotfast/whiteboard\nclaude plugin install whiteboard@devfast --scope user\nclaude mcp remove -s user whiteboard # old manual registration, if any\n```"];
+		case "codex": return ["Run:\n\n```sh\ncodex plugin marketplace add devdotfast/whiteboard\ncodex plugin add whiteboard@devfast\ncodex mcp remove whiteboard # old manual registration, if any\n```"];
+		case "opencode": {
+			const launch = reviewMcpLaunch(true, platform);
+			const entry = JSON.stringify({ whiteboard: {
+				type: "local",
+				command: [launch.command, ...launch.args]
+			} }, null, 2);
+			return [`On OpenCode 2.0 or later, run:\n\n\`\`\`sh\nopencode mcp add --global whiteboard -- ${launchCommand(launch)}\n\`\`\`\n\nOn older OpenCode, add this entry to "mcp" in ~/.config/opencode/opencode.json, keeping the rest of the file:\n\n\`\`\`json\n${entry}\n\`\`\``, `Remove "@dev.fast/opencode-whiteboard" from "plugin" in ~/.config/opencode/opencode.json if it is there.`];
+		}
+		case "copilot":
+			if (platform === "win32") return [`Run:\n\n\`\`\`sh\ncopilot plugin uninstall whiteboard@devfast # its launch cannot start on Windows, if installed\ncopilot mcp remove whiteboard # old registration, if any\n${COPILOT_WINDOWS_MCP_ADD}\n\`\`\``];
+			return ["Run:\n\n```sh\ncopilot plugin marketplace add devdotfast/whiteboard\ncopilot plugin install whiteboard@devfast\ncopilot mcp remove whiteboard # old manual registration, if any\n```"];
+		case "pi": return [`On Pi 0.99.0 or later, run:\n\n\`\`\`sh\npi mcp add whiteboard -- ${launchCommand(reviewMcpLaunch(true, platform))}\npi remove ${PI_WHITEBOARD_PACKAGE} # if installed\n\`\`\`\n\nOn older Pi, run \`pi install ${PI_WHITEBOARD_PACKAGE}\`.`];
+		case "omp": return [`Add this entry to mcpServers in ~/.omp/agent/mcp.json, keeping the rest of the file:\n\n\`\`\`json\n${JSON.stringify({ whiteboard: reviewMcpLaunch(true, platform) }, null, 2)}\n\`\`\``, `Run \`omp plugin uninstall @dev.fast/pi-whiteboard\` if installed.`];
+	}
+}
+function launchCommand(launch) {
+	return [launch.command, ...launch.args].map((arg) => /^[\w./-]+$/.test(arg) ? arg : shellQuote(arg)).join(" ");
+}
+function cursorSteps() {
+	const launch = reviewMcpLaunch(true);
+	const deeplink = cursorInstallDeeplink(launch);
+	const entry = JSON.stringify({ whiteboard: launch }, null, 2);
+	return [`Do not paste the install link in chat. Chat clients do not open cursor:// links. Open Cursor's MCP install deeplink with the OS URL handler using the command for this operating system, then stop and let me confirm the install:\n\nmacOS: open ${shellQuote(deeplink)}\nLinux: xdg-open ${shellQuote(deeplink)}\nWindows: cmd /c start "" "${deeplink}"`, `After I confirm, check for a whiteboard server in ~/.cursor/mcp.json. If the deeplink did not add it, merge this entry into the file's mcpServers object without removing other servers or settings (create the file and object if missing). Do not use this fallback if I declined the install:\n\n\`\`\`json\n${entry}\n\`\`\``];
+}
+function connectPrompt(target, input) {
+	if (!input.hasShim) return "Connect this agent to dev.fast Whiteboard.\n\nStop and ask me to install the whiteboard command in Whiteboard Desktop (Settings → Command line), then run this connect command again. The connection requires ~/.local/bin/whiteboard.";
+	const extra = target === "claude" || target === "codex" || target === "pi" || target === "omp" ? fffSteps(input, target) : [];
+	const verify = target === "pi" ? "Ask me to run /reload, then call `session_get_instructions` on the Whiteboard server (older Pi: `whiteboard api session_get_instructions '{}'`). Do not author anything yet." : target === "omp" ? "Ask me to run /mcp reload, then call `session_get_instructions` on the Whiteboard server. Do not author anything yet." : target === "opencode" ? "Stop and tell me to quit and reopen OpenCode: it loads MCP servers only at startup. After I reopen it, call `session_get_instructions` on the Whiteboard server to confirm the connection. Do not author anything yet." : "Reload your MCP tools and call `session_get_instructions` on the Whiteboard server. If a restart is needed, tell me and verify after it. Do not author anything yet.";
+	return [
+		"Connect this agent to dev.fast Whiteboard.",
+		"",
+		...numbered([
+			...input.legacyPaths.length ? [`Delete these old Whiteboard skill folders and plugin files:\n${input.legacyPaths.map((item) => `- ${JSON.stringify(item)}`).join("\n")}`] : [],
+			...target === "cursor" ? cursorSteps() : [...pluginSteps(target, input.platform ?? process.platform), ...extra],
+			verify
+		])
+	].join("\n");
+}
+function connectSetupPrompt(target) {
+	return `Run \`whiteboard connect ${target}\` and follow the instructions to connect this agent to Whiteboard.`;
+}
+function connectSetupPrompts() {
+	return {
+		claude: connectSetupPrompt("claude"),
+		codex: connectSetupPrompt("codex"),
+		cursor: connectSetupPrompt("cursor"),
+		opencode: connectSetupPrompt("opencode"),
+		pi: connectSetupPrompt("pi"),
+		omp: connectSetupPrompt("omp"),
+		copilot: connectSetupPrompt("copilot")
+	};
+}
+function connectPrompts(input) {
+	return {
+		claude: connectPrompt("claude", input),
+		codex: connectPrompt("codex", input),
+		cursor: connectPrompt("cursor", input),
+		opencode: connectPrompt("opencode", input),
+		pi: connectPrompt("pi", input),
+		omp: connectPrompt("omp", input),
+		copilot: connectPrompt("copilot", input)
+	};
+}
+//#endregion
+//#region src/legacy-skills.ts
+const LEGACY_SKILL_NAMES = [
+	"whiteboard",
+	"dev-review",
+	"dev-review-batch",
+	"dev-file-lenses",
+	"scratchpad",
+	"trace-archaeology",
+	"dev-review-map",
+	"review",
+	"review-map",
+	"review-stop",
+	"progressive-review",
+	"pr-review"
+];
+function legacySkillRoots(homeDir) {
+	return [
+		path.join(homeDir, ".claude", "skills"),
+		path.join(homeDir, ".cursor", "skills"),
+		path.join(homeDir, ".config", "opencode", "skills"),
+		path.join(homeDir, ".agents", "skills")
+	];
+}
+/**
+* True only for a real skill directory (never a symlink to someone else's)
+* holding a regular SKILL.md whose frontmatter Review Desktop wrote.
+*/
+async function isReviewStamped(skillDir) {
+	const file = path.join(skillDir, "SKILL.md");
+	try {
+		if (!(await lstat(skillDir)).isDirectory()) return false;
+		if (!(await lstat(file)).isFile()) return false;
+	} catch {
+		return false;
+	}
+	const source = await readTextOrUndefined(file);
+	if (source === void 0) return false;
+	const metadata = (/^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1])?.match(/^metadata:\r?\n((?:[ \t]+[^\n]*(?:\n|$))*)/m)?.[1];
+	if (!metadata || !(/^  review-managed-by: "Review Desktop"\r?$/m.test(metadata) && /^  review-generated: "[^"\r\n]+"\r?$/m.test(metadata) || /^  whiteboard-managed-by: "Whiteboard(?: Desktop)?"\r?$/m.test(metadata) && /^  whiteboard-generated: "[^"\r\n]+"\r?$/m.test(metadata))) return false;
+	const version = metadata.match(/^  (?:review|whiteboard)-version: "([^"\r\n]+)"\r?$/m)?.[1];
+	return version !== void 0 && (version === "development" || valid(version) !== null);
+}
+const OPENCODE_PLUGIN_MARKER = "// Managed by Review Desktop (@dev.fast/review).";
+/** The OpenCode plugin file Review Desktop wrote before it connected over MCP. */
+async function isLegacyOpenCodePlugin(file) {
+	try {
+		if (!(await lstat(file)).isFile()) return false;
+	} catch {
+		return false;
+	}
+	return (await readTextOrUndefined(file))?.split(/\r?\n/, 1)[0] === OPENCODE_PLUGIN_MARKER;
+}
+async function readTextOrUndefined(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch {
+		return;
+	}
+}
+async function scanLegacySkills(homeDir) {
+	const found = [];
+	for (const name of ["review.ts", "whiteboard.ts"]) {
+		const plugin = path.join(homeDir, ".config", "opencode", "plugins", name);
+		if (await isLegacyOpenCodePlugin(plugin)) found.push(plugin);
+	}
+	for (const root of legacySkillRoots(homeDir)) for (const name of LEGACY_SKILL_NAMES) {
+		const skillDir = path.join(root, name);
+		if (await isReviewStamped(skillDir)) found.push(skillDir);
+	}
+	return found.sort();
+}
+async function removeLegacySkills(homeDir) {
+	const removed = [];
+	for (const skillDir of await scanLegacySkills(homeDir)) {
+		await rm(skillDir, {
+			recursive: true,
+			force: true
+		});
+		removed.push(skillDir);
+	}
+	return { removed };
+}
+//#endregion
+//#region src/windows-cli.ts
+const execFileAsync = promisify(execFile);
+/** cmd expands percent signs even inside quotes; delayed expansion stays off. */
+function batchPath(value) {
+	if (/["\r\n\0]/.test(value)) throw new Error("Invalid Windows command path");
+	return value.replaceAll("%", "%%");
+}
+function windowsCliShim(cliPath, runtimePath, devHome) {
+	const lines = [
+		"@echo off",
+		"rem Managed by Whiteboard Desktop. Do not edit.",
+		"setlocal DisableDelayedExpansion",
+		"set \"ELECTRON_RUN_AS_NODE=1\""
+	];
+	if (devHome) lines.push(`if not defined DEV_REVIEW_HOME set "DEV_REVIEW_HOME=${batchPath(devHome)}"`);
+	lines.push(`"${batchPath(runtimePath)}" "${batchPath(cliPath)}" %*`, "exit /b %errorlevel%", "");
+	return lines.join("\r\n");
+}
+/** Preserve the unexpanded user PATH, including entries such as %USERPROFILE%. */
+async function updateWindowsUserPath(directory, remove = false) {
+	await execFileAsync("powershell.exe", [
+		"-NoProfile",
+		"-NonInteractive",
+		"-ExecutionPolicy",
+		"Bypass",
+		"-EncodedCommand",
+		Buffer.from(`
+$ErrorActionPreference = 'Stop'
+$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+$state = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Software\\dev.fast\\Whiteboard\\CLI')
+try {
+  $old = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  $dir = $env:WHITEBOARD_COMMAND_DIRECTORY
+  $entries = @($old.Split(';'))
+  $matches = @($entries | Where-Object { [Environment]::ExpandEnvironmentVariables($_).TrimEnd('\\') -ieq $dir.TrimEnd('\\') })
+  if ($env:WHITEBOARD_REMOVE_COMMAND_PATH -eq '1') {
+    if ([string]$state.GetValue('Path', '') -ine $dir) { return }
+    $entries = @($entries | Where-Object { [Environment]::ExpandEnvironmentVariables($_).TrimEnd('\\') -ine $dir.TrimEnd('\\') })
+    $key.SetValue('Path', ($entries -join ';'), [Microsoft.Win32.RegistryValueKind]::ExpandString)
+    $state.DeleteValue('Path', $false)
+  } else {
+    if ($matches.Count -gt 0) { return }
+    $state.SetValue('Path', $dir)
+    $value = if ($old) { $dir + ';' + $old } else { $dir }
+    $key.SetValue('Path', $value, [Microsoft.Win32.RegistryValueKind]::ExpandString)
+  }
+} finally { $state.Dispose(); $key.Dispose() }
+Add-Type -Namespace Whiteboard -Name EnvironmentChange -MemberDefinition '[System.Runtime.InteropServices.DllImport("user32.dll", CharSet=System.Runtime.InteropServices.CharSet.Unicode)] public static extern System.IntPtr SendMessageTimeout(System.IntPtr h, uint m, System.UIntPtr w, string l, uint f, uint t, out System.UIntPtr r);'
+$result = [UIntPtr]::Zero
+[void][Whiteboard.EnvironmentChange]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$result)
+`, "utf16le").toString("base64")
+	], {
+		windowsHide: true,
+		env: {
+			...process.env,
+			WHITEBOARD_COMMAND_DIRECTORY: directory,
+			WHITEBOARD_REMOVE_COMMAND_PATH: remove ? "1" : "0"
+		}
+	});
+}
+/**
+* A running process keeps the PATH it started with, so the saved user PATH is
+* what tells whether new terminals will find the command.
+*/
+async function windowsUserPathContains(directory, key = "HKCU\\Environment") {
+	let stdout;
+	try {
+		({stdout} = await execFileAsync("reg.exe", [
+			"query",
+			key,
+			"/v",
+			"Path"
+		], { windowsHide: true }));
+	} catch {
+		return false;
+	}
+	const saved = stdout.match(/^\s*Path\s+REG_\w+\s*(.*)$/im)?.[1] ?? "";
+	const target = path.win32.resolve(directory).toLowerCase();
+	return saved.split(";").some((entry) => {
+		const expanded = entry.trim().replace(/%([^%]+)%/g, (whole, name) => process.env[name] ?? whole);
+		return expanded.length > 0 && path.win32.resolve(expanded).toLowerCase() === target;
+	});
+}
+//#endregion
+//#region src/cli-install.ts
+const installErrors = /* @__PURE__ */ new Map();
+const SHIM_MARKER = "Managed by Whiteboard";
+function hasManagedShimMarker(source) {
+	return source.includes(SHIM_MARKER) || source.includes("Managed by Review Desktop") || source.includes("Managed by Whiteboard Desktop");
+}
+const PROFILE_MARKER = "# Managed by Review Desktop: review command PATH. Do not edit.";
+const PROFILE_BLOCK = `\n${PROFILE_MARKER}\nexport PATH="\$HOME/.local/bin:\$PATH"\n`;
+const SHELL_PROFILE_NAMES = [".zprofile", ".bash_profile"];
+function cliInstallStampPath(env = process.env) {
+	return path.join(reviewDesktopStateDir(env), "cli-install.json");
+}
+/**
+* Present once this build's setup is current. It sits beside the stamp, not in
+* it, because older builds parse the stamp strictly and would drop a stamp
+* carrying a new key.
+*/
+function cliInstallUpdateMarkerPath(env = process.env) {
+	return path.join(reviewDesktopStateDir(env), "cli-install-updated");
+}
+function pathShimPath(homeDir = os.homedir()) {
+	return path.join(homeDir, ".local", "bin", process.platform === "win32" ? "whiteboard.cmd" : "whiteboard");
+}
+async function resolveCliInstallStatus(input) {
+	const homeDir = input.homeDir ?? os.homedir();
+	const env = input.env ?? process.env;
+	const shimPath = pathShimPath(homeDir);
+	const cliPath = path.join(input.packageRoot, "dist", "cli.js");
+	const [fingerprint, stamp, updated, trace, legacySkills, cliBuilt, hasShim] = await Promise.all([
+		installFingerprint(input.packageRoot),
+		readCliInstallStamp(cliInstallStampPath(env)),
+		isFile(cliInstallUpdateMarkerPath(env)),
+		traceMachineStatus({
+			homeDir,
+			env
+		}),
+		scanLegacySkills(homeDir),
+		isFile(cliPath),
+		isOwnedShim(shimPath)
+	]);
+	const granted = stamp?.consent === "granted";
+	const installerCommand = hasShim ? void 0 : await windowsInstallerCommand(input.packageRoot, env);
+	const hasCommand = hasShim || installerCommand !== void 0;
+	const status = {
+		fingerprint,
+		stamp,
+		stale: granted && stamp.fingerprint !== fingerprint,
+		updateNeeded: legacySkills.length > 0 || granted && !updated,
+		shim: installerCommand ?? {
+			path: shimPath,
+			installed: hasShim,
+			profileConfigured: process.platform === "win32" ? hasShim && stamp?.userPath !== void 0 && sameWindowsPath(stamp.userPath, path.dirname(shimPath)) || await windowsUserPathContains(path.dirname(shimPath)) : await isShellProfileConfigured(homeDir),
+			onPath: pathContainsDirectory(env.PATH, path.dirname(shimPath))
+		},
+		trace,
+		cli: cliBuilt ? {
+			path: cliPath,
+			version: readReviewPackageVersion(pathToFileURL(cliPath).href)
+		} : null,
+		connect: {
+			...reviewMcpLaunch(hasCommand),
+			prompts: connectSetupPrompts(),
+			plugins: connectPlugins(hasCommand)
+		},
+		legacySkills: legacySkills.map((skillPath) => ({ path: homeRelative(homeDir, skillPath) }))
+	};
+	const error = installErrors.get(homeDir);
+	if (error) status.error = error;
+	return status;
+}
+/**
+* The Windows installer's "Add to PATH" task puts <install dir>\bin, which
+* holds a whiteboard.cmd, on the user or machine PATH.
+*/
+async function windowsInstallerCommand(packageRoot, env) {
+	if (process.platform !== "win32") return void 0;
+	const bin = path.resolve(packageRoot, "..", "..", "..", "bin");
+	const command = path.join(bin, "whiteboard.cmd");
+	if (!await isOwnedShim(command)) return void 0;
+	const profileConfigured = await windowsUserPathContains(bin) || await windowsUserPathContains(bin, "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment");
+	const onPath = pathContainsDirectory(env.PATH, bin);
+	if (!profileConfigured && !onPath) return void 0;
+	return {
+		path: command,
+		installed: true,
+		profileConfigured,
+		onPath,
+		installer: true
+	};
+}
+async function applyCliInstall(input) {
+	if (!input.autoUpdate && input.shim !== true && input.trace === void 0) return {
+		code: 0,
+		output: ""
+	};
+	const homeDir = input.homeDir ?? os.homedir();
+	try {
+		const result = await withDesktopInstallLock(input.env, () => input.autoUpdate ? resyncCliInstallUnlocked(input) : applyCliInstallUnlocked(input));
+		if (result.code === 0) installErrors.delete(homeDir);
+		else installErrors.set(homeDir, result.output);
+		return result;
+	} catch (error) {
+		const output = error instanceof Error ? error.message : String(error);
+		installErrors.set(homeDir, output);
+		return {
+			code: 1,
+			output
+		};
+	}
+}
+async function withDesktopInstallLock(env = process.env, operation) {
+	const outcome = await withFileLock(`${cliInstallStampPath(env)}.lock`, {
+		retryMs: 50,
+		timeoutMs: 3e4,
+		staleMs: 3e5,
+		unownedGraceMs: 5e3
+	}, operation);
+	if (!outcome.acquired) throw new Error("Another Whiteboard setup operation is running. Retry shortly.");
+	return outcome.result;
+}
+/**
+* Silent app-update resync: rewrites the shim for the new build. Consent is
+* re-read under the lock, so a stale UI snapshot never reinstalls a command
+* the user has since removed or declined.
+*/
+async function resyncCliInstallUnlocked(input) {
+	const env = input.env ?? process.env;
+	const stamp = await readCliInstallStamp(cliInstallStampPath(env));
+	const fingerprint = await installFingerprint(input.packageRoot);
+	if (stamp?.consent !== "granted" || stamp.fingerprint === fingerprint) return {
+		code: 0,
+		output: ""
+	};
+	const chunks = [];
+	let shimPath;
+	let userPath = stamp.userPath;
+	if (stamp.shimPath && !stamp.commandDisabled) {
+		const installed = await installShim(input, chunks);
+		if (installed.code !== 0) return installed;
+		shimPath = installed.shimPath;
+		userPath = installed.userPath ?? userPath;
+	}
+	const next = {
+		...stamp,
+		fingerprint,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	if (userPath) next.userPath = userPath;
+	await writePrivateJsonAtomic(cliInstallStampPath(env), next);
+	return withShimPath({
+		code: 0,
+		output: chunks.join("")
+	}, shimPath);
+}
+async function applyCliInstallUnlocked(input) {
+	const homeDir = input.homeDir ?? os.homedir();
+	const env = input.env ?? process.env;
+	const previous = await readCliInstallStamp(cliInstallStampPath(env));
+	const granted = previous?.consent === "granted";
+	const chunks = [];
+	let traceEnabled = false;
+	if (input.trace !== void 0) try {
+		const status = await configureTraceMachine({
+			homeDir,
+			env,
+			credentials: input.trace === true ? void 0 : input.trace
+		});
+		traceEnabled = status.enabled;
+		chunks.push(`[ok] trace capture -> ${status.envPath}\n`);
+		if (status.error) chunks.push(`Trace storage check failed: ${status.error}\n`);
+	} catch (cause) {
+		chunks.push(`${cause instanceof Error ? cause.message : String(cause)}\n`);
+		return {
+			code: 1,
+			output: chunks.join("")
+		};
+	}
+	let shimPath;
+	let userPath;
+	if (input.shim === true) {
+		const installed = await installShim(input, chunks);
+		if (installed.code !== 0) return installed;
+		shimPath = installed.shimPath;
+		userPath = installed.userPath;
+	}
+	if (traceEnabled) {
+		const executable = await isOwnedShim(pathShimPath(homeDir)) ? pathShimPath(homeDir) : void 0;
+		const hooks = await installHarnessHooks({
+			homeDir,
+			env,
+			executable
+		});
+		for (const hook of hooks.installed) chunks.push(`[ok] ${hook.agent} trace hook -> ${hook.path}\n`);
+	}
+	const stamp = {
+		consent: "granted",
+		fingerprint: await installFingerprint(input.packageRoot),
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	const stampShimPath = shimPath ?? (granted ? previous.shimPath : void 0);
+	if (stampShimPath) stamp.shimPath = stampShimPath;
+	if (granted && previous.commandDisabled && input.shim !== true) stamp.commandDisabled = true;
+	if (input.trace !== void 0 || granted && previous.traceManaged) stamp.traceManaged = true;
+	const stampUserPath = userPath ?? (granted && !shimPath ? previous.userPath : void 0);
+	if (stampUserPath) stamp.userPath = stampUserPath;
+	await writeCurrentStamp(env, stamp);
+	return withShimPath({
+		code: 0,
+		output: chunks.join("")
+	}, shimPath);
+}
+async function installShim(input, chunks) {
+	if (!input.cliPath) {
+		chunks.push("This server has no built CLI to install the command from.\n");
+		return {
+			code: 1,
+			output: chunks.join("")
+		};
+	}
+	const installed = await installReviewCommand({
+		cliPath: input.cliPath,
+		cliRuntimePath: input.cliRuntimePath,
+		homeDir: input.homeDir,
+		env: input.env
+	});
+	chunks.push(installed.output);
+	const result = {
+		code: 0,
+		output: "",
+		shimPath: installed.shimPath
+	};
+	if (installed.userPath) result.userPath = installed.userPath;
+	return result;
+}
+function withShimPath(result, shimPath) {
+	if (shimPath) result.shimPath = shimPath;
+	return result;
+}
+/** The published plugin per harness; Cursor's link needs the shim it launches. */
+function connectPlugins(hasShim) {
+	return {
+		claude: process.platform === "win32" ? {
+			label: "Add the Claude Code MCP server",
+			command: CLAUDE_WINDOWS_MCP_ADD
+		} : {
+			label: "Install the Claude Code plugin",
+			command: "/plugin marketplace add devdotfast/whiteboard\n/plugin install whiteboard@devfast"
+		},
+		codex: {
+			label: "Install the Codex plugin",
+			command: "codex plugin marketplace add devdotfast/whiteboard\ncodex plugin add whiteboard@devfast"
+		},
+		cursor: hasShim ? {
+			label: "Install in Cursor",
+			url: cursorInstallDeeplink(reviewMcpLaunch(true))
+		} : { label: "Install in Cursor" },
+		opencode: {
+			label: "Add the OpenCode MCP server (OpenCode 2+)",
+			command: `opencode mcp add --global whiteboard -- ${launchCommand(reviewMcpLaunch(hasShim))}`
+		},
+		pi: {
+			label: "Add the Pi MCP server (Pi 0.99+)",
+			command: `pi mcp add whiteboard -- ${launchCommand(reviewMcpLaunch(hasShim))}`
+		},
+		omp: {
+			label: "Add the oh-my-pi MCP server",
+			command: `Add ${JSON.stringify({ whiteboard: reviewMcpLaunch(hasShim) })}\nto "mcpServers" in ~/.omp/agent/mcp.json, then run /mcp reload.`
+		},
+		copilot: process.platform === "win32" ? {
+			label: "Add the Copilot CLI MCP server",
+			command: COPILOT_WINDOWS_MCP_ADD
+		} : {
+			label: "Install the Copilot CLI plugin",
+			command: "copilot plugin marketplace add devdotfast/whiteboard\ncopilot plugin install whiteboard@devfast"
+		}
+	};
+}
+/** Removes the skills Whiteboard Desktop installed before it connected over MCP. */
+async function removeLegacyReviewSkills(input = {}) {
+	return withDesktopInstallLock(input.env, () => removeLegacySkills(input.homeDir ?? os.homedir()));
+}
+/** Records setup completion; remaining legacy skills still require the update screen. */
+async function finishCliInstallUpdate(env = process.env) {
+	await withDesktopInstallLock(env, async () => {
+		if ((await readCliInstallStamp(cliInstallStampPath(env)))?.consent !== "granted") return;
+		await writeUpdateMarker(env);
+	});
+}
+async function declineCliInstall(env = process.env) {
+	await withDesktopInstallLock(env, () => writeCurrentStamp(env, {
+		consent: "declined",
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	}));
+}
+async function skipCliInstall(env = process.env) {
+	await withDesktopInstallLock(env, async () => {
+		if (await readCliInstallStamp(cliInstallStampPath(env))) return;
+		await writeCurrentStamp(env, {
+			consent: "skipped",
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	});
+}
+/** Removes the stamp entirely, so the next app launch prompts again. */
+async function resetCliInstall(env = process.env) {
+	await withDesktopInstallLock(env, async () => {
+		await rm(cliInstallStampPath(env), { force: true });
+		await rm(cliInstallUpdateMarkerPath(env), { force: true });
+	});
+}
+/** Writes a stamp this build decided, which also makes the setup current. */
+async function writeCurrentStamp(env, stamp) {
+	await writePrivateJsonAtomic(cliInstallStampPath(env), stamp);
+	await writeUpdateMarker(env);
+}
+async function writeUpdateMarker(env) {
+	await writeFileAtomicAsync(cliInstallUpdateMarkerPath(env), "", {
+		encoding: "utf8",
+		mode: 384
+	});
+}
+async function removeCliInstall(input) {
+	return withDesktopInstallLock(input.env, () => removeCliInstallUnlocked(input));
+}
+async function removeCliInstallUnlocked(input) {
+	const homeDir = input.homeDir ?? os.homedir();
+	const env = input.env ?? process.env;
+	const chunks = [];
+	const expectedTraceCommand = await isOwnedShim(pathShimPath(homeDir)) ? pathShimPath(homeDir) : "";
+	const previous = await readCliInstallStamp(cliInstallStampPath(env));
+	if (input.shim) {
+		const shimPath = pathShimPath(homeDir);
+		const contents = await readTextIfExists(shimPath);
+		if (contents.includes(SHIM_MARKER)) {
+			await rm(shimPath, { force: true });
+			if (process.platform === "win32") {
+				const bashShim = shimPath.replace(/\.cmd$/i, "");
+				if (await isOwnedShim(bashShim)) await rm(bashShim, { force: true });
+			}
+			chunks.push(`[ok] removed whiteboard command ${shimPath}\n`);
+		} else if (contents) chunks.push(`${shimPath} was not installed by Whiteboard Desktop; left in place.\n`);
+		for (const profilePath of await removeShellProfilePath(homeDir)) chunks.push(`[ok] removed Whiteboard PATH entry from ${profilePath}\n`);
+	}
+	if (input.trace) {
+		const { kept } = await disableAllTraceRepositories(traceScope({
+			homeDir,
+			env
+		}), expectedTraceCommand);
+		for (const agent of AGENT_TRACE_HOOK_AGENTS) await removeAgentTraceHook(agent, homeDir, env, expectedTraceCommand);
+		const remaining = await describeTraceHookOwners(homeDir, env);
+		if (kept.length || Object.values(remaining).some(Boolean)) chunks.push("[skip] kept trace capture for another Whiteboard installation\n");
+		else {
+			await disableTraceMachine({
+				homeDir,
+				env
+			});
+			chunks.push("[ok] disabled Whiteboard trace capture\n");
+		}
+	}
+	if (previous?.consent === "granted") {
+		const stamp = {
+			consent: "granted",
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		if (previous.fingerprint) stamp.fingerprint = previous.fingerprint;
+		if (!input.shim && previous.shimPath) stamp.shimPath = previous.shimPath;
+		if (input.shim || previous.commandDisabled) stamp.commandDisabled = true;
+		if (!input.trace && previous.traceManaged) stamp.traceManaged = true;
+		if (!input.shim && previous.userPath) stamp.userPath = previous.userPath;
+		await writeCurrentStamp(env, stamp);
+	}
+	return { output: chunks.join("") };
+}
+/**
+* Fingerprint of the package manifest and built CLI. Content-based so it
+* works identically in a dev checkout and a packaged review-runtime, with no
+* build-time stamping.
+*/
+async function installFingerprint(packageRoot) {
+	const hash = createHash("sha256");
+	hash.update(await readTextIfExists(path.join(packageRoot, "package.json")));
+	hash.update("dist/cli.js\0");
+	hash.update(await readTextIfExists(path.join(packageRoot, "dist", "cli.js")));
+	return hash.digest("hex").slice(0, 20);
+}
+async function readCliInstallStamp(stampPath) {
+	let value;
+	try {
+		value = JSON.parse(await readFile(stampPath, "utf8"));
+	} catch {
+		return null;
+	}
+	const parsed = ReviewCliInstallStampSchema.safeParse(value);
+	return parsed.success ? parsed.data : null;
+}
+async function isOwnedShim(shimPath) {
+	return hasManagedShimMarker(await readTextIfExists(shimPath));
+}
+/**
+* The shim is POSIX sh, so running `review` needs no Node.js at all to start.
+* It prefers the CLI and runtime the running Whiteboard Desktop advertises in its
+* discovery file, falls back to the paths baked in by the app that wrote it,
+* and runs the CLI under the app's Electron binary as Node
+* (ELECTRON_RUN_AS_NODE) — the exact runtime the server uses. System Node is
+* the last resort and gets a clear version check instead of a cryptic crash.
+*/
+async function writePathShim(shimPath, cliPath, runtimePath, devHome) {
+	if (process.platform === "win32") {
+		await writeFileAtomicAsync(shimPath, windowsCliShim(cliPath, runtimePath ?? process.execPath, devHome), { replaceSymlink: true });
+		shimPath = shimPath.replace(/\.cmd$/i, "");
+	}
+	const source = `#!/bin/sh
+# Managed by Whiteboard Desktop ("Whiteboard: Install CLI in PATH"). Do not edit.
+FALLBACK_CLI=${shSingleQuote(cliPath)}
+FALLBACK_RUNTIME=${shSingleQuote(runtimePath ?? "")}
+DEFAULT_HOME=${shSingleQuote(devHome)}
+export DEV_REVIEW_HOME="\${DEV_REVIEW_HOME:-$DEFAULT_HOME}"
+DESKTOP="$DEV_REVIEW_HOME/review-desktop"
+
+# A record counts only while its server process is alive.
+live() {
+  [ -f "$1" ] || return 1
+  pid=$(sed -n 's/.*"serverPid"[[:space:]]*:[[:space:]]*\\([0-9][0-9]*\\).*/\\1/p' "$1" | head -n 1)
+  [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
+}
+
+# Same order as the CLI: DEV_REVIEW_INSTANCE, the machine default, the only
+# live Desktop, then stable. A stable Desktop that predates instances wrote
+# only server.json; it never stands in for any other key.
+LEGACY="$DESKTOP/server.json"
+STABLE="$DESKTOP/instances/stable.json"
+[ -f "$STABLE" ] || STABLE="$LEGACY"
+key="\${DEV_REVIEW_INSTANCE:-}"
+if [ -z "$key" ] && [ -f "$DESKTOP/default-instance" ]; then
+  key=$(head -n 1 "$DESKTOP/default-instance" | tr -d '[:space:]')
+fi
+DISCOVERY=""
+case "$key" in
+  # Keys name files; the CLI rejects anything else.
+  *[!A-Za-z0-9_.-]*) ;;
+  stable) DISCOVERY="$STABLE" ;;
+  ?*) DISCOVERY="$DESKTOP/instances/$key.json" ;;
+  *)
+    for record in "$DESKTOP"/instances/*.json "$LEGACY"; do
+      if [ "$record" = "$LEGACY" ] && [ "$STABLE" != "$LEGACY" ]; then continue; fi
+      if live "$record"; then
+        if [ -n "$DISCOVERY" ]; then DISCOVERY=""; break; fi
+        DISCOVERY="$record"
+      fi
+    done
+    [ -n "$DISCOVERY" ] || DISCOVERY="$STABLE"
+    ;;
+esac
+
+cli=""
+runtime=""
+delegated=""
+manage_instances=""
+for arg in "$@"; do
+  if [ "$arg" = "instances" ]; then manage_instances=1; break; fi
+done
+if [ -z "$manage_instances" ] && [ -z "\${DEV_FAST_REVIEW_CLI_NO_DELEGATE:-}" ] && live "$DISCOVERY"; then
+  cli=$(sed -n 's/.*"cliPath"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' "$DISCOVERY" | head -n 1)
+  delegated="1"
+  runtime=$(sed -n 's/.*"cliRuntimePath"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' "$DISCOVERY" | head -n 1)
+fi
+if [ -z "$cli" ] || [ ! -f "$cli" ] || { [ -n "$runtime" ] && [ ! -x "$runtime" ]; }; then
+  delegated=""
+  cli="$FALLBACK_CLI"
+  runtime="$FALLBACK_RUNTIME"
+fi
+
+if [ ! -f "$cli" ]; then
+  echo "Whiteboard CLI not found at $cli. Start Whiteboard Desktop, or run npx @dev.fast/whiteboard instead." >&2
+  exit 1
+fi
+
+# Prevent bootstrap from overriding this selection.
+export DEV_FAST_REVIEW_CLI_NO_DELEGATE=1
+export DEV_FAST_REVIEW_CLI_DELEGATED="$delegated"
+
+# The app's Electron binary runs as plain Node.js and matches the server's
+# runtime exactly; no system Node is required on this path.
+if [ -n "$runtime" ] && [ -x "$runtime" ]; then
+  export ELECTRON_RUN_AS_NODE=1
+  exec "$runtime" "$cli" "$@"
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Whiteboard needs Node.js 24 or newer and none was found. Install Node 24, or install Whiteboard Desktop." >&2
+  exit 1
+fi
+major=$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)
+case "$major" in *[!0-9]*) major=0;; esac
+if [ "$major" -lt 24 ]; then
+  echo "Whiteboard needs Node.js 24 or newer; found $(node -v 2>/dev/null). Update Node, or install Whiteboard Desktop." >&2
+  exit 1
+fi
+exec node "$cli" "$@"
+`;
+	await writeFileAtomicAsync(shimPath, source, {
+		encoding: "utf8",
+		mode: 493,
+		replaceSymlink: true
+	});
+	await chmod(shimPath, 493);
+}
+async function installReviewCommand(input) {
+	const homeDir = input.homeDir ?? os.homedir();
+	const env = input.env ?? process.env;
+	const shimPath = pathShimPath(homeDir);
+	if (await isFile(shimPath) && !await isOwnedShim(shimPath)) return {
+		shimPath,
+		output: `[skip] kept the existing whiteboard command at ${shimPath}\n`
+	};
+	const shadowingCommand = await resolvePathCommand("whiteboard", shimPath, env);
+	await writePathShim(shimPath, input.cliPath, input.cliRuntimePath, devReviewHome(env, homeDir));
+	if (await traceMachineEnabled({
+		homeDir,
+		env
+	})) {
+		const scope = traceScope({
+			homeDir,
+			env
+		});
+		for (const cwd of await listTraceRepositoryRoots(homeDir)) {
+			if (!await isDirectory(cwd)) continue;
+			if ((await traceRepositoryStatus(cwd)).enabled) await enableTraceRepository({
+				cwd,
+				scope,
+				reviewCommand: shimPath,
+				replaceCommand: true
+			});
+		}
+	}
+	const legacyShim = path.join(path.dirname(shimPath), "review");
+	if (await isOwnedShim(legacyShim)) await rm(legacyShim, { force: true });
+	const output = `[ok] whiteboard command -> ${shimPath}\n${await ensureShellProfilePath({
+		homeDir,
+		env
+	})}${shadowingCommand ? `Warning: ${shadowingCommand} currently shadows ${shimPath}. Remove that PATH entry or put ${path.dirname(shimPath)} before it.\n` : ""}`;
+	return process.platform === "win32" ? {
+		shimPath,
+		output,
+		userPath: path.dirname(shimPath)
+	} : {
+		shimPath,
+		output
+	};
+}
+async function ensureShellProfilePath(input) {
+	const shimDirectory = path.dirname(pathShimPath(input.homeDir));
+	if (pathContainsDirectory(input.env.PATH, shimDirectory)) return "";
+	if (process.platform === "win32") {
+		await updateWindowsUserPath(shimDirectory);
+		return `[ok] added ${shimDirectory} to your user PATH; open a new terminal\n`;
+	}
+	const shell = path.basename(input.env.SHELL?.trim() ?? "");
+	let profileName;
+	if (shell === "bash") profileName = ".bash_profile";
+	else if (shell === "zsh" || shell !== "fish" && process.platform === "darwin") profileName = ".zprofile";
+	if (!profileName) return "Whiteboard did not update PATH for this shell. Add ~/.local/bin to PATH. Fish users can run: fish_add_path ~/.local/bin\n";
+	const profilePath = path.join(input.homeDir, profileName);
+	const source = await readTextIfExists(profilePath);
+	if (source.includes(PROFILE_MARKER) || source.includes(".local/bin")) return "";
+	await writeTextAtomic(profilePath, `${source}${PROFILE_BLOCK}`);
+	return `[ok] added ${shimDirectory} to PATH in ${profilePath}\n`;
+}
+async function removeShellProfilePath(homeDir) {
+	if (process.platform === "win32") {
+		await updateWindowsUserPath(path.dirname(pathShimPath(homeDir)), true);
+		return ["user PATH"];
+	}
+	const removed = [];
+	for (const profileName of SHELL_PROFILE_NAMES) {
+		const profilePath = path.join(homeDir, profileName);
+		const source = await readTextIfExists(profilePath);
+		if (!source.includes(PROFILE_BLOCK)) continue;
+		await writeTextAtomic(profilePath, source.replaceAll(PROFILE_BLOCK, ""));
+		removed.push(profilePath);
+	}
+	return removed;
+}
+function shSingleQuote(value) {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+async function resolvePathCommand(command, shimPath, env) {
+	const entries = (env.PATH ?? "").split(path.delimiter);
+	const shimDirectory = path.resolve(path.dirname(shimPath));
+	const shimIndex = entries.findIndex((entry) => path.resolve(entry || ".") === shimDirectory);
+	for (let index = 0; index < entries.length; index += 1) {
+		const candidate = path.join(entries[index] || ".", command);
+		if (!await isExecutableFile(candidate)) continue;
+		if ((await readTextIfExists(candidate)).includes(SHIM_MARKER)) return;
+		return shimIndex === -1 || index < shimIndex ? path.resolve(candidate) : void 0;
+	}
+}
+function sameWindowsPath(left, right) {
+	return path.win32.resolve(left).toLowerCase() === path.win32.resolve(right).toLowerCase();
+}
+function pathContainsDirectory(pathValue, directory) {
+	return (pathValue ?? "").split(path.delimiter).some((entry) => entry.length > 0 && path.resolve(entry) === path.resolve(directory));
+}
+async function isShellProfileConfigured(homeDir) {
+	return (await Promise.all(SHELL_PROFILE_NAMES.map((profileName) => readTextIfExists(path.join(homeDir, profileName))))).some((source) => source.includes(PROFILE_MARKER));
+}
+async function writeTextAtomic(filePath, source) {
+	let mode = 420;
+	try {
+		mode = (await stat(filePath)).mode & 511;
+	} catch {}
+	await writeFileAtomicAsync(filePath, source, {
+		encoding: "utf8",
+		mode
+	});
+}
+async function readTextIfExists(filePath) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch {
+		return "";
+	}
+}
+async function isExecutableFile(target) {
+	if (!await isFile(target)) return false;
+	try {
+		await access(target, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** `~/…` for paths under the home directory; the card shows these, removal rescans. */
+function homeRelative(homeDir, target) {
+	const relative = path.relative(homeDir, target);
+	return relative.startsWith("..") || path.isAbsolute(relative) ? target : `~/${relative.split(path.sep).join("/")}`;
+}
+//#endregion
+//#region src/server/account-alias.ts
+/**
+* After a login, link this install to the signed-in account by a hash of its
+* account id. Best effort and never throws: the login already succeeded.
+*/
+async function aliasInstallationToAccount(telemetry, env = process.env, fetchImpl) {
+	try {
+		const auth = await readStoreAuth(env);
+		if (!auth) return;
+		await telemetry.captureAccountAlias(async () => {
+			return (await new StoreClient({
+				origin: auth.origin,
+				token: auth.token,
+				fetch: fetchImpl
+			}).session()).user.id;
+		});
+	} catch {}
+}
+//#endregion
+export { isOwnedShim as a, removeLegacyReviewSkills as c, skipCliInstall as d, windowsInstallerCommand as f, finishCliInstallUpdate as i, resetCliInstall as l, connectPrompts as m, applyCliInstall as n, pathShimPath as o, scanLegacySkills as p, declineCliInstall as r, removeCliInstall as s, aliasInstallationToAccount as t, resolveCliInstallStatus as u };