rea-agents 6.0.0 → 6.2.0

package/dist/application/MacHopper.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { access, mkdir, mkdtemp, readdir, rename, rm, writeFile, } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { z } from "zod";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 const execFileAsync = promisify(execFile);
 const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
@@ -21,7 +22,7 @@ export const macHopperInstallDisclosure = {
     ],
 };
 /** Download, verify, and install Hopper into the current user's Applications directory. */
-export const installMacHopper = async (options = {}, host = systemMacHopperInstallHost()) => {
+export const installMacHopper = async (options = {}, host = systemMacHopperInstallHost(homeDirectoryFromEnvironment(process.env, process.platform), process.env)) => {
     let temporary;
     let mounted = false;
     try {
@@ -77,7 +78,8 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
         }
     }
 };
-const systemMacHopperInstallHost = () => ({
+/** Compose installer paths and subprocesses from one selected caller context. */
+export const systemMacHopperInstallHost = (homeDirectory, environment) => ({
     download: downloadPackage,
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
     createMountDirectory: (path) => mkdir(path),
@@ -90,10 +92,10 @@ const systemMacHopperInstallHost = () => ({
             "-mountpoint",
             mountPath,
             packagePath,
-        ]);
+        ], environment);
     },
     async unmount(mountPath) {
-        await commandSucceeds("hdiutil", ["detach", mountPath, "-force"]);
+        await commandSucceeds("hdiutil", ["detach", mountPath, "-force"], environment);
     },
     async appBundle(mountPath) {
         const entries = await readdir(mountPath, { withFileTypes: true });
@@ -101,19 +103,14 @@ const systemMacHopperInstallHost = () => ({
         return app === undefined ? undefined : join(mountPath, app.name);
     },
     async validBundle(appPath) {
-        if (!(await commandSucceeds("codesign", [
-            "--verify",
-            "--deep",
-            "--strict",
-            appPath,
-        ])))
+        if (!(await commandSucceeds("codesign", ["--verify", "--deep", "--strict", appPath], environment)))
             return false;
         try {
             const identifier = (await execFileAsync("/usr/libexec/PlistBuddy", [
                 "-c",
                 "Print :CFBundleIdentifier",
                 join(appPath, "Contents/Info.plist"),
-            ])).stdout.trim();
+            ], { env: environment })).stdout.trim();
             return identifier === BUNDLE_IDENTIFIER;
         }
         catch (cause) {
@@ -136,10 +133,10 @@ const systemMacHopperInstallHost = () => ({
     async installBundle(source, destination, stage, replaceExisting) {
         const previous = `${stage}-previous`;
         try {
-            await mkdir(join(homedir(), "Applications"), { recursive: true });
+            await mkdir(join(homeDirectory, "Applications"), { recursive: true });
             await rm(stage, { recursive: true, force: true });
             await rm(previous, { recursive: true, force: true });
-            await execFileAsync("ditto", [source, stage]);
+            await execFileAsync("ditto", [source, stage], { env: environment });
             await access(join(stage, "Contents/MacOS/hopper"));
             if (replaceExisting)
                 await rename(destination, previous);
@@ -176,10 +173,10 @@ const systemMacHopperInstallHost = () => ({
         }
     },
     async openApplication(path) {
-        await execFileAsync("open", [path]);
+        await execFileAsync("open", [path], { env: environment });
     },
     cleanup: (path) => rm(path, { recursive: true, force: true }),
-    destination: () => join(homedir(), "Applications/Hopper Disassembler.app"),
+    destination: () => join(homeDirectory, "Applications/Hopper Disassembler.app"),
 });
 const downloadPackage = async (url) => {
     const response = await fetch(url, {
@@ -196,9 +193,9 @@ const parseJson = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
 const integrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
     bytes.byteLength <= MAX_PACKAGE_BYTES &&
     createHash("sha1").update(bytes).digest("hex") === release.file_hash;
-const commandSucceeds = async (command, args) => {
+const commandSucceeds = async (command, args, environment) => {
     try {
-        await execFileAsync(command, args);
+        await execFileAsync(command, args, { env: environment });
         return true;
     }
     catch (cause) {

package/dist/application/ProcedureAddressResolution.js

@@ -0,0 +1,11 @@
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Resolve a caller selector to an observed provider procedure identity. */
+export const resolveProcedureAddress = async (call, procedure, signal) => {
+    const result = await call("procedure_address", { procedure }, signal);
+    if (!result.ok)
+        return result;
+    return typeof result.value === "string" && result.value.length > 0
+        ? ok(result.value)
+        : err(new AnalysisOutputError("procedure_address", "provider returned no canonical procedure address"));
+};

package/dist/application/RealHopperAssertions.js

@@ -11,17 +11,6 @@ export const firstProcedureAddress = (input) => {
         throw new TypeError("Procedure inventory was empty");
     return first.address;
 };
-/** Reject two target paths that resolve to the same binary content. */
-export const requireDistinctTargetHashes = (firstHash, secondHash) => {
-    if (typeof firstHash !== "string" ||
-        typeof secondHash !== "string" ||
-        firstHash.length === 0 ||
-        secondHash.length === 0) {
-        throw new TypeError("Target hashes must be non-empty strings");
-    }
-    if (firstHash === secondHash)
-        throw new TypeError("Real-Hopper verification requires distinct binaries");
-};
 /** Reject empty and success-shaped embedded decompilation failures. */
 export const requirePseudocode = (input, operation) => {
     if (typeof input !== "string" || input.trim().length === 0)

package/dist/application/ReconstructionCoverageService.js

@@ -1,20 +1,23 @@
+import { z } from "zod";
 import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { evaluateReconstructionClosure } from "../domain/reconstructionCoverage.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { requestInputError, workflowInputError } from "./workflowInputError.js";
+const OPERATION = "evaluate_reconstruction_coverage";
 /** Evaluate inline reconstruction coverage against a named boundary. */
 export const evaluateReconstructionCoverage = (rawInput, nowEpochMs = Date.now()) => {
     const parsed = reconstructionCoverageEvaluationInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError("evaluate_reconstruction_coverage", {
-            cause: parsed.error,
-        }));
+        return err(requestInputError(OPERATION, parsed.error, rawInput));
     try {
         return ok(jsonValueSchema.parse(evaluateReconstructionClosure(parsed.data.coverage, parsed.data.boundary_id, nowEpochMs)));
     }
     catch (cause) {
-        return err(new AnalysisInputError("evaluate_reconstruction_coverage", { cause }));
+        return err(cause instanceof TypeError || cause instanceof z.ZodError
+            ? workflowInputError(OPERATION, cause)
+            : new AnalysisInputError(OPERATION, { cause }));
     }
 };

package/dist/application/ReconstructionObligationCandidates.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { parseEvidenceBundle, } from "../domain/evidenceBundle.js";
-import { parseProcessCapture } from "../domain/process/processCapture.js";
+import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
 import { parseApplicationGraphEvidence } from "./javascript/JavaScriptApplicationEvidenceGraph.js";
 import { applicationObligationPolicy, semanticObligationPolicy, } from "./ReconstructionObligationPolicies.js";
 /** Derive conservative candidates from graph, process, and reviewed inputs. */

package/dist/application/ReconstructionObligationLedgerService.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
 import { err, ok } from "../domain/result.js";
+import { requestInputError, workflowInputError } from "./workflowInputError.js";
 import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
 import { deriveReconstructionObligationCandidates } from "./ReconstructionObligationCandidates.js";
 import { evaluateReconstructionObligationLedger } from "./ReconstructionObligationLedgerEvaluation.js";
@@ -14,7 +15,7 @@ export const resolveReconstructionObligationLedgerRequest = (input) => {
     const parsed = reconstructionObligationLedgerInputSchema.safeParse(input);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+        : err(requestInputError(OPERATION, parsed.error, input));
 };
 /** Build the complete deterministic ledger and wrap it in portable Evidence. */
 export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
@@ -30,7 +31,7 @@ export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
     }
     catch (cause) {
         if (cause instanceof z.ZodError)
-            return err(new AnalysisInputError(OPERATION, { cause }));
+            return err(workflowInputError(OPERATION, cause));
         return err(new AnalysisProtocolError("Reconstruction obligation ledger generation failed", { cause }));
     }
 };

package/dist/application/ReferenceSourceImportEntries.js

@@ -32,7 +32,7 @@ const failedEntry = (entry) => {
         return {
             path: entry.path,
             kind: "symlink",
-            target: "<unreadable>",
+            target: null,
             target_state: "unreadable",
             classifications,
             limitations: [limitation],

package/dist/application/Setup.js

@@ -1,6 +1,7 @@
+import { manualRegistrationRemediation, } from "./SupportedClients.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
-import { filterClientsNeedingConfigure, hostRemediation, initialProviderEnvironment, setupRegistrationCommand, systemSetupHost, } from "./SetupHost.js";
+import { filterClientsNeedingConfigure, hostRemediation, systemSetupHost, } from "./SetupHost.js";
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const appliedActions = [];
@@ -12,22 +13,14 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const unsupported = await hostRemediation(host, false);
     if (unsupported !== undefined)
         return fail(unsupported);
-    const initialState = await host.initialSetupState?.(options.readinessScope);
-    let hopperPath = initialState === undefined
-        ? await host.hopperPath()
-        : initialState.hopperPath;
-    let providerEnvironment = initialState === undefined
-        ? await initialProviderEnvironment(host, hopperPath)
-        : initialState.providerEnvironment;
+    const initialState = await host.initialSetupState(options.readinessScope);
+    let { hopperPath, providerEnvironment } = initialState;
     const discovery = await discoverSetupState({
         host,
         providerEnvironment,
         forceHopperInstall: options.installHopper,
         proposeHopper: options.proposeHopper ?? (confirm !== undefined && !options.structured),
-        doctorScope: options.readinessScope,
-        ...(initialState === undefined
-            ? {}
-            : { initialDoctor: initialState.doctor }),
+        initialDoctor: initialState.doctor,
     });
     clientStates = discovery.clientStates;
     const clientSelectionAllowed = options.clientIds === undefined &&
@@ -51,7 +44,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             discovery,
             host,
             providerEnvironment,
-            command: setupRegistrationCommand(host.platform),
+            command: host.registrationCommand,
             clientIds: [],
             installSkill: offerSkillAction,
         });
@@ -91,7 +84,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         discovery: planDiscovery,
         host,
         providerEnvironment,
-        command: setupRegistrationCommand(host.platform),
+        command: host.registrationCommand,
         clientIds: selectedClientIds,
         installSkill,
     });
@@ -109,6 +102,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         clientsToConfigure: planned.clientsToConfigure,
     };
     readinessScope = resolvedReadinessScope(options.readinessScope, planSelection);
+    const manualRemediation = manualClientsRemediation(planned.selectedClients);
     if (options.dryRun === true)
         return {
             status: "planned",
@@ -117,6 +111,9 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             clients,
             doctor: summarizeDoctor(discovery.initialDoctor),
             clientStates,
+            ...(manualRemediation === undefined
+                ? {}
+                : { remediation: manualRemediation }),
         };
     let approved = options.approved || plannedActions.length === 0;
     let interactiveApproval = false;
@@ -170,7 +167,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         host,
         detectedClients: selectedClients,
         providerEnvironment,
-        command: setupRegistrationCommand(host.platform),
+        command: host.registrationCommand,
         clients,
         appliedActions,
         ...(options.onProgress === undefined
@@ -183,7 +180,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         !(await installSkillAction(host, options, appliedActions)))
         return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
     const doctor = summarizeDoctor(await host.doctor(readinessScope));
-    const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
+    const remediation = combineRemediation(finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath), manualRemediation);
     return {
         status: remediation === undefined ? "ready" : "needs_human",
         plannedActions,
@@ -236,7 +233,7 @@ const installHopperAction = async (input) => {
     return {
         hopperPath: installed.launcherPath,
         providerEnvironment,
-        selectedClients: await filterClientsNeedingConfigure(input.host, input.selectedClients, providerEnvironment, setupRegistrationCommand(input.host.platform)),
+        selectedClients: await filterClientsNeedingConfigure(input.host, input.selectedClients, providerEnvironment, input.host.registrationCommand),
     };
 };
 const installSkillAction = async (host, options, appliedActions) => {
@@ -277,6 +274,13 @@ const setupFailure = async (remediation, [host, plannedActions, appliedActions,
     };
 };
 const emitProgress = (options, event) => options.onProgress?.(event);
+const manualClientsRemediation = (clients) => clients
+    .map((client) => manualRegistrationRemediation(client.name))
+    .find((remediation) => remediation !== undefined);
+const combineRemediation = (...parts) => {
+    const present = parts.filter((part) => part !== undefined && part !== "");
+    return present.length === 0 ? undefined : present.join(" ");
+};
 const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
     if (platform === "darwin" && installedHopper)
         return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";

package/dist/application/SetupClientConfiguration.js

@@ -1,21 +1,13 @@
-import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, grokServerListedDisabled, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-const defaultCommand = () => [
-    "npx",
-    "-y",
-    PRODUCT_IDENTITY.registrationPackageSpecifier,
-    "mcp",
-];
-/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
-export const configureJsonClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "json");
-/** Back up, atomically update, and semantically read back one TOML MCP configuration. */
-export const configureTomlClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "toml");
+const defaultCommand = () => npxRegistrationCommand();
 /** Configure one supported client's native stdio MCP registration shape. */
 export const configureClientConfiguration = (client, environment = {}, command = defaultCommand()) => {
     if (client.format === undefined || client.format === "unsupported")
@@ -36,7 +28,7 @@ const configureClientDocument = async (client, environment, command, format) =>
     }
     let parsed;
     try {
-        parsed = parseClientConfiguration(original ?? (format === "toml" ? "" : "{}"), format);
+        parsed = parseClientConfiguration(original ?? (format === "toml" || format === "grok" ? "" : "{}"), format);
     }
     catch (cause) {
         // Malformed existing configuration fails the readback gate.
@@ -163,14 +155,17 @@ const restoreConfig = async (path, original) => {
         void cause;
     }
 };
-/** Whether REA's entry matches and no conflicting legacy entry remains. */
-const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) && !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey);
+/** Whether REA's entry matches, no legacy entry remains, and Grok is not suppressing it. */
+const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
+    !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
+    !(parsed.dialect === "grok" &&
+        grokServerListedDisabled(parsed.document, PRODUCT_IDENTITY.mcpServerKey));
 const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);
     return {
         ...registration,
-        ...(client.name === "codex"
+        ...(client.name === "codex" || client.name === "grok_build"
             ? {
                 startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
             }

package/dist/application/SetupHost.js

@@ -1,19 +1,19 @@
 import { access } from "node:fs/promises";
-import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
-import { installLinuxHopper, readLinuxDistribution } from "./LinuxHopper.js";
-import { installMacHopper } from "./MacHopper.js";
+import { installLinuxHopper, readLinuxDistribution, systemLinuxHopperInstallHost, } from "./LinuxHopper.js";
+import { installMacHopper, systemMacHopperInstallHost } from "./MacHopper.js";
 import { supportedClients } from "./SupportedClients.js";
 import { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
 import { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
 import { setupInstallFailure } from "./SetupInstallFailure.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
 /** Resolve the executable and arguments used in a managed MCP registration. */
-export const setupRegistrationCommand = (platform, useNpmRunner = process.env.npm_command === "exec") => useNpmRunner
-    ? PRODUCT_IDENTITY.mcpCommand.split(" ")
+export const setupRegistrationCommand = (platform, useNpmRunner) => useNpmRunner
+    ? npxRegistrationCommand(platform)
     : platform === "win32"
         ? [
             process.execPath,
@@ -25,10 +25,6 @@ export const filterClientsNeedingConfigure = async (host, detectedClients, provi
     const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, providerEnvironment, command)));
     return detectedClients.filter((_, index) => needs[index]);
 };
-export const initialProviderEnvironment = async (host, hopperPath) => ({
-    ...(await host.providerEnvironment?.()),
-    ...(hopperPath === undefined ? {} : { HOPPER_LAUNCHER_PATH: hopperPath }),
-});
 export const hostRemediation = async (host, installHopper) => {
     if (!supportsNodeVersion(host.nodeVersion))
         return `Install ${SUPPORTED_NODE_VERSION_PROSE} and rerun setup.`;
@@ -47,14 +43,17 @@ export const hostRemediation = async (host, installHopper) => {
     return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and CachyOS; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
-export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
+export const systemSetupHost = (selectedDoctorHost = undefined, environment = process.env) => {
+    const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
     const platform = doctorHost.platform;
+    const { homeDirectory } = doctorHost;
     return {
         platform,
+        homeDirectory,
+        registrationCommand: setupRegistrationCommand(platform, environment.npm_command === "exec"),
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
-        hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
         initialSetupState: async (scope) => {
             const diagnosis = await runDoctor(undefined, doctorHost, scope);
             return {
@@ -70,39 +69,32 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
                 doctor: diagnosis,
             };
         },
-        providerEnvironment: async () => {
-            const diagnosis = await runDoctor(undefined, doctorHost);
-            return {
-                ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
-                ...(diagnosis.hopperPath === undefined
-                    ? {}
-                    : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
-            };
-        },
         installHopper: async (replaceExisting) => {
             const result = platform === "linux"
-                ? await installLinuxHopper()
-                : await installMacHopper({ replaceExisting });
+                ? await installLinuxHopper(systemLinuxHopperInstallHost(environment))
+                : await installMacHopper({ replaceExisting }, systemMacHopperInstallHost(homeDirectory, environment));
             if (result.status === "installed")
                 return result;
             return setupInstallFailure(result.reason);
         },
-        detectedClients: () => detectClients(homedir()),
-        supportedClients: () => Promise.resolve(supportedClients(homedir())),
+        detectedClients: () => detectClients(homeDirectory, platform, environment),
+        supportedClients: () => Promise.resolve(supportedClients(homeDirectory, platform, environment)),
         configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
             : configureClientConfiguration(client, providerEnvironment, command),
-        clientNeedsConfigure: (client, providerEnvironment, command) => clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
+        clientNeedsConfigure: (client, providerEnvironment, command) => client.format === "unsupported"
+            ? Promise.resolve(false)
+            : clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
         inspectClientConfiguration: inspectClientConfiguration,
-        skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
-        installSkill: () => installCanonicalSkill(homedir()),
+        skillNeedsInstall: () => canonicalSkillNeedsInstall(homeDirectory),
+        installSkill: () => installCanonicalSkill(homeDirectory),
         doctor: (scope) => runDoctor(undefined, doctorHost, scope),
     };
 };
 /** Detect supported agents from their config files or stable installation markers. */
-export const detectClients = async (home) => {
+export const detectClients = async (home, platform = process.platform, environment = process.env) => {
     const detected = [];
-    for (const candidate of supportedClients(home)) {
+    for (const candidate of supportedClients(home, platform, environment)) {
         const [hasConfig, hasMarker] = await Promise.all([
             exists(candidate.configPath),
             candidate.markerPath === undefined ? false : exists(candidate.markerPath),

package/dist/application/SetupPlan.js

@@ -1,4 +1,3 @@
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
@@ -6,7 +5,7 @@ import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
 /** Discover supported clients and current registrations without mutation. */
 export const discoverSetupState = async (input) => {
-    const initialDoctor = input.initialDoctor ?? (await input.host.doctor(input.doctorScope));
+    const { initialDoctor } = input;
     const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
         (name === "hopper-demo-runtime" ||
             (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
@@ -22,7 +21,7 @@ export const discoverSetupState = async (input) => {
             (Object.keys(input.providerEnvironment).length === 0 ||
                 linuxHopperRepairNeeded));
     const [clients, detectedClients, skillNeedsInstall] = await Promise.all([
-        input.host.supportedClients?.() ?? input.host.detectedClients(),
+        input.host.supportedClients(),
         input.host.detectedClients(),
         input.host.skillNeedsInstall(),
     ]);
@@ -85,7 +84,7 @@ export const planSetupActions = async (input) => {
     });
     const inspections = await Promise.all(selectedClients.map(async (client) => ({
         client,
-        inspection: (await input.host.inspectClientConfiguration?.(client, input.providerEnvironment, input.command)) ?? { status: "update" },
+        inspection: await input.host.inspectClientConfiguration(client, input.providerEnvironment, input.command),
     })));
     const invalid = inspections.find(({ inspection }) => inspection.status === "invalid");
     if (invalid?.inspection.status === "invalid") {
@@ -96,9 +95,11 @@ export const planSetupActions = async (input) => {
             blocker: `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`,
         };
     }
-    const clientPlans = inspections.flatMap(({ client, inspection }) => inspection.status === "create" ||
-        inspection.status === "update" ||
-        (input.discovery.installHopper && inspection.status === "already_current")
+    const clientPlans = inspections.flatMap(({ client, inspection }) => client.format !== "unsupported" &&
+        (inspection.status === "create" ||
+            inspection.status === "update" ||
+            (input.discovery.installHopper &&
+                inspection.status === "already_current"))
         ? [
             {
                 client,
@@ -115,6 +116,7 @@ export const planSetupActions = async (input) => {
     return {
         plannedActions: setupPlan({
             platform: input.host.platform,
+            homeDirectory: input.host.homeDirectory,
             installHopper: input.discovery.installHopper,
             installSkill: input.installSkill,
             clients: clientPlans,
@@ -137,7 +139,7 @@ const setupPlan = (input) => [
                 kind: "install_hopper",
                 label: "Hopper deep-analysis provider",
                 target: input.platform === "darwin"
-                    ? join(homedir(), "Applications/Hopper Disassembler.app")
+                    ? join(input.homeDirectory, "Applications/Hopper Disassembler.app")
                     : "system package manager",
                 detail: input.platform === "linux"
                     ? "Download, verify, and install Hopper plus its Xvfb demo-session dependencies. For the supported demo build, REA uses a private display and selects Hopper's offered demo mode for each analysis session."
@@ -173,7 +175,7 @@ const setupPlan = (input) => [
                 id: "install_skill",
                 kind: "install_skill",
                 label: "REA reverse-engineering skill",
-                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName),
+                target: join(input.homeDirectory, ".agents/skills", PRODUCT_IDENTITY.skillName),
                 detail: "Install or update the bundled REA reverse-engineering skill and on-demand references.",
                 external: false,
                 operation: "install",

package/dist/application/SupportedClients.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { lstatSync } from "node:fs";
 const vscodeUserDirectory = ({ home, platform, env, }) => {
     if (platform === "win32")
@@ -17,6 +17,23 @@ const claudeDesktopDirectory = ({ home, platform, env, }) => {
 const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? home;
 const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 const codexDirectory = ({ home, env }) => env.CODEX_HOME ?? join(home, ".codex");
+const grokDirectory = ({ home, env }) => env.GROK_HOME ?? join(home, ".grok");
+/** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
+const grokBotDirectory = ({ home, env }) => {
+    const root = env.SAND_DATA_ROOT;
+    return root !== undefined && root !== "" && isAbsolute(root)
+        ? root
+        : join(home, ".grokbot");
+};
+/**
+ * Grok Bot stores connectors in the signed-in account and runs them on its
+ * hosted computer. The data directory is only a detection marker.
+ */
+export const GROK_BOT_MANUAL_REGISTRATION_REMEDIATION = "Grok Bot keeps connectors in the signed-in account and runs them on its hosted computer. Setup does not write that account store, and a data-directory mcp.json is not a registration. In the Grok Bot chat, add a custom MCP server named rea that runs on the Bot's computer with `npx -y rea-agents@<version> mcp`. Do not put credentials in the command or arguments. A stdio server on this machine is not attached.";
+/** Remediation for a client whose connector is not a local configuration file. */
+export const manualRegistrationRemediation = (clientName) => clientName === "grok_bot"
+    ? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION
+    : undefined;
 const copilotDirectory = ({ home, env }) => env.COPILOT_HOME ?? join(home, ".copilot");
 const commandCodeDirectory = ({ home }) => join(home, ".commandcode");
 const opencodeDirectory = ({ home, env }) => join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode");
@@ -133,6 +150,20 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
         markerPath: vscodeUserDirectory,
         format: "vscode",
     },
+    {
+        name: "grok_build",
+        displayName: "Grok Build",
+        configPath: (context) => join(grokDirectory(context), "config.toml"),
+        markerPath: grokDirectory,
+        format: "grok",
+    },
+    {
+        name: "grok_bot",
+        displayName: "Grok Bot",
+        configPath: grokBotDirectory,
+        markerPath: grokBotDirectory,
+        format: "unsupported",
+    },
 ];
 const resolvePath = (path, context) => typeof path === "function" ? path(context) : join(context.home, ...path);
 /** Describe every client location that setup, doctor, or uninstall may inspect. */
@@ -141,7 +172,9 @@ export const supportedClients = (home, platform = process.platform, env = {
     CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
     CODEX_HOME: process.env.CODEX_HOME,
     COPILOT_HOME: process.env.COPILOT_HOME,
+    GROK_HOME: process.env.GROK_HOME,
     OPENCODE_CONFIG: process.env.OPENCODE_CONFIG,
+    SAND_DATA_ROOT: process.env.SAND_DATA_ROOT,
     XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
 }) => {
     const context = { home, platform, env };