rea-agents 6.1.0 → 6.2.0

package/dist/application/EnhancedTools.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { addressDistance, functionDossierSchema, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
@@ -179,20 +179,34 @@ export class EnhancedTools {
     }
     async #batchDecompile(addresses, signal) {
         const items = await Promise.all(addresses.map(async (address) => {
-            const result = await this.#call("procedure_pseudo_code", { procedure: address }, signal);
+            const resolved = await resolveProcedureAddress(this.#call.bind(this), address, signal);
+            const procedure = resolved.ok
+                ? await this.#batchProcedureIdentity(resolved.value, signal)
+                : {
+                    status: "unknown",
+                    error: projectAnalysisError(resolved.error),
+                };
+            const result = await this.#call("procedure_pseudo_code", { procedure: resolved.ok ? resolved.value : address }, signal);
             if (!result.ok)
                 return {
                     address,
+                    procedure,
                     status: "error",
                     error: projectAnalysisError(result.error),
                 };
             if (typeof result.value !== "string" || result.value.length === 0)
                 return {
                     address,
+                    procedure,
                     status: "error",
                     error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
                 };
-            return { address, status: "ok", pseudocode: result.value };
+            return {
+                address,
+                procedure,
+                status: "ok",
+                pseudocode: result.value,
+            };
         }));
         const succeeded = items.filter(({ status }) => status === "ok").length;
         return ok({
@@ -202,6 +216,23 @@ export class EnhancedTools {
             failed: items.length - succeeded,
         });
     }
+    async #batchProcedureIdentity(address, signal) {
+        const observed = await this.#call("address_name", { address }, signal);
+        const named = observed.ok &&
+            (typeof observed.value === "string" || observed.value === null);
+        return {
+            status: "resolved",
+            address,
+            name: named ? observed.value : null,
+            ...(named
+                ? {}
+                : {
+                    name_error: projectAnalysisError(observed.ok
+                        ? new AnalysisOutputError("address_name", "provider returned an invalid entry label")
+                        : observed.error),
+                }),
+        };
+    }
     async #callGraph(input, signal) {
         const relation = input.direction === "forward" ? "callees" : "callers";
         const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
@@ -254,9 +285,23 @@ export class EnhancedTools {
     }
     async #analyzeSwiftTypes(input, signal) {
         const procedures = await this.#allAddressed("list_procedures", signal);
-        return procedures.ok
-            ? ok(categorizeSwiftTypes(procedures.value, input))
-            : procedures;
+        if (!procedures.ok)
+            return procedures;
+        const symbols = await this.#allAddressed("list_names", signal);
+        if (!symbols.ok &&
+            !(symbols.error instanceof AnalysisCapabilityUnavailableError))
+            return symbols;
+        const result = categorizeSwiftTypes(procedures.value, input, symbols.ok ? symbols.value : []);
+        return ok(symbols.ok
+            ? result
+            : {
+                ...result,
+                symbol_inventory_error: projectAnalysisError(symbols.error),
+                limitations: [
+                    ...result.limitations,
+                    "The provider's symbol inventory is unavailable; demangled procedures could not be joined to their Swift aliases.",
+                ],
+            });
     }
     async #findXrefs(name, signal) {
         const names = await this.#allAddressed("list_names", signal);

package/dist/application/EvidenceBundleFiles.js

@@ -1,7 +1,8 @@
 import { describeEvidenceBundleFailure, describeValidationFailure, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { err, ok } from "../domain/result.js";
-import { parseProcessCapture } from "../domain/process/processCapture.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
 import { bufferedJsonParts, canonicalJsonParts, } from "../domain/jsonSerialization.js";
 import { readJsonFile, writeTextParts } from "./JsonFiles.js";
 /** Read and validate an evidence bundle at the caller-supplied path. */
@@ -35,7 +36,9 @@ export const readEvidenceBundle = async (path) => {
     return ok(bundle);
 };
 /** Atomically write deterministic evidence JSON at the caller-supplied path. */
-export const writeEvidenceBundle = async (bundle, path, overwrite) => {
+export const writeEvidenceBundle = async (bundle, path, overwrite, signal) => {
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError("export_evidence_bundle"));
     let checked;
     try {
         checked = parseEvidenceBundle(bundle);
@@ -45,5 +48,7 @@ export const writeEvidenceBundle = async (bundle, path, overwrite) => {
             cause,
         }));
     }
-    return writeTextParts(bufferedJsonParts(canonicalJsonParts(checked)), path, overwrite);
+    return writeTextParts(bufferedJsonParts(canonicalJsonParts(checked)), path, overwrite, signal === undefined
+        ? undefined
+        : { signal, operation: "export_evidence_bundle" });
 };

package/dist/application/InvestigationProviders.js

@@ -8,7 +8,9 @@ export const REA_WORKFLOW_PROVIDER = {
 /** Commit a workflow result to its upstream profile and applicable semantic revision. */
 export const workflowAnalysisProfile = (upstream, operation) => createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
     upstream_analysis_profile: upstream,
-    ...(operation === "binary_overview" ? { workflow_revision: 2 } : {}),
+    ...(operation === "binary_overview" || operation === "batch_decompile"
+        ? { workflow_revision: 2 }
+        : {}),
 });
 /** Provider identity for deterministic artifact inventories. */
 export const ARTIFACT_GRAPH_PROVIDER = {
@@ -58,6 +60,12 @@ export const JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER = {
     name: "REA JavaScript runtime reconciliation",
     version: "1",
 };
+/** Provider identity for selected views of retained analysis Evidence. */
+export const ANALYSIS_VIEW_PROVIDER = {
+    id: "rea-analysis-view",
+    name: "REA analysis view projection",
+    version: "1",
+};
 /** Provider identity for graph-native feature tracing and version comparison. */
 export const JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER = {
     id: "rea-javascript-application-workflows",

package/dist/application/JsonFiles.js

@@ -1,6 +1,7 @@
 import { link, lstat, mkdtemp, open, readFile, realpath, rename, rm, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { EvidenceFileError } from "../domain/evidenceErrors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
 export const readJsonFile = async (path) => {
@@ -32,10 +33,10 @@ export const readJsonFile = async (path) => {
 };
 /** Atomically write text to the caller-supplied path. */
 export const writeTextFile = async (encoded, path, overwrite) => writeTextParts([encoded], path, overwrite);
-/** Publish complete streamed text atomically, keeping only one encoded part in memory. */
-export const writeTextParts = async (parts, path, overwrite) => {
+export async function writeTextParts(parts, path, overwrite, cancellation) {
     const requestedPath = resolve(path);
     try {
+        assertWriteActive(cancellation);
         const canonicalParent = await realpath(dirname(requestedPath));
         const destination = resolve(canonicalParent, basename(requestedPath));
         const existing = await lstat(destination).catch((cause) => {
@@ -49,10 +50,15 @@ export const writeTextParts = async (parts, path, overwrite) => {
             if (!existing.isFile() || existing.isSymbolicLink())
                 return err(new EvidenceFileError("write", "not-file", { path: requestedPath }));
         }
-        const bytes = await publishFile(destination, parts, overwrite);
+        assertWriteActive(cancellation);
+        const bytes = await publishFile(destination, parts, overwrite, cancellation);
         return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
+        if (cancellation?.signal.aborted === true &&
+            cause instanceof AnalysisCancelledError &&
+            cause.operation === cancellation.operation)
+            return err(cause);
         if (!overwrite && fileErrorCode(cause) === "EEXIST")
             return err(new EvidenceFileError("write", "exists", {
                 cause,
@@ -63,28 +69,28 @@ export const writeTextParts = async (parts, path, overwrite) => {
             path: requestedPath,
         }));
     }
-};
+}
 /** A missing path or parent is a selection error, not a permission failure. */
 const missingOrIo = (cause) => {
     const code = fileErrorCode(cause);
     return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "io";
 };
-const publishFile = async (destination, parts, overwrite) => {
+const publishFile = async (destination, parts, overwrite, cancellation) => {
     const stagingDirectory = await mkdtemp(resolve(dirname(destination), ".rea-write-"));
     try {
         const staged = resolve(stagingDirectory, "content");
         const file = await open(staged, "wx", 0o600);
         let bytes = 0;
         try {
-            for (const part of parts) {
-                await file.writeFile(part, { encoding: "utf8" });
-                bytes += Buffer.byteLength(part, "utf8");
-            }
+            bytes = await writeStagedParts(file, parts, cancellation);
+            assertWriteActive(cancellation);
             await file.sync();
         }
         finally {
             await file.close();
         }
+        // Once submitted, the atomic publication can win a later cancellation race.
+        assertWriteActive(cancellation);
         if (overwrite)
             await rename(staged, destination);
         // A hard link publishes complete bytes atomically and cannot replace an existing name.
@@ -96,6 +102,33 @@ const publishFile = async (destination, parts, overwrite) => {
         await rm(stagingDirectory, { recursive: true, force: true });
     }
 };
+const writeStagedParts = async (file, parts, cancellation) => {
+    assertWriteActive(cancellation);
+    const iterator = parts[Symbol.iterator]();
+    let exhausted = false;
+    let bytes = 0;
+    try {
+        for (;;) {
+            assertWriteActive(cancellation);
+            const part = iterator.next();
+            if (part.done)
+                exhausted = true;
+            assertWriteActive(cancellation);
+            if (part.done)
+                return bytes;
+            await file.writeFile(part.value, { encoding: "utf8" });
+            bytes += Buffer.byteLength(part.value, "utf8");
+        }
+    }
+    finally {
+        if (!exhausted)
+            iterator.return?.();
+    }
+};
+const assertWriteActive = (cancellation) => {
+    if (cancellation?.signal.aborted === true)
+        throw new AnalysisCancelledError(cancellation.operation);
+};
 const fileErrorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
     ? cause.code
     : undefined;

package/dist/application/LinuxHopper.js

@@ -84,7 +84,7 @@ export const readLinuxDistribution = async () => {
     }
 };
 /** Download, verify, install, and read back the official Hopper Linux package. */
-export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(), options = {}) => {
+export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(process.env), options = {}) => {
     if (options.signal?.aborted === true)
         return { status: "failed", reason: "cancelled" };
     const distribution = await host.distribution();
@@ -124,7 +124,8 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
 };
 /** Canonical launcher path for a legacy user-local Linux Hopper installation. */
 export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/hopper/bin/Hopper");
-const systemLinuxHopperInstallHost = () => ({
+/** Compose package-manager and linker checks from the selected caller environment. */
+export const systemLinuxHopperInstallHost = (environment) => ({
     distribution: readLinuxDistribution,
     async download(url, options) {
         const response = await fetch(url, {
@@ -138,11 +139,11 @@ const systemLinuxHopperInstallHost = () => ({
     },
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
-    installPackage: installSystemPackage,
+    installPackage: (family, archive) => installSystemPackage(family, archive, environment),
     async launcherStatus(path) {
         try {
             await access(path);
-            const linked = await execFileOutput("ldd", [path]);
+            const linked = await execFileOutput("ldd", [path], { env: environment });
             if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
                 return "runtime_dependencies";
             return (await linuxHopperBinarySupported(path))
@@ -175,10 +176,12 @@ export const linuxHopperBinarySupported = async (path) => {
 export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_SHA256.has(digest);
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
-const installSystemPackage = async (family, archive) => {
+const installSystemPackage = async (family, archive, environment) => {
     try {
         for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
-            await execFileAsync(command.executable, command.args);
+            await execFileAsync(command.executable, command.args, {
+                env: environment,
+            });
         return true;
     }
     catch (cause) {

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/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/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/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,7 +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 = [];
@@ -13,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 &&
@@ -52,7 +44,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             discovery,
             host,
             providerEnvironment,
-            command: setupRegistrationCommand(host.platform),
+            command: host.registrationCommand,
             clientIds: [],
             installSkill: offerSkillAction,
         });
@@ -92,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,
     });
@@ -175,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
@@ -241,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) => {

package/dist/application/SetupHost.js

@@ -1,19 +1,18 @@
 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
+export const setupRegistrationCommand = (platform, useNpmRunner) => useNpmRunner
     ? npxRegistrationCommand(platform)
     : platform === "win32"
         ? [
@@ -26,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.`;
@@ -48,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 {
@@ -71,25 +69,16 @@ 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),
@@ -97,15 +86,15 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
             ? 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),