rea-agents 5.0.0 → 6.0.0

package/dist/native/LldbCallTracer.js

@@ -0,0 +1,278 @@
+import { spawn } from "node:child_process";
+import { open, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { nativeCallEventSchema, nativeCodeLocationSchema, } from "../domain/native/nativeCallObservation.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
+import { execFileOutput } from "../process/ExecFileOutput.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { resolveXcrunTool } from "./CommandRunner.js";
+const OPERATION = "observe_native_calls";
+const PROVIDER = "native-macos";
+/** 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. */
+const DEADLINE_GRACE_MS = 60_000;
+const DIAGNOSTIC_BYTES = 16 * 1024;
+const BRIDGE = fileURLToPath(new URL("../../bridge/native/rea_lldb_tracer.py", import.meta.url));
+/** JSON the LLDB bridge writes after a completed run. */
+const tracedSchema = z.strictObject({
+    status: z.literal("traced"),
+    version: z.string(),
+    pid: z.number().int().positive(),
+    outcome: z.enum(["exited", "duration-elapsed", "event-limit", "stop-limit"]),
+    exit_status: z.number().int().nullable(),
+    exit_description: z.string().nullable(),
+    killed: z.boolean(),
+    terminated: z.boolean(),
+    elapsed_ms: z.number().nonnegative(),
+    breakpoints: z.array(z.strictObject({
+        index: z.number().int().nonnegative(),
+        location_count: z.number().int().nonnegative(),
+        locations: z.array(nativeCodeLocationSchema),
+    })),
+    events: z.array(nativeCallEventSchema),
+    other_stops: z.array(z.string()),
+});
+const tracerOutputSchema = z.discriminatedUnion("status", [
+    tracedSchema,
+    z.strictObject({
+        status: z.enum(["target-error", "launch-error", "tracer-error"]),
+        error: z.string().nullable(),
+    }),
+]);
+/** Remediation for a target LLDB may not debug. */
+const ATTACH_REMEDIATION = "Allow debugging for this user (Developer Tools access: `DevToolsSecurity -enable`, or membership in the _developer group). A hardened-runtime target is debuggable only with the com.apple.security.get-task-allow entitlement; see inspect_signature's debugger-attach facet.";
+/** Production tracer: `lldb --batch` running the REA LLDB bridge. */
+export class LldbCallTracer {
+    async trace(request, signal) {
+        const lldb = await resolveXcrunTool("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"));
+        const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
+        try {
+            return await this.#run(lldb.value, root.path, request, signal);
+        }
+        finally {
+            await root.close();
+        }
+    }
+    async #run(lldb, directory, request, signal) {
+        const paths = {
+            config: join(directory, "config.json"),
+            result: join(directory, "result.json"),
+            pid: join(directory, "pid"),
+            stdout: join(directory, "stdout"),
+            stderr: join(directory, "stderr"),
+        };
+        const { input } = request;
+        await writeFile(paths.config, JSON.stringify({
+            executable: request.executable,
+            architecture: request.architecture,
+            arguments: input.arguments,
+            environment: input.environment,
+            working_directory: input.working_directory ?? null,
+            breakpoints: input.breakpoints.map((breakpoint) => breakpoint.kind === "function"
+                ? { ...breakpoint, module: breakpoint.module ?? null }
+                : { ...breakpoint, class_name: breakpoint.class_name ?? null }),
+            duration_ms: input.duration_ms,
+            max_events: input.max_events,
+            argument_registers: input.argument_registers,
+            backtrace_frames: input.backtrace_frames,
+            stdout_path: paths.stdout,
+            stderr_path: paths.stderr,
+            result_path: paths.result,
+            pid_path: paths.pid,
+        }), { mode: 0o600 });
+        const exited = await runLldb(lldb.path, [
+            "--batch",
+            "--no-lldbinit",
+            "--no-use-colors",
+            "-o",
+            `command script import ${quote(BRIDGE)}`,
+            "-o",
+            `rea_trace ${paths.config}`,
+        ], {
+            deadlineMs: input.duration_ms + DEADLINE_GRACE_MS,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const terminated = await ensureTerminated(paths.pid, request.executable);
+        if (exited.kind === "cancelled")
+            return err(new AnalysisCancelledError(OPERATION));
+        if (exited.kind === "timeout")
+            return err(new AnalysisTimeoutError(OPERATION, input.duration_ms + DEADLINE_GRACE_MS));
+        const output = await readTracerOutput(paths.result);
+        if (output === undefined)
+            return err(new ProviderAdapterError(PROVIDER, OPERATION, {
+                diagnostics: {
+                    reason: "LLDB exited without a tracer result",
+                    exit_code: exited.exitCode,
+                    lldb_output: exited.output,
+                },
+            }));
+        if (output.status !== "traced")
+            return err(tracerFailure(output));
+        return ok({
+            debugger: { ...lldb, version: output.version },
+            run: output,
+            stdout: await capturedOutput(paths.stdout),
+            stderr: await capturedOutput(paths.stderr),
+            terminated,
+        });
+    }
+}
+/** LLDB command arguments are quoted; the bridge path is REA's own install path. */
+const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+const tracerFailure = (output) => {
+    const message = output.error ?? "no LLDB error text";
+    if (output.status === "tracer-error")
+        return new ProviderAdapterError(PROVIDER, OPERATION, {
+            diagnostics: { reason: `LLDB bridge failed: ${message}` },
+        });
+    if (output.status === "target-error")
+        return new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `lldb-target-unloadable: ${message}`);
+    // debugserver reports denied task access as an attach failure.
+    return /attach|not allowed|permission|denied|debugserver/iu.test(message)
+        ? new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `debugger-attach-denied: ${message}`, { userMessage: ATTACH_REMEDIATION })
+        : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `launch-failed: ${message}`);
+};
+const readTracerOutput = async (path) => {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = safeParseJson(text);
+    if (!parsed.ok)
+        return undefined;
+    const output = tracerOutputSchema.safeParse(parsed.value);
+    return output.success ? output.data : undefined;
+};
+const capturedOutput = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch {
+        return { text: "", bytes: 0, truncated: false };
+    }
+    try {
+        const { size } = await handle.stat();
+        const buffer = Buffer.alloc(Math.min(size, MAX_OUTPUT_BYTES));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        return {
+            text: buffer.subarray(0, bytesRead).toString("utf8"),
+            bytes: size,
+            truncated: size > MAX_OUTPUT_BYTES,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Run LLDB in its own process group so cancellation can stop it and debugserver. */
+const runLldb = (executable, arguments_, options) => new Promise((resolve) => {
+    if (options.signal?.aborted === true) {
+        resolve({ kind: "cancelled" });
+        return;
+    }
+    const child = spawn(executable, [...arguments_], {
+        shell: false,
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    let stopped;
+    const keep = (chunk) => {
+        output = (output + chunk.toString("utf8")).slice(-DIAGNOSTIC_BYTES);
+    };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const kill = (reason) => {
+        stopped ??= reason;
+        if (child.pid !== undefined)
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                // The group already exited.
+            }
+    };
+    const timer = setTimeout(() => {
+        kill("timeout");
+    }, options.deadlineMs);
+    const onAbort = () => {
+        kill("cancelled");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const finish = (exitCode) => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve(stopped === undefined
+            ? { kind: "exited", exitCode, output }
+            : { kind: stopped });
+    };
+    child.on("error", () => {
+        finish(null);
+    });
+    child.on("close", (code) => {
+        finish(code);
+    });
+});
+/**
+ * debugserver kills the traced process when LLDB exits. Confirm it, and kill a
+ * survivor only when its executable is still the traced one.
+ */
+const ensureTerminated = async (pidPath, executable) => {
+    let pid;
+    try {
+        pid = Number.parseInt(await readFile(pidPath, "utf8"), 10);
+    }
+    catch {
+        // LLDB never launched the target.
+        return true;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    for (let attempt = 0; attempt < 20; attempt++) {
+        if (!alive(pid))
+            return true;
+        if (attempt === 10 && (await commandOf(pid)) === executable)
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // It exited between the checks.
+            }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return !alive(pid);
+};
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return !(cause instanceof Error &&
+            "code" in cause &&
+            cause.code === "ESRCH");
+    }
+};
+const commandOf = async (pid) => {
+    try {
+        const { stdout } = await execFileOutput("/bin/ps", ["-o", "comm=", "-p", String(pid)], { timeout: 5_000 });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/native/NativeCallObservation.js

@@ -0,0 +1,135 @@
+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 { 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) => {
+    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.
+    if ((await fileSha256(target.path, signal)) !== 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,
+        input: parsed.data,
+    }, signal);
+    if (!traced.ok)
+        return traced;
+    return ok(projectNativeCalls(target, parsed.data, traced.value));
+};
+/** 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 partial = eventLimit || run.outcome === "stop-limit" || unresolved.length > 0;
+    return nativeCallObservationResultSchema.parse({
+        target: {
+            path: target.path,
+            sha256: target.sha256,
+            architecture: target.architecture,
+            arguments: input.arguments,
+            working_directory: input.working_directory ?? null,
+        },
+        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,
+            unresolved_breakpoints: unresolved,
+        },
+        limitations: [
+            ...NATIVE_CALL_OBSERVATION_LIMITATIONS,
+            ...(eventLimit
+                ? [
+                    `Observation stopped at max_events (${input.max_events}); later calls were not recorded and the process was killed.`,
+                ]
+                : []),
+            ...(run.outcome === "duration-elapsed"
+                ? [
+                    `The process was still running after duration_ms (${input.duration_ms}) and was killed.`,
+                ]
+                : []),
+            ...(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.",
+                ]
+                : []),
+            ...(trace.stdout.truncated || trace.stderr.truncated
+                ? ["Target output beyond 1 MiB per stream is counted but not kept."]
+                : []),
+            ...(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,6 +2,8 @@ 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";
@@ -24,9 +26,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 +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)
@@ -83,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, {
@@ -117,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);

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,

package/dist/native/pwndbg/PwndbgCoreContext.js

@@ -0,0 +1,160 @@
+import { access, mkdir, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { recordedCrashDebuggerSchema, } from "../../domain/native/recordedCrash.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { runOwnedCommand } from "../../process/OwnedCommand.js";
+import { capturedPwntoolsOutput, pwntoolsDecoderFailure, } from "../pwntools/PwntoolsFailures.js";
+import { PWNTOOLS_LIMITS } from "../pwntools/PwntoolsRelease.js";
+import { readPwntoolsFailureEvidence } from "../pwntools/PwntoolsResourceLimits.js";
+const OPERATION = "inspect_recorded_crash";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: recordedCrashDebuggerSchema }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum([
+            "unavailable",
+            "unsupported",
+            "decoder",
+            "format",
+            "output-limit",
+        ]),
+        message: z.string(),
+    }),
+]);
+/** Add mapping candidates from an owned core-only debugger, using the existing snapshot. */
+export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, options, launcher, }) => {
+    const gdb = environment.REA_PWNDBG_GDB ?? "/usr/bin/gdb";
+    const entry = environment.REA_PWNDBG_GDBINIT ?? "";
+    const venv = environment.REA_PWNDBG_VENV_PATH ?? "";
+    const unavailable = (message, cause) => new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, message, {
+        ...(cause === undefined ? {} : { cause }),
+        userMessage: message,
+        capturedOutput: diagnostics,
+    });
+    for (const [key, path, kind] of [
+        ["REA_PWNDBG_GDB", gdb, "file"],
+        ["REA_PWNDBG_GDBINIT", entry, "file"],
+        ["REA_PWNDBG_VENV_PATH", venv, "directory"],
+    ]) {
+        try {
+            if (!isAbsolute(path))
+                throw new Error("Expected an absolute caller-supplied path.");
+            await access(path, key === "REA_PWNDBG_GDB" ? constants.X_OK : constants.R_OK);
+            const information = await stat(path);
+            if (kind === "file" ? !information.isFile() : !information.isDirectory())
+                throw new Error(`Expected a ${kind}.`);
+        }
+        catch (cause) {
+            throw unavailable(`${key} is unavailable at ${path}: ${cause instanceof Error ? cause.message : String(cause)}. Configure the requested core-only context, or omit include_debugger_context for basic recorded evidence.`, cause);
+        }
+    }
+    const stage = join(rootPath, "debugger");
+    await mkdir(stage, { mode: 0o700 });
+    const requestPath = join(stage, "request.json");
+    const replyPath = join(stage, "reply.json");
+    await writeFile(requestPath, JSON.stringify({
+        snapshot_path: join(rootPath, "object.snapshot"),
+        reply_path: replyPath,
+        gdb,
+        gdbinit: entry,
+        venv,
+    }), { flag: "wx", mode: 0o600 });
+    let output;
+    try {
+        options?.signal?.throwIfAborted();
+        const execution = await runOwnedCommand({
+            command: environment.REA_PWNTOOLS_PYTHON ?? "",
+            arguments: [
+                "-I",
+                fileURLToPath(new URL("../../../bridge/pwndbg/launch.py", import.meta.url)),
+                join(stage, "resource.failure"),
+                requestPath,
+            ],
+            cwd: stage,
+            runId: `rea-recorded-core-debugger-${randomUUID()}`,
+            hostEnvironment: {
+                ...environment,
+                PWNDBG_NO_AUTOUPDATE: "1",
+                PWNDBG_VENV_PATH: venv,
+                PWNLIB_NOTERM: "1",
+                TERM: "dumb",
+                HOME: stage,
+                XDG_CACHE_HOME: join(stage, "cache"),
+                XDG_CONFIG_HOME: join(stage, "config"),
+                PYTHONNOUSERSITE: "1",
+                OPENBLAS_NUM_THREADS: "1",
+                OMP_NUM_THREADS: "1",
+            },
+        }, {
+            timeoutMs: PWNTOOLS_LIMITS.timeoutMs,
+            diagnosticBytes: PWNTOOLS_LIMITS.diagnosticBytes,
+        }, {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(launcher === undefined ? {} : { launcher }),
+        });
+        output = capturedPwntoolsOutput(execution);
+        let reply;
+        try {
+            const raw = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal);
+            reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                cause,
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        }
+        if (!reply.ok) {
+            if (reply.reason === "unavailable" || reply.reason === "unsupported")
+                throw new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, reply.message, {
+                    userMessage: reply.message,
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            if (reply.reason === "format" || reply.reason === "output-limit")
+                throw new AnalysisOutputError(OPERATION, reply.message, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new ProviderAdapterError("pwndbg-core", OPERATION, {
+                diagnostics: {
+                    stage: "debugger",
+                    reason: reply.message,
+                    captured_output: { ...recordedCrashStageOutput(diagnostics, output) },
+                },
+            });
+        }
+        if (reply.value.status !== "available")
+            throw new AnalysisOutputError(OPERATION, "Requested debugger context returned no core evidence.", { capturedOutput: recordedCrashStageOutput(diagnostics, output) });
+        return { ...reply.value, diagnostics: output };
+    }
+    catch (cause) {
+        if (options?.signal?.aborted &&
+            (cause === options.signal.reason ||
+                (cause instanceof Error && cause.name === "AbortError")))
+            throw new AnalysisCancelledError(OPERATION, {
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        throw pwntoolsDecoderFailure(cause, "debugger", gdb, environment.REA_PWNTOOLS_PYTHON ?? "", await readPwntoolsFailureEvidence(cause, stage), {
+            operation: OPERATION,
+            providerId: "pwndbg-core",
+            precedingOutput: diagnostics,
+        });
+    }
+};
+/** Preserve both stages' exact text and their independently observed truncation state. */
+export const recordedCrashStageOutput = (basic, debuggerOutput) => debuggerOutput === undefined
+    ? basic
+    : {
+        stdout: `[core decoder]\n${basic.stdout}\n[debugger]\n${debuggerOutput.stdout}`,
+        stderr: `[core decoder]\n${basic.stderr}\n[debugger]\n${debuggerOutput.stderr}`,
+        truncated: basic.truncated || debuggerOutput.truncated,
+    };