Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(clients): register ZCode during setup (#1564)
Iven Koo51d6c87cdbf5
diff --git a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.mdindex 9b06a93fc..dbddb0eb9 100644--- a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md+++ b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md@@ -46,7 +46,7 @@ rea setup --client codex --dry-run --jsonUse the current supported client's ID: `claude_code`, `claude_desktop`, `codex`,`cursor`, `gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`,`copilot_cli`, `commandcode`, `qwen_code`, `vscode`, `grok_build`, `omp`, `pi`,-`hermes`, `dsh`, or `grok_bot`. If unknown, inspect `doctor --json` before choosing a+`hermes`, `zcode`, `dsh`, or `grok_bot`. If unknown, inspect `doctor --json` before choosing ascope. `grok_bot` uses a chat registration step rather than local `mcp.json`.For unsupported clients, use version-pinned manual stdio registration or CLI.diff --git a/docs/client-configuration.md b/docs/client-configuration.mdindex 640f559eb..16ba81400 100644--- a/docs/client-configuration.md+++ b/docs/client-configuration.md@@ -145,6 +145,26 @@ REA follows `HERMES_HOME` whitespace trimming, environment-variable expansion,and home expansion before resolving that profile. Setup previews the resolvedconfiguration and skill destinations; doctor and uninstall use those same paths.+## ZCode++For [ZCode](https://zcode.z.ai/en/docs/mcp-services), setup registers `rea` in the nested `mcp.servers` table of the+user-level `~/.zcode/cli/config.json`. Entries carry `command`, `args`, and+`env` without a transport discriminator. ZCode discovers personal skills from+`~/.zcode/skills` rather than the shared directory, so setup installs its+skill copy there.++ZCode reads the user-scope `~/.agents/mcp.json` fallback only while the native+`.zcode` config defines no servers at all, with no merging. When setup writes+the first native server into an empty table, it copies the fallback's+`mcpServers` entries into the native table so they keep loading, and leaves+the fallback file untouched. Existing REA environment overrides are preserved+when refreshing its command. A malformed or unreadable fallback file fails setup instead of+being silently suppressed; repair or remove it and rerun. ZCode disables a+server with `enable: false` on its entry; doctor reports such a registration+as stale, and rerunning setup removes the flag to repair it. Native configuration+uses strict JSON; setup refuses comments, trailing commas and a BOM rather than+writing a registration ZCode cannot load.+## DeepSeek HarnessDeepSeek Harness registers MCP clients through a Cordis YAML patch sequencediff --git a/docs/installation.md b/docs/installation.mdindex 181b75c92..69e800f05 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -280,6 +280,7 @@ hosted connector; see [its configuration](client-configuration.md#other-client-s| OMP | `omp` || Pi | `pi` || Hermes | `hermes` |+| ZCode | `zcode` || DeepSeek Harness | `dsh` |`dsh` is main-only until a release after 6.4.0. The registry check above doesdiff --git a/src/application/ClientConfigurationDocument.ts b/src/application/ClientConfigurationDocument.tsindex 27b5393d2..cecbd440a 100644--- a/src/application/ClientConfigurationDocument.ts+++ b/src/application/ClientConfigurationDocument.ts@@ -86,6 +86,7 @@ export const clientConfigurationServersKey = (case "hermes":return "mcp_servers";case "opencode":+ case "zcode":return "mcp";case "vscode":return "servers";@@ -116,6 +117,8 @@ const parseDocument = (if (isEmptyClientConfigurationText(text)) return {};// Hermes stores MCP servers in `mcp_servers` inside a YAML document.if (format === "hermes") return objectSchema.parse(parseYaml(text));+ // ZCode loads nonempty native files with strict JSON.parse.+ if (format === "zcode") return objectSchema.parse(JSON.parse(text));const errors: ParseError[] = [];// Accept a UTF-8 BOM without shifting diagnostics or editing the original text.const jsonText = text.startsWith("\uFEFF") ? ` ${text.slice(1)}` : text;@@ -142,6 +145,23 @@ const requireObject = (});};+/** ZCode reads the same-scope fallback as strict JSON with a mcpServers table. */+export const parseZcodeFallbackConfiguration = (+ text: string,+): ClientConfigurationDocument => {+ const document = requireObject(JSON.parse(text), "ZCode fallback root");+ return {+ document,+ servers:+ document.mcpServers === undefined+ ? {}+ : requireObject(document.mcpServers, "ZCode fallback mcpServers"),+ serversPath: ["mcpServers"],+ dialect: "json",+ legacyServers: {},+ };+};+/** Members of OpenCode V2's `mcp` object that are not server names. */const OPENCODE_V2_MCP_SETTINGS = new Set(["servers", "timeout"]);@@ -169,6 +189,21 @@ export const parseClientConfiguration = (const value = document[serversKey];const servers =value === undefined ? {} : requireObject(value, `"${serversKey}"`);+ // ZCode reads stdio servers from the nested `mcp.servers` table of+ // `~/.zcode/cli/config.json`; entries carry `command`, `args`, and `env`.+ if (format === "zcode") {+ const nested = servers.servers;+ return {+ document,+ servers:+ nested === undefined+ ? {}+ : requireObject(nested, `"${serversKey}.servers"`),+ serversPath: [serversKey, "servers"],+ dialect: format,+ legacyServers: {},+ };+ }const native = servers.servers;// A V1 server named `servers` has a string `type` discriminator; the V2// table may instead hold a server object named `type`.@@ -228,8 +263,16 @@ export const withClientServers = (: editDshDocument(parsed);const [key = "", nested] = parsed.serversPath;if (nested === undefined) return { ...parsed.document, [key]: servers };- const outer = { ...objectSchema.parse(parsed.document[key]) };- if (removeLegacy !== undefined && !OPENCODE_V2_MCP_SETTINGS.has(removeLegacy))+ // A fresh document may not hold the outer table yet (for example a new+ // ZCode `config.json` without an `mcp` object), so treat absence as empty.+ const outerValue = parsed.document[key];+ const outer =+ outerValue === undefined ? {} : { ...objectSchema.parse(outerValue) };+ if (+ parsed.dialect === "opencode_v2" &&+ removeLegacy !== undefined &&+ !OPENCODE_V2_MCP_SETTINGS.has(removeLegacy)+ )delete outer[removeLegacy];return { ...parsed.document, [key]: { ...outer, [nested]: servers } };};diff --git a/src/application/ClientRegistrationStatus.ts b/src/application/ClientRegistrationStatus.tsindex dc246d5e6..e2696e088 100644--- a/src/application/ClientRegistrationStatus.ts+++ b/src/application/ClientRegistrationStatus.ts@@ -226,7 +226,9 @@ const registrationAligned = (const command = [registration.command, ...registration.args];if ((client.format !== "grok" && registration.disabled === true) ||- (registration.enabled === false && !forcedEnabled)+ (registration.enabled === false && !forcedEnabled) ||+ // ZCode's native flag is `enable`; other dialects leave that field opaque.+ (client.format === "zcode" && registration.enable === false))return false;if (!isOwnedClientRegistrationCommand(command, currentCommandPath))diff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.tsindex a4f4e837e..bfab80cbf 100644--- a/src/application/SetupClientConfiguration.ts+++ b/src/application/SetupClientConfiguration.ts@@ -1,5 +1,9 @@import { readClientPolicyBlock } from "./GeminiClientSettings.js";-import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";+import {+ readClientConfigurationFiles,+ readConfigurationText,+} from "./ClientConfigurationFiles.js";+import { err, ok, type Result } from "../domain/result.js";import {clientRegistrationEntry,clientConfigurationValuesEqual,@@ -8,6 +12,7 @@ import {legacyClientServerPath,OMP_DISABLED_SERVERS_KEY,parseClientConfiguration,+ parseZcodeFallbackConfiguration,serializeClientConfiguration,withClientServers,type ClientConfigurationDocument,@@ -120,12 +125,15 @@ const configureClientDocument = async (void cause;return { status: "failed", reason: "readback" };}- const desired = clientConfigurationDesired(- client,- environment,- command,- parsed,- );+ const fallback = await readZcodeFallbackServers(client, parsed);+ if (!fallback.ok) {+ throwCleanupFailure(fallback.error);+ return { status: "failed", reason: "readback" };+ }+ const desired = clientConfigurationDesired(client, environment, command, {+ ...parsed,+ servers: { ...fallback.value, ...parsed.servers },+ });if (registrationCurrent(parsed, desired)) return { status: "unchanged" };return persistClientConfiguration({client,@@ -134,6 +142,7 @@ const configureClientDocument = async (original,parsed,desired,+ fallbackServers: fallback.value,});};@@ -144,6 +153,7 @@ interface ClientConfigurationUpdate {readonly original: string | undefined;readonly parsed: ClientConfigurationDocument;readonly desired: unknown;+ readonly fallbackServers: Readonly<Record<string, unknown>>;}const persistClientConfiguration = async ({@@ -153,6 +163,7 @@ const persistClientConfiguration = async ({original,parsed,desired,+ fallbackServers,}: ClientConfigurationUpdate): Promise<ClientConfigurationResult> => {const backupPath =original === undefined ? undefined : `${client.configPath}.rea.backup`;@@ -169,7 +180,11 @@ const persistClientConfiguration = async ({);const registered = withClientServers(parsed,- { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired },+ {+ ...fallbackServers,+ ...parsed.servers,+ [PRODUCT_IDENTITY.mcpServerKey]: desired,+ },PRODUCT_IDENTITY.mcpServerKey,);// OMP's denylist would hide the registration; keep every other listed name.@@ -194,6 +209,9 @@ const persistClientConfiguration = async ({await writeFileAtomic(transactionPath,serializeClientConfiguration(document, format, original, [+ ...Object.keys(fallbackServers)+ .filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey)+ .map((name) => clientServerPath(parsed, name)),clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),...(legacyPath === undefined ? [] : [legacyPath]),...(enableOmp ? [[OMP_DISABLED_SERVERS_KEY]] : []),@@ -213,7 +231,14 @@ const persistClientConfiguration = async ({await readRegularFileText(transactionPath),format,);- if (!registrationCurrent(readback, desired)) {+ if (+ !registrationCurrent(readback, desired) ||+ Object.entries(fallbackServers).some(+ ([name, entry]) =>+ name !== PRODUCT_IDENTITY.mcpServerKey &&+ !clientConfigurationValuesEqual(readback.servers[name], entry),+ )+ ) {await restoreConfig(transactionPath, original);return { status: "failed", reason: "readback" };}@@ -329,7 +354,14 @@ export const inspectClientConfiguration = async (original = await readRegularFileText(transactionPath);} catch (cause: unknown) {if (cause instanceof RegularFileCleanupFailure) throw cause;- if (isMissing(cause)) return { status: "create" };+ if (isMissing(cause)) {+ const fallback = await readZcodeFallbackServers(client);+ if (!fallback.ok) {+ throwCleanupFailure(fallback.error);+ return { status: "invalid", remediation: fallback.error.detail };+ }+ return { status: "create" };+ }return {status: "invalid",remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${cause instanceof Error ? cause.message : String(cause)}`,@@ -359,6 +391,11 @@ export const inspectClientConfiguration = async ();if (registrationCurrent(parsed, desired))return { status: "already_current" };+ const fallback = await readZcodeFallbackServers(client, parsed);+ if (!fallback.ok) {+ throwCleanupFailure(fallback.error);+ return { status: "invalid", remediation: fallback.error.detail };+ }} catch (cause: unknown) {if (cause instanceof RegularFileCleanupFailure) throw cause;// Malformed configuration is reported with the invalid remediation.@@ -382,6 +419,48 @@ const throwCleanupFailure = (error: ClientConfigurationFileError): void => {if (error.cleanupFailure !== undefined) throw error.cleanupFailure;};+/** Admit the fallback only when the first native ZCode server would suppress it. */+const readZcodeFallbackServers = async (+ client: SetupClient,+ parsed?: ClientConfigurationDocument,+): Promise<+ Result<Readonly<Record<string, unknown>>, ClientConfigurationFileError>+> => {+ if (+ client.format !== "zcode" ||+ (parsed !== undefined && Object.keys(parsed.servers).length > 0)+ )+ return ok({});+ const path = client.zcodeFallbackPath;+ const detail = `The ZCode fallback configuration ${path ?? "path"} is unresolved, malformed or unreadable. Repair it before rerunning setup: the first native server would suppress that fallback.`;+ if (path === undefined)+ return err({ kind: "unreadable", path: client.configPath, detail });+ const transactionPath = await resolveClientConfigTransactionPath(path);+ if (transactionPath === undefined)+ return err({ kind: "unreadable", path, detail });+ const source = await readConfigurationText(transactionPath);+ if (!source.ok)+ return err({ ...source.error, detail: `${detail} ${source.error.detail}` });+ if (source.value === undefined) return ok({});+ try {+ const parsed = parseZcodeFallbackConfiguration(source.value);+ const environment = clientRegistrationEnvironment(parsed);+ if (!environment.ok)+ return err({+ kind: "malformed",+ path,+ detail: `${detail} ${environment.error.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}`,+ });+ return ok(parsed.servers);+ } catch (cause: unknown) {+ return err({+ kind: "malformed",+ path,+ detail: `${detail} ${cause instanceof Error ? cause.message : String(cause)}`,+ });+ }+};+const preserveConfigBackup = async (source: string,destination: string,diff --git a/src/application/SupportedClients.ts b/src/application/SupportedClients.tsindex b44e5017a..5c74bb972 100644--- a/src/application/SupportedClients.ts+++ b/src/application/SupportedClients.ts@@ -26,6 +26,8 @@ export interface SetupClient {};/** Unresolved path evidence only; consumers must not perform I/O on it. */readonly configPathError?: string;+ /** Same-scope fallback ZCode stops loading after its first native server. */+ readonly zcodeFallbackPath?: string;readonly markerPath?: string;readonly format?:| "json"@@ -38,6 +40,7 @@ export interface SetupClient {| "omp"| "pi"| "hermes"+ | "zcode"| "dsh"| "unsupported";}@@ -64,6 +67,7 @@ interface ClientDefinition {readonly configPath: ClientPath;readonly markerPath: ClientPath;readonly format: NonNullable<SetupClient["format"]>;+ readonly zcodeFallbackPath?: (context: ClientPathContext) => string;readonly skillPath?: ClientPath;readonly configPaths?: (context: ClientPathContext) => readonly string[];readonly geminiSettings?: (@@ -499,6 +503,16 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [markerPath: hermesDirectory,format: "hermes",},+ {+ name: "zcode",+ zcodeFallbackPath: ({ home }: ClientPathContext) =>+ join(home, ".agents", "mcp.json"),+ displayName: "ZCode",+ configPath: [".zcode", "cli", "config.json"],+ markerPath: [".zcode", "cli"],+ skillPath: [".zcode", "skills"],+ format: "zcode",+ },{name: "dsh",displayName: "DeepSeek Harness",@@ -590,6 +604,9 @@ export const supportedClients = (...new Set([...definition.configPaths(context), configPath]),],}),+ ...(definition.zcodeFallbackPath === undefined+ ? {}+ : { zcodeFallbackPath: definition.zcodeFallbackPath(context) }),markerPath: marker.value,format: definition.format,};diff --git a/tests/boundary/filesystem/clientLifecycle.test.ts b/tests/boundary/filesystem/clientLifecycle.test.tsindex 89c4dc95a..caf154949 100644--- a/tests/boundary/filesystem/clientLifecycle.test.ts+++ b/tests/boundary/filesystem/clientLifecycle.test.ts@@ -69,6 +69,7 @@ describe("client configuration filesystem lifecycle", () => {"omp","pi","hermes",+ "zcode","dsh","grok_bot",]);diff --git a/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts b/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.tsindex 19a1c77d5..3bf33c312 100644--- a/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts+++ b/tests/boundary/filesystem/setupClientConfigCleanupOwnership.test.ts@@ -31,6 +31,66 @@ beforeEach(async () => {afterEach(() => openMock.mockReset());+describe("ZCode fallback cleanup ownership", () => {+ it.each(["preflight", "configure"])(+ "retains a failed ZCode fallback close during %s until host cleanup",+ async (operation) => {+ const home = await createTestTempDirectory("rea-zcode-fallback-close-");+ const host = systemSetupHost(+ { platform: "linux", homeDirectory: home } as DoctorHost,+ { HOME: home },+ );+ const client = (await host.supportedClients()).find(+ ({ name }) => name === "zcode",+ );+ if (client?.zcodeFallbackPath === undefined)+ throw new Error("ZCode fallback path missing");+ const fallback = client.zcodeFallbackPath;+ await mkdir(dirname(fallback), { recursive: true });+ const original = '{"mcpServers":{"other":{"command":"other"}}}\n';+ await writeFile(fallback, original);+ const closeAttempts: object[] = [];+ let allowClose = false;+ openMock.mockImplementation(async (...args) => {+ const handle = await actualFs.open(...args);+ if (String(args[0]) !== fallback) return handle;+ const nativeClose = handle.close.bind(handle);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ closeAttempts.push(handle);+ if (!allowClose) throw new Error("held fallback handle");+ await nativeClose();+ });+ return handle;+ });+ try {+ const action =+ operation === "preflight"+ ? host.inspectClientConfiguration?.(client, {}, ["rea", "mcp"])+ : host.configureClient(client, {}, ["rea", "mcp"]);+ if (action === undefined) throw new Error("setup preflight missing");+ await expect(action).rejects.toMatchObject({+ _tag: "ConfigurationError",+ cause: expect.any(RegularFileCleanupFailure),+ cleanup: { resources: [fallback] },+ });+ expect(closeAttempts).toHaveLength(2);+ expect(closeAttempts[0]).toBe(closeAttempts[1]);+ expect(await readFile(fallback, "utf8")).toBe(original);+ await expect(readFile(client.configPath)).rejects.toMatchObject({+ code: "ENOENT",+ });+ allowClose = true;+ expect(await host.close?.()).toBeUndefined();+ expect(closeAttempts).toHaveLength(3);+ expect(closeAttempts[2]).toBe(closeAttempts[0]);+ } finally {+ allowClose = true;+ await host.close?.();+ }+ },+ );+});+describe("setup client configuration cleanup ownership", () => {it("stops client configuration and retries the same alignment handle from host close", async () => {const home = await createTestTempDirectory("rea-setup-config-close-");diff --git a/tests/boundary/filesystem/zcodeClientConfiguration.test.ts b/tests/boundary/filesystem/zcodeClientConfiguration.test.tsnew file mode 100644index 000000000..4b00a2e01--- /dev/null+++ b/tests/boundary/filesystem/zcodeClientConfiguration.test.ts@@ -0,0 +1,401 @@+import { execFile } from "node:child_process";+import { mkdir, readFile, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { promisify } from "node:util";++import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js";+import { npxRegistrationCommand } from "../../../src/application/ClientRegistrationIdentity.js";+import {+ configureClientConfiguration,+ inspectClientConfiguration,+} from "../../../src/application/SetupClientConfiguration.js";+import { skillDestinations } from "../../../src/application/SetupSkill.js";+import { supportedClients } from "../../../src/application/SupportedClients.js";+import { systemUninstallHost } from "../../../src/application/Uninstall.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";++/**+ * The registration command setup writes on the host running the tests. Windows+ * wraps it in `cmd.exe /d /c`, so the expected entry follows the host too.+ */+const command = npxRegistrationCommand(process.platform);++beforeEach(clearClientLocationEnvironment);+afterEach(() => vi.unstubAllEnvs());++const zcodePath = (+ home: string,+ platform: NodeJS.Platform = "linux",+ env: Parameters<typeof supportedClients>[2] = {},+) => supportedClients(home, platform, env).find(({ name }) => name === "zcode");++describe("ZCode configuration paths", () => {+ it("resolves the user config file and marker directory", () => {+ expect(zcodePath("/home/a")).toEqual({+ name: "zcode",+ displayName: "ZCode",+ configPath: join("/home/a", ".zcode", "cli", "config.json"),+ markerPath: join("/home/a", ".zcode", "cli"),+ format: "zcode",+ zcodeFallbackPath: join("/home/a", ".agents", "mcp.json"),+ });+ expect(zcodePath("/Users/a", "darwin")?.configPath).toBe(+ join("/Users/a", ".zcode", "cli", "config.json"),+ );+ expect(zcodePath("C:\\Users\\a", "win32")?.configPath).toBe(+ join("C:\\Users\\a", ".zcode", "cli", "config.json"),+ );+ });++ it("resolves the personal skills directory beside the config root", () => {+ expect(+ skillDestinations("/home/a", ["zcode"]).map(({ path }) => path),+ ).toEqual([+ join("/home/a", ".zcode", "skills", "reverse-engineer-anything"),+ ]);+ });+});++const zcodeClient = async () => {+ const home = await createTestTempDirectory("rea-zcode-");+ const client = zcodePath(home, process.platform);+ if (client?.markerPath === undefined) throw new Error("missing ZCode client");+ await mkdir(client.markerPath, { recursive: true });+ return { home, client };+};++describe("ZCode JSON registration", () => {+ it("upserts rea into mcp.servers while preserving unrelated settings", async () => {+ const { home, client } = await zcodeClient();+ await writeFile(+ client.configPath,+ `{+ "mcp": {+ "rea": { "unrelated": true },+ "servers": {+ "other": { "command": "other-server" }+ }+ }+}`,+ );++ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.mcp.rea).toEqual({ unrelated: true });+ expect(parsed.mcp.servers.other).toEqual({ command: "other-server" });+ expect(parsed.mcp.servers.rea).toEqual({+ command: command[0],+ args: command.slice(1),+ });++ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "unchanged",+ });+ expect(+ (+ await readClientRegistrationStatuses(home, undefined, {+ platform: process.platform,+ environment: {},+ })+ ).find(({ client }) => client === "zcode"),+ ).toMatchObject({ state: "aligned", command });+ });++ it("creates the mcp.servers table in an existing config without servers", async () => {+ const { client } = await zcodeClient();+ await writeFile(+ client.configPath,+ JSON.stringify({ ui: { theme: "dark" } }, null, 2),+ );+ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.ui).toEqual({ theme: "dark" });+ expect(parsed.mcp.servers.rea).toEqual({+ command: command[0],+ args: command.slice(1),+ });+ });++ it("registers into an empty config file", async () => {+ const { client } = await zcodeClient();+ await writeFile(client.configPath, "");+ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.mcp.servers.rea).toEqual({+ command: command[0],+ args: command.slice(1),+ });+ });++ it("removes only the rea entry on uninstall", async () => {+ const { home, client } = await zcodeClient();+ await writeFile(+ client.configPath,+ JSON.stringify(+ { mcp: { servers: { other: { command: "other-server" } } } },+ null,+ 2,+ ),+ );+ await configureClientConfiguration(client, {}, command);++ expect((await systemUninstallHost(home).removeClient(client)).status).toBe(+ "removed",+ );+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.mcp.servers.other).toEqual({ command: "other-server" });+ expect(parsed.mcp.servers.rea).toBeUndefined();+ });+});++const fallbackPath = (home: string) => join(home, ".agents", "mcp.json");++describe("ZCode .agents fallback preservation", () => {+ it.each([undefined, '{"ui":{"theme":"dark"}}\n', '{"mcp":{"servers":{}}}\n'])(+ "migrates fallback servers with native config %s",+ async (original) => {+ const { home, client } = await zcodeClient();+ if (original !== undefined) await writeFile(client.configPath, original);+ await mkdir(join(home, ".agents"), { recursive: true });+ await writeFile(+ fallbackPath(home),+ JSON.stringify(+ {+ mcpServers: {+ other: { command: "other-server", env: { TOKEN: "x" } },+ rea: {+ command: "old-rea",+ args: ["mcp"],+ env: {+ REA_MCP_INPUT_SCHEMA_PROFILE: "compact",+ GHIDRA_INSTALL_DIR: "/caller/ghidra",+ CALLER_CHOICE: "keep-me",+ },+ },+ },+ },+ null,+ 2,+ ),+ );++ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.mcp.servers.other).toEqual({+ command: "other-server",+ env: { TOKEN: "x" },+ });+ expect(parsed.mcp.servers.rea).toEqual({+ command: command[0],+ args: command.slice(1),+ env: {+ REA_MCP_INPUT_SCHEMA_PROFILE: "compact",+ GHIDRA_INSTALL_DIR: "/caller/ghidra",+ CALLER_CHOICE: "keep-me",+ },+ });+ if (original !== undefined) {+ expect(await readFile(`${client.configPath}.rea.backup`, "utf8")).toBe(+ original,+ );+ if (JSON.parse(original).ui !== undefined)+ expect(parsed.ui).toEqual({ theme: "dark" });+ }+ // The fallback file stays in place; ZCode ignores it from now on.+ expect(+ JSON.parse(await readFile(fallbackPath(home), "utf8")).mcpServers.other,+ ).toEqual({ command: "other-server", env: { TOKEN: "x" } });+ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "unchanged",+ });+ },+ );++ it("leaves an existing native table alone instead of merging the fallback", async () => {+ const { home, client } = await zcodeClient();+ await mkdir(join(home, ".agents"), { recursive: true });+ await writeFile(+ fallbackPath(home),+ JSON.stringify(+ { mcpServers: { shared: { command: "fallback-server" } } },+ null,+ 2,+ ),+ );+ await writeFile(+ client.configPath,+ JSON.stringify(+ { mcp: { servers: { existing: { command: "existing-server" } } } },+ null,+ 2,+ ),+ );++ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ const parsed = JSON.parse(await readFile(client.configPath, "utf8"));+ expect(parsed.mcp.servers.existing).toEqual({+ command: "existing-server",+ });+ expect(parsed.mcp.servers.rea).toEqual({+ command: command[0],+ args: command.slice(1),+ });+ expect(parsed.mcp.servers.shared).toBeUndefined();+ });+});++describe("ZCode fallback admission", () => {+ it.each([{ PORT: 123 }, { REA_MCP_INPUT_SCHEMA_PROFILE: "unknown" }])(+ "refuses malformed fallback REA environment %j before native writes",+ async (env) => {+ const { home, client } = await zcodeClient();+ await mkdir(join(home, ".agents"), { recursive: true });+ const original = JSON.stringify({+ mcpServers: { rea: { command: "old-rea", env } },+ });+ await writeFile(fallbackPath(home), original);+ expect(+ await inspectClientConfiguration(client, {}, command),+ ).toMatchObject({+ status: "invalid",+ remediation: expect.stringContaining(+ Object.keys(env)[0] ?? "environment",+ ),+ });+ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "failed",+ reason: "readback",+ });+ await expect(readFile(client.configPath)).rejects.toMatchObject({+ code: "ENOENT",+ });+ expect(await readFile(fallbackPath(home), "utf8")).toBe(original);+ },+ );++ it("fails closed when the fallback configuration is malformed", async () => {+ const { home, client } = await zcodeClient();+ await mkdir(join(home, ".agents"), { recursive: true });+ await writeFile(fallbackPath(home), "{ not json");++ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "failed",+ reason: "readback",+ });+ await expect(readFile(client.configPath, "utf8")).rejects.toThrow();+ expect(await inspectClientConfiguration(client, {}, command)).toMatchObject(+ { status: "invalid" },+ );+ });++ it("fails closed when the fallback path is not a regular file", async () => {+ const { home, client } = await zcodeClient();+ await mkdir(fallbackPath(home), { recursive: true });++ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "failed",+ reason: "readback",+ });+ await expect(readFile(client.configPath, "utf8")).rejects.toThrow();+ expect(await inspectClientConfiguration(client, {}, command)).toMatchObject(+ { status: "invalid" },+ );+ });++ it.skipIf(process.platform === "win32")(+ "rejects a FIFO fallback without blocking on it",+ async () => {+ const { home, client } = await zcodeClient();+ await mkdir(join(home, ".agents"), { recursive: true });+ await promisify(execFile)("mkfifo", [fallbackPath(home)]);++ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "failed",+ reason: "readback",+ });+ await expect(readFile(client.configPath, "utf8")).rejects.toThrow();+ expect(+ await inspectClientConfiguration(client, {}, command),+ ).toMatchObject({ status: "invalid" });+ },+ );+});++describe("ZCode disabled registrations", () => {+ it("reports enable: false as stale and repairs it on setup", async () => {+ const { home, client } = await zcodeClient();+ await writeFile(+ client.configPath,+ JSON.stringify(+ {+ mcp: {+ servers: {+ rea: {+ command: command[0],+ args: command.slice(1),+ enable: false,+ },+ },+ },+ },+ null,+ 2,+ ),+ );+ const statusFor = async () =>+ (+ await readClientRegistrationStatuses(home, undefined, {+ platform: process.platform,+ environment: {},+ })+ ).find(({ client }) => client === "zcode");+ expect(await statusFor()).toMatchObject({ state: "stale" });++ expect(+ (await configureClientConfiguration(client, {}, command)).status,+ ).toBe("configured");+ expect(await statusFor()).toMatchObject({ state: "aligned", command });+ });+});++describe("ZCode strict native JSON", () => {+ it.each(['{ // comment\n "mcp": {}}', '{"mcp":{},}', "\uFEFF{}"])(+ "rejects unreadable native syntax without modifying %s",+ async (original) => {+ const { home, client } = await zcodeClient();+ await writeFile(client.configPath, original);+ expect(+ await inspectClientConfiguration(client, {}, command),+ ).toMatchObject({ status: "invalid" });+ expect(await configureClientConfiguration(client, {}, command)).toEqual({+ status: "failed",+ reason: "readback",+ });+ expect(await readFile(client.configPath, "utf8")).toBe(original);+ await expect(+ readFile(`${client.configPath}.rea.backup`),+ ).rejects.toMatchObject({ code: "ENOENT" });+ expect(+ (+ await readClientRegistrationStatuses(home, undefined, {+ platform: process.platform,+ environment: {},+ })+ ).find(({ client }) => client === "zcode"),+ ).toMatchObject({ state: "invalid" });+ },+ );+});