rea-agents 6.2.0 → 6.3.0

package/dist/native/LldbCallTracer.js

@@ -6,13 +6,15 @@ 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";
@@ -93,37 +95,147 @@ export class LldbCallTracer {
     launch;
     resolveTool;
     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_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,
@@ -149,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",
@@ -165,16 +276,30 @@ export class LldbCallTracer {
             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,
@@ -184,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"
@@ -228,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)
@@ -345,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 {
@@ -389,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,
@@ -431,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();
     }
 };
@@ -483,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

@@ -29,13 +29,14 @@ import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspect
 /** Read-only semantic provider composed from Xcode command-line utilities. */
 export class NativeMacOSProvider {
     runner;
-    tracer;
     #capabilities;
     #environment;
-    constructor(environment, runner = new XcrunCommandRunner(environment), 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() {
@@ -45,7 +46,7 @@ export class NativeMacOSProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new NativeMacOSClient(target, this.runner, this.tracer, this.#environment);
+        return new NativeMacOSClient(target, this.runner, this.#tracerFactory(), this.#environment);
     }
 }
 class NativeMacOSClient {
@@ -133,7 +134,7 @@ class NativeMacOSClient {
         }
     }
     close() {
-        return Promise.resolve(ok(null));
+        return this.tracer.close();
     }
     #dispatch(operation, parameters, signal) {
         switch (operation) {
@@ -154,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;

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/process/ProcessOwnershipObservation.js

@@ -5,7 +5,7 @@ import { descendantsOf, liveProcesses } from "./ProcessOwnershipProcessTree.js";
 import { execFileOutput } from "./ExecFileOutput.js";
 import { createDarwinProcessRunTokenReader } from "./DarwinProcessRunTokenReader.js";
 /** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroupWithHost = async (ownership, host, signal) => {
+export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, signal) => {
     signal?.throwIfAborted();
     let members;
     try {
@@ -45,8 +45,14 @@ export const observeOwnedProcessGroupWithHost = async (ownership, host, signal)
     }
     return { state: "alive" };
 };
-/** Record the live launcher and descendant lineage after run-token validation. */
-export const observeOwnedProcessLineageWithHost = async (ownership, host) => {
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => {
     let processes;
     try {
         processes = liveProcesses(await host.listProcesses());
@@ -331,16 +337,6 @@ export const signalProcessWithStartIdentity = async (pid, expectedIdentity, sign
 export const prepareProcessOwnershipInspection = async (signal) => {
     await systemProcessOwnershipHost.prepare?.(signal);
 };
-/** Observe one group without signaling it, failing closed on identity doubt. */
-export const observeOwnedProcessGroup = async (ownership, host = systemProcessOwnershipHost, signal) => observeOwnedProcessGroupWithHost(ownership, host, signal);
-/**
- * Record the live launcher and descendant lineage after run-token validation.
- *
- * The observation is intentionally point-in-time. A verified empty descendant
- * list means no descendants were live during this observation, not that the
- * run never created a short-lived child.
- */
-export const observeOwnedProcessLineage = async (ownership, host = systemProcessOwnershipHost) => observeOwnedProcessLineageWithHost(ownership, host);
 const processIsGone = async (host, pid) => {
     try {
         return !liveProcesses(await host.listProcesses()).some((process) => process.pid === pid);