rea-agents 6.1.0 → 6.3.0

package/dist/native/LldbCallTracer.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { randomUUID } from "node:crypto";
 import { open, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -5,19 +6,22 @@ import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { nativeCallEventSchema, nativeCodeLocationSchema, } from "../domain/native/nativeCallObservation.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
-import { observeProcessStartIdentity, prepareProcessOwnershipInspection, signalProcessWithStartIdentity, } from "../process/ProcessOwnershipObservation.js";
+import { observeProcessStartIdentity, signalProcessWithStartIdentity, } from "../process/ProcessOwnershipObservation.js";
 import { ProviderStartupDeadline, waitForAbortableDelay, } from "../process/ProviderDeadline.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { resolveXcrunTool } from "./CommandRunner.js";
 import { readLldbObservationJournal, readBoundedPrefix, readPartialCapture, projectLldbPartialObservation, } from "./LldbRetainedObservations.js";
 const OPERATION = "observe_native_calls";
 const PROVIDER = "native-macos";
+const LLDB_REQUIREMENT = "LLDB from Xcode or the Command Line Tools is not available";
 /** Captured target output kept per stream; the rest is counted, not stored. */
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 /** LLDB startup, symbol loading and teardown beyond the observation window. */
@@ -90,36 +94,148 @@ const ATTACH_REMEDIATION = "Allow debugging for this user (Developer Tools acces
 export class LldbCallTracer {
     launch;
     resolveTool;
-    constructor(launch = runLldb, resolveTool = resolveXcrunTool) {
+    environment;
+    #tail = Promise.resolve();
+    #pendingCleanup;
+    constructor(environment, launch = runLldb, resolveTool = (tool, signal) => resolveXcrunTool(tool, this.environment, signal)) {
         this.launch = launch;
         this.resolveTool = resolveTool;
+        this.environment = snapshotEnvironment(environment);
     }
     async trace(request, signal) {
+        return this.#serialize(() => this.#trace(request, signal));
+    }
+    async #trace(request, signal) {
+        const pendingCleanup = await this.#retryPendingCleanup();
+        if (pendingCleanup !== undefined)
+            return err(pendingCleanup);
         const lldb = await this.resolveTool("lldb", signal);
         if (!lldb.ok)
             return err(lldb.error.reason === "cancelled"
                 ? new AnalysisCancelledError(OPERATION)
-                : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, "LLDB from Xcode or the Command Line Tools is not available"));
+                : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, LLDB_REQUIREMENT, { userMessage: LLDB_REQUIREMENT }));
         const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
+        const paths = lldbRuntimePaths(root.path);
+        let result;
         try {
-            return await this.#run(lldb.value, root.path, request, signal);
+            result = await this.#run(lldb.value, root, request, signal);
         }
-        finally {
+        catch (cause) {
+            const partialObservation = await partialNativeObservation({
+                request,
+                pidPath: paths.pid,
+                stdoutPath: paths.stdoutCapture,
+                stderrPath: paths.stderrCapture,
+                observationPath: paths.observations,
+                version: null,
+                reason: "tracer-failure",
+            });
+            const retained = this.#pendingCleanup;
+            const resources = retained === undefined ? [] : await lldbCleanupResources(retained);
+            result = err(new ProviderAdapterError(PROVIDER, OPERATION, {
+                cause,
+                diagnostics: {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                },
+                partialObservation,
+                ...(retained === undefined
+                    ? {}
+                    : {
+                        cleanup: {
+                            reason: "LLDB trace failed while owned resources remain",
+                            resources,
+                        },
+                    }),
+            }));
+        }
+        if (this.#pendingCleanup?.root === root)
+            return result;
+        try {
             await root.close();
         }
+        catch (cause) {
+            this.#pendingCleanup = {
+                root,
+                supervisor: undefined,
+                pidPath: paths.pid,
+                targetIdentity: undefined,
+                processStopped: true,
+                targetStopped: true,
+            };
+            const partialObservation = result.ok
+                ? partialObservationFromTrace(request, result.value)
+                : result.error.partialObservation;
+            return err(new ProviderCleanupError(PROVIDER, [root.path], {
+                reason: cause instanceof Error ? cause.message : String(cause),
+                ...(result.ok
+                    ? {}
+                    : {
+                        execution_failure: projectAnalysisError(result.error).code,
+                        primary_failure: result.error.message,
+                    }),
+            }, {
+                operation: OPERATION,
+                cause: result.ok
+                    ? cause
+                    : new AggregateError([result.error, cause], "LLDB trace and runtime cleanup both failed"),
+                ...(partialObservation === undefined ? {} : { partialObservation }),
+            }));
+        }
+        return result;
     }
-    async #run(lldb, directory, request, signal) {
-        const paths = {
-            config: join(directory, "config.json"),
-            result: join(directory, "result.json"),
-            pid: join(directory, "pid"),
-            identityAck: join(directory, "identity.ack"),
-            stdout: join(directory, "stdout"),
-            stderr: join(directory, "stderr"),
-            stdoutCapture: join(directory, "stdout.capture"),
-            stderrCapture: join(directory, "stderr.capture"),
-            observations: join(directory, "observations.jsonl"),
-        };
+    /** Retry retained LLDB cleanup without abandoning its process or runtime owner. */
+    async close() {
+        return this.#serialize(() => this.#close());
+    }
+    async #close() {
+        const failure = await this.#retryPendingCleanup();
+        return failure === undefined ? ok(null) : err(failure);
+    }
+    #serialize(operation) {
+        const call = this.#tail.then(operation, operation);
+        this.#tail = call.then(() => undefined, () => undefined);
+        return call;
+    }
+    async #retryPendingCleanup() {
+        const owner = this.#pendingCleanup;
+        if (owner === undefined)
+            return undefined;
+        let firstFailure;
+        if (!owner.processStopped) {
+            const stopped = await owner.supervisor?.stop();
+            if (stopped?.status === "incomplete")
+                firstFailure = stopped.reason;
+            else {
+                owner.supervisor?.dispose();
+                owner.processStopped = true;
+            }
+        }
+        if (firstFailure === undefined && !owner.targetStopped) {
+            const targetTermination = await ensureTerminated(owner.pidPath, owner.targetIdentity, true);
+            if (targetTermination !== "terminated")
+                firstFailure = targetTerminationReason(targetTermination);
+            else
+                owner.targetStopped = true;
+        }
+        if (firstFailure === undefined) {
+            try {
+                await owner.root.close();
+                this.#pendingCleanup = undefined;
+                return undefined;
+            }
+            catch (cause) {
+                firstFailure = cause instanceof Error ? cause.message : String(cause);
+            }
+        }
+        const resources = await lldbCleanupResources(owner);
+        return new ProviderCleanupError(PROVIDER, resources, {
+            reason: firstFailure ?? "LLDB cleanup remains incomplete",
+            resources,
+        }, { operation: OPERATION });
+    }
+    async #run(lldb, root, request, signal) {
+        const directory = root.path;
+        const paths = lldbRuntimePaths(directory);
         const { input } = request;
         await writeFile(paths.config, JSON.stringify({
             executable: request.executable,
@@ -145,7 +261,6 @@ export class LldbCallTracer {
             identity_ack_path: paths.identityAck,
             observation_path: paths.observations,
         }), { mode: 0o600 });
-        await prepareProcessOwnershipInspection(signal);
         const exited = await this.launch(lldb.path, [
             "--batch",
             "--no-lldbinit",
@@ -158,18 +273,33 @@ export class LldbCallTracer {
             deadlineMs: input.duration_ms + DEADLINE_GRACE_MS,
             pidPath: paths.pid,
             identityAckPath: paths.identityAck,
+            environment: this.environment,
             ...(signal === undefined ? {} : { signal }),
         });
+        const retained = {
+            root,
+            supervisor: exited.cleanupOwner,
+            pidPath: paths.pid,
+            targetIdentity: exited.targetIdentity,
+            processStopped: exited.cleanupOwner === undefined,
+            targetStopped: !exited.targetLaunched,
+        };
+        this.#pendingCleanup = retained;
         const output = exited.kind === "exited"
             ? await readTracerOutput(paths.result)
             : undefined;
-        let targetTermination = await ensureTerminated(paths.pid, exited.targetIdentity, true);
+        let targetTermination = exited.targetLaunched
+            ? await ensureTerminated(paths.pid, exited.targetIdentity, true)
+            : "terminated";
         // These two bridge outcomes are emitted before a target process exists.
         // Other missing-PID cases, including a missing result, remain unknown.
         if (output !== undefined &&
             (output.status === "target-error" || output.status === "launch-error") &&
             (await readTargetPid(paths.pid)) === undefined)
             targetTermination = "terminated";
+        retained.targetStopped = targetTermination === "terminated";
+        if (retained.processStopped && retained.targetStopped)
+            this.#pendingCleanup = undefined;
         const terminated = targetTermination === "terminated";
         const cleanupDetails = [
             exited.cleanupFailure,
@@ -179,16 +309,7 @@ export class LldbCallTracer {
             ? undefined
             : {
                 reason: cleanupDetails.join("; "),
-                resources: [
-                    ...(exited.cleanupFailure === undefined
-                        ? []
-                        : ["lldb-process-group"]),
-                    ...(terminated
-                        ? []
-                        : [
-                            `native-target:${String((await readTargetPid(paths.pid)) ?? "unknown")}`,
-                        ]),
-                ],
+                resources: await lldbCleanupResources(retained),
             };
         const partialReason = exited.kind === "cancelled"
             ? "cancelled"
@@ -223,18 +344,24 @@ export class LldbCallTracer {
         if (output !== undefined && output.status !== "traced")
             return err(tracerFailure(output, lifecycleCleanup, await getPartialObservation()));
         if (exited.cleanupFailure !== undefined)
-            return err(new ProviderAdapterError(PROVIDER, OPERATION, {
-                cleanup: lifecycleCleanup ?? {
-                    reason: exited.cleanupFailure,
-                    resources: ["lldb-process-group"],
-                },
-                diagnostics: {
-                    reason: "LLDB process-group cleanup could not be verified",
-                    cleanup_failure: exited.cleanupFailure,
-                    ...(lifecycleCleanup === undefined
-                        ? {}
-                        : { target_cleanup: lifecycleCleanup }),
-                },
+            return err(new ProviderCleanupError(PROVIDER, await lldbCleanupResources(retained), {
+                reason: "LLDB process-group cleanup could not be verified",
+                cleanup_failure: exited.cleanupFailure,
+                ...(lifecycleCleanup === undefined
+                    ? {}
+                    : { target_cleanup: lifecycleCleanup }),
+            }, {
+                operation: OPERATION,
+                partialObservation: await getPartialObservation(),
+            }));
+        if (!terminated)
+            return err(new ProviderCleanupError(PROVIDER, await lldbCleanupResources(retained), {
+                reason: "LLDB target process termination could not be verified",
+                ...(lifecycleCleanup === undefined
+                    ? {}
+                    : { target_cleanup: lifecycleCleanup }),
+            }, {
+                operation: OPERATION,
                 partialObservation: await getPartialObservation(),
             }));
         if (output === undefined)
@@ -340,6 +467,37 @@ const partialNativeObservation = async (options) => {
         reason: options.reason,
     });
 };
+const partialObservationFromTrace = (request, trace) => projectLldbPartialObservation({
+    target: {
+        path: request.executable,
+        sha256: request.expectedSha256,
+        architecture: request.architecture,
+        arguments: request.input.arguments,
+        environment: request.input.environment,
+        working_directory: request.input.working_directory ?? null,
+    },
+    pid: trace.run.pid,
+    stdout: trace.stdout,
+    stderr: trace.stderr,
+    version: trace.run.version,
+    journal: {
+        events: trace.run.events,
+        otherStops: trace.run.other_stops,
+        limitations: [],
+    },
+    reason: "cleanup-failure",
+});
+const lldbRuntimePaths = (directory) => ({
+    config: join(directory, "config.json"),
+    result: join(directory, "result.json"),
+    pid: join(directory, "pid"),
+    identityAck: join(directory, "identity.ack"),
+    stdout: join(directory, "stdout"),
+    stderr: join(directory, "stderr"),
+    stdoutCapture: join(directory, "stdout.capture"),
+    stderrCapture: join(directory, "stderr.capture"),
+    observations: join(directory, "observations.jsonl"),
+});
 const readTracerOutput = async (path) => {
     let text;
     try {
@@ -384,17 +542,43 @@ const capturedOutput = async (path, observedBytes, truncated, complete) => {
         return err(failure);
     }
 };
+const lldbCleanupResources = async (owner) => [
+    ...(owner.processStopped ? [] : ["lldb-process-group"]),
+    ...(owner.targetStopped
+        ? []
+        : [
+            `native-target:${String((await readTargetPid(owner.pidPath)) ?? "unknown")}`,
+        ]),
+    owner.root.path,
+];
 /** Supervise LLDB as an owned process group while observing its target PID identity. */
 const runLldb = async (executable, arguments_, options) => {
     if (options.signal?.aborted === true)
         return {
             kind: "cancelled",
+            targetLaunched: false,
             targetIdentity: undefined,
             cleanupFailure: undefined,
         };
     const deadline = new ProviderStartupDeadline(options.deadlineMs, options.signal);
     let targetIdentity;
     let supervisor;
+    let retained = false;
+    const finish = async (outcome) => {
+        const stopped = await supervisor?.stop();
+        retained = stopped?.status === "incomplete";
+        return {
+            ...(deadline.interruption === undefined
+                ? outcome
+                : { kind: deadline.interruption }),
+            targetLaunched: supervisor !== undefined,
+            targetIdentity,
+            cleanupFailure: stopped?.status === "incomplete" ? stopped.reason : undefined,
+            ...(retained && supervisor !== undefined
+                ? { cleanupOwner: supervisor }
+                : {}),
+        };
+    };
     try {
         const launched = await spawnOwnedProviderProcess({
             command: executable,
@@ -402,6 +586,7 @@ const runLldb = async (executable, arguments_, options) => {
             runId: randomUUID(),
             expectedCommand: executable,
             signal: deadline.signal,
+            hostEnvironment: options.environment,
         });
         supervisor = new ProviderProcessSupervisor({
             ...launched,
@@ -425,49 +610,33 @@ const runLldb = async (executable, arguments_, options) => {
                 identityAckWritten = true;
             }
             const interruption = deadline.interruption;
-            if (interruption !== undefined) {
-                const stopped = await supervisor.stop();
-                const cleanupFailure = stopped.status === "incomplete" ? stopped.reason : undefined;
-                return interruption === "cancelled"
-                    ? { kind: "cancelled", targetIdentity, cleanupFailure }
-                    : { kind: "timeout", targetIdentity, cleanupFailure };
-            }
+            if (interruption !== undefined)
+                return await finish({ kind: interruption });
             await waitForAbortableDelay(20, deadline.signal);
         }
         const snapshot = supervisor.snapshot();
-        const stopped = await supervisor.stop();
-        const cleanupFailure = stopped.status === "incomplete" ? stopped.reason : undefined;
         const interruption = deadline.interruption;
-        if (interruption === "cancelled")
-            return { kind: "cancelled", targetIdentity, cleanupFailure };
-        if (interruption === "timeout")
-            return { kind: "timeout", targetIdentity, cleanupFailure };
-        return {
-            kind: "exited",
-            exitCode: snapshot.exitCode ?? null,
-            output: `${snapshot.stdout.text}${snapshot.stderr.text}`.slice(-DIAGNOSTIC_BYTES),
-            targetIdentity,
-            cleanupFailure,
-        };
+        return await finish(interruption === undefined
+            ? {
+                kind: "exited",
+                exitCode: snapshot.exitCode ?? null,
+                output: `${snapshot.stdout.text}${snapshot.stderr.text}`.slice(-DIAGNOSTIC_BYTES),
+            }
+            : { kind: interruption });
     }
     catch (cause) {
         const interruption = deadline.interruption;
-        const stopped = await supervisor?.stop();
-        const cleanupFailure = stopped?.status === "incomplete" ? stopped.reason : undefined;
-        return interruption === "timeout"
-            ? { kind: "timeout", targetIdentity, cleanupFailure }
-            : interruption === "cancelled"
-                ? { kind: "cancelled", targetIdentity, cleanupFailure }
-                : {
-                    kind: "exited",
-                    exitCode: null,
-                    output: cause instanceof Error ? cause.message : String(cause),
-                    targetIdentity,
-                    cleanupFailure,
-                };
+        return await finish(interruption === undefined
+            ? {
+                kind: "exited",
+                exitCode: null,
+                output: cause instanceof Error ? cause.message : String(cause),
+            }
+            : { kind: interruption });
     }
     finally {
-        supervisor?.dispose();
+        if (!retained)
+            supervisor?.dispose();
         deadline.dispose();
     }
 };
@@ -477,8 +646,11 @@ const runLldb = async (executable, arguments_, options) => {
  */
 const readTargetPid = async (pidPath) => {
     try {
-        const pid = Number.parseInt(await readFile(pidPath, "utf8"), 10);
-        return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+        const contents = (await readFile(pidPath, "utf8")).trim();
+        if (!/^[1-9]\d*$/u.test(contents))
+            return undefined;
+        const pid = Number(contents);
+        return Number.isSafeInteger(pid) ? pid : undefined;
     }
     catch {
         return undefined;

package/dist/native/NativeMacOSProvider.js

@@ -1,5 +1,5 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY, nativeMacOSCapabilities, } from "./NativeMacOSProviderMetadata.js";
-export { NATIVE_MACOS_PROVIDER_IDENTITY } from "./NativeMacOSProviderMetadata.js";
 import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
 import { observeNativeUi } from "./NativeUiObservation.js";
 import { LldbCallTracer } from "./LldbCallTracer.js";
@@ -9,6 +9,8 @@ import { open, realpath, stat } from "node:fs/promises";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { NATIVE_TOOL_CONTRACTS, } from "../contracts/native/nativeToolContracts.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -27,11 +29,14 @@ import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspect
 /** Read-only semantic provider composed from Xcode command-line utilities. */
 export class NativeMacOSProvider {
     runner;
-    tracer;
     #capabilities;
-    constructor(runner = new XcrunCommandRunner(), platform = process.platform, tracer = new LldbCallTracer()) {
+    #environment;
+    #tracerFactory;
+    constructor(environment, runner = new XcrunCommandRunner(environment), platform = process.platform, tracerFactory) {
         this.runner = runner;
-        this.tracer = tracer;
+        this.#environment = snapshotEnvironment(environment, platform);
+        this.#tracerFactory =
+            tracerFactory ?? (() => new LldbCallTracer(this.#environment));
         this.#capabilities = nativeMacOSCapabilities(platform);
     }
     identity() {
@@ -41,17 +46,19 @@ export class NativeMacOSProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new NativeMacOSClient(target, this.runner, this.tracer);
+        return new NativeMacOSClient(target, this.runner, this.#tracerFactory(), this.#environment);
     }
 }
 class NativeMacOSClient {
     target;
     runner;
     tracer;
-    constructor(target, runner, tracer) {
+    environment;
+    constructor(target, runner, tracer, environment) {
         this.target = target;
         this.runner = runner;
         this.tracer = tracer;
+        this.environment = environment;
     }
     async execute(operation, parameters, options) {
         if (options?.signal?.aborted === true)
@@ -59,16 +66,15 @@ class NativeMacOSClient {
         if (operation === "health")
             return ok(createAnalysisExecution(null, IDENTITY));
         if (operation === "inspect_native_dispatch_metadata") {
+            const input = toolContract(operation).inputSchema.safeParse(parameters);
+            if (!input.success)
+                return err(analysisInputErrorFromIssues(operation, input.error.issues, parameters, {
+                    cause: input.error,
+                }));
             if (this.target.kind !== "executable" || this.target.format !== "mach-o")
                 return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Binary Apple metadata requires Mach-O; other providers can report symbol-only metadata"));
             try {
-                const maxRecords = z
-                    .number()
-                    .int()
-                    .min(1)
-                    .max(20000)
-                    .parse(parameters.max_records ?? 5000);
-                const result = await inspectAppleDispatchMetadata(this.target, maxRecords, options?.signal);
+                const result = await inspectAppleDispatchMetadata(this.target, input.data.max_records, options?.signal);
                 return ok(createAnalysisExecution(result, result.provider, {
                     locations: [{ kind: "artifact-path", path: this.target.path }],
                     limitations: result.result.coverage.flatMap(({ reason }) => reason === null ? [] : [reason]),
@@ -102,6 +108,7 @@ class NativeMacOSClient {
         if (operation === "observe_native_ui" ||
             operation === "capture_native_ui_scenario") {
             const result = await observeNativeUi(this.target, operation, parameters, {
+                environment: this.environment,
                 signal: options?.signal,
             });
             return result.ok
@@ -127,7 +134,7 @@ class NativeMacOSClient {
         }
     }
     close() {
-        return Promise.resolve();
+        return this.tracer.close();
     }
     #dispatch(operation, parameters, signal) {
         switch (operation) {
@@ -148,6 +155,10 @@ class NativeMacOSClient {
         }
     }
     async #listArchitectures(signal) {
+        // lipo reads only Mach-O; its refusal of a PE, ELF, or plist target is not
+        // a tool failure that a retry or `rea doctor` could repair.
+        if (this.target.format !== "mach-o")
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, "list_architectures", "Active artifact is not Mach-O."));
         const capture = await this.#run("list_architectures", "lipo", ["-detailed_info", this.target.path], { signal });
         if (!capture.ok)
             return capture;
@@ -424,8 +435,10 @@ const translateCommandFailure = (operation, failure) => {
         ...(capturedOutput === undefined ? {} : { capturedOutput }),
         ...(cleanup === undefined ? {} : { cleanup }),
     };
-    if (failure.reason === "unavailable")
-        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`, errorOptions);
+    if (failure.reason === "unavailable") {
+        const reason = `${failure.tool} is unavailable through xcrun.`;
+        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, reason, { ...errorOptions, userMessage: reason });
+    }
     if (failure.reason === "cancelled")
         return new AnalysisCancelledError(operation, errorOptions);
     if (failure.reason === "timeout")
@@ -513,8 +526,10 @@ const parseEntitlements = (output) => {
  */
 const unreadablePlist = (path, requested, reason) => {
     const sentence = reason.endsWith(".") ? reason : `${reason}.`;
+    // Name the default that is missing and the selection that still works.
+    const missingDefault = `The target has no readable Contents/Info.plist at ${path}: ${sentence} Select another plist in the target with the path input (CLI: --relative-path).`;
     return requested === undefined
-        ? new AnalysisCapabilityUnavailableError(IDENTITY.id, "inspect_plist", `The target has no readable Contents/Info.plist at ${path}: ${sentence} Pass path to inspect another plist.`)
+        ? new AnalysisCapabilityUnavailableError(IDENTITY.id, "inspect_plist", missingDefault, { userMessage: missingDefault })
         : new AnalysisInputError("inspect_plist", undefined, [
             {
                 path: ["path"],

package/dist/native/NativeMacOSProviderMetadata.js

@@ -5,7 +5,6 @@ export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
     name: "macOS native inspection utilities",
     version: null,
 });
-const IDENTITY = NATIVE_MACOS_PROVIDER_IDENTITY;
 /** Operations whose target process can show UI, use the network and write files. */
 const OWNED_PROCESS_OPERATIONS = new Set([
     "capture_native_ui_scenario",
@@ -26,7 +25,7 @@ export const nativeMacOSCapabilities = (platform = process.platform) => {
                 reason: "Native macOS utilities require macOS.",
             };
         return Object.freeze({
-            provider: IDENTITY,
+            provider: NATIVE_MACOS_PROVIDER_IDENTITY,
             operation: contract.name,
             ...availability,
             effects: Object.freeze({

package/dist/native/NativeUiHelperRuntime.js

@@ -1,12 +1,15 @@
-import { mkdtemp, rm, symlink } from "node:fs/promises";
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { SWIFTC_INTERRUPT } from "../process/DarwinProcessRunTokenReader.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { NATIVE_UI_HELPER_MAX_BUFFER } from "./NativeUiOutputBudget.js";
 /** Lazily compile one owned helper per observation/scenario and remove its compiler cache. */
-export const createNativeUiHelperRuntime = () => {
+export const createNativeUiHelperRuntime = (environment) => {
+    const selectedEnvironment = snapshotEnvironment(environment);
     let root;
     let executable;
     const invoke = async (parameters, signal) => {
@@ -15,6 +18,9 @@ export const createNativeUiHelperRuntime = () => {
             const output = join(root, "observer");
             const main = join(root, "main.swift");
             await symlink(fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url)), main);
+            // Keep swiftc's intermediate objects inside the removable root.
+            const compilerTemporary = join(root, "tmp");
+            await mkdir(compilerTemporary);
             await execFileOutput("/usr/bin/xcrun", [
                 "swiftc",
                 "-module-cache-path",
@@ -26,6 +32,8 @@ export const createNativeUiHelperRuntime = () => {
             ], {
                 timeout: 60_000,
                 maxBuffer: 1024 * 1024,
+                stopSignal: SWIFTC_INTERRUPT,
+                env: { ...selectedEnvironment, TMPDIR: compilerTemporary },
                 ...(signal === undefined ? {} : { signal }),
             });
             executable = output;
@@ -33,6 +41,7 @@ export const createNativeUiHelperRuntime = () => {
         const output = await execFileOutput(executable, [JSON.stringify(parameters)], {
             timeout: 30_000,
             maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER,
+            env: selectedEnvironment,
             ...(signal === undefined ? {} : { signal }),
         });
         const parsed = safeParseJson(output.stdout);

package/dist/native/NativeUiObservation.js

@@ -17,8 +17,8 @@ const responseSchema = z.discriminatedUnion("ok", [
     }),
 ]);
 /** Capture a selected existing app window and run explicitly selected scenarios. */
-export const observeNativeUi = async (target, operation, parameters, options = {}) => {
-    const runtime = createNativeUiHelperRuntime();
+export const observeNativeUi = async (target, operation, parameters, options) => {
+    const runtime = createNativeUiHelperRuntime(options.environment);
     try {
         return await observeWithHelper(target, operation, parameters, {
             ...options,