rea-agents 4.1.0 → 6.0.0

package/dist/native/NativeMacOSProvider.js

@@ -1,67 +1,37 @@
+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";
+import { observeNativeCalls } from "./NativeCallObservation.js";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { stat } from "node:fs/promises";
-import { parse as parseXmlPlist } from "plist";
+import { open, realpath, stat } from "node:fs/promises";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { NATIVE_TOOL_CONTRACTS, } from "../contracts/nativeToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { NATIVE_TOOL_CONTRACTS, } from "../contracts/native/nativeToolContracts.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { demangleSwiftSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.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 { parseCodeSignature } from "./parsers/codesign.js";
 import { parseDemangledSymbols } from "./parsers/demangle.js";
 import { parseLipoArchitectures } from "./parsers/lipo.js";
-import { parsePlistJson } from "./parsers/plist.js";
+import { parsePlistJson, parsePlistXml, plistJsonNeedsNumberTypes, } from "./parsers/plist.js";
 import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspection.js";
-/** Public identity committed by macOS-native inspection observations. */
-export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
-    id: "native-macos",
-    name: "macOS native inspection utilities",
-    version: null,
-});
-const IDENTITY = NATIVE_MACOS_PROVIDER_IDENTITY;
 /** 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;
-        const available = platform === "darwin";
-        this.#capabilities = Object.freeze([
-            ...NATIVE_TOOL_CONTRACTS,
-            { name: "inspect_native_dispatch_metadata" },
-        ].map((contract) => {
-            const availability = available
-                ? { available: true, reason: null }
-                : {
-                    available: false,
-                    availabilityCode: "unsupported_host",
-                    reason: "Native macOS utilities require macOS.",
-                };
-            return Object.freeze({
-                provider: IDENTITY,
-                operation: contract.name,
-                ...availability,
-                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" ||
-                        contract.name === "observe_native_ui",
-                    changesPermissions: false,
-                    requiresRoot: false,
-                }),
-                limitations: Object.freeze([
-                    "Availability and textual formats depend on the installed macOS/Xcode toolchain.",
-                ]),
-            });
-        }));
+        this.tracer = tracer;
+        this.#capabilities = nativeMacOSCapabilities(platform);
     }
     identity() {
         return IDENTITY;
@@ -70,15 +40,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)
@@ -117,6 +89,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, {
@@ -151,6 +132,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);
@@ -191,7 +173,9 @@ class NativeMacOSClient {
         const symbols = z.array(z.string()).safeParse(parameters.symbols);
         if (!symbols.success)
             return err(new AnalysisOutputError("demangle_swift", "symbols were not parsed strings"));
-        const capture = await this.#run("demangle_swift", "swift-demangle", ["--compact", ...symbols.data], { signal });
+        const capture = await this.#run("demangle_swift", "swift-demangle", 
+        // `--` keeps symbols that begin with `-` from selecting demangler options.
+        ["--compact", "--", ...symbols.data], { signal });
         if (!capture.ok)
             return capture;
         const provenance = [invocation(capture.value, this.target.path)];
@@ -211,8 +195,7 @@ class NativeMacOSClient {
         const display = await this.#run("inspect_signature", "codesign", ["-d", "--verbose=4", this.target.path], { signal, acceptNonZero: true });
         if (!display.ok)
             return display;
-        const displayOutput = commandOutput(display.value);
-        const unsigned = isUnsignedCodeSignObservation(display.value);
+        const unsigned = isNonzeroUnsignedObservation(display.value);
         const displayFailure = codeSignCaptureFailure(display.value);
         if (displayFailure !== null)
             return err(displayFailure);
@@ -228,16 +211,29 @@ class NativeMacOSClient {
         const entitlementsFailure = codeSignCaptureFailure(entitlements.value);
         if (entitlementsFailure !== null)
             return err(entitlementsFailure);
-        const parsed = parseCodeSignature(displayOutput, unsigned);
-        const requirementText = /designated\s*=>\s*(.+)$/mu.exec(commandOutput(requirements.value))?.[1] ?? null;
-        const entitlementValue = parseEntitlements(commandOutput(entitlements.value));
+        // codesign echoes the resolved executable path in its diagnostics.
+        const parsed = parseCodeSignature(display.value.stderr, unsigned, [
+            this.target.path,
+            ...(await canonicalPath(this.target.path)),
+        ]);
+        // The requirement is printed to stdout; stderr echoes the path.
+        const requirementText = /designated\s*=>\s*(.+)$/mu.exec(requirements.value.stdout)?.[1] ?? null;
+        // Entitlements XML is printed to stdout; stderr echoes the path.
+        const entitlementValue = parseEntitlements(entitlements.value.stdout);
         const captures = [display.value, requirements.value, entitlements.value];
-        const limitations = [...parsed.limitations];
+        const limitations = [
+            ...parsed.limitations,
+            ...(entitlementValue.omittedPrototypeKeys === 0
+                ? []
+                : [
+                    `Entitlements: ${omittedPrototypeKeysLimitation(entitlementValue.omittedPrototypeKeys)}`,
+                ]),
+        ];
         const mixedSigning = !unsigned &&
             (isNonzeroUnsignedObservation(requirements.value) ||
                 isNonzeroUnsignedObservation(entitlements.value));
         if (mixedSigning) {
-            const slices = await this.#inspectMixedSignatureSlices(displayOutput, requirements.value.exitCode !== 0, entitlements.value.exitCode !== 0, signal);
+            const slices = await this.#inspectMixedSignatureSlices(parsed.format, requirements.value.exitCode !== 0, entitlements.value.exitCode !== 0, signal);
             if (!slices.ok)
                 return slices;
             captures.push(...slices.value.captures);
@@ -247,7 +243,7 @@ class NativeMacOSClient {
         const result = inspectSignatureSchema.parse({
             ...parsed,
             designated_requirement: requirementText,
-            entitlements: entitlementValue,
+            entitlements: entitlementValue.value,
             provenance,
             limitations,
         });
@@ -258,11 +254,11 @@ class NativeMacOSClient {
             locations: [],
         });
     }
-    async #inspectMixedSignatureSlices(displayOutput, requirementsUnavailable, entitlementsUnavailable, signal) {
+    async #inspectMixedSignatureSlices(format, requirementsUnavailable, entitlementsUnavailable, signal) {
         const captures = [];
         const unsigned = [];
         const unclassified = [];
-        for (const architecture of codeSignArchitectures(displayOutput, this.target)) {
+        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 });
             if (!slice.ok)
                 return slice;
@@ -294,31 +290,55 @@ class NativeMacOSClient {
         const plist = await resolvePlistPath(this.target, requested);
         if (!plist.ok)
             return plist;
+        const selected = await requireRegularPlist(plist.value, requested);
+        if (!selected.ok)
+            return selected;
         const classified = await this.#run("inspect_plist", "file", ["-b", plist.value], { signal });
         if (!classified.ok)
             return classified;
-        const capture = await this.#run("inspect_plist", "plutil", ["-convert", "json", "-o", "-", "--", plist.value], { signal });
-        if (!capture.ok)
-            return capture;
-        const parsed = parsePlistJson(capture.value.stdout);
+        const json = await this.#run("inspect_plist", "plutil", ["-convert", "json", "-o", "-", "--", plist.value], { signal, acceptNonZero: true });
+        if (!json.ok)
+            return json;
+        // JSON cannot express data, dates, or non-finite reals; plutil rejects
+        // such plists, so decode its lossless XML conversion instead. JSON also
+        // prints an integral <real> like an <integer>, so a number beyond the
+        // exact JSON range takes its element type from the XML conversion.
+        const jsonDecoded = json.value.exitCode === 0;
+        const xml = jsonDecoded && !plistJsonNeedsNumberTypes(json.value.stdout)
+            ? undefined
+            : await this.#run("inspect_plist", "plutil", ["-convert", "xml1", "-o", "-", "--", plist.value], { signal, acceptNonZero: !jsonDecoded });
+        if (xml !== undefined && !xml.ok)
+            return xml;
+        if (xml !== undefined && xml.value.exitCode !== 0)
+            return err(unreadablePlist(plist.value, requested, `plutil could not decode it as a property list (${plutilDiagnostic(xml.value.stderr, plist.value)})`));
+        const parsed = xml === undefined
+            ? parsePlistJson(json.value.stdout)
+            : jsonDecoded
+                ? parsePlistJson(json.value.stdout, xml.value.stdout)
+                : parsePlistXml(xml.value.stdout);
         if (!parsed.ok)
             return parsed;
-        const provenance = [classified.value, capture.value].map((item) => invocation(item, plist.value, "$PLIST"));
+        const provenance = [
+            classified.value,
+            json.value,
+            ...(xml === undefined ? [] : [xml.value]),
+        ].map((item) => invocation(item, plist.value, "$PLIST"));
         const result = inspectPlistSchema.parse({
             format: /binary property list/iu.test(classified.value.stdout)
                 ? "binary"
                 : /XML|text/iu.test(classified.value.stdout)
                     ? "xml"
                     : "unknown",
-            ...parsed.value,
+            value: parsed.value.value,
+            bundle: parsed.value.bundle,
             source_path: plist.value,
             provenance,
-            limitations: [],
+            limitations: parsed.value.limitations,
         });
         return ok({
             result: jsonValueSchema.parse(result),
             provenance,
-            limitations: [],
+            limitations: parsed.value.limitations,
             locations: [{ kind: "artifact-path", path: plist.value }],
         });
     }
@@ -354,15 +374,26 @@ const translateCommandFailure = (operation, failure) => {
 };
 const translateCodeSignExitFailure = (capture) => translateCommandFailure("inspect_signature", new NativeCommandFailure("codesign", "nonzero-exit", capture.exitCode));
 const commandOutput = (capture) => `${capture.stdout}\n${capture.stderr}`;
-const isUnsignedCodeSignObservation = (capture) => /not signed at all|code object is not signed/iu.test(commandOutput(capture));
+/**
+ * A signed artifact exits zero; its diagnostics can still contain this text
+ * through the echoed path or identifier.
+ */
 const isNonzeroUnsignedObservation = (capture) => capture.exitCode !== null &&
     capture.exitCode !== 0 &&
-    isUnsignedCodeSignObservation(capture);
+    /not signed at all|code object is not signed/iu.test(commandOutput(capture));
+const canonicalPath = async (path) => {
+    try {
+        return [await realpath(path)];
+    }
+    catch {
+        return [];
+    }
+};
 const codeSignCaptureFailure = (capture) => capture.exitCode === 0 || isNonzeroUnsignedObservation(capture)
     ? null
     : translateCodeSignExitFailure(capture);
-const codeSignArchitectures = (displayOutput, target) => {
-    const universal = /^Format=Mach-O universal \(([^)\r\n]+)\)$/mu.exec(displayOutput)?.[1];
+const codeSignArchitectures = (format, target) => {
+    const universal = /^Mach-O universal \(([^)\r\n]+)\)$/u.exec(format ?? "")?.[1];
     if (universal !== undefined) {
         const architectures = universal
             .split(/\s+/u)
@@ -391,8 +422,51 @@ const parseEntitlements = (output) => {
     const start = output.indexOf("<?xml");
     const end = output.lastIndexOf("</plist>");
     if (start < 0 || end < start)
-        return null;
-    return jsonValueSchema.parse(parseXmlPlist(output.slice(start, end + "</plist>".length)));
+        return { value: null, omittedPrototypeKeys: 0 };
+    const { value, omittedPrototypeKeys } = parseXmlPropertyList(output.slice(start, end + "</plist>".length));
+    return { value: jsonValueSchema.parse(value), omittedPrototypeKeys };
+};
+/**
+ * Report a plist that cannot be decoded as the caller's selection, or as the
+ * target's missing default, rather than as a failed tool run.
+ */
+const unreadablePlist = (path, requested, reason) => {
+    const sentence = reason.endsWith(".") ? reason : `${reason}.`;
+    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 AnalysisInputError("inspect_plist", undefined, [
+            {
+                path: ["path"],
+                reason: "invalid_value",
+                message: `Cannot inspect ${path}: ${sentence}`,
+            },
+        ]);
+};
+/** plutil prefixes its diagnostic with the path the message already names. */
+const plutilDiagnostic = (stderr, path) => {
+    const text = stderr.trim();
+    return text.startsWith(`${path}: `) ? text.slice(path.length + 2) : text;
+};
+/**
+ * Admit a readable regular file before plutil runs, so a later plutil failure
+ * reflects the bytes rather than a missing path or a host permission denial.
+ */
+const requireRegularPlist = async (path, requested) => {
+    try {
+        if (!(await stat(path)).isFile())
+            return err(unreadablePlist(path, requested, "it is not a regular file"));
+        // Opening also observes ACL and macOS privacy denials that stat permits.
+        await (await open(path, "r")).close();
+        return ok(null);
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return err(unreadablePlist(path, requested, "no file exists there"));
+        if (code === "EACCES" || code === "EPERM")
+            return err(new BinaryTargetError(path, `permission denied while reading plist (${code})`, { cause }));
+        return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist", { cause }));
+    }
 };
 const resolvePlistPath = async (target, requested) => {
     try {
@@ -401,9 +475,11 @@ const resolvePlistPath = async (target, requested) => {
             return ok(resolve(requested));
         const sourceMetadata = await stat(source);
         const root = sourceMetadata.isDirectory() ? source : dirname(target.path);
-        return ok(requested === undefined
-            ? resolve(root, "Contents/Info.plist")
-            : resolve(root, requested));
+        if (requested !== undefined)
+            return ok(resolve(root, requested));
+        // A bundle target records the Info.plist its program file was declared
+        // in: Contents/Info.plist, or the root plist of an iOS-style bundle.
+        return ok(target.bundleInfoPlist ?? resolve(root, "Contents/Info.plist"));
     }
     catch (cause) {
         return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist", { cause }));

package/dist/native/NativeMacOSProviderMetadata.js

@@ -0,0 +1,47 @@
+import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
+/** Public identity committed by macOS-native inspection observations. */
+export const NATIVE_MACOS_PROVIDER_IDENTITY = Object.freeze({
+    id: "native-macos",
+    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",
+    "observe_native_calls",
+]);
+/** Declare native host coverage without creating a command runner. */
+export const nativeMacOSCapabilities = (platform = process.platform) => {
+    const available = platform === "darwin";
+    return Object.freeze([
+        ...NATIVE_TOOL_CONTRACTS,
+        { name: "inspect_native_dispatch_metadata" },
+    ].map((contract) => {
+        const availability = available
+            ? { available: true, reason: null }
+            : {
+                available: false,
+                availabilityCode: "unsupported_host",
+                reason: "Native macOS utilities require macOS.",
+            };
+        return Object.freeze({
+            provider: IDENTITY,
+            operation: contract.name,
+            ...availability,
+            effects: Object.freeze({
+                mutatesArtifact: false,
+                launchesProcess: contract.name !== "inspect_native_dispatch_metadata",
+                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,
+            }),
+            limitations: Object.freeze([
+                "Availability and textual formats depend on the installed macOS/Xcode toolchain.",
+            ]),
+        });
+    }));
+};

package/dist/native/NativeMachoInspection.js

@@ -1,8 +1,9 @@
-import { inspectMachoSchema, } from "../domain/nativeInspection.js";
+import { inspectMachoSchema, } from "../domain/native/nativeInspection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { parseDyldSymbols } from "./parsers/dyldInfo.js";
 import { parseLipoArchitectures } from "./parsers/lipo.js";
+import { withoutEchoedPathHeader } from "./parsers/echoedPath.js";
 import { parseOtoolLoadCommands } from "./parsers/otool.js";
 const DISCOVERY_COMMANDS = [
     ["file", ["-b"]],
@@ -53,25 +54,33 @@ export const inspectNativeMacho = async (context) => {
         limitations.push(VTOOL_UNAVAILABLE_LIMITATION);
     else
         return err(optional.error);
-    const result = normalizeMacho(captures, context.invocation, limitations);
+    const normalized = normalizeMacho(captures, context.invocation, limitations);
+    const segmentOffset = segmentContainerOffset(normalized, selectedArchitecture, /^Non-fat file:/mu.test(lipo.stdout));
+    const result = segmentOffset === undefined
+        ? inspectMachoSchema.parse({
+            ...normalized,
+            limitations: [
+                ...normalized.limitations,
+                "Segment evidence file offsets are unavailable because the selected Mach-O slice's container offset was not observed.",
+            ],
+        })
+        : normalized;
     return ok({
         result: jsonValueSchema.parse(result),
         provenance: result.provenance,
         limitations: result.limitations,
-        locations: fileOffsetLocations(result),
+        locations: fileOffsetLocations(result, segmentOffset),
     });
 };
 const normalizeMacho = (captures, toInvocation, additionalLimitations) => {
     const byTool = captureLookup(captures);
     const architectures = parseLipoArchitectures(byTool("lipo").stdout);
-    const load = parseOtoolLoadCommands(byTool("otool").stdout);
-    const imports = parseDyldSymbols(byTool("dyld_info", 0).stdout, "imports");
+    const load = parseOtoolLoadCommands(sliceOutput(byTool("otool")));
+    const imports = parseDyldSymbols(sliceOutput(byTool("dyld_info", 0)), "imports");
     const imageBase = load.segments.find((segment) => segment.file_offset === 0 && (segment.file_size ?? 0) > 0)?.vm_address ?? null;
-    const dyldExports = parseDyldSymbols(byTool("dyld_info", 1).stdout, "exports", imageBase);
-    const exports = uniqueSymbols([
-        ...dyldExports,
-        ...parseNmExports(byTool("nm").stdout),
-    ]);
+    const nmExports = parseNmExports(byTool("nm").stdout);
+    const dyldExports = parseDyldSymbols(sliceOutput(byTool("dyld_info", 1)), "exports", imageBase, new Set(nmExports.map(({ name }) => name)));
+    const exports = uniqueSymbols([...dyldExports, ...nmExports]);
     const uuid = /UUID:\s*([A-Fa-f0-9-]+)/u.exec(byTool("dwarfdump").stdout)?.[1] ??
         load.uuid;
     const provenance = captures.map(toInvocation);
@@ -90,7 +99,7 @@ const normalizeMacho = (captures, toInvocation, additionalLimitations) => {
         ...additionalLimitations,
         ...(threadEntrypoint ? [threadEntrypointLimitation] : []),
         ...(imageBase === null &&
-            /^\s*offset\s+symbol\s*$/mu.test(byTool("dyld_info", 1).stdout)
+            /^\s*offset\s+symbol\s*$/mu.test(sliceOutput(byTool("dyld_info", 1)))
             ? [
                 "Export virtual addresses are unavailable because no file-backed image base was observed.",
             ]
@@ -122,6 +131,8 @@ const normalizeMacho = (captures, toInvocation, additionalLimitations) => {
         limitations,
     });
 };
+/** Slice output without the echoed operand path, which can contain any text. */
+const sliceOutput = (capture) => withoutEchoedPathHeader(capture.stdout, capture.arguments.at(-1));
 const captureLookup = (captures) => (tool, occurrence = 0) => {
     const capture = captures.filter((item) => item.tool === tool)[occurrence];
     if (capture === undefined)
@@ -157,19 +168,39 @@ const uniqueSymbols = (items) => {
             unique.set(item.name, item);
     return [...unique.values()].sort((left, right) => left.name.localeCompare(right.name));
 };
-const fileOffsetLocations = (macho) => {
+const fileOffsetLocations = (macho, segmentOffset) => {
     const locations = architectureLocations(macho.architectures.items);
+    if (segmentOffset === undefined)
+        return locations;
     for (const segment of macho.segments.items) {
         if (segment.file_offset === null || segment.file_size === null)
             continue;
         locations.push({
             kind: "file-offset-range",
-            start: segment.file_offset,
-            end: segment.file_offset + segment.file_size,
+            start: segmentOffset + segment.file_offset,
+            end: segmentOffset + segment.file_offset + segment.file_size,
         });
     }
     return locations;
 };
+/** otool segment offsets are slice-relative; evidence addresses the input file. */
+const segmentContainerOffset = (macho, selectedArchitecture, thinInput) => {
+    const architectures = macho.architectures.items;
+    const slice = selectedArchitecture === null
+        ? architectures.length === 1
+            ? architectures[0]
+            : undefined
+        : architectures.find(({ name }) => name === selectedArchitecture);
+    if (slice?.file_offset !== null && slice?.file_offset !== undefined)
+        return slice.file_offset;
+    // A thin lipo observation has no separate slice offset. Unknown FAT slice
+    // offsets must not silently become zero and identify unrelated container bytes.
+    return thinInput &&
+        selectedArchitecture === null &&
+        architectures.length === 1
+        ? 0
+        : undefined;
+};
 /** Project architecture slices into evidence file-offset locations. */
 export const architectureLocations = (architectures) => {
     const locations = [];

package/dist/native/NativeUiHelperRuntime.js

@@ -1,9 +1,10 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 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 = () => {
     let root;
@@ -12,11 +13,14 @@ export const createNativeUiHelperRuntime = () => {
         if (executable === undefined) {
             root = await mkdtemp(join(tmpdir(), "rea-native-ui-"));
             const output = join(root, "observer");
+            const main = join(root, "main.swift");
+            await symlink(fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url)), main);
             await execFileOutput("/usr/bin/xcrun", [
                 "swiftc",
                 "-module-cache-path",
                 join(root, "modules"),
-                fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url)),
+                fileURLToPath(new URL("../../bridge/native/NativeUIChildren.swift", import.meta.url)),
+                main,
                 "-o",
                 output,
             ], {
@@ -28,7 +32,7 @@ export const createNativeUiHelperRuntime = () => {
         }
         const output = await execFileOutput(executable, [JSON.stringify(parameters)], {
             timeout: 30_000,
-            maxBuffer: 16 * 1024 * 1024,
+            maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER,
             ...(signal === undefined ? {} : { signal }),
         });
         const parsed = safeParseJson(output.stdout);

package/dist/native/NativeUiObservation.js

@@ -1,11 +1,12 @@
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import { nativeUiObservationInputSchema, nativeUiScenarioInputSchema, nativeUiSnapshotSchema, nativeUiResultSchema, } from "../domain/nativeUiObservation.js";
+import { nativeUiObservationInputSchema, nativeUiScenarioInputSchema, nativeUiSnapshotSchema, nativeUiResultSchema, } from "../domain/native/nativeUiObservation.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
 import { createNativeUiHelperRuntime } from "./NativeUiHelperRuntime.js";
+import { NATIVE_UI_OUTPUT_BUDGET_BYTES, NATIVE_UI_OUTPUT_WEIGHT, } from "./NativeUiOutputBudget.js";
 const helper = fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url));
 const responseSchema = z.discriminatedUnion("ok", [
     z.strictObject({ ok: z.literal(true), result: nativeUiSnapshotSchema }),
@@ -74,8 +75,10 @@ const observeWithHelper = async (target, operation, parameters, options) => {
                     response.result.window.launch_time !== launchTime))
                 return err(new AnalysisCapabilityUnavailableError("native-macos", operation, "Native helper returned a different target process or window"));
             launchTime = response.result.window.launch_time;
-            outputBytes += 2 * Buffer.byteLength(JSON.stringify(response.result));
-            if (outputBytes > 64 * 1024 * 1024)
+            outputBytes +=
+                NATIVE_UI_OUTPUT_WEIGHT *
+                    Buffer.byteLength(JSON.stringify(response.result));
+            if (outputBytes > NATIVE_UI_OUTPUT_BUDGET_BYTES)
                 return err(new AnalysisCapabilityUnavailableError("native-macos", operation, "Scenario captures exceeded the 64 MiB output budget"));
             return ok(response.result);
         }
@@ -86,7 +89,8 @@ const observeWithHelper = async (target, operation, parameters, options) => {
                     cause,
                     diagnostics: {
                         helper_path: helper,
-                        reason: "Native helper failed, timed out, or returned malformed capture data; install compatible Xcode command-line tools and inspect local OS permissions",
+                        reason: cause instanceof Error ? cause.message : String(cause),
+                        remediation: "Native helper failed, timed out, or returned malformed capture data; install compatible Xcode command-line tools and inspect local OS permissions",
                     },
                 }));
         }

package/dist/native/NativeUiOutputBudget.js

@@ -0,0 +1,8 @@
+const HELPER_SUCCESS_WRAPPER = Buffer.from(JSON.stringify({ ok: true, result: {} }));
+/** Scenario output is charged at twice the encoded result size before return. */
+export const NATIVE_UI_OUTPUT_BUDGET_BYTES = 64 * 1024 * 1024;
+export const NATIVE_UI_OUTPUT_WEIGHT = 2;
+/** Bytes added around a result by the helper's success JSON response. */
+export const NATIVE_UI_HELPER_ENVELOPE_BYTES = HELPER_SUCCESS_WRAPPER.byteLength - Buffer.byteLength("{}");
+/** Raw helper output is bounded by the scenario's existing unweighted byte budget. */
+export const NATIVE_UI_HELPER_MAX_BUFFER = NATIVE_UI_OUTPUT_BUDGET_BYTES + NATIVE_UI_HELPER_ENVELOPE_BYTES;