rea-agents 5.0.0 → 6.1.0

package/dist/native/LldbRetainedObservations.js

@@ -0,0 +1,178 @@
+import { open } from "node:fs/promises";
+import { nativeCallEventSchema } from "../domain/native/nativeCallObservation.js";
+/** Maximum journal size enforced by the LLDB bridge. */
+export const LLDB_OBSERVATION_JOURNAL_MAX_BYTES = 8 * 1024 * 1024;
+const MAX_CAPTURE_BYTES = 1024 * 1024;
+/** Join safely retained journal and process evidence into its failure contract. */
+export const projectLldbPartialObservation = (input) => ({
+    kind: "native-call-observation",
+    target: input.target,
+    process: {
+        pid: input.pid ?? null,
+        stdout: input.stdout,
+        stderr: input.stderr,
+        other_stops: input.journal.otherStops,
+    },
+    debugger: { version: input.version },
+    events: input.journal.events,
+    coverage: { status: "partial", reason: input.reason },
+    limitations: [
+        "The LLDB run did not produce a complete native call observation result.",
+        "The target SHA-256 identifies the selected artifact; LLDB did not verify the bytes loaded into the process.",
+        "Captured output byte counts are observed lower bounds because LLDB did not report final stream counters.",
+        ...input.journal.limitations,
+        ...(input.journalLimitations ?? []),
+        ...(input.limitations ?? []),
+        ...(input.pid === undefined ? ["The target PID was unavailable."] : []),
+        ...(input.stdout === null
+            ? ["The target stdout capture was unavailable."]
+            : []),
+        ...(input.stderr === null
+            ? ["The target stderr capture was unavailable."]
+            : []),
+    ],
+});
+/** Parse completed JSONL records while retaining valid records around bad ones. */
+export const parseLldbObservationJournal = (bytes) => {
+    const completeText = Buffer.from(bytes).toString("utf8");
+    const newline = completeText.lastIndexOf("\n");
+    const hasTornTail = newline !== completeText.length - 1;
+    const events = [];
+    const otherStops = [];
+    const limitations = [];
+    let malformedCount = 0;
+    let firstMalformedRow;
+    let start = 0;
+    let rowNumber = 0;
+    while (start <= newline && newline >= 0) {
+        const end = completeText.indexOf("\n", start);
+        if (end < 0 || end > newline)
+            break;
+        const line = completeText.slice(start, end);
+        start = end + 1;
+        if (line.length === 0)
+            continue;
+        rowNumber += 1;
+        const markMalformed = () => {
+            malformedCount += 1;
+            firstMalformedRow ??= rowNumber;
+        };
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            markMalformed();
+            continue;
+        }
+        if (typeof row !== "object" ||
+            row === null ||
+            !("kind" in row) ||
+            typeof row.kind !== "string") {
+            markMalformed();
+            continue;
+        }
+        if (row.kind === "event" && "event" in row) {
+            const event = nativeCallEventSchema.safeParse(row.event);
+            if (event.success)
+                events.push(event.data);
+            else
+                markMalformed();
+        }
+        else if (row.kind === "other-stop" &&
+            "reason" in row &&
+            typeof row.reason === "string") {
+            otherStops.push(row.reason);
+        }
+        else {
+            markMalformed();
+        }
+    }
+    if (malformedCount > 0)
+        limitations.push(`${malformedCount} observation journal row(s) were malformed or invalid and ignored (first at row ${String(firstMalformedRow)}).`);
+    if (hasTornTail)
+        limitations.push("The final observation journal record was incomplete and was ignored.");
+    return { events, otherStops, limitations };
+};
+/** Keep reading a bounded prefix across short reads until EOF or the bound. */
+export const readBoundedPrefix = async (requestedBytes, readChunk) => {
+    const buffer = Buffer.alloc(requestedBytes);
+    let bytesRead = 0;
+    while (bytesRead < requestedBytes) {
+        const count = await readChunk(buffer, bytesRead, requestedBytes - bytesRead, bytesRead);
+        if (count === 0)
+            break;
+        if (count > requestedBytes - bytesRead)
+            throw new Error("The bounded read returned more bytes than requested");
+        bytesRead += count;
+    }
+    return { buffer, bytesRead };
+};
+const readPrefix = (handle, requestedBytes) => readBoundedPrefix(requestedBytes, async (buffer, offset, length, position) => (await handle.read(buffer, offset, length, position)).bytesRead);
+/** Read at most the bridge's journal bound, checking size before allocation. */
+export const readLldbObservationJournal = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const { size } = await handle.stat();
+        const length = Math.min(size, LLDB_OBSERVATION_JOURNAL_MAX_BYTES);
+        const { buffer, bytesRead } = await readPrefix(handle, length);
+        const parsed = parseLldbObservationJournal(buffer.subarray(0, bytesRead));
+        const limitations = [
+            ...(size > LLDB_OBSERVATION_JOURNAL_MAX_BYTES
+                ? [
+                    "The observation journal exceeded 8 MiB; only its bounded prefix was read.",
+                ]
+                : []),
+            ...(bytesRead < length
+                ? [
+                    "The observation journal became shorter while being read; the available prefix was parsed.",
+                ]
+                : []),
+        ];
+        return {
+            parsed,
+            limitations,
+        };
+    }
+    catch (cause) {
+        return {
+            parsed: { events: [], otherStops: [], limitations: [] },
+            limitations: [
+                `The observation journal could not be read: ${cause instanceof Error ? cause.message : String(cause)}`,
+            ],
+        };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+/** Retain an available output prefix without claiming an unreported total. */
+export const readPartialCapture = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const { size } = await handle.stat();
+        const length = Math.min(size, MAX_CAPTURE_BYTES);
+        const { buffer, bytesRead } = await readPrefix(handle, length);
+        return {
+            capture: {
+                text: buffer.subarray(0, bytesRead).toString("utf8"),
+                bytes: Math.max(size, bytesRead),
+                truncated: true,
+                complete: false,
+            },
+            limitations: bytesRead < length
+                ? [
+                    "A target output capture became shorter while being read; its retained prefix may be incomplete.",
+                ]
+                : [],
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/native/NativeCallObservation.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
+import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { nativeCallObservationInputSchema, nativeCallObservationResultSchema, } from "../domain/native/nativeCallObservation.js";
+import { err, ok } from "../domain/result.js";
+const OPERATION = "observe_native_calls";
+/** What every call observation leaves unobserved or approximated. */
+export const NATIVE_CALL_OBSERVATION_LIMITATIONS = [
+    "Only entries are observed; return values, floating-point and stack-passed arguments are not captured.",
+    "Registers are the raw integer argument registers at entry. For Objective-C methods the first two hold the receiver and the selector.",
+    "Receiver classes come from LLDB's Objective-C runtime reader without running target code; they are null for class methods and for receivers LLDB cannot classify.",
+    "Calls that never reach a symbol's entry, such as inlined code or objc_direct methods called directly, are not observed.",
+    "The target is launched directly under LLDB, not through LaunchServices; LLDB disables ASLR for it, so load addresses can equal file addresses.",
+    "The observation window is checked about once a second, and recording pauses the process at every entry, which slows it.",
+];
+/** Launch the active Mach-O under LLDB, record requested call entries, then stop it. */
+export const observeNativeCalls = async (target, parameters, tracer, signal, readTargetDigest = fileSha256) => {
+    if (target.kind !== "executable" || target.format !== "mach-o")
+        return err(new AnalysisCapabilityUnavailableError("native-macos", OPERATION, "Native call observation launches a Mach-O executable; the active target is not one"));
+    const parsed = nativeCallObservationInputSchema.safeParse(parameters);
+    if (!parsed.success)
+        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+    // Observe the bytes the session's other Evidence describes.
+    let digest;
+    try {
+        digest = await readTargetDigest(target.path, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true || isAbortError(cause))
+            return err(new AnalysisCancelledError(OPERATION));
+        return err(new ProviderAdapterError("native-macos", OPERATION, {
+            diagnostics: {
+                reason: "Unable to verify the selected target digest",
+                detail: cause instanceof Error ? cause.message : String(cause),
+            },
+        }));
+    }
+    if (digest !== target.sha256)
+        return err(new EvidenceIntegrityError("Native call observation target digest changed after session binding"));
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError(OPERATION));
+    const traced = await tracer.trace({
+        executable: target.path,
+        architecture: target.architecture,
+        expectedSha256: target.sha256,
+        input: parsed.data,
+    }, signal);
+    if (!traced.ok)
+        return traced;
+    return ok(projectNativeCalls(target, parsed.data, traced.value));
+};
+const isAbortError = (cause) => cause instanceof Error && cause.name === "AbortError";
+/** Join the request, the tracer's run and REA's own checks into the result contract. */
+export const projectNativeCalls = (target, input, trace) => {
+    const { run } = trace;
+    const unresolved = run.breakpoints
+        .filter(({ location_count: count }) => count === 0)
+        .map(({ index }) => index);
+    const eventLimit = run.outcome === "event-limit";
+    const resourceLimit = run.outcome === "resource-limit";
+    const breakpointLocationLimit = run.breakpoint_locations_truncated === true;
+    const partial = eventLimit ||
+        resourceLimit ||
+        breakpointLocationLimit ||
+        run.outcome === "duration-elapsed" ||
+        run.outcome === "stop-limit" ||
+        unresolved.length > 0;
+    return nativeCallObservationResultSchema.parse({
+        target: {
+            path: target.path,
+            sha256: target.sha256,
+            architecture: target.architecture,
+            arguments: input.arguments,
+            environment: input.environment,
+            working_directory: input.working_directory ?? null,
+            launch_identity: {
+                loaded_image_sha256: run.target_identity.loaded_image_sha256,
+                file_device: run.target_identity.file_device,
+                file_inode: run.target_identity.file_inode,
+                selected_file_sha256: run.target_identity.selected_file_sha256,
+                module_path: run.target_identity.module_path,
+                module_uuid: run.target_identity.module_uuid,
+                stable: run.target_identity.stable,
+            },
+        },
+        debugger: trace.debugger,
+        process: {
+            pid: run.pid,
+            outcome: run.outcome,
+            exit_status: run.exit_status,
+            exit_description: run.exit_description,
+            terminated: run.terminated && trace.terminated,
+            elapsed_ms: run.elapsed_ms,
+            stdout: trace.stdout,
+            stderr: trace.stderr,
+            other_stops: run.other_stops,
+        },
+        breakpoints: input.breakpoints.map((request, index) => ({
+            index,
+            request: request.kind === "function"
+                ? { ...request, module: request.module ?? null }
+                : { ...request, class_name: request.class_name ?? null },
+            location_count: run.breakpoints[index]?.location_count ?? 0,
+            locations: run.breakpoints[index]?.locations ?? [],
+        })),
+        events: run.events,
+        coverage: {
+            status: partial ? "partial" : "complete",
+            event_limit_reached: eventLimit,
+            resource_limit_reached: resourceLimit,
+            ...(breakpointLocationLimit
+                ? { breakpoint_locations_truncated: true }
+                : {}),
+            unresolved_breakpoints: unresolved,
+        },
+        limitations: [
+            ...NATIVE_CALL_OBSERVATION_LIMITATIONS,
+            "The selected pathname digest and LLDB module identity are checked around launch. No immutable executable snapshot is used; concurrent in-place mutation or replacement and restoration cannot be ruled out, so the loaded-image digest remains unknown.",
+            ...(eventLimit
+                ? [
+                    `Observation stopped at max_events (${input.max_events}); later calls were not recorded and the process was killed.`,
+                ]
+                : []),
+            ...(resourceLimit
+                ? [
+                    "Observation stopped before retaining the next complete event because the estimated 8 MiB trace-payload or 65,536-frame aggregate budget was reached; the process was killed.",
+                ]
+                : []),
+            ...(run.outcome === "duration-elapsed"
+                ? [
+                    `The process was still running after duration_ms (${input.duration_ms}) and was killed.`,
+                ]
+                : []),
+            ...(run.target_identity.stable
+                ? []
+                : [
+                    "LLDB did not provide enough module identity evidence to confirm pathname and module continuity around launch.",
+                ]),
+            ...(run.outcome === "stop-limit"
+                ? [
+                    "Observation stopped after repeated signal or exception stops; the process was killed.",
+                ]
+                : []),
+            ...(unresolved.length === 0
+                ? []
+                : [
+                    `Breakpoints ${unresolved.join(", ")} matched no code in any image loaded while observing; their calls could not be observed.`,
+                ]),
+            ...(run.breakpoints.some(({ location_count: count, locations }) => locations.length < count)
+                ? [
+                    "Breakpoints with many matching locations list only the first 64; location_count gives the total.",
+                ]
+                : []),
+            ...(breakpointLocationLimit
+                ? [
+                    "Resolved breakpoint locations exceeded the aggregate 8 MiB metadata budget; omitted locations are counted in location_count. This metadata limit does not change the process outcome.",
+                ]
+                : []),
+            ...(trace.stdout.truncated || trace.stderr.truncated
+                ? ["Target output beyond 1 MiB per stream is counted but not kept."]
+                : []),
+            ...(!trace.stdout.complete || !trace.stderr.complete
+                ? [
+                    "Target output draining did not complete; reported byte counts are observed lower bounds, not stream totals.",
+                ]
+                : []),
+            ...(run.terminated && trace.terminated
+                ? []
+                : [
+                    `REA could not confirm that process ${run.pid} exited; check for it before relying on host state.`,
+                ]),
+        ],
+    });
+};
+const fileSha256 = async (path, signal) => {
+    const handle = await open(path, "r");
+    try {
+        const hash = createHash("sha256");
+        const buffer = new Uint8Array(1024 * 1024);
+        for (;;) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+        return hash.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+};

package/dist/native/NativeMacOSProvider.js

@@ -2,12 +2,14 @@ import { NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY, nativeMacOSCapabilities, }
 export { NATIVE_MACOS_PROVIDER_IDENTITY } from "./NativeMacOSProviderMetadata.js";
 import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
 import { observeNativeUi } from "./NativeUiObservation.js";
+import { LldbCallTracer } from "./LldbCallTracer.js";
+import { observeNativeCalls } from "./NativeCallObservation.js";
 import { dirname, isAbsolute, resolve } from "node:path";
 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 { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
@@ -15,7 +17,8 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 import { omittedPrototypeKeysLimitation, parseXmlPropertyList, } from "../domain/propertyListKeys.js";
 import { demangleSwiftSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/native/nativeInspection.js";
 import { err, ok } from "../domain/result.js";
-import { NativeCommandFailure, XcrunCommandRunner, } from "./CommandRunner.js";
+import { NATIVE_COMMAND_TIMEOUT_MS, NATIVE_COMMAND_OUTPUT_BUDGET_BYTES, NativeCommandFailure, XcrunCommandRunner, } from "./CommandRunner.js";
+import { withSignatureTarget, verifySignatureTarget, } from "./SignatureTargetBinding.js";
 import { parseCodeSignature } from "./parsers/codesign.js";
 import { parseDemangledSymbols } from "./parsers/demangle.js";
 import { parseLipoArchitectures } from "./parsers/lipo.js";
@@ -24,9 +27,11 @@ 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) {
+    constructor(runner = new XcrunCommandRunner(), platform = process.platform, tracer = new LldbCallTracer()) {
         this.runner = runner;
+        this.tracer = tracer;
         this.#capabilities = nativeMacOSCapabilities(platform);
     }
     identity() {
@@ -36,15 +41,17 @@ export class NativeMacOSProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new NativeMacOSClient(target, this.runner);
+        return new NativeMacOSClient(target, this.runner, this.tracer);
     }
 }
 class NativeMacOSClient {
     target;
     runner;
-    constructor(target, runner) {
+    tracer;
+    constructor(target, runner, tracer) {
         this.target = target;
         this.runner = runner;
+        this.tracer = tracer;
     }
     async execute(operation, parameters, options) {
         if (options?.signal?.aborted === true)
@@ -83,6 +90,15 @@ class NativeMacOSClient {
         }
         if (!isNativeOperation(operation))
             return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by native macOS tools."));
+        if (operation === "observe_native_calls") {
+            const result = await observeNativeCalls(this.target, parameters, this.tracer, options?.signal);
+            return result.ok
+                ? ok(createAnalysisExecution(result.value, IDENTITY, {
+                    limitations: result.value.limitations,
+                    locations: [{ kind: "artifact-path", path: this.target.path }],
+                }))
+                : result;
+        }
         if (operation === "observe_native_ui" ||
             operation === "capture_native_ui_scenario") {
             const result = await observeNativeUi(this.target, operation, parameters, {
@@ -117,6 +133,7 @@ class NativeMacOSClient {
         switch (operation) {
             case "observe_native_ui":
             case "capture_native_ui_scenario":
+            case "observe_native_calls":
                 return Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "UI observation uses its explicit authority boundary")));
             case "inspect_macho":
                 return this.#inspectMacho(signal);
@@ -176,20 +193,23 @@ class NativeMacOSClient {
         });
     }
     async #inspectSignature(signal) {
-        const display = await this.#run("inspect_signature", "codesign", ["-d", "--verbose=4", this.target.path], { signal, acceptNonZero: true });
+        return withSignatureTarget(this.target, (binding) => this.#inspectBoundSignature(binding, signal), signal);
+    }
+    async #inspectBoundSignature(binding, signal) {
+        const display = await this.#captureSignature(binding, ["-d", "--verbose=4"], signal);
         if (!display.ok)
             return display;
         const unsigned = isNonzeroUnsignedObservation(display.value);
         const displayFailure = codeSignCaptureFailure(display.value);
         if (displayFailure !== null)
             return err(displayFailure);
-        const requirements = await this.#run("inspect_signature", "codesign", ["-d", "-r-", this.target.path], { signal, acceptNonZero: true });
+        const requirements = await this.#captureSignature(binding, ["-d", "-r-"], signal);
         if (!requirements.ok)
             return requirements;
         const requirementsFailure = codeSignCaptureFailure(requirements.value);
         if (requirementsFailure !== null)
             return err(requirementsFailure);
-        const entitlements = await this.#run("inspect_signature", "codesign", ["-d", "--entitlements", ":-", this.target.path], { signal, acceptNonZero: true });
+        const entitlements = await this.#captureSignature(binding, ["-d", "--entitlements", ":-"], signal);
         if (!entitlements.ok)
             return entitlements;
         const entitlementsFailure = codeSignCaptureFailure(entitlements.value);
@@ -197,8 +217,8 @@ class NativeMacOSClient {
             return err(entitlementsFailure);
         // codesign echoes the resolved executable path in its diagnostics.
         const parsed = parseCodeSignature(display.value.stderr, unsigned, [
-            this.target.path,
-            ...(await canonicalPath(this.target.path)),
+            binding.snapshotPath,
+            ...(await canonicalPath(binding.snapshotPath)),
         ]);
         // The requirement is printed to stdout; stderr echoes the path.
         const requirementText = /designated\s*=>\s*(.+)$/mu.exec(requirements.value.stdout)?.[1] ?? null;
@@ -207,6 +227,7 @@ class NativeMacOSClient {
         const captures = [display.value, requirements.value, entitlements.value];
         const limitations = [
             ...parsed.limitations,
+            "Inspected a digest-verified Mach-O byte snapshot; filesystem-bound signing context and trust validation are not examined.",
             ...(entitlementValue.omittedPrototypeKeys === 0
                 ? []
                 : [
@@ -217,13 +238,19 @@ class NativeMacOSClient {
             (isNonzeroUnsignedObservation(requirements.value) ||
                 isNonzeroUnsignedObservation(entitlements.value));
         if (mixedSigning) {
-            const slices = await this.#inspectMixedSignatureSlices(parsed.format, requirements.value.exitCode !== 0, entitlements.value.exitCode !== 0, signal);
+            const slices = await this.#inspectMixedSignatureSlices(binding, parsed.format, {
+                requirements: requirements.value.exitCode,
+                entitlements: entitlements.value.exitCode,
+            }, signal);
             if (!slices.ok)
                 return slices;
             captures.push(...slices.value.captures);
             limitations.push(...slices.value.limitations);
         }
-        const provenance = captures.map((capture) => invocation(capture, this.target.path));
+        const provenance = captures.map((capture) => invocation(capture, binding.snapshotPath));
+        const version = await verifySignatureTarget(this.target, binding, signal);
+        if (!version.ok)
+            return version;
         const result = inspectSignatureSchema.parse({
             ...parsed,
             designated_requirement: requirementText,
@@ -238,12 +265,12 @@ class NativeMacOSClient {
             locations: [],
         });
     }
-    async #inspectMixedSignatureSlices(format, requirementsUnavailable, entitlementsUnavailable, signal) {
+    async #inspectMixedSignatureSlices(binding, format, aggregateExits, signal) {
         const captures = [];
         const unsigned = [];
         const unclassified = [];
         for (const architecture of codeSignArchitectures(format, this.target)) {
-            const slice = await this.#run("inspect_signature", "codesign", ["-d", "-a", architecture, "--verbose=4", this.target.path], { signal, acceptNonZero: true });
+            const slice = await this.#captureSignature(binding, ["-d", "-a", architecture, "--verbose=4"], signal);
             if (!slice.ok)
                 return slice;
             captures.push(slice.value);
@@ -261,12 +288,38 @@ class NativeMacOSClient {
         ];
         if (unclassified.length > 0)
             limitations.push(`Signature state could not be classified for Mach-O slices: ${unclassified.join(", ")}.`);
-        if (requirementsUnavailable)
+        if (aggregateExits.requirements !== 0)
             limitations.push("The aggregate designated requirement is unavailable because Mach-O slices have mixed signing states.");
-        if (entitlementsUnavailable)
+        if (aggregateExits.entitlements !== 0)
             limitations.push("The aggregate entitlements are unavailable because Mach-O slices have mixed signing states.");
         return ok({ captures, limitations });
     }
+    async #captureSignature(binding, args, signal) {
+        const before = await verifySignatureTarget(this.target, binding, signal);
+        if (!before.ok)
+            return before;
+        let capture;
+        try {
+            capture = await this.#run("inspect_signature", "codesign", [...args, binding.snapshotPath], {
+                signal,
+                acceptNonZero: true,
+            });
+        }
+        catch (cause) {
+            capture = err(new ProviderAdapterError(IDENTITY.id, "inspect_signature", {
+                cause,
+                diagnostics: {
+                    phase: "codesign-capture",
+                    path: this.target.path,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                },
+            }));
+        }
+        // Verify failed captures too: a disappearing target is not a codesign
+        // execution failure, and later captures must never use another version.
+        const after = await verifySignatureTarget(this.target, binding, signal);
+        return after.ok ? capture : after;
+    }
     async #inspectPlist(parameters, signal) {
         const requested = parameters.path;
         if (requested !== undefined && typeof requested !== "string")
@@ -350,13 +403,57 @@ class NativeMacOSClient {
 }
 const isNativeOperation = (operation) => NATIVE_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const translateCommandFailure = (operation, failure) => {
+    const capturedOutput = failure.capture === null
+        ? undefined
+        : {
+            stdout: failure.capture.stdout,
+            stderr: failure.capture.stderr,
+            truncated: failure.capture.truncated,
+            stdout_bytes: failure.capture.stdoutBytes,
+            stderr_bytes: failure.capture.stderrBytes,
+            exit_code: failure.capture.exitCode,
+            signal: failure.capture.signal,
+        };
+    const cleanup = failure.cleanupFailure === null
+        ? undefined
+        : {
+            reason: failure.cleanupFailure,
+            resources: [...failure.cleanupResources],
+        };
+    const errorOptions = {
+        ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        ...(cleanup === undefined ? {} : { cleanup }),
+    };
     if (failure.reason === "unavailable")
-        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`);
+        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`, errorOptions);
     if (failure.reason === "cancelled")
-        return new AnalysisCancelledError(operation);
-    return new ProviderAdapterError(IDENTITY.id, operation, { cause: failure });
+        return new AnalysisCancelledError(operation, errorOptions);
+    if (failure.reason === "timeout")
+        return new AnalysisTimeoutError(operation, NATIVE_COMMAND_TIMEOUT_MS, errorOptions);
+    if (failure.reason === "output-limit")
+        return new AnalysisResourceConstraintError(operation, "memory", `Native command output exceeded ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)} bytes; complete output is required for analysis.`, { max_output_bytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES }, errorOptions);
+    return new ProviderAdapterError(IDENTITY.id, operation, {
+        cause: failure,
+        ...errorOptions,
+        diagnostics: {
+            tool: failure.tool,
+            reason: failure.reason,
+            exit_code: failure.capture?.exitCode ?? failure.exitCode,
+            signal: failure.capture?.signal ?? null,
+            stdout_bytes: failure.capture?.stdoutBytes ?? 0,
+            stderr_bytes: failure.capture?.stderrBytes ?? 0,
+        },
+    });
 };
-const translateCodeSignExitFailure = (capture) => translateCommandFailure("inspect_signature", new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode));
+const translateCodeSignExitFailure = (capture) => translateCommandFailure("inspect_signature", new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode, undefined, {
+    stdout: capture.stdout,
+    stderr: capture.stderr,
+    stdoutBytes: capture.stdoutBytes,
+    stderrBytes: capture.stderrBytes,
+    exitCode: capture.exitCode,
+    signal: capture.signal,
+    truncated: false,
+}));
 const commandOutput = (capture) => `${capture.stdout}\n${capture.stderr}`;
 /**
  * A signed artifact exits zero; its diagnostics can still contain this text

package/dist/native/NativeMacOSProviderMetadata.js

@@ -6,6 +6,11 @@ export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
     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",
+    "observe_native_calls",
+]);
 /** Declare native host coverage without creating a command runner. */
 export const nativeMacOSCapabilities = (platform = process.platform) => {
     const available = platform === "darwin";
@@ -27,9 +32,9 @@ export const nativeMacOSCapabilities = (platform = process.platform) => {
             effects: Object.freeze({
                 mutatesArtifact: false,
                 launchesProcess: contract.name !== "inspect_native_dispatch_metadata",
-                mayShowUi: contract.name === "capture_native_ui_scenario",
-                mayAccessNetwork: contract.name === "capture_native_ui_scenario",
-                mayWriteFilesystem: contract.name === "capture_native_ui_scenario" ||
+                mayShowUi: OWNED_PROCESS_OPERATIONS.has(contract.name),
+                mayAccessNetwork: OWNED_PROCESS_OPERATIONS.has(contract.name),
+                mayWriteFilesystem: OWNED_PROCESS_OPERATIONS.has(contract.name) ||
                     contract.name === "observe_native_ui",
                 changesPermissions: false,
                 requiresRoot: false,