Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(setup): resolve the configuration MSIX Claude Desktop reads (#2426)
FeeHaardfd65e278be4d
diff --git a/docs/client-configuration.md b/docs/client-configuration.mdindex e27866f7d..1a85dbdfa 100644--- a/docs/client-configuration.md+++ b/docs/client-configuration.md@@ -33,6 +33,71 @@ schema constraints; REA still validates complete canonical inputs. Full-profile`gpt-5.4` metadata is also verified locally. Live model API acceptance andWindows remain unverified; see [native client verification](testing.md).+## Claude Desktop++Setup registers `mcpServers.rea` in `claude_desktop_config.json`: under+`~/Library/Application Support/Claude` on macOS, under+`$XDG_CONFIG_HOME/Claude` (default `~/.config/Claude`) on Linux, and on Windows+in the file the installed app reads:++- Without Claude Desktop's MSIX package storage, setup uses+ `%APPDATA%\Claude\claude_desktop_config.json`.+- The MSIX build (package family `Claude_pzs8sxrjxfjjc`, installed under+ `C:\Program Files\WindowsApps\Claude_<version>_x64__pzs8sxrjxfjjc`)+ virtualizes AppData writes. Once it has saved its configuration, it reads+ the package-private copy+ `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`+ and ignores the `%APPDATA%` file. Setup, doctor and uninstall use that+ private copy when it exists. Before the package has saved one, they use the+ `%APPDATA%` file it still reads; with neither file, setup creates the+ private copy.+- If `%LOCALAPPDATA%\Packages` holds a `Claude_<publisher ID>` package from+ another publisher, or cannot be read, REA cannot establish which file Claude+ Desktop reads. Setup, doctor and uninstall report that instead of falling+ back to `%APPDATA%`. Doctor then reports `claude_desktop` as invalid, and+ uninstall stops before removing anything for any client.++Quit Claude Desktop fully before approving setup; closing its window is not+enough. A running Claude Desktop can rewrite its configuration from memory and+drop the registration. This was observed with the Windows MSIX build. Start+Claude Desktop again after setup. If the package saves its private copy after+setup planned to write the `%APPDATA%` file, setup makes no change and asks you+to rerun it.++A process that the MSIX app started, such as a terminal in Claude Desktop's+Code tab, sees the package's private files at their `%APPDATA%` paths even+though it reports no package identity. Setup compares one of those files at+both paths. When it finds that redirected view, the app is running, so setup+and uninstall refuse to change Claude Desktop's configuration; rerun them from+a terminal that Claude Desktop did not start. If the package has no private+file to compare, setup and uninstall cannot rule that out and also refuse; open+Claude Desktop once if it has never run, quit it fully, then rerun. Doctor+reads the same file from either kind of process.++The same process also writes everything under `%APPDATA%` and+`%LOCALAPPDATA%` into the package's private storage, where other apps never+read it. From that redirected view, setup and uninstall refuse to change other+clients' files there (VS Code, Trae, Devin and Hermes) and skill directories+there. `npm install -g` run from such a process installs into the package's+`LocalCache\Roaming\npm`, which other processes cannot see at the `%APPDATA%`+path. Setup refuses to register a launcher stored in any MSIX package's+private storage. Install REA from an ordinary terminal and rerun setup there.++Uninstall removes REA's entry from both the private copy and the `%APPDATA%`+file, including registrations that earlier releases wrote to `%APPDATA%`.++REA recognizes only the MSIX package. A non-MSIX Claude Desktop installed+beside it, which would read the `%APPDATA%` file, is not detected.++The package identity, both file locations, the redirected view, and these+setup and doctor results were observed on Windows 11 with the MSIX build+2.31226.1.0, using read-only `doctor` and `setup --dry-run` runs both inside+and outside the app. On that host, setup run from an ordinary terminal with+the app quit wrote the package-private copy; after the app restarted, the+entry was still present, doctor reported it aligned, and Claude Desktop's MCP+log showed REA starting and answering `tools/list`. Uninstall against the real+app is unverified.+## Claude CodeClaude Code normally defers MCP tool definitions through tool search. Itdiff --git a/docs/installation.md b/docs/installation.mdindex 9285883e3..bb0adfbc9 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -20,7 +20,9 @@ npx rea-agents setupChoose the agents to configure, review the proposed paths and changes, andapprove the plan. npm's package-download approval and REA's setup approval areseparate. Setup asks before changing agent configuration or installing Hopper.-Restart the agents named in the completion message.+Restart the agents named in the completion message. Quit Claude Desktop fully+before approving, because a running app can overwrite the registration; on+Windows, see [where Claude Desktop reads its configuration](client-configuration.md#claude-desktop).For the latest published release, use `npx rea-agents@latest setup`.[Package-runner and global-installation options](#package-runners-and-global-installation)diff --git a/scripts/verify-package-environment.mjs b/scripts/verify-package-environment.mjsindex cd84655b2..e57f7784b 100644--- a/scripts/verify-package-environment.mjs+++ b/scripts/verify-package-environment.mjs@@ -76,6 +76,7 @@ export async function verifyPackageEnvironment({HOME: home,USERPROFILE: home,APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),CLAUDE_CONFIG_DIR: home,CODEX_HOME: codexDir,COPILOT_HOME: join(home, ".copilot"),diff --git a/scripts/verify-package-update.mjs b/scripts/verify-package-update.mjsindex 5998ab77f..8d8582b44 100644--- a/scripts/verify-package-update.mjs+++ b/scripts/verify-package-update.mjs@@ -98,6 +98,7 @@ export async function verifyPackageUpdate({HOME: home,USERPROFILE: home,APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),CLAUDE_CONFIG_DIR: home,CODEX_HOME: join(home, ".codex"),COPILOT_HOME: join(home, ".copilot"),diff --git a/scripts/verify-published-package.mjs b/scripts/verify-published-package.mjsindex 8c0281d56..8a5eb48d8 100644--- a/scripts/verify-published-package.mjs+++ b/scripts/verify-published-package.mjs@@ -118,6 +118,7 @@ async function verifyPublishedUpdate({ version: targetVersion, canaryRoot }) {HOME: home,USERPROFILE: home,APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),CLAUDE_CONFIG_DIR: home,CODEX_HOME: join(home, ".codex"),COPILOT_HOME: join(home, ".copilot"),diff --git a/scripts/verify-windows-package.mjs b/scripts/verify-windows-package.mjsindex 7ac204868..425b5cbd3 100644--- a/scripts/verify-windows-package.mjs+++ b/scripts/verify-windows-package.mjs@@ -110,6 +110,7 @@ try {HOME: home,USERPROFILE: home,APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),CLAUDE_CONFIG_DIR: home,CODEX_HOME: join(home, ".codex"),XDG_CONFIG_HOME: join(home, ".config"),diff --git a/src/application/ClaudeDesktopConfigLocation.test.ts b/src/application/ClaudeDesktopConfigLocation.test.tsnew file mode 100644index 000000000..84d8ca8bc--- /dev/null+++ b/src/application/ClaudeDesktopConfigLocation.test.ts@@ -0,0 +1,341 @@+import { basename, dirname, join, sep } from "node:path";++import { describe, expect, it } from "vitest";++import {+ CLAUDE_DESKTOP_PACKAGE_FAMILY,+ resolveWindowsClaudeDesktopLocation,+ type ClaudeDesktopLocationFileSystem,+} from "./ClaudeDesktopConfigLocation.js";+import {+ packagePrivateLauncherBlocker,+ packagePrivateStorageFamily,+ redirectedWriteBlocker,+ type MsixPackageView,+} from "./MsixPackageStorage.js";++const home = join("/profile", "a");+const env = {+ APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),+};+const packages = join(env.LOCALAPPDATA, "Packages");+const appDataConfig = join(env.APPDATA, "Claude", "claude_desktop_config.json");+const privateConfig = join(+ packages,+ CLAUDE_DESKTOP_PACKAGE_FAMILY,+ "LocalCache",+ "Roaming",+ "Claude",+ "claude_desktop_config.json",+);++const failure = (code: string): Error =>+ Object.assign(new Error(`${code}: injected`), { code });++const file = { isFile: () => true };+const privateDirectory = dirname(privateConfig);+const privatePreferences = join(privateDirectory, "Preferences");+const appDataDirectory = dirname(appDataConfig);++/** Package storage holding `privateFiles`; realpath decides the process view. */+const packagedFileSystem = (+ realpath: ClaudeDesktopLocationFileSystem["realpath"],+ privateFiles: readonly string[] = [privateConfig],+): ClaudeDesktopLocationFileSystem => ({+ readdir: (path) => {+ if (path === packages) return [CLAUDE_DESKTOP_PACKAGE_FAMILY];+ if (path === privateDirectory)+ return privateFiles.map((name) => basename(name));+ throw failure("ENOENT");+ },+ lstat: (path) => {+ if (!privateFiles.includes(path)) throw failure("ENOENT");+ return file;+ },+ realpath,+});++describe("Claude Desktop MSIX process view", () => {+ it("recognizes a process that sees the private copy at the AppData path", () => {+ const location = resolveWindowsClaudeDesktopLocation(+ home,+ env,+ packagedFileSystem((path) =>+ path === appDataConfig ? privateConfig : path,+ ),+ );+ expect(location).toEqual({+ ok: true,+ value: expect.objectContaining({+ configPath: privateConfig,+ msixPackage: expect.objectContaining({ processView: "redirected" }),+ }),+ });+ });++ it("treats an absent AppData file as an unredirected process", () => {+ const location = resolveWindowsClaudeDesktopLocation(+ home,+ env,+ packagedFileSystem((path) => {+ if (path === appDataConfig) throw failure("ENOENT");+ return path;+ }),+ );+ expect(location.ok && location.value.msixPackage?.processView).toBe(+ "direct",+ );+ });++ it("recognizes redirection through another private file before the configuration exists", () => {+ const location = resolveWindowsClaudeDesktopLocation(+ home,+ env,+ packagedFileSystem(+ (path) =>+ path === join(appDataDirectory, "Preferences")+ ? privatePreferences+ : path,+ [privatePreferences],+ ),+ );+ expect(location.ok && location.value.configPath).toBe(privateConfig);+ expect(location.ok && location.value.msixPackage?.processView).toBe(+ "redirected",+ );+ });++ it("continues after a listed private file disappears", () => {+ const fs = packagedFileSystem(+ (path) =>+ path === join(appDataDirectory, "Preferences")+ ? privatePreferences+ : path,+ [privatePreferences],+ );+ const location = resolveWindowsClaudeDesktopLocation(home, env, {+ ...fs,+ readdir: (path) =>+ path === privateDirectory+ ? ["vanished", "Preferences"]+ : fs.readdir(path),+ });+ expect(location.ok && location.value.msixPackage?.processView).toBe(+ "redirected",+ );+ });++ it("keeps the view unknown when the package has no private files", () => {+ const location = resolveWindowsClaudeDesktopLocation(+ home,+ env,+ packagedFileSystem((path) => path, []),+ );+ expect(location.ok && location.value.msixPackage?.processView).toBe(+ "unknown",+ );+ });++ it("keeps the view unknown when the AppData path cannot be resolved", () => {+ const location = resolveWindowsClaudeDesktopLocation(+ home,+ env,+ packagedFileSystem((path) => {+ if (path === appDataConfig) throw failure("EACCES");+ return path;+ }),+ );+ expect(location.ok && location.value.msixPackage?.processView).toBe(+ "unknown",+ );+ });+});++describe("unresolved Claude Desktop package identity", () => {+ it("reports unreadable package storage instead of assuming AppData", () => {+ const location = resolveWindowsClaudeDesktopLocation(home, env, {+ readdir: () => {+ throw failure("EACCES");+ },+ lstat: () => file,+ realpath: (path) => path,+ });+ expect(location).toEqual({+ ok: false,+ error: {+ path: packages,+ message: expect.stringContaining("could not be inspected"),+ },+ });+ });++ it("reports an uninspectable private copy instead of choosing a file", () => {+ const location = resolveWindowsClaudeDesktopLocation(home, env, {+ readdir: () => [CLAUDE_DESKTOP_PACKAGE_FAMILY],+ lstat: () => {+ throw failure("EPERM");+ },+ realpath: (path) => path,+ });+ expect(location.ok).toBe(false);+ expect(!location.ok && location.error.path).toBe(privateConfig);+ });++ it("matches the package family case-insensitively, as Windows does", () => {+ const location = resolveWindowsClaudeDesktopLocation(home, env, {+ readdir: () => [CLAUDE_DESKTOP_PACKAGE_FAMILY.toUpperCase()],+ lstat: () => {+ throw failure("ENOENT");+ },+ realpath: (path) => path,+ });+ expect(location.ok && location.value.msixPackage?.packageFamilyName).toBe(+ CLAUDE_DESKTOP_PACKAGE_FAMILY.toUpperCase(),+ );+ });+});++describe("package-private REA launchers", () => {+ const launcher = join(+ env.APPDATA,+ "npm",+ "node_modules",+ "rea-agents",+ "scripts",+ "rea.mjs",+ );+ const stored = join(+ packages,+ CLAUDE_DESKTOP_PACKAGE_FAMILY,+ "LocalCache",+ "Roaming",+ "npm",+ "node_modules",+ "rea-agents",+ "scripts",+ "rea.mjs",+ );++ it("names the package that privately stores a path", () => {+ expect(packagePrivateStorageFamily(stored, packages)).toBe(+ CLAUDE_DESKTOP_PACKAGE_FAMILY,+ );+ expect(packagePrivateStorageFamily(launcher, packages)).toBeUndefined();+ expect(+ packagePrivateStorageFamily(+ join(packages, CLAUDE_DESKTOP_PACKAGE_FAMILY, "LocalState", "x"),+ packages,+ ),+ ).toBeUndefined();+ });++ it("blocks a launcher that only the package's processes can see", () => {+ const blocker = packagePrivateLauncherBlocker(+ [join("/Program Files", "nodejs", "node.exe"), launcher, "mcp"],+ packages,+ (path) => (path === launcher ? stored : path),+ );+ expect(blocker).toContain(stored);+ expect(blocker).toContain(CLAUDE_DESKTOP_PACKAGE_FAMILY);+ expect(blocker).toContain("npm install -g rea-agents");+ });++ it("compares the launcher with the canonical package storage path", () => {+ const shortProfilePackages = join(+ "/profile",+ "A~1",+ "AppData",+ "Local",+ "Packages",+ );+ const blocker = packagePrivateLauncherBlocker(+ [launcher, "mcp"],+ shortProfilePackages,+ (path) =>+ path === shortProfilePackages+ ? packages+ : path === launcher+ ? stored+ : path,+ );+ expect(blocker).toContain(CLAUDE_DESKTOP_PACKAGE_FAMILY);+ });++ it("allows ordinary and unresolvable launchers", () => {+ expect(+ packagePrivateLauncherBlocker(+ ["cmd.exe", "/d", "/c", "npx", "-y", "[email protected]", "mcp"],+ packages,+ () => {+ throw new Error("package runners are not resolved");+ },+ ),+ ).toBeUndefined();+ expect(+ packagePrivateLauncherBlocker([launcher, "mcp"], packages, () => {+ throw failure("ENOENT");+ }),+ ).toBeUndefined();+ });+});++describe("writes from a redirected AppData view", () => {+ const view: MsixPackageView = {+ packageFamilyName: CLAUDE_DESKTOP_PACKAGE_FAMILY,+ privateConfigPath: privateConfig,+ appDataConfigPath: appDataConfig,+ virtualizedRoots: [env.APPDATA, env.LOCALAPPDATA],+ processView: "redirected",+ };+ const vscode = join(env.APPDATA, "Code", "User", "mcp.json");+ const hermes = join(env.LOCALAPPDATA, "hermes", "config.yaml");+ const codex = join(home, ".codex", "config.toml");++ it("refuses only targets under the package's virtualized roots", () => {+ const blocker = redirectedWriteBlocker(+ view,+ [vscode, codex, hermes],+ "setup",+ );+ expect(blocker).toContain(`${vscode}, ${hermes}`);+ expect(blocker).not.toContain(codex);+ expect(blocker).toContain("Rerun setup from a terminal");+ expect(redirectedWriteBlocker(view, [codex], "setup")).toBeUndefined();+ });++ it("compares aliases through the existing parent of a new destination", () => {+ const alias = join(home, "skill-alias");+ const target = join(alias, "skills", "reverse-engineer-anything");+ const blocker = redirectedWriteBlocker(+ view,+ [target],+ "uninstall",+ (path) => {+ if (path === alias) return join(env.APPDATA, "dsh");+ if (path.startsWith(`${alias}${sep}`)) throw failure("ENOENT");+ return path;+ },+ );+ expect(blocker).toContain(target);+ expect(blocker).toContain("Rerun uninstall");+ });++ it("keeps canonicalization failures visible instead of assuming a target is outside AppData", () => {+ expect(+ redirectedWriteBlocker(view, [codex], "setup", () => {+ throw failure("EACCES");+ }),+ ).toContain("Cannot establish the MSIX write location");+ });++ it("allows every target without positive evidence of redirection", () => {+ for (const processView of ["direct", "unknown"] as const)+ expect(+ redirectedWriteBlocker({ ...view, processView }, [vscode], "uninstall"),+ ).toBeUndefined();+ expect(+ redirectedWriteBlocker(undefined, [vscode], "setup"),+ ).toBeUndefined();+ });+});diff --git a/src/application/ClaudeDesktopConfigLocation.ts b/src/application/ClaudeDesktopConfigLocation.tsnew file mode 100644index 000000000..899aadbbb--- /dev/null+++ b/src/application/ClaudeDesktopConfigLocation.ts@@ -0,0 +1,199 @@+import { lstatSync, readdirSync, realpathSync } from "node:fs";+import { join } from "node:path";++import { err, ok, type Result } from "../domain/result.js";+import {+ windowsAppDataRoots,+ type MsixPackageView,+} from "./MsixPackageStorage.js";++const CONFIG_FILE = "claude_desktop_config.json";++/** Private files compared at most when looking for a redirected AppData view. */+const PROCESS_VIEW_PROBES = 8;++/**+ * Claude Desktop's MSIX package family: package name `Claude` and the+ * publisher ID Windows derives from `CN="Anthropic, PBC", O="Anthropic, PBC",+ * L=San Francisco, S=California, C=US, …`.+ */+export const CLAUDE_DESKTOP_PACKAGE_FAMILY = "Claude_pzs8sxrjxfjjc";++/** `Claude_` plus a 13-character Crockford base32 MSIX publisher ID. */+const CLAUDE_PACKAGE_FAMILY = /^Claude_[0-9a-hjkmnp-tv-z]{13}$/iu;++/** The configuration Claude Desktop reads and the evidence that it is installed. */+export interface ClaudeDesktopLocation {+ readonly configPath: string;+ readonly markerPath: string;+ readonly msixPackage?: MsixPackageView;+}++/** Unresolved Claude Desktop identity, reported instead of guessing a file. */+export interface ClaudeDesktopLocationFailure {+ readonly path: string;+ readonly message: string;+}++/** Synchronous probes; each throws for failures other than absence. */+export interface ClaudeDesktopLocationFileSystem {+ readonly readdir: (path: string) => readonly string[];+ readonly lstat: (path: string) => { isFile(): boolean };+ readonly realpath: (path: string) => string;+}++const systemFileSystem: ClaudeDesktopLocationFileSystem = {+ readdir: (path) => readdirSync(path),+ lstat: (path) => lstatSync(path),+ realpath: (path) => realpathSync.native(path),+};++/**+ * Resolve the `claude_desktop_config.json` that Windows Claude Desktop reads.+ * Without its MSIX package storage, that is the AppData file. With it, the+ * package reads its private copy when one exists and the AppData file+ * otherwise; a new registration goes to the private copy. A `Claude_*`+ * package from another publisher leaves the reader unknown.+ */+export const resolveWindowsClaudeDesktopLocation = (+ home: string,+ env: Readonly<NodeJS.ProcessEnv>,+ fileSystem: ClaudeDesktopLocationFileSystem = systemFileSystem,+): Result<ClaudeDesktopLocation, ClaudeDesktopLocationFailure> => {+ const roots = windowsAppDataRoots(home, env);+ const appDataDirectory = join(roots.roaming, "Claude");+ const appDataConfigPath = join(appDataDirectory, CONFIG_FILE);+ const packagesDirectory = join(roots.local, "Packages");+ let families: readonly string[];+ try {+ families = fileSystem+ .readdir(packagesDirectory)+ .filter((name) => CLAUDE_PACKAGE_FAMILY.test(name));+ } catch (cause: unknown) {+ if (!isMissing(cause))+ return err({+ path: packagesDirectory,+ message: `MSIX package storage ${packagesDirectory} could not be inspected, so REA cannot establish whether Claude Desktop reads ${appDataConfigPath} or a package-private copy: ${errorMessage(cause)}. Repair access to that directory, then rerun.`,+ });+ families = [];+ }+ const foreign = families.filter(+ (name) =>+ name.toLowerCase() !== CLAUDE_DESKTOP_PACKAGE_FAMILY.toLowerCase(),+ );+ if (foreign.length > 0)+ return err({+ path: join(packagesDirectory, foreign[0] ?? ""),+ message: `MSIX package storage ${foreign.map((name) => join(packagesDirectory, name)).join(", ")} uses Claude Desktop's package name with an unrecognized publisher (Claude Desktop is ${CLAUDE_DESKTOP_PACKAGE_FAMILY}). REA cannot establish which ${CONFIG_FILE} that package reads and does not fall back to ${appDataConfigPath}. Remove the unrecognized package, or register REA in the configuration it reads.`,+ });+ const family = families[0];+ if (family === undefined)+ return ok({ configPath: appDataConfigPath, markerPath: appDataDirectory });+ const container = join(packagesDirectory, family);+ const privateDirectory = join(container, "LocalCache", "Roaming", "Claude");+ const privateConfigPath = join(privateDirectory, CONFIG_FILE);+ const privateCopy = present(fileSystem, privateConfigPath);+ if (!privateCopy.ok) return privateCopy;+ const appDataCopy = privateCopy.value+ ? ok(false)+ : present(fileSystem, appDataConfigPath);+ if (!appDataCopy.ok) return appDataCopy;+ return ok({+ configPath:+ privateCopy.value || !appDataCopy.value+ ? privateConfigPath+ : appDataConfigPath,+ markerPath: container,+ msixPackage: {+ packageFamilyName: family,+ privateConfigPath,+ appDataConfigPath,+ virtualizedRoots: [roots.roaming, roots.local],+ processView: processView(+ fileSystem,+ privateDirectory,+ appDataDirectory,+ privateCopy.value,+ ),+ },+ });+};++/**+ * A process the package started sees the package's private files at their+ * AppData paths; any other process sees the real AppData files or nothing.+ * Claude Desktop saves its user data there while it runs, so the+ * configuration, or any other private file, can show which view this is.+ */+const processView = (+ fileSystem: ClaudeDesktopLocationFileSystem,+ privateDirectory: string,+ appDataDirectory: string,+ privateConfig: boolean,+): MsixPackageView["processView"] => {+ let probes: readonly string[];+ try {+ probes = privateConfig+ ? [CONFIG_FILE]+ : fileSystem+ .readdir(privateDirectory)+ .filter((name) => {+ try {+ return fileSystem.lstat(join(privateDirectory, name)).isFile();+ } catch (cause: unknown) {+ // A candidate may vanish or become unreadable while listed.+ void cause;+ return false;+ }+ })+ .slice(0, PROCESS_VIEW_PROBES);+ } catch (cause: unknown) {+ // No private file can be listed, so no view can be compared.+ void cause;+ return "unknown";+ }+ let view: MsixPackageView["processView"] = "unknown";+ for (const name of probes) {+ let privateTarget: string;+ try {+ privateTarget = fileSystem.realpath(join(privateDirectory, name));+ } catch (cause: unknown) {+ // A private file that vanished cannot be compared; try another.+ void cause;+ continue;+ }+ try {+ if (fileSystem.realpath(join(appDataDirectory, name)) === privateTarget)+ return "redirected";+ view = "direct";+ } catch (cause: unknown) {+ if (!isMissing(cause)) return "unknown";+ view = "direct";+ }+ }+ return view;+};++const present = (+ fileSystem: ClaudeDesktopLocationFileSystem,+ path: string,+): Result<boolean, ClaudeDesktopLocationFailure> => {+ try {+ fileSystem.lstat(path);+ return ok(true);+ } catch (cause: unknown) {+ if (isMissing(cause)) return ok(false);+ return err({+ path,+ message: `${path} could not be inspected, so REA cannot establish which ${CONFIG_FILE} Claude Desktop's MSIX package reads: ${errorMessage(cause)}. Repair access to that path, then rerun.`,+ });+ }+};++const isMissing = (cause: unknown): boolean =>+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR");++const errorMessage = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);diff --git a/src/application/ClientRegistrationStatus.ts b/src/application/ClientRegistrationStatus.tsindex caeba4fb6..d107c5f32 100644--- a/src/application/ClientRegistrationStatus.ts+++ b/src/application/ClientRegistrationStatus.ts@@ -155,7 +155,7 @@ export const readClientRegistrationInspections = async (}const parsed = effectiveClientConfiguration(files.value);if (parsed === undefined) {- record(unavailableStatus(client.name, client.configPath, "missing"));+ record(unavailableStatus(client, "missing"));continue;}const policy = await readClientPolicyBlock(@@ -191,7 +191,7 @@ export const readClientRegistrationInspections = async (});continue;}- record(unavailableStatus(client.name, client.configPath, "missing"));+ record(unavailableStatus(client, "missing"));continue;}const registration = parseRegistration(raw, client);@@ -202,8 +202,7 @@ export const readClientRegistrationInspections = async (const activation = registrationActivation(registration, client, parsed);record(configuredStatus(- client.name,- client.configPath,+ client,command,activation === "enabled" &®istrationAligned(@@ -222,11 +221,7 @@ export const readClientRegistrationInspections = async ();} catch (cause: unknown) {record(- unavailableStatus(- client.name,- client.configPath,- isMissing(cause) ? "missing" : "invalid",- ),+ unavailableStatus(client, isMissing(cause) ? "missing" : "invalid"),);}}@@ -352,36 +347,45 @@ const parseRegistration = (return registration;};-const remediation =- "Run rea setup to refresh this registration, then restart the client.";+/** A client that rewrites its file from memory must be quit before setup. */+const remediation = (client: SetupClient): string => {+ if (client.quitBeforeSetup !== true)+ return "Run rea setup to refresh this registration, then restart the client.";+ const name = client.displayName ?? client.name;+ return `Quit ${name} fully, run rea setup to refresh this registration, then start ${name} again. A running ${name} can rewrite its configuration from memory and drop the registration.`;+};const configuredStatus = (- client: string,- configPath: string,+ client: SetupClient,command: RegistrationCommand,state: "aligned" | "stale",policyRemediation?: string,): ClientRegistrationStatus =>state === "aligned"- ? { client, config_path: configPath, command, state, remediation: null }+ ? {+ client: client.name,+ config_path: client.configPath,+ command,+ state,+ remediation: null,+ }: {- client,- config_path: configPath,+ client: client.name,+ config_path: client.configPath,command,state,- remediation: policyRemediation ?? remediation,+ remediation: policyRemediation ?? remediation(client),};const unavailableStatus = (- client: string,- configPath: string,+ client: SetupClient,state: "missing" | "invalid",): ClientRegistrationStatus => ({- client,- config_path: configPath,+ client: client.name,+ config_path: client.configPath,command: [],state,- remediation,+ remediation: remediation(client),});const clientEvidencePresent = async (client: SetupClient): Promise<boolean> => {diff --git a/src/application/MsixPackageStorage.ts b/src/application/MsixPackageStorage.tsnew file mode 100644index 000000000..098b2f1db--- /dev/null+++ b/src/application/MsixPackageStorage.ts@@ -0,0 +1,187 @@+import { lstat } from "node:fs/promises";+import { realpathSync } from "node:fs";+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";+import { err, ok, type Result } from "../domain/result.js";++/**+ * How one MSIX-packaged client reads its AppData configuration. A package+ * with write virtualization saves AppData files to its private+ * `LocalCache\Roaming` copy, then reads that copy whenever it exists and the+ * ordinary AppData file otherwise.+ */+export interface MsixPackageView {+ readonly packageFamilyName: string;+ /** The package-private copy, which shadows the AppData file once it exists. */+ readonly privateConfigPath: string;+ /** The AppData path that unpackaged processes read and write. */+ readonly appDataConfigPath: string;+ /** Roots whose writes the package redirects for processes it starts. */+ readonly virtualizedRoots: readonly string[];+ /**+ * `redirected`: this process sees one of the package's private files at its+ * AppData path, so the running package started it. `direct`: it does not.+ * `unknown`: no private file could be compared.+ */+ readonly processView: "redirected" | "direct" | "unknown";+}++/** Windows' roaming and local application data roots; empty means unset. */+export const windowsAppDataRoots = (+ home: string,+ env: Readonly<NodeJS.ProcessEnv>,+): { readonly roaming: string; readonly local: string } => ({+ roaming: env.APPDATA?.trim() || join(home, "AppData", "Roaming"),+ local: env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"),+});++/** The per-user root of MSIX package data containers. */+export const msixPackagesDirectory = (+ home: string,+ env: Readonly<NodeJS.ProcessEnv>,+): string => join(windowsAppDataRoots(home, env).local, "Packages");++/** Whether `path` is `root` or inside it, using the host's path comparison. */+const pathWithin = (path: string, root: string): boolean => {+ const inner = relative(root, path);+ return (+ inner === "" ||+ (inner !== ".." && !inner.startsWith(`..${sep}`) && !isAbsolute(inner))+ );+};++/**+ * Name the package whose private `LocalCache` holds a canonical path. Its+ * processes see those files at virtual AppData locations; other processes do+ * not, and Windows removes them with the package.+ */+export const packagePrivateStorageFamily = (+ canonicalPath: string,+ packagesDirectory: string,+): string | undefined => {+ if (!pathWithin(canonicalPath, packagesDirectory)) return undefined;+ const [family, storage] = relative(packagesDirectory, canonicalPath).split(+ /[\\/]/u,+ );+ return family !== undefined &&+ family !== "" &&+ storage?.toLowerCase() === "localcache"+ ? family+ : undefined;+};++/**+ * Explain why setup must not register a launcher that exists only in one+ * package's private storage. Other clients could not start it, and doctor+ * outside that package could not verify it.+ */+export const packagePrivateLauncherBlocker = (+ command: readonly string[],+ packagesDirectory: string,+ canonicalPath: (path: string) => string = realpathSync.native,+): string | undefined => {+ // Compare canonical forms: a short-name, junctioned or substituted profile+ // spells the same directory differently.+ let packages = packagesDirectory;+ try {+ packages = canonicalPath(packagesDirectory);+ } catch (cause: unknown) {+ // Without package storage, the spelled path is the only comparison.+ void cause;+ }+ for (const part of command) {+ if (!isAbsolute(part)) continue;+ let resolved: string;+ try {+ resolved = canonicalPath(part);+ } catch (cause: unknown) {+ // A launcher that cannot be resolved is not evidence of package storage.+ void cause;+ continue;+ }+ const family = packagePrivateStorageFamily(resolved, packages);+ if (family !== undefined)+ return `The REA launcher ${part} is stored at ${resolved}, inside the private storage of MSIX package ${family}. Only processes started by that app can see it at ${part}, and Windows removes it with the package, so other clients could not start this registration. Install REA from a terminal that the app did not start (for example with \`npm install -g rea-agents\`), then rerun setup from that terminal.`;+ }+ return undefined;+};++/**+ * Explain why this process must not write `targets`: the running package+ * started it, so writes under its virtualized roots land in that package's+ * private storage, which the targets' owners never read.+ */+const canonicalDestination = (+ path: string,+ canonicalPath: (path: string) => string,+): Result<string, { readonly path: string; readonly detail: string }> => {+ let ancestor = path;+ const missing: string[] = [];+ while (true) {+ try {+ return ok(join(canonicalPath(ancestor), ...missing));+ } catch (cause: unknown) {+ if (+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR") &&+ dirname(ancestor) !== ancestor+ ) {+ missing.unshift(basename(ancestor));+ ancestor = dirname(ancestor);+ continue;+ }+ return err({+ path,+ detail: cause instanceof Error ? cause.message : String(cause),+ });+ }+ }+};++export const redirectedWriteBlocker = (+ view: MsixPackageView | undefined,+ targets: readonly string[],+ operation: "setup" | "uninstall",+ canonicalPath: (path: string) => string = realpathSync.native,+): string | undefined => {+ if (view?.processView !== "redirected" || targets.length === 0)+ return undefined;+ const roots: string[] = [];+ const redirected: string[] = [];+ for (const root of view.virtualizedRoots) {+ const resolved = canonicalDestination(root, canonicalPath);+ if (!resolved.ok)+ return `Cannot establish the MSIX write location for ${resolved.error.path}: ${resolved.error.detail}. Rerun ${operation} from a terminal that this app did not start.`;+ roots.push(resolved.value);+ }+ for (const target of targets) {+ const resolved = canonicalDestination(target, canonicalPath);+ if (!resolved.ok)+ return `Cannot establish the MSIX write location for ${resolved.error.path}: ${resolved.error.detail}. Rerun ${operation} from a terminal that this app did not start.`;+ if (roots.some((root) => pathWithin(resolved.value, root)))+ redirected.push(target);+ }+ if (redirected.length === 0) return undefined;+ return `This process was started by MSIX package ${view.packageFamilyName}, which redirects its writes under ${view.virtualizedRoots.join(" and ")} into the package's private storage. Changes to ${redirected.join(", ")} would not reach the files other apps read. Rerun ${operation} from a terminal that this app did not start.`;+};++/**+ * Whether the package began reading its private copy after the AppData file+ * was chosen, for example by saving its settings when it quit.+ */+export const packageReadTargetChanged = async (+ view: MsixPackageView,+ configPath: string,+): Promise<boolean> => {+ if (configPath !== view.appDataConfigPath) return false;+ try {+ await lstat(view.privateConfigPath);+ return true;+ } catch (cause: unknown) {+ return !(+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR")+ );+ }+};diff --git a/src/application/Setup.configuration.test.ts b/src/application/Setup.configuration.test.tsindex 4ba11f622..3bd08cd4f 100644--- a/src/application/Setup.configuration.test.ts+++ b/src/application/Setup.configuration.test.ts@@ -1,9 +1,43 @@import { describe, expect, it } from "vitest";-import { resolve } from "node:path";+import { join, resolve } from "node:path";import { FakeSetupHost, options } from "./Setup.fixture.js";import { runSetup } from "./Setup.js";import { setupRegistrationCommand } from "./SetupHost.js";+import type { MsixPackageView } from "./MsixPackageStorage.js";+import type { SetupClient } from "./SupportedClients.js";++// Host joins keep containment checks meaningful on POSIX test hosts too.+const PROFILE = String.raw`C:\Users\a`;+const ROAMING = join(PROFILE, "AppData", "Roaming");+const LOCAL = join(PROFILE, "AppData", "Local");+const PRIVATE_CONFIG = join(+ LOCAL,+ "Packages",+ "Claude_pzs8sxrjxfjjc",+ "LocalCache",+ "Roaming",+ "Claude",+ "claude_desktop_config.json",+);+const APPDATA_CONFIG = join(ROAMING, "Claude", "claude_desktop_config.json");++/** Claude Desktop as setup resolves it from its MSIX package storage. */+const msixClaudeDesktop = (+ processView: MsixPackageView["processView"],+): SetupClient => ({+ name: "claude_desktop",+ displayName: "Claude Desktop",+ configPath: PRIVATE_CONFIG,+ quitBeforeSetup: true,+ msixPackage: {+ packageFamilyName: "Claude_pzs8sxrjxfjjc",+ privateConfigPath: PRIVATE_CONFIG,+ appDataConfigPath: APPDATA_CONFIG,+ virtualizedRoots: [ROAMING, LOCAL],+ processView,+ },+});describe("setup workflow", () => {it("omits an aligned managed skill from an otherwise empty plan", async () => {@@ -293,3 +327,85 @@ describe("setup workflow action selection", () => {expect(result.remediation).not.toContain("internal_client_key");});});++describe("MSIX Claude Desktop setup", () => {+ it("discloses which file MSIX Claude Desktop reads and that it must be quit", async () => {+ const host = new FakeSetupHost("win32");+ host.hopper = join(PROFILE, "Hopper");+ host.skill = "unchanged";+ host.clients = [msixClaudeDesktop("direct")];++ const result = await runSetup(+ { ...options(false), clientIds: ["claude_desktop"], dryRun: true },+ host,+ );++ expect(result.status).toBe("planned");+ const [action] = result.plannedActions;+ expect(action?.target).toBe(PRIVATE_CONFIG);+ expect(action?.detail).toContain(+ `Claude Desktop is installed as MSIX package Claude_pzs8sxrjxfjjc, which reads this package-private file instead of ${APPDATA_CONFIG}.`,+ );+ expect(action?.detail).toContain(+ "Quit Claude Desktop fully before approving; closing its window is not enough.",+ );+ });++ it("refuses AppData writes from a process the MSIX package started", async () => {+ const host = new FakeSetupHost("win32");+ host.hopper = join(PROFILE, "Hopper");+ host.skill = "unchanged";+ const vscode = join(ROAMING, "Code", "User", "mcp.json");+ host.clients = [+ msixClaudeDesktop("redirected"),+ { name: "vscode", displayName: "VS Code", configPath: vscode },+ {+ name: "codex",+ displayName: "Codex",+ configPath: join(PROFILE, ".codex", "config.toml"),+ },+ ];++ const blocked = await runSetup(+ { ...options(true), clientIds: ["vscode", "codex"] },+ host,+ );+ expect(blocked.status).toBe("needs_human");+ expect(blocked.remediation).toContain(+ `Changes to ${vscode} would not reach the files other apps read.`,+ );+ expect(host.configurations).toBe(0);++ const homeOnly = await runSetup(+ { ...options(true), clientIds: ["codex"] },+ host,+ );+ expect(homeOnly.status).toBe("ready");+ expect(host.configurations).toBe(1);+ });++ it("refuses registrations whose launcher only one MSIX package can see", async () => {+ const host = new FakeSetupHost("win32");+ host.hopper = join(PROFILE, "Hopper");+ host.registrationCommandBlocker = "Install REA outside the package.";+ host.clients = [+ { name: "codex", displayName: "Codex", configPath: "/codex.toml" },+ ];++ const blocked = await runSetup(+ { ...options(true), clientIds: ["codex"] },+ host,+ );+ expect(blocked.status).toBe("needs_human");+ expect(blocked.remediation).toBe("Install REA outside the package.");+ expect(host.configurations).toBe(0);+ expect(host.skillInstalls).toBe(0);++ const skillOnly = await runSetup(+ { ...options(true), clientIds: [], installSkill: true },+ host,+ );+ expect(skillOnly.status).toBe("ready");+ expect(host.skillInstalls).toBe(1);+ });+});diff --git a/src/application/Setup.fixture.ts b/src/application/Setup.fixture.tsindex a99897494..3c7c21d35 100644--- a/src/application/Setup.fixture.ts+++ b/src/application/Setup.fixture.ts@@ -25,6 +25,7 @@ export class FakeSetupHost implements SetupHost {return skillDestinations(this.homeDirectory, clientIds);}readonly registrationCommand: readonly string[];+ registrationCommandBlocker?: string;nodeVersion = "24.18.0";version: string | undefined = "14.5";distribution: LinuxDistribution | undefined;diff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.tsindex 981b829a4..a868c6177 100644--- a/src/application/SetupClientConfiguration.ts+++ b/src/application/SetupClientConfiguration.ts@@ -29,6 +29,7 @@ import { PRODUCT_IDENTITY } from "../identity.js";import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";+import { packageReadTargetChanged } from "./MsixPackageStorage.js";import {readRegularFile,readRegularFileText,@@ -40,7 +41,10 @@ import type {ClientConfigurationResult,SetupProviderEnvironment,} from "./SetupTypes.js";-import type { SetupClient } from "./SupportedClients.js";+import {+ registrationWriteBlocker,+ type SetupClient,+} from "./SupportedClients.js";export class ClientConfigurationCleanupRollbackFailure extends RegularFileCleanupFailure<string> {constructor(@@ -187,6 +191,13 @@ const persistClientConfiguration = async ({desired,fallbackServers,}: ClientConfigurationUpdate): Promise<ClientConfigurationResult> => {+ // The plan chose this file; an MSIX package may have switched to its+ // private copy since, for example when it quit.+ if (+ client.msixPackage !== undefined &&+ (await packageReadTargetChanged(client.msixPackage, client.configPath))+ )+ return { status: "failed", reason: "target_changed" };const backupPath =original === undefined ? undefined : `${client.configPath}.rea.backup`;let recoveryBackupPath: string | undefined;@@ -358,6 +369,25 @@ export const inspectClientConfiguration = async (client: SetupClient,providerEnvironment: SetupProviderEnvironment,command: readonly string[],+): Promise<ClientConfigurationInspection> => {+ const inspection = await inspectClientDocument(+ client,+ providerEnvironment,+ command,+ );+ if (inspection.status !== "create" && inspection.status !== "update")+ return inspection;+ // A change the running client would overwrite is not a persisted registration.+ const blocker = registrationWriteBlocker(client, "setup");+ return blocker === undefined+ ? inspection+ : { status: "invalid", remediation: blocker };+};++const inspectClientDocument = async (+ client: SetupClient,+ providerEnvironment: SetupProviderEnvironment,+ command: readonly string[],): Promise<ClientConfigurationInspection> => {if (client.configPathError !== undefined)return { status: "invalid", remediation: client.configPathError };diff --git a/src/application/SetupClients.ts b/src/application/SetupClients.tsindex d86d04b9e..5ceccb21a 100644--- a/src/application/SetupClients.ts+++ b/src/application/SetupClients.ts@@ -9,6 +9,8 @@ import type { SetupClient } from "./SupportedClients.js";export const failedConfigurationMessage = (result: Extract<ClientConfigurationResult, { readonly status: "failed" }>,): string => {+ if (result.reason === "target_changed")+ return "The client began reading a different configuration file after the plan was shown, so no change was made. Rerun setup to review the new target.";if (result.reason === "path")return "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.";if (result.reason === "backup")diff --git a/src/application/SetupHost.ts b/src/application/SetupHost.tsindex 7ac6828fd..022cecc62 100644--- a/src/application/SetupHost.ts+++ b/src/application/SetupHost.ts@@ -44,6 +44,10 @@ import {retryRegularFileCleanup,} from "./RegularFileRead.js";import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";+import {+ msixPackagesDirectory,+ packagePrivateLauncherBlocker,+} from "./MsixPackageStorage.js";import type {SetupHost,SetupInitialState,@@ -66,6 +70,31 @@ export const setupRegistrationCommand = (]: [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];+/**+ * The launcher setup registers, and why it must not be registered when it+ * exists only inside one MSIX package's private storage.+ */+const setupRegistration = (+ platform: NodeJS.Platform,+ homeDirectory: string,+ environment: Readonly<NodeJS.ProcessEnv>,+): Pick<SetupHost, "registrationCommand" | "registrationCommandBlocker"> => {+ const registrationCommand = setupRegistrationCommand(+ platform,+ invokingPackageRunner(environment, platform),+ );+ const registrationCommandBlocker =+ platform === "win32"+ ? packagePrivateLauncherBlocker(+ registrationCommand,+ msixPackagesDirectory(homeDirectory, environment),+ )+ : undefined;+ return registrationCommandBlocker === undefined+ ? { registrationCommand }+ : { registrationCommand, registrationCommandBlocker };+};+export const filterClientsNeedingConfigure = async (host: SetupHost,detectedClients: readonly SetupClient[],@@ -117,10 +146,7 @@ export const systemSetupHost = (homeDirectory,skillDestinations: (clientIds) =>skillDestinations(homeDirectory, clientIds, environment, platform),- registrationCommand: setupRegistrationCommand(- platform,- invokingPackageRunner(environment, platform),- ),+ ...setupRegistration(platform, homeDirectory, environment),nodeVersion: process.versions.node,macosVersion: () => doctorHost.macosVersion(),linuxDistribution: readLinuxDistribution,diff --git a/src/application/SetupPlan.ts b/src/application/SetupPlan.tsindex a78697c80..35db28de4 100644--- a/src/application/SetupPlan.ts+++ b/src/application/SetupPlan.ts@@ -8,12 +8,18 @@ import {import type { SkillDestination } from "./SetupSkill.js";import { macHopperInstallDisclosure } from "./MacHopper.js";import type {+ ClientConfigurationInspection,SetupAction,SetupClientState,SetupHost,SetupProviderEnvironment,} from "./SetupTypes.js";-import type { SetupClient } from "./SupportedClients.js";+import {+ appDataRedirection,+ registrationPersistenceDetail,+ type SetupClient,+} from "./SupportedClients.js";+import { redirectedWriteBlocker } from "./MsixPackageStorage.js";import type { DoctorReport } from "./Doctor.js";import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";@@ -161,12 +167,58 @@ export const planSetupActions = async (input: {blocker: `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`,};}- const clientPlans = inspections.flatMap(({ client, inspection }) =>+ const clientPlans = plannedClientWrites(+ inspections,+ input.discovery.installHopper,+ );+ const plannedActions = setupPlan({+ platform: input.host.platform,+ homeDirectory: input.host.homeDirectory,+ installHopper: input.discovery.installHopper,+ installSkill: input.installSkill,+ skillClientIds: input.skillClientIds,+ skillDestinations: input.host.skillDestinations(input.skillClientIds),+ clients: clientPlans,+ providerEnvironment: input.providerEnvironment,+ ...(input.discovery.linuxPackageFamily === undefined+ ? {}+ : { linuxPackageFamily: input.discovery.linuxPackageFamily }),+ command: input.command,+ });+ const blocker =+ (clientPlans.length > 0+ ? input.host.registrationCommandBlocker+ : undefined) ??+ redirectedWriteBlocker(+ appDataRedirection(input.discovery.clients),+ plannedActions+ .filter(({ kind }) => kind !== "install_hopper")+ .map(({ target }) => target),+ "setup",+ );+ return {+ plannedActions,+ selectedClients,+ clientsToConfigure: selectedClients.filter((client) =>+ clientPlans.some(({ client: planned }) => planned.name === client.name),+ ),+ ...(blocker === undefined ? {} : { blocker }),+ };+};++/** Selected clients whose registration setup writes, with the disclosed operation. */+const plannedClientWrites = (+ inspections: readonly {+ readonly client: SetupClient;+ readonly inspection: ClientConfigurationInspection;+ }[],+ installHopper: boolean,+) =>+ inspections.flatMap(({ client, inspection }) =>client.format !== "unsupported" &&(inspection.status === "create" ||inspection.status === "update" ||- (input.discovery.installHopper &&- inspection.status === "already_current"))+ (installHopper && inspection.status === "already_current"))? [{client,@@ -182,27 +234,6 @@ export const planSetupActions = async (input: {]: [],);- return {- plannedActions: setupPlan({- platform: input.host.platform,- homeDirectory: input.host.homeDirectory,- installHopper: input.discovery.installHopper,- installSkill: input.installSkill,- skillClientIds: input.skillClientIds,- skillDestinations: input.host.skillDestinations(input.skillClientIds),- clients: clientPlans,- providerEnvironment: input.providerEnvironment,- ...(input.discovery.linuxPackageFamily === undefined- ? {}- : { linuxPackageFamily: input.discovery.linuxPackageFamily }),- command: input.command,- }),- selectedClients,- clientsToConfigure: selectedClients.filter((client) =>- clientPlans.some(({ client: planned }) => planned.name === client.name),- ),- };-};/** Describe every selected setup mutation before user approval. */const setupPlan = (input: {@@ -259,7 +290,7 @@ const setupPlan = (input: {label: client.displayName ?? client.name,target: client.configPath,detail: clientConfigurationDetail(- client.displayName ?? client.name,+ client,input.command,input.providerEnvironment,input.installHopper,@@ -303,7 +334,7 @@ const majorVersion = (version: string): number =>Number.parseInt(version.split(".")[0] ?? "0", 10);const clientConfigurationDetail = (- client: string,+ client: SetupClient,command: readonly string[],environment: SetupProviderEnvironment,installHopper: boolean,@@ -320,5 +351,6 @@ const clientConfigurationDetail = (? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation.": " The HOPPER_LAUNCHER_PATH value shown above is the current fallback; if this plan installs Hopper, REA will replace it with the launcher path reported by that installation.": "";- return `Add the REA MCP registration for ${client}; preserve unrelated configuration. The backup path reflects the configuration inspected for this plan; if that file changes before execution, setup will select a recovery path for its current contents. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}`;+ const persistence = registrationPersistenceDetail(client);+ return `Add the REA MCP registration for ${client.displayName ?? client.name}; preserve unrelated configuration. The backup path reflects the configuration inspected for this plan; if that file changes before execution, setup will select a recovery path for its current contents. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}${persistence === undefined ? "" : ` ${persistence}`}`;};diff --git a/src/application/SetupTypes.ts b/src/application/SetupTypes.tsindex 241e0f6dd..f0cf61c59 100644--- a/src/application/SetupTypes.ts+++ b/src/application/SetupTypes.ts@@ -25,7 +25,12 @@ export type ClientConfigurationResult =}| {readonly status: "failed";- readonly reason: "path" | "backup" | "write" | "readback";+ readonly reason:+ | "path"+ | "target_changed"+ | "backup"+ | "write"+ | "readback";}| {readonly status: "failed";@@ -55,6 +60,8 @@ export interface SetupHost {readonly homeDirectory: string;skillDestinations(clientIds: readonly string[]): readonly SkillDestination[];readonly registrationCommand: readonly string[];+ /** Why no client may be registered with `registrationCommand` from this host. */+ readonly registrationCommandBlocker?: string;readonly nodeVersion: string;macosVersion(): Promise<string | undefined>;linuxDistribution(): Promise<LinuxDistribution | undefined>;diff --git a/src/application/SupportedClients.ts b/src/application/SupportedClients.tsindex 0a7352627..8407da4c0 100644--- a/src/application/SupportedClients.ts+++ b/src/application/SupportedClients.ts@@ -7,6 +7,8 @@ import {resolveHermesClientHome,} from "./HermesClientHome.js";import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";+import { resolveWindowsClaudeDesktopLocation } from "./ClaudeDesktopConfigLocation.js";+import type { MsixPackageView } from "./MsixPackageStorage.js";/** One supported client configuration location. */export interface SetupClient {@@ -29,6 +31,10 @@ export interface SetupClient {/** Same-scope fallback ZCode stops loading after its first native server. */readonly zcodeFallbackPath?: string;readonly markerPath?: string;+ /** MSIX package storage that decides which configuration the client reads. */+ readonly msixPackage?: MsixPackageView;+ /** A running client can rewrite its configuration from memory. */+ readonly quitBeforeSetup?: boolean;readonly format?:| "json"| "toml"@@ -61,12 +67,35 @@ interface ClientPathContext {readonly env: Readonly<NodeJS.ProcessEnv>;}-interface ClientDefinition {+/** One resolved configuration location and its detection evidence. */+interface ClientLocation {+ readonly configPath: string;+ readonly markerPath: string;+ readonly msixPackage?: MsixPackageView;+}++type ClientDefinition = ClientDefinitionBase &+ (+ | {+ readonly configPath: ClientPath;+ readonly markerPath: ClientPath;+ readonly location?: undefined;+ }+ | {+ /** Resolve configuration and marker together when they share probes. */+ readonly location: (+ context: ClientPathContext,+ ) => Result<ClientLocation, ClientPathFailure>;+ readonly configPath?: undefined;+ readonly markerPath?: undefined;+ }+ );++interface ClientDefinitionBase {readonly name: string;readonly displayName: string;- readonly configPath: ClientPath;- readonly markerPath: ClientPath;readonly format: NonNullable<SetupClient["format"]>;+ readonly quitBeforeSetup?: boolean;readonly zcodeFallbackPath?: (context: ClientPathContext) => string;readonly skillPath?: ClientPath;readonly configPaths?: (context: ClientPathContext) => readonly string[];@@ -111,16 +140,20 @@ const traeUserDirectory = ({return join(xdgConfigHome({ home, platform, env }), "Trae", "User");};-const claudeDesktopDirectory = ({- home,- platform,- env,-}: ClientPathContext): string => {- if (platform === "win32")- return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude");- if (platform === "linux")- return join(xdgConfigHome({ home, platform, env }), "Claude");- return join(home, "Library", "Application Support", "Claude");+/** Windows packaging decides which file Claude Desktop reads; see its resolver. */+const claudeDesktopLocation = (+ context: ClientPathContext,+): Result<ClientLocation, ClientPathFailure> => {+ if (context.platform === "win32")+ return resolveWindowsClaudeDesktopLocation(context.home, context.env);+ const directory =+ context.platform === "linux"+ ? join(xdgConfigHome(context), "Claude")+ : join(context.home, "Library", "Application Support", "Claude");+ return ok({+ configPath: join(directory, "claude_desktop_config.json"),+ markerPath: directory,+ });};const claudeCodeConfigDirectory = ({ home, env }: ClientPathContext): string =>@@ -211,6 +244,55 @@ export const manualRegistrationRemediation = (? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION: undefined;+/**+ * Facts a setup plan must disclose so an approved registration persists:+ * which file an MSIX package reads, and that a running client can overwrite it.+ */+export const registrationPersistenceDetail = (+ client: SetupClient,+): string | undefined => {+ const name = client.displayName ?? client.name;+ const msix = client.msixPackage;+ const packageDetail =+ msix === undefined+ ? undefined+ : client.configPath === msix.privateConfigPath+ ? `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this package-private file instead of ${msix.appDataConfigPath}.`+ : `${name} is installed as MSIX package ${msix.packageFamilyName}, which reads this file until it saves its own copy at ${msix.privateConfigPath}.`;+ const quitDetail =+ client.quitBeforeSetup === true+ ? `Quit ${name} fully before approving; closing its window is not enough. A running ${name} can rewrite this file from memory and drop the registration. Start it again after setup.`+ : undefined;+ const details = [packageDetail, quitDetail].filter(+ (detail): detail is string => detail !== undefined,+ );+ return details.length === 0 ? undefined : details.join(" ");+};++/**+ * Why this process must not change an MSIX client's configuration. A process+ * the running app started sees its redirected AppData, and the app would+ * overwrite the change from memory; an unknown view cannot rule that out.+ */+export const registrationWriteBlocker = (+ client: SetupClient,+ operation: "setup" | "uninstall",+): string | undefined => {+ const msix = client.msixPackage;+ if (msix === undefined || msix.processView === "direct") return undefined;+ const name = client.displayName ?? client.name;+ return msix.processView === "redirected"+ ? `This process was started from ${name}'s MSIX package ${msix.packageFamilyName}: its AppData is redirected into that package, so ${name} is running and would overwrite ${msix.privateConfigPath} from memory. Quit ${name} fully, then rerun ${operation} from a terminal that ${name} did not start.`+ : `REA cannot tell whether ${name}'s MSIX package ${msix.packageFamilyName} started this process, because none of its files under ${dirname(msix.privateConfigPath)} could be compared with ${dirname(msix.appDataConfigPath)}. A running ${name} would overwrite the change. Open ${name} once if it has never run, quit it fully, then rerun ${operation} from a terminal that ${name} did not start.`;+};++/** The MSIX package view, if any, that redirects this process's AppData writes. */+export const appDataRedirection = (+ clients: readonly SetupClient[],+): MsixPackageView | undefined =>+ clients.find(({ msixPackage }) => msixPackage?.processView === "redirected")+ ?.msixPackage;+const OMP_PROFILE_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/u;const OMP_RESERVED_PROFILE =/^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/iu;@@ -408,9 +490,8 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [{name: "claude_desktop",displayName: "Claude Desktop",- configPath: (context: ClientPathContext) =>- join(claudeDesktopDirectory(context), "claude_desktop_config.json"),- markerPath: claudeDesktopDirectory,+ location: claudeDesktopLocation,+ quitBeforeSetup: true,format: "json",},{@@ -627,6 +708,19 @@ const resolvePath = (return typeof resolved === "string" ? ok(resolved) : resolved;};+const resolveLocation = (+ definition: ClientDefinition,+ context: ClientPathContext,+): Result<ClientLocation, ClientPathFailure> => {+ if (definition.location !== undefined) return definition.location(context);+ const config = resolvePath(definition.configPath, context);+ if (!config.ok) return config;+ const marker = resolvePath(definition.markerPath, context);+ return marker.ok+ ? ok({ configPath: config.value, markerPath: marker.value })+ : marker;+};+/** Describe every client location that setup, doctor, or uninstall may inspect. */export const supportedClients = (home: string,@@ -637,27 +731,16 @@ export const supportedClients = (const definitions: readonly ClientDefinition[] = SUPPORTED_CLIENT_DEFINITIONS;return definitions.map((definition) => {try {- const config = resolvePath(definition.configPath, context);- const marker = config.ok- ? resolvePath(definition.markerPath, context)- : config;- if (!config.ok)- return {- name: definition.name,- displayName: definition.displayName,- format: definition.format,- configPath: config.error.path,- configPathError: config.error.message,- };- if (!marker.ok)+ const location = resolveLocation(definition, context);+ if (!location.ok)return {name: definition.name,displayName: definition.displayName,format: definition.format,- configPath: marker.error.path,- configPathError: marker.error.message,+ configPath: location.error.path,+ configPathError: location.error.message,};- const configPath = config.value;+ const { configPath, markerPath, msixPackage } = location.value;return {name: definition.name,displayName: definition.displayName,@@ -675,7 +758,11 @@ export const supportedClients = (...(definition.zcodeFallbackPath === undefined? {}: { zcodeFallbackPath: definition.zcodeFallbackPath(context) }),- markerPath: marker.value,+ markerPath,+ ...(msixPackage === undefined ? {} : { msixPackage }),+ ...(definition.quitBeforeSetup === true+ ? { quitBeforeSetup: true }+ : {}),format: definition.format,};} catch (cause: unknown) {diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.tsindex a7f051a49..a4561c45e 100644--- a/src/application/Uninstall.ts+++ b/src/application/Uninstall.ts@@ -32,10 +32,16 @@ import {} from "./RegularFileRead.js";import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import {+ appDataRedirection,manualRegistrationRemediation,+ registrationWriteBlocker,supportedClients,type SetupClient,} from "./SupportedClients.js";+import {+ redirectedWriteBlocker,+ type MsixPackageView,+} from "./MsixPackageStorage.js";export { isUninstallFailure } from "./UninstallFailure.js";interface ManagedPathStats {@@ -93,6 +99,7 @@ export interface UninstallHost {/** Report a configuration that cannot be read safely, before any removal. */inspectClient(client: SetupClient): Promise<UninstallItem | undefined>;removeClient(client: SetupClient): Promise<UninstallItem>;+ inspectSkill?(): Promise<UninstallItem | undefined>;removeSkill(): Promise<UninstallItem>;purgeData(): Promise<readonly UninstallItem[]>;close?(): Promise<string | undefined>;@@ -118,6 +125,8 @@ export const runUninstall = async (const blocking = await host.inspectClient(client);if (blocking !== undefined) blocked.push(blocking);}+ const skillBlocker = await host.inspectSkill?.();+ if (skillBlocker !== undefined) blocked.push(skillBlocker);const items: UninstallItem[] =blocked.length > 0? [@@ -209,27 +218,70 @@ export const systemUninstallHost = (selectedHome ?? homeDirectoryFromEnvironment(environment, platform);const resources = new ArtifactResourceScope();const fileSystem = selectedFileSystem ?? systemFileSystem(resources);+ // Set with the client list: the package view that redirects this+ // process's AppData writes, if any.+ let redirection: MsixPackageView | undefined;+ const clientWriteBlocker = (client: SetupClient): string | undefined =>+ registrationWriteBlocker(client, "uninstall") ??+ redirectedWriteBlocker(redirection, [client.configPath], "uninstall");+ const skillWriteBlocker = (path: string): string | undefined =>+ redirectedWriteBlocker(redirection, [path], "uninstall");return {- clients: () =>- Promise.resolve(- supportedClients(home, platform, environment).flatMap((client) =>- client.configPaths === undefined- ? [client]- : client.configPaths.map((configPath) => ({- ...client,- configPath,- })),+ clients: () => {+ const clients = supportedClients(home, platform, environment);+ redirection = appDataRedirection(clients);+ return Promise.resolve(+ clients.flatMap((client) =>+ uninstallConfigPaths(client).map((configPath) => ({+ ...client,+ configPath,+ })),),- ),+ );+ },inspectClient: async (client) => {const read = await readClientConfiguration(client, fileSystem);- return read.kind === "item" && read.item.status === "failed"- ? read.item- : undefined;+ if (read.kind === "item")+ return read.item.status === "failed" ? read.item : undefined;+ const removal = clientRegistrationRemoval(read.parsed, client);+ if (!removal.removeNative && removal.legacyPath === undefined)+ return undefined;+ // A removal the running package would revert, or redirect into its+ // private storage, would leave the registration in place.+ const blocker = clientWriteBlocker(client);+ return blocker === undefined+ ? undefined+ : item(client.name, "failed", blocker);+ },+ removeClient: (client) =>+ removeClient(client, fileSystem, () => clientWriteBlocker(client)),+ inspectSkill: async () => {+ for (const destination of skillDestinations(+ home,+ undefined,+ environment,+ platform,+ )) {+ const inspected = await inspectManagedSkill(+ destination.path,+ destination.client,+ fileSystem,+ );+ if (inspected?.status === "failed") return inspected;+ if (inspected !== undefined) continue;+ const blocker = skillWriteBlocker(destination.path);+ if (blocker !== undefined) return item("skill", "failed", blocker);+ }+ return undefined;},- removeClient: (client) => removeClient(client, fileSystem),removeSkill: () =>- removeManagedSkills(home, fileSystem, environment, platform),+ removeManagedSkills(+ home,+ fileSystem,+ environment,+ platform,+ skillWriteBlocker,+ ),purgeData: () => purgeManagedData(join(home, ".rea"), fileSystem),close: async () => {try {@@ -242,6 +294,36 @@ export const systemUninstallHost = (};};+/**+ * Every user file that can hold REA's registration for one client. An MSIX+ * package can read either its private copy or the AppData file, and earlier+ * setups wrote the AppData file, so both lose REA's entry.+ */+const uninstallConfigPaths = (client: SetupClient): readonly string[] => [+ ...new Set([+ ...(client.configPaths ?? [client.configPath]),+ ...(client.msixPackage === undefined+ ? []+ : [+ client.msixPackage.privateConfigPath,+ client.msixPackage.appDataConfigPath,+ ]),+ ]),+];++/** Whether removal would change this configuration. */+const registrationPresent = (parsed: ClientConfigurationDocument): boolean => {+ const name = PRODUCT_IDENTITY.mcpServerKey;+ return (+ Object.hasOwn(parsed.servers, name) ||+ // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`.+ legacyClientServerPath(parsed, name) !== undefined ||+ // Harness ownership is the stable entry id. A stale or malformed launcher+ // still belongs to that id, and so does a direct patch that projects no row.+ (parsed.dialect === "dsh" && dshDocument(parsed.document).carriesEntry)+ );+};+type ClientConfigurationRead =| { readonly kind: "item"; readonly item: UninstallItem }| {@@ -308,21 +390,47 @@ const itemRead = (result: UninstallItem): ClientConfigurationRead => ({item: result,});+/**+ * Share the exact ownership and applicability decision with preflight. A+ * removable legacy entry carries its document path, so removal edits exactly+ * the entry this decision admitted.+ */+const clientRegistrationRemoval = (+ parsed: ClientConfigurationDocument,+ client: SetupClient,+): {+ readonly removeNative: boolean;+ readonly legacyPath: readonly string[] | undefined;+} => {+ const name = PRODUCT_IDENTITY.mcpServerKey;+ if (+ parsed.dialect === "dsh" &&+ dshDocument(parsed.document).hasUnknownStructure+ )+ return { removeNative: false, legacyPath: undefined };+ const legacyPath = legacyClientServerPath(parsed, name);+ return {+ removeNative:+ (parsed.dialect === "dsh" && dshDocument(parsed.document).carriesEntry) ||+ (Object.hasOwn(parsed.servers, name) &&+ isOwnedRegistration(parsed.servers[name], client)),+ legacyPath:+ legacyPath !== undefined &&+ isOwnedRegistration(parsed.legacyServers[name], client)+ ? legacyPath+ : undefined,+ };+};+const removeClient = async (client: SetupClient,fileSystem: UninstallFileSystem,+ writeBlocker?: () => string | undefined,): Promise<UninstallItem> => {const read = await readClientConfiguration(client, fileSystem);if (read.kind === "item") return read.item;const { transactionPath, original, parsed } = read;const name = PRODUCT_IDENTITY.mcpServerKey;- // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`.- const legacyPath = legacyClientServerPath(parsed, name);- const hasNative = Object.hasOwn(parsed.servers, name);- // Harness ownership is the stable entry id. A stale or malformed launcher- // still belongs to that id, and so does a direct patch that projects no row.- const carriesDshEntry =- parsed.dialect === "dsh" && dshDocument(parsed.document).carriesEntry;if (parsed.dialect === "dsh" &&dshDocument(parsed.document).hasUnknownStructure@@ -332,20 +440,21 @@ const removeClient = async ("retained","A Cordis expression may produce registration rows, so the patch was retained without changes.",);- if (!hasNative && legacyPath === undefined && !carriesDshEntry)+ if (!registrationPresent(parsed))return item(client.name, "skipped", "REA registration is absent.");- const removeNative =- carriesDshEntry ||- (hasNative && isOwnedRegistration(parsed.servers[name], client));- const removeLegacy =- legacyPath !== undefined &&- isOwnedRegistration(parsed.legacyServers[name], client);+ const { removeNative, legacyPath } = clientRegistrationRemoval(+ parsed,+ client,+ );+ const removeLegacy = legacyPath !== undefined;if (!removeNative && !removeLegacy)return item(client.name,"retained","The rea-named registration is not REA-owned.",);+ const blocker = writeBlocker?.();+ if (blocker !== undefined) return item(client.name, "failed", blocker);const remaining = { ...parsed.servers };if (removeNative) delete remaining[name];const document = withClientServers(@@ -355,7 +464,7 @@ const removeClient = async ();const editedPaths = [...(removeNative ? [clientServerPath(parsed, name)] : []),- ...(removeLegacy ? [legacyPath] : []),+ ...(legacyPath === undefined ? [] : [legacyPath]),];const backupPath = `${client.configPath}.rea.backup`;try {@@ -516,12 +625,13 @@ const removeManagedSkills = async (fileSystem: UninstallFileSystem,environment: Readonly<NodeJS.ProcessEnv>,platform: NodeJS.Platform,+ writeBlocker?: (path: string) => string | undefined,): Promise<UninstallItem> => {// Every destination shares one summary item, so each result is labeled by// the directory it refers to.const results = await Promise.all(skillDestinations(home, undefined, environment, platform).map(({ path }) =>- removeManagedSkill(path, path, fileSystem),+ removeManagedSkill(path, path, fileSystem, writeBlocker),),);const failed = results.find(({ status }) => status === "failed");@@ -552,11 +662,11 @@ const removeManagedSkills = async ();};-const removeManagedSkill = async (+const inspectManagedSkill = async (path: string,name: string,fileSystem: UninstallFileSystem,-): Promise<UninstallItem> => {+): Promise<UninstallItem | undefined> => {let root: ManagedPathStats;try {root = await fileSystem.stat(path);@@ -594,6 +704,20 @@ const removeManagedSkill = async (if (!isManagedSkillManifest(content))return item(name, "retained", "Skill manifest is not REA-owned.");+ return undefined;+};++const removeManagedSkill = async (+ path: string,+ name: string,+ fileSystem: UninstallFileSystem,+ writeBlocker?: (path: string) => string | undefined,+): Promise<UninstallItem> => {+ const inspection = await inspectManagedSkill(path, name, fileSystem);+ if (inspection !== undefined) return inspection;+ const blocker = writeBlocker?.(path);+ if (blocker !== undefined) return item(name, "failed", blocker);+const manifestName = "SKILL.md";const otherFiles = MANAGED_SKILL_FILES.filter((relativePath) => relativePath !== manifestName,diff --git a/tests/boundary/filesystem/claudeDesktopClientConfiguration.test.ts b/tests/boundary/filesystem/claudeDesktopClientConfiguration.test.tsnew file mode 100644index 000000000..b411aeb4b--- /dev/null+++ b/tests/boundary/filesystem/claudeDesktopClientConfiguration.test.ts@@ -0,0 +1,412 @@+import {+ access,+ mkdir,+ readFile,+ rm,+ symlink,+ writeFile,+} from "node:fs/promises";+import { dirname, join } from "node:path";++import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { CLAUDE_DESKTOP_PACKAGE_FAMILY } from "../../../src/application/ClaudeDesktopConfigLocation.js";+import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js";+import { npxRegistrationCommand } from "../../../src/application/ClientRegistrationIdentity.js";+import {+ configureClientConfiguration,+ inspectClientConfiguration,+} from "../../../src/application/SetupClientConfiguration.js";+import { detectClients } from "../../../src/application/SetupHost.js";+import {+ supportedClients,+ type SetupClient,+} from "../../../src/application/SupportedClients.js";+import {+ runUninstall,+ systemUninstallHost,+} from "../../../src/application/Uninstall.js";+import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++/** The Windows registration setup writes, independent of the test host. */+const command = npxRegistrationCommand("win32");+const CONFIG = "claude_desktop_config.json";++const roots: string[] = [];+beforeEach(clearClientLocationEnvironment);+afterEach(async () => {+ vi.unstubAllEnvs();+ await Promise.all(+ roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),+ );+});++/** A Windows profile with separate roaming and local AppData roots. */+const windowsProfile = async () => {+ const home = await createTestTempDirectory("rea-claude-desktop-");+ roots.push(home);+ const env = {+ APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),+ };+ const appDataConfig = join(env.APPDATA, "Claude", CONFIG);+ const container = join(+ env.LOCALAPPDATA,+ "Packages",+ CLAUDE_DESKTOP_PACKAGE_FAMILY,+ );+ const privateConfig = join(+ container,+ "LocalCache",+ "Roaming",+ "Claude",+ CONFIG,+ );+ return { home, env, appDataConfig, container, privateConfig };+};++const claudeDesktop = (+ home: string,+ env: Readonly<Record<string, string>>,+): SetupClient => {+ const client = supportedClients(home, "win32", env).find(+ ({ name }) => name === "claude_desktop",+ );+ if (client === undefined) throw new Error("claude_desktop is not supported");+ return client;+};++const writeJson = async (path: string, value: unknown): Promise<void> => {+ await mkdir(dirname(path), { recursive: true });+ await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);+};++const readJson = async (path: string): Promise<Record<string, unknown>> =>+ JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;++const reaEntry = { command: command[0], args: command.slice(1) };++describe("Windows Claude Desktop configuration location", () => {+ it("uses AppData when no MSIX package storage exists", async () => {+ const { home, env, appDataConfig } = await windowsProfile();+ await mkdir(+ join(env.LOCALAPPDATA, "Packages", "Contoso.App_8wekyb3d8bbwe"),+ {+ recursive: true,+ },+ );++ const client = claudeDesktop(home, env);++ expect(client.configPath).toBe(appDataConfig);+ expect(client.markerPath).toBe(dirname(appDataConfig));+ expect(client.msixPackage).toBeUndefined();+ expect(client.quitBeforeSetup).toBe(true);+ });++ it("uses the package-private copy that the MSIX package reads", async () => {+ const { home, env, appDataConfig, container, privateConfig } =+ await windowsProfile();+ await writeJson(privateConfig, { preferences: { theme: "dark" } });+ await writeJson(appDataConfig, { mcpServers: {} });++ const client = claudeDesktop(home, env);++ expect(client.configPath).toBe(privateConfig);+ expect(client.markerPath).toBe(container);+ expect(client.msixPackage).toEqual({+ packageFamilyName: CLAUDE_DESKTOP_PACKAGE_FAMILY,+ privateConfigPath: privateConfig,+ appDataConfigPath: appDataConfig,+ virtualizedRoots: [env.APPDATA, env.LOCALAPPDATA],+ processView: "direct",+ });+ expect(+ (await detectClients(home, "win32", env)).map(({ name }) => name),+ ).toContain("claude_desktop");+ });++ it("uses AppData while the MSIX package has no private copy", async () => {+ const { home, env, appDataConfig, container, privateConfig } =+ await windowsProfile();+ await mkdir(container, { recursive: true });+ await writeJson(appDataConfig, { preferences: {} });++ const client = claudeDesktop(home, env);++ expect(client.configPath).toBe(appDataConfig);+ expect(client.msixPackage).toMatchObject({+ privateConfigPath: privateConfig,+ processView: "unknown",+ });+ // No private file shows whether the running package started this process.+ const inspection = await inspectClientConfiguration(client, {}, command);+ expect(inspection.status).toBe("invalid");+ expect(inspection.status === "invalid" && inspection.remediation).toContain(+ "Open Claude Desktop once if it has never run, quit it fully, then rerun setup",+ );+ });++ it("creates the private copy when the MSIX package has no configuration", async () => {+ const { home, env, privateConfig } = await windowsProfile();+ await writeJson(join(dirname(privateConfig), "Local State"), {});++ const client = claudeDesktop(home, env);+ expect(client.configPath).toBe(privateConfig);+ expect(client.msixPackage?.processView).toBe("direct");+ await expect(+ inspectClientConfiguration(client, {}, command),+ ).resolves.toEqual({ status: "create" });+ await expect(+ configureClientConfiguration(client, {}, command),+ ).resolves.toEqual({ status: "configured" });+ expect(await readJson(privateConfig)).toEqual({+ mcpServers: { rea: reaEntry },+ });+ });++ it("reports an unrecognized Claude package instead of falling back to AppData", async () => {+ const { home, env, appDataConfig } = await windowsProfile();+ const foreign = join(env.LOCALAPPDATA, "Packages", "Claude_abcdefghjkmnp");+ await mkdir(foreign, { recursive: true });+ await writeJson(appDataConfig, { mcpServers: {} });++ const client = claudeDesktop(home, env);++ expect(client.configPath).toBe(foreign);+ expect(client.configPathError).toContain("unrecognized publisher");+ expect(client.configPathError).toContain(CLAUDE_DESKTOP_PACKAGE_FAMILY);+ expect(+ (await detectClients(home, "win32", env)).map(({ name }) => name),+ ).not.toContain("claude_desktop");+ const status = (+ await readClientRegistrationStatuses(home, "unused", {+ platform: "win32",+ environment: env,+ })+ ).find(({ client: name }) => name === "claude_desktop");+ expect(status).toMatchObject({ state: "invalid", config_path: foreign });+ await expect(+ inspectClientConfiguration(client, {}, command),+ ).resolves.toMatchObject({ status: "invalid" });+ });+});++describe("MSIX Claude Desktop registration lifecycle", () => {+ it("registers in the private copy and reports an AppData-only entry as missing", async () => {+ const { home, env, appDataConfig, privateConfig } = await windowsProfile();+ const privateOriginal = {+ coworkUserFilesPath: "C:\\Users\\a\\Claude",+ preferences: { menuBarEnabled: false },+ mcpServers: { other: { command: "other", args: ["serve"] } },+ };+ await writeJson(privateConfig, privateOriginal);+ // Earlier setups wrote AppData, which the package never reads.+ await writeJson(appDataConfig, { mcpServers: { rea: reaEntry } });+ const appDataOriginal = await readFile(appDataConfig, "utf8");+ const status = async () =>+ (+ await readClientRegistrationStatuses(home, "unused", {+ platform: "win32",+ environment: env,+ })+ ).find(({ client }) => client === "claude_desktop");++ expect(await status()).toMatchObject({+ state: "missing",+ config_path: privateConfig,+ });+ expect((await status())?.remediation).toContain(+ "Quit Claude Desktop fully",+ );++ const client = claudeDesktop(home, env);+ await expect(+ inspectClientConfiguration(client, {}, command),+ ).resolves.toEqual({+ status: "update",+ backupPath: `${privateConfig}.rea.backup`,+ });+ await expect(+ configureClientConfiguration(client, {}, command),+ ).resolves.toEqual({+ status: "configured",+ backupPath: `${privateConfig}.rea.backup`,+ });++ expect(await readJson(privateConfig)).toEqual({+ ...privateOriginal,+ mcpServers: {+ ...privateOriginal.mcpServers,+ rea: reaEntry,+ },+ });+ expect(await readJson(`${privateConfig}.rea.backup`)).toEqual(+ privateOriginal,+ );+ expect(await readFile(appDataConfig, "utf8")).toBe(appDataOriginal);+ expect(await status()).toMatchObject({+ state: "aligned",+ config_path: privateConfig,+ });+ await expect(+ configureClientConfiguration(client, {}, command),+ ).resolves.toEqual({ status: "unchanged" });+ });++ it("refuses to write from a process the running package started", async () => {+ const { home, env, privateConfig } = await windowsProfile();+ await writeJson(privateConfig, { preferences: {} });+ const resolved = claudeDesktop(home, env);+ if (resolved.msixPackage === undefined)+ throw new Error("expected MSIX package storage");+ // Only a packaged process sees AppData redirected; model that observation.+ const client: SetupClient = {+ ...resolved,+ msixPackage: { ...resolved.msixPackage, processView: "redirected" },+ };++ const inspection = await inspectClientConfiguration(client, {}, command);++ expect(inspection.status).toBe("invalid");+ expect(inspection.status === "invalid" && inspection.remediation).toContain(+ "Quit Claude Desktop fully, then rerun setup from a terminal that Claude Desktop did not start",+ );+ expect(await readJson(privateConfig)).toEqual({ preferences: {} });++ await configureClientConfiguration(resolved, {}, command);+ await expect(+ inspectClientConfiguration(client, {}, command),+ ).resolves.toEqual({ status: "already_current" });+ });++ it("refuses a write once the package reads a newer private copy", async () => {+ const { home, env, appDataConfig, privateConfig } = await windowsProfile();+ await writeJson(join(dirname(privateConfig), "Preferences"), {});+ await writeJson(appDataConfig, { preferences: {} });+ const client = claudeDesktop(home, env);+ expect(client.configPath).toBe(appDataConfig);+ // Quitting the app after the plan was shown can save its private copy.+ await writeJson(privateConfig, { preferences: {} });++ await expect(+ configureClientConfiguration(client, {}, command),+ ).resolves.toEqual({ status: "failed", reason: "target_changed" });+ expect(await readJson(appDataConfig)).toEqual({ preferences: {} });+ expect(await readJson(privateConfig)).toEqual({ preferences: {} });+ });++ it("registers in AppData while the package has no private copy", async () => {+ const { home, env, appDataConfig, privateConfig } = await windowsProfile();+ await writeJson(join(dirname(privateConfig), "Preferences"), {});+ await writeJson(appDataConfig, { preferences: { theme: "light" } });++ const client = claudeDesktop(home, env);+ expect(client.configPath).toBe(appDataConfig);+ expect(client.msixPackage?.processView).toBe("direct");+ await expect(+ configureClientConfiguration(client, {}, command),+ ).resolves.toMatchObject({ status: "configured" });++ expect(await readJson(appDataConfig)).toEqual({+ preferences: { theme: "light" },+ mcpServers: { rea: reaEntry },+ });+ await expect(access(privateConfig)).rejects.toMatchObject({+ code: "ENOENT",+ });+ });+});++describe("MSIX Claude Desktop uninstall", () => {+ it("refuses uninstall when the package view is unknown", async () => {+ const { home, env, appDataConfig, container } = await windowsProfile();+ await mkdir(container, { recursive: true });+ await writeJson(appDataConfig, { mcpServers: { rea: reaEntry } });++ const result = await runUninstall(+ false,+ systemUninstallHost(home, undefined, env, "win32"),+ );++ expect(result.status).toBe("failed");+ expect(result.items).toContainEqual(+ expect.objectContaining({+ name: "claude_desktop",+ status: "failed",+ detail: expect.stringContaining("rerun uninstall"),+ }),+ );+ expect(await readJson(appDataConfig)).toEqual({+ mcpServers: { rea: reaEntry },+ });+ });++ it("retains an unrelated rea-named entry when the package view is unknown", async () => {+ const { home, env, appDataConfig, container } = await windowsProfile();+ await mkdir(container, { recursive: true });+ const unrelated = { mcpServers: { rea: { command: "unrelated-server" } } };+ await writeJson(appDataConfig, unrelated);+ const result = await runUninstall(+ false,+ systemUninstallHost(home, undefined, env, "win32"),+ );+ expect(result.status).toBe("complete");+ expect(await readJson(appDataConfig)).toEqual(unrelated);+ });++ it("blocks managed skill removal through redirected AppData before any removal", async () => {+ const { home, env, appDataConfig, privateConfig } = await windowsProfile();+ await writeJson(join(dirname(privateConfig), "Preferences"), {});+ await mkdir(dirname(dirname(appDataConfig)), { recursive: true });+ await symlink(dirname(privateConfig), dirname(appDataConfig), "dir");+ const agents = join(env.APPDATA, "dsh", "agents");+ const manifest = join(+ agents,+ "skills",+ "reverse-engineer-anything",+ "SKILL.md",+ );+ await mkdir(dirname(manifest), { recursive: true });+ await writeFile(+ manifest,+ "---\nname: reverse-engineer-anything\n---\nmanaged fixture\n",+ );+ const environment = { ...env, DSH_AGENTS_HOME: agents };+ const result = await runUninstall(+ false,+ systemUninstallHost(home, undefined, environment, "win32"),+ );+ expect(result.status).toBe("failed");+ expect(result.items).toContainEqual(+ expect.objectContaining({+ name: "skill",+ status: "failed",+ detail: expect.stringContaining("redirects its writes"),+ }),+ );+ expect(await readFile(manifest, "utf8")).toContain("managed fixture");+ });++ it("removes REA from both the private copy and AppData on uninstall", async () => {+ const { home, env, appDataConfig, privateConfig } = await windowsProfile();+ await writeJson(privateConfig, {+ preferences: {},+ mcpServers: { other: { command: "other" }, rea: reaEntry },+ });+ await writeJson(appDataConfig, { mcpServers: { rea: reaEntry } });++ const result = await runUninstall(+ false,+ systemUninstallHost(home, undefined, env, "win32"),+ );++ expect(result.status).toBe("complete");+ expect(await readJson(privateConfig)).toEqual({+ preferences: {},+ mcpServers: { other: { command: "other" } },+ });+ expect(await readJson(appDataConfig)).toEqual({ mcpServers: {} });+ });+});diff --git a/tests/process-global/updateMaintenance.test.ts b/tests/process-global/updateMaintenance.test.tsindex ae057bab2..171761478 100644--- a/tests/process-global/updateMaintenance.test.ts+++ b/tests/process-global/updateMaintenance.test.ts@@ -25,6 +25,7 @@ beforeEach(async () => {HOME: home,USERPROFILE: home,APPDATA: join(home, "AppData", "Roaming"),+ LOCALAPPDATA: join(home, "AppData", "Local"),CLAUDE_CONFIG_DIR: home,CODEX_HOME: join(home, ".codex"),COPILOT_HOME: join(home, ".copilot"),