rea-agents 6.2.0 → 6.4.0

package/dist/application/BinaryTargetResolver.js

@@ -1,9 +1,12 @@
 import { constants } from "node:fs";
 import { createHash } from "node:crypto";
-import { access, open, realpath, stat, } from "node:fs/promises";
+import { access, lstat, realpath, stat, } from "node:fs/promises";
 import { extname, isAbsolute, resolve } from "node:path";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
+import { readMipsElfAbiFlags } from "./MipsElfAbiFlags.js";
 import { resolveAppBundleExecutable, } from "./AppBundleExecutable.js";
 import { validateDosComLength, } from "../domain/dosCom.js";
 import { mzWindowsHeaderOffset } from "../domain/dosMz.js";
@@ -14,30 +17,41 @@ import { parseExecutableHeader, parsePeRecord, } from "../domain/binaryTarget.js
  * FAT Mach-O inputs select only a host-compatible architecture so setup remains
  * non-interactive; unsupported or ambiguous inputs are returned as typed errors.
  */
-export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitecture = process.arch, targetKind, formatHint) => {
+export const parseBinaryTarget = async (input, options = {}) => {
+    const cwd = options.cwd ?? process.cwd();
+    const hostArchitecture = options.hostArchitecture ?? process.arch;
+    const { targetKind, formatHint, signal } = options;
     const candidate = isAbsolute(input) ? input : resolve(cwd, input);
     try {
+        throwIfTargetResolutionCancelled(signal);
         await access(candidate, constants.R_OK);
+        throwIfTargetResolutionCancelled(signal);
         const canonical = await realpath(candidate);
+        throwIfTargetResolutionCancelled(signal);
         const resolved = await resolveAppBundle(canonical);
+        throwIfTargetResolutionCancelled(signal);
         if (!resolved.ok)
             return err(resolved.error);
         const { executable: path, infoPlist } = resolved.value;
         const bundle = infoPlist === undefined ? {} : { bundleInfoPlist: infoPlist };
-        const handle = await open(path, "r");
+        const handle = await openRegularFile(path, {
+            symlinks: "reject",
+            signal,
+        });
         try {
-            if (!(await handle.stat()).isFile())
-                return err(new BinaryTargetError(path, "target is not a regular file"));
+            throwIfTargetResolutionCancelled(signal);
+            const metadata = await handle.stat();
+            throwIfTargetResolutionCancelled(signal);
             if (formatHint === "dos-com") {
                 if (targetKind !== undefined && targetKind !== "executable")
                     return err(new BinaryTargetError(path, "DOS COM format requires an executable target kind"));
-                const length = validateDosComLength((await handle.stat()).size);
+                const length = validateDosComLength(metadata.size);
                 if (!length.ok)
                     return err(new BinaryTargetError(path, length.error));
                 return ok({
                     path,
                     sourcePath: canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "executable",
                     format: "dos-com",
                     architecture: "x86",
@@ -49,29 +63,29 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
                 return ok({
                     path,
                     sourcePath: process.platform === "win32" ? candidate : canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                     kind: "database",
                     format: "analysis-database",
                 });
-            const artifactFormat = await detectArtifactFormat(path, handle);
+            const artifactFormat = await detectArtifactFormat(path, handle, signal);
             if (artifactFormat !== undefined) {
                 const identity = {
                     path,
                     sourcePath: process.platform === "win32" ? candidate : canonical,
-                    sha256: await sha256Handle(handle),
+                    sha256: await sha256Handle(handle, path, metadata, signal),
                 };
                 return isArchiveFormat(artifactFormat)
                     ? ok({ ...identity, kind: "archive", format: artifactFormat })
                     : ok({ ...identity, kind: "artifact", format: artifactFormat });
             }
-            const detected = await readExecutableMetadata(handle, hostArchitecture);
+            const detected = await readExecutableMetadata(handle, hostArchitecture, signal);
             if (!detected.ok)
                 return err(new BinaryTargetError(path, detected.error));
             return ok({
                 path,
                 sourcePath: process.platform === "win32" ? candidate : canonical,
                 ...bundle,
-                sha256: await sha256Handle(handle),
+                sha256: await sha256Handle(handle, path, metadata, signal),
                 kind: "executable",
                 ...detected.value,
             });
@@ -81,6 +95,10 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         }
     }
     catch (cause) {
+        if (cause instanceof AnalysisCancelledError)
+            return err(cause);
+        if (cause instanceof BinaryTargetError)
+            return err(cause);
         if (!(cause instanceof Error))
             throw cause;
         const code = filesystemErrorCode(cause);
@@ -103,14 +121,24 @@ const targetFailureReason = (code, detail) => {
             return `permission denied while reading target: ${detail}`;
         case "EISDIR":
             return `target is a directory, not a readable file: ${detail}`;
+        case "ENOTFILE":
+            return "target is not a regular file";
+        case "ELOOP":
+            return `target changed while being opened: ${detail}`;
         default:
             return `target could not be read (${code}): ${detail}`;
     }
 };
-const detectArtifactFormat = async (path, handle) => {
+const throwIfTargetResolutionCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError("resolve_binary_target");
+};
+const detectArtifactFormat = async (path, handle, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const lower = path.toLowerCase();
     const magic = Buffer.alloc(8);
     const observed = await handle.read(magic, 0, magic.length, 0);
+    throwIfTargetResolutionCancelled(signal);
     if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
         return zipPackageFormatForPath(lower) ?? "zip";
     }
@@ -122,10 +150,13 @@ const detectArtifactFormat = async (path, handle) => {
         magic.subarray(0, 4).toString("ascii") === "xar!")
         return "pkg";
     if (lower.endsWith(".dmg")) {
+        throwIfTargetResolutionCancelled(signal);
         const size = (await handle.stat()).size;
+        throwIfTargetResolutionCancelled(signal);
         if (size >= 512) {
             const trailer = Buffer.alloc(4);
             const read = await handle.read(trailer, 0, trailer.length, size - 512);
+            throwIfTargetResolutionCancelled(signal);
             if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
                 return "dmg";
         }
@@ -142,17 +173,27 @@ const namedArtifactFormat = (lowerPath) => {
     return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
 };
 const isArchiveFormat = (format) => ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
-const sha256Handle = async (handle) => {
+const sha256Handle = async (handle, path, initial, signal) => {
     const hash = createHash("sha256");
     const chunk = Buffer.allocUnsafe(64 * 1024);
     let position = 0;
     while (true) {
-        const observed = await handle.read(chunk, 0, chunk.length, position);
+        throwIfTargetResolutionCancelled(signal);
+        const observed = await handle.read(chunk, 0, Math.min(chunk.length, initial.size - position + 1), position);
+        throwIfTargetResolutionCancelled(signal);
         if (observed.bytesRead === 0)
             break;
         hash.update(chunk.subarray(0, observed.bytesRead));
         position += observed.bytesRead;
+        if (position > initial.size)
+            throw new BinaryTargetError(path, "target grew while being read");
     }
+    throwIfTargetResolutionCancelled(signal);
+    const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
+    if (!sameRegularFileState(initial, opened) ||
+        !sameRegularFileState(initial, currentPath) ||
+        position !== initial.size)
+        throw new BinaryTargetError(path, "target changed while being read");
     return hash.digest("hex");
 };
 const resolveAppBundle = async (path) => {
@@ -165,19 +206,22 @@ const resolveAppBundle = async (path) => {
         }));
     return resolveAppBundleExecutable(path);
 };
-const readExecutableMetadata = async (handle, hostArchitecture) => {
+const readExecutableMetadata = async (handle, hostArchitecture, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const prefix = Buffer.alloc(4096);
     const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
+    throwIfTargetResolutionCancelled(signal);
     const bytes = prefix.subarray(0, prefixRead.bytesRead);
     // Header commitments such as Mach-O load commands and FAT slices are
     // checked against the whole file, not the probed prefix.
     const fileSize = (await handle.stat()).size;
+    throwIfTargetResolutionCancelled(signal);
     if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
         const offset = mzWindowsHeaderOffset(bytes);
         if (offset !== null) {
             if (offset < 64)
                 return err("invalid Windows new-header offset in MZ image");
-            return readPeMetadata(handle, offset);
+            return readPeMetadata(handle, offset, signal);
         }
         // MZ relocation records may extend past the initial probe; their format
         // bounds are at most 65535 records inside a 65535-paragraph header.
@@ -190,6 +234,7 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
             tableEnd <= fileSize) {
             const table = Buffer.alloc(tableEnd);
             const observed = await handle.read(table, 0, table.length, 0);
+            throwIfTargetResolutionCancelled(signal);
             return parseExecutableHeader(table.subarray(0, observed.bytesRead), hostArchitecture, fileSize);
         }
         return parseExecutableHeader(bytes, hostArchitecture, fileSize);
@@ -203,15 +248,35 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
             if (count <= 128 && required > bytes.length) {
                 const header = Buffer.alloc(required);
                 const headerRead = await handle.read(header, 0, header.length, 0);
+                throwIfTargetResolutionCancelled(signal);
                 return parseExecutableHeader(header.subarray(0, headerRead.bytesRead), hostArchitecture, fileSize);
             }
         }
     }
-    return parseExecutableHeader(bytes, hostArchitecture, fileSize);
+    const parsed = parseExecutableHeader(bytes, hostArchitecture, fileSize);
+    if (!parsed.ok ||
+        parsed.value.architecture !== "mips" ||
+        parsed.value.mips.elfClass !== 32)
+        return parsed;
+    const abiFlags = await readMipsElfAbiFlags(handle, parsed.value.mips, () => throwIfTargetResolutionCancelled(signal));
+    if (!abiFlags.ok)
+        return abiFlags;
+    return ok({
+        ...parsed.value,
+        mips: {
+            ...parsed.value.mips,
+            abiFlags: abiFlags.value.abiFlags,
+            ...(abiFlags.value.limitations.length === 0
+                ? {}
+                : { limitations: abiFlags.value.limitations }),
+        },
+    });
 };
-const readPeMetadata = async (handle, offset) => {
+const readPeMetadata = async (handle, offset, signal) => {
+    throwIfTargetResolutionCancelled(signal);
     const fileHeader = Buffer.alloc(24);
     const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
+    throwIfTargetResolutionCancelled(signal);
     if (fileHeaderRead.bytesRead !== fileHeader.length)
         return err("invalid or truncated PE header");
     const signature = fileHeader.toString("ascii", 0, 2);
@@ -222,6 +287,7 @@ const readPeMetadata = async (handle, offset) => {
         return err("invalid PE optional header size");
     const record = Buffer.alloc(24 + optionalHeaderSize);
     const recordRead = await handle.read(record, 0, record.length, offset);
+    throwIfTargetResolutionCancelled(signal);
     return recordRead.bytesRead === record.length
         ? parsePeRecord(record)
         : err("invalid or truncated PE header");

package/dist/application/BrowserScenarioEvidence.js

@@ -1,9 +1,9 @@
-import { canonicalDigest } from "../domain/comparisonSemantics.js";
+import { digestCanonicalValue } from "../domain/canonicalDigest.js";
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 const browserScenarioParameters = (scenario) => ({
     ...jsonObjectSchema.parse(scenario),
-    scenario_sha256: canonicalDigest(scenario, "Browser scenario"),
+    scenario_sha256: digestCanonicalValue(scenario, "Browser scenario"),
 });
 /** Create Evidence without retaining resolved scenario secret values. */
 export const createBrowserScenarioEvidence = (scenario, capture, provider) => createEvidence(undefined, provider, {

package/dist/application/CapabilityInventory.js

@@ -203,7 +203,7 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
             ? { reason: "available", remediation: null }
             : {
                 reason: "provider_missing",
-                remediation: "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru 1.13.0 and util-linux prlimit. No binary target is required.",
+                remediation: "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru ^1.13.0 (verified with 1.14.0) and util-linux prlimit; see docs/javascript-recovery.md#install-wakaru. No binary target is required.",
             };
     if (name === "inspect_binary_layout")
         return policy.binaryLayoutEnabled === true
@@ -212,6 +212,8 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
                 reason: "provider_missing",
                 remediation: "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",
             };
+    if (name === "inspect_pe_resources")
+        return { reason: "available", remediation: null };
     if (name === "inspect_evm_interface")
         return policy.evmInterfaceEnabled === true
             ? { reason: "available", remediation: null }
@@ -247,6 +249,14 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
                 remediation: policy.androidAnalysisAvailability?.reason ??
                     "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux, macOS, or Windows x64 with its matching bundled native controls.",
             };
+    if (kind === "jeb-provider")
+        return policy.jebAnalysisAvailability?.status === "available"
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: policy.jebAnalysisAvailability?.reason ??
+                    "Start a JEB client serving MCP (GUI client, or headless via its programmatic launcher) and point REA_JEB_MCP_URL at it (default http://127.0.0.1:8425/mcp). REA does not install or launch JEB.",
+            };
     const browser = browserProviderAvailability(name, kind, policy);
     if (browser !== null)
         return browser;

package/dist/application/ClientConfigurationDocument.js

@@ -1,4 +1,5 @@
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { parse as parseYaml, parseDocument as parseYamlDocument, stringify as stringifyYaml, } from "yaml";
 import { isDeepStrictEqual } from "node:util";
 import { applyEdits, findNodeAtLocation, modify, parse as parseJsonc, parseTree, printParseErrorCode, } from "jsonc-parser";
 import { z } from "zod";
@@ -20,6 +21,7 @@ export const clientConfigurationServersKey = (format) => {
     switch (format) {
         case "toml":
         case "grok":
+        case "hermes":
             return "mcp_servers";
         case "opencode":
             return "mcp";
@@ -37,6 +39,14 @@ const isEmptyClientConfigurationText = (text) => text.replace(/^\uFEFF/, "").tri
 const parseDocument = (text, format) => {
     if (format === "toml" || format === "grok")
         return objectSchema.parse(parseToml(text));
+    // Pi loads `mcp.json` with a strict `JSON.parse` and no BOM tolerance, so
+    // comments, trailing commas, a BOM, or an empty existing file must be
+    // rejected instead of registering into a document Pi cannot load.
+    if (format === "pi")
+        return objectSchema.parse(JSON.parse(text));
+    // Hermes stores MCP servers in `mcp_servers` inside a YAML document.
+    if (format === "hermes")
+        return objectSchema.parse(parseYaml(text));
     // An empty file, which some clients create before any server is added,
     // holds no settings to preserve.
     if (isEmptyClientConfigurationText(text))
@@ -858,6 +868,33 @@ const tomlServerEntry = (document, serverKey) => {
 /** Whether Grok Build's root disable list names `serverKey`. */
 export const grokServerListedDisabled = (document, serverKey) => Array.isArray(document.disabled_mcp_servers) &&
     document.disabled_mcp_servers.includes(serverKey);
+/**
+ * OMP's user `disabledServers` denylist hides a server by name regardless of
+ * its entry, so a listed REA registration is not loaded.
+ */
+export const OMP_DISABLED_SERVERS_KEY = "disabledServers";
+/** Whether OMP's root `disabledServers` denylist names `serverKey`. */
+export const ompServerListedDisabled = (document, serverKey) => {
+    const listed = document[OMP_DISABLED_SERVERS_KEY];
+    return Array.isArray(listed) && listed.includes(serverKey);
+};
+/** OMP's user `enabledServers` allowlist overrides an entry's `enabled: false`. */
+const OMP_ENABLED_SERVERS_KEY = "enabledServers";
+/**
+ * Whether OMP's allowlist forces `serverKey` on despite its entry's
+ * `enabled: false`. The `disabledServers` denylist still wins over it.
+ */
+export const clientServerForcedEnabled = (parsed, serverKey) => {
+    if (parsed.dialect !== "omp")
+        return false;
+    const listed = parsed.document[OMP_ENABLED_SERVERS_KEY];
+    return Array.isArray(listed) && listed.includes(serverKey);
+};
+/** Whether a client's own disable list suppresses `serverKey`. */
+export const clientServerListedDisabled = (parsed, serverKey) => (parsed.dialect === "grok" &&
+    grokServerListedDisabled(parsed.document, serverKey)) ||
+    (parsed.dialect === "omp" &&
+        ompServerListedDisabled(parsed.document, serverKey));
 /** Keep an existing Grok document intact aside from the REA server tables. */
 const serializeGrokConfiguration = (document, originalText) => {
     const entry = tomlServerEntry(document, PRODUCT_IDENTITY.mcpServerKey);
@@ -1004,6 +1041,8 @@ export const serializeClientConfiguration = (document, format, originalText, edi
         return serializeCodexConfiguration(document, originalText);
     if (format === "grok")
         return serializeGrokConfiguration(document, originalText);
+    if (format === "hermes")
+        return serializeHermesConfiguration(document, originalText);
     // An empty original holds no comments or settings to preserve. Writing a
     // fresh document also keeps a lone BOM from shifting past the closing brace.
     if (originalText !== undefined &&
@@ -1028,6 +1067,28 @@ export const clientServerPath = (parsed, name) => [...parsed.serversPath, name];
 export const legacyClientServerPath = (parsed, name) => Object.hasOwn(parsed.legacyServers, name)
     ? [parsed.serversPath[0] ?? "mcp", name]
     : undefined;
+/**
+ * Keep an existing Hermes `config.yaml` intact aside from the REA server entry.
+ * Hermes config files carry user comments and unrelated settings, so the rea
+ * entry is upserted into the parsed YAML document (which retains formatting and
+ * comments) rather than re-serializing the whole object.
+ */
+const serializeHermesConfiguration = (document, originalText) => {
+    if (originalText === undefined ||
+        isEmptyClientConfigurationText(originalText))
+        return stringifyYaml(document);
+    const serversKey = clientConfigurationServersKey("hermes");
+    const servers = document[serversKey];
+    const entry = typeof servers === "object" && servers !== null
+        ? servers[PRODUCT_IDENTITY.mcpServerKey]
+        : undefined;
+    const yamlDocument = parseYamlDocument(originalText);
+    if (entry === undefined)
+        yamlDocument.deleteIn([serversKey, PRODUCT_IDENTITY.mcpServerKey]);
+    else
+        yamlDocument.setIn([serversKey, PRODUCT_IDENTITY.mcpServerKey], entry);
+    return yamlDocument.toString();
+};
 /** Build the stdio entry shape expected by one client's configuration dialect. */
 export const clientRegistrationEntry = (format, command, environment) => {
     const [executable = "rea", ...args] = command;
@@ -1051,6 +1112,8 @@ export const clientRegistrationEntry = (format, command, environment) => {
                     : { environment: { ...environment } }),
             };
         case "vscode":
+        case "omp":
+        case "pi":
             return {
                 type: "stdio",
                 command: executable,
@@ -1073,6 +1136,15 @@ export const clientRegistrationEntry = (format, command, environment) => {
                 args,
                 ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
             };
+        case "hermes":
+            // Hermes reads stdio servers from `mcp_servers.<name>` and connects them
+            // unless `enabled` is false, so the entry states it explicitly.
+            return {
+                command: executable,
+                args,
+                ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+                enabled: true,
+            };
         default:
             return {
                 command: executable,
@@ -1081,3 +1153,29 @@ export const clientRegistrationEntry = (format, command, environment) => {
             };
     }
 };
+/** Parse one Gemini policy at its source boundary before consolidating scopes. */
+export const parseGeminiMcpPolicy = (parsed) => z
+    .object({
+    allowed: z.array(z.string()).optional(),
+    excluded: z.array(z.string()).optional(),
+})
+    .passthrough()
+    .parse(parsed.document.mcp ?? {});
+/** Gemini consolidates excludes by union and allowlists by normalized intersection. */
+export const geminiServerPolicyBlock = (policies, serverKey) => {
+    if (policies.some(({ excluded }) => excluded?.includes(serverKey)))
+        return `Gemini mcp.excluded blocks ${serverKey}. Review the selected settings policies before rerunning setup.`;
+    const allowlists = policies.flatMap(({ allowed }) => allowed === undefined ? [] : [allowed]);
+    const allowed = allowlists.reduce((previous, current) => {
+        if (previous === undefined)
+            return current;
+        const normalized = new Set(current.map((name) => name.toLowerCase().trim()));
+        return previous.filter((name) => normalized.has(name.toLowerCase().trim()));
+    }, undefined);
+    // Gemini's manager applies the consolidated allowlist only when nonempty.
+    if (allowed !== undefined &&
+        allowed.length > 0 &&
+        !allowed.includes(serverKey))
+        return `Gemini mcp.allowed does not include ${serverKey}. Review the selected settings policies before rerunning setup.`;
+    return undefined;
+};

package/dist/application/ClientConfigurationFiles.js

@@ -0,0 +1,91 @@
+import { err, ok } from "../domain/result.js";
+import { RegularFileCleanupFailure, readRegularFileText, } from "./RegularFileRead.js";
+import { effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
+/** Preserve named read failures and distinguish a missing source from an empty file. */
+export const readConfigurationText = async (path) => {
+    try {
+        return ok(await readRegularFileText(path));
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return ok(undefined);
+        return err({
+            kind: "unreadable",
+            path,
+            detail: `Configuration ${path} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`,
+            ...(cause instanceof RegularFileCleanupFailure
+                ? { cleanupFailure: cause }
+                : {}),
+        });
+    }
+};
+/** Read and parse one configuration at its source boundary. */
+export const readConfigurationFile = async (path, format) => {
+    const source = await readConfigurationText(path);
+    if (!source.ok)
+        return source;
+    const content = source.value;
+    if (content === undefined)
+        return ok(undefined);
+    try {
+        return ok(parseClientConfiguration(content, format));
+    }
+    catch (cause) {
+        return err({
+            kind: "malformed",
+            path,
+            detail: `Configuration ${path} is malformed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        });
+    }
+};
+/** Read every applicable user file; malformed lower-priority files also stop setup. */
+export const readClientConfigurationFiles = async (client) => {
+    const documents = [];
+    for (const path of client.configPaths ?? [client.configPath]) {
+        const document = await readConfigurationFile(path, client.format);
+        if (!document.ok)
+            return document;
+        if (document.value !== undefined) {
+            const environment = clientRegistrationEnvironment(document.value);
+            if (!environment.ok)
+                return err({
+                    kind: "malformed",
+                    path,
+                    detail: `Configuration ${path} has an invalid REA server environment: ${environment.error.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}. Repair it before rerunning setup.`,
+                });
+            documents.push(document.value);
+        }
+    }
+    return ok(documents);
+};
+/** OpenCode merges server objects in file order, replacing arrays and scalar values. */
+const mergeConfigurationValue = (previous, next) => {
+    if (!isObject(previous) || !isObject(next))
+        return next;
+    return Object.fromEntries([...new Set([...Object.keys(previous), ...Object.keys(next)])].map((key) => [
+        key,
+        Object.hasOwn(next, key)
+            ? mergeConfigurationValue(previous[key], next[key])
+            : previous[key],
+    ]));
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Project a client's effective user registration without modifying its source files. */
+export const effectiveClientConfiguration = (documents) => {
+    const last = documents.at(-1);
+    if (last === undefined)
+        return undefined;
+    if (documents.length === 1)
+        return last;
+    const servers = {};
+    for (const document of documents) {
+        const names = new Set([
+            ...Object.keys(document.legacyServers),
+            ...Object.keys(document.servers),
+        ]);
+        for (const name of names)
+            servers[name] = mergeConfigurationValue(servers[name], effectiveClientServer(document, name));
+    }
+    return { ...last, servers, legacyServers: {} };
+};

package/dist/application/ClientRegistrationEnvironment.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { parseEnvironment } from "../config/environment.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { err, ok } from "../domain/result.js";
+import { effectiveClientServer, } from "./ClientConfigurationDocument.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+/** Read explicit REA overrides without dropping peers when one value is invalid. */
+export const clientRegistrationEnvironment = (parsed, overrides = {}) => {
+    const key = parsed?.dialect === "opencode" || parsed?.dialect === "opencode_v2"
+        ? "environment"
+        : "env";
+    const registration = parsed === undefined
+        ? undefined
+        : effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey);
+    const raw = typeof registration === "object" && registration !== null
+        ? Reflect.get(registration, key)
+        : undefined;
+    const existing = z
+        .record(z.string(), z.string())
+        .safeParse(raw === undefined ? {} : raw);
+    if (!existing.success)
+        return err(new ConfigurationError("Invalid REA server environment", {
+            settings: existing.error.issues.map((issue) => ({
+                setting: [key, ...issue.path].join("."),
+                constraint: "Server environment must be an object containing only string values",
+            })),
+        }));
+    // Validate known settings with the runtime's parser, but retain the original
+    // string overrides, including unknown client-specific keys and no defaults.
+    const environment = { ...existing.data, ...overrides };
+    const validated = parseEnvironment(environment);
+    if (!validated.ok)
+        return validated;
+    return ok(Object.fromEntries(Object.entries(environment).sort(([left], [right]) => left.localeCompare(right))));
+};