rea-agents 6.3.0 → 6.5.0

package/dist/rizin/RizinDebugSessionManager.js

@@ -0,0 +1,1072 @@
+import { randomUUID } from "node:crypto";
+import { isUtf8 } from "node:buffer";
+import { open, readFile, readlink, realpath, stat } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { isatty } from "node:tty";
+import { resolve } from "node:path";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { err, ok } from "../domain/result.js";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
+import { closeOwnedDebuggerSessions, stopOwnedDebuggerProcess, verifyOwnedInferiorsEnded, } from "../process/ownedDebuggerSession.js";
+const MAX_SESSIONS = 8;
+const MAX_PENDING_COMMANDS = 16;
+const FRAME_TIMEOUT_MS = 120_000;
+const CLEANUP_COMMAND_TIMEOUT_MS = 1_000;
+const STARTUP_TIMEOUT_MS = 30_000;
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+const MAX_COMMAND_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MAX_QUEUED_FRAME_BYTES = 4 * 1024 * 1024;
+const MAX_QUEUED_FRAMES = 4096;
+const MIN_QUEUED_FRAME_CHARGE_BYTES = 64;
+const MAX_COMMAND_FRAMES = 4096;
+const MAX_RECENT_FRAME_BYTES = 16 * 1024;
+const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
+export const RIZIN_DEBUGGER_PROVIDER_IDENTITY = {
+    id: "rizin.debugger",
+    name: "Rizin debugger",
+    version: null,
+};
+const RIZIN_LAUNCH_PROVENANCE_LIMITATION = "Launch provenance records the original and resolved startup paths; it does not establish the current target after unrestricted debugger commands.";
+const createRizinCommandEvidence = ({ sessionId, command, result, inferiorTty, launchProvenance, limitations, }) => createEvidence(undefined, RIZIN_DEBUGGER_PROVIDER_IDENTITY, {
+    predicateType: "rea.debugger.command-observation",
+    operation: "rizin_debug_command",
+    parameters: {
+        session_id: sessionId,
+        command,
+        inferior_tty: inferiorTty,
+        launch_provenance: { ...launchProvenance },
+    },
+    result: { ...result },
+    rawResult: { ...result },
+    subjectUnavailableReason: "The current debugger target identity is not established by the Rizin session identifier.",
+    limitations: [
+        ...limitations,
+        ...(result.output_invalid_utf8
+            ? [
+                "Collected command frames contained invalid UTF-8 bytes; decoded text may contain replacement characters.",
+            ]
+            : []),
+        RIZIN_LAUNCH_PROVENANCE_LIMITATION,
+    ],
+});
+export class RizinCommandTimeoutError extends Error {
+    partialOutput;
+    outputInvalidUtf8;
+    constructor(partialOutput, outputInvalidUtf8 = false) {
+        super("Timed out waiting for Rizin's command-completion marker");
+        this.partialOutput = partialOutput;
+        this.outputInvalidUtf8 = outputInvalidUtf8;
+    }
+}
+export const isRizinCommandDeadlineExpired = (remainingMs) => remainingMs <= 0;
+export const createRizinCommandTimeoutError = (partialFrames, outputInvalidUtf8 = false) => new RizinCommandTimeoutError(partialFrames.join("\n"), outputInvalidUtf8);
+export const createRizinCommandTimeoutEvidence = ({ sessionId, command, result, inferiorTty, cleanupFailure, launchProvenance, }) => createRizinCommandEvidence({
+    sessionId,
+    command,
+    result,
+    inferiorTty,
+    launchProvenance,
+    limitations: [
+        "The command timed out before its completion marker; retained output is partial and completion is unknown.",
+        ...(result.output_invalid_utf8
+            ? [
+                "Collected command frame bytes did not form valid UTF-8; displayed output contains replacement characters.",
+            ]
+            : []),
+        ...(cleanupFailure === undefined
+            ? [
+                "The owned debugger session was stopped because output correlation could no longer be guaranteed.",
+            ]
+            : [
+                `The owned debugger session remains retained because cleanup could not be verified: ${cleanupFailure}`,
+            ]),
+        "The command is unrestricted and may access local files, the shell, network, or mutate the target.",
+    ],
+});
+class RizinProcessExitError extends Error {
+    partialOutput;
+    outputInvalidUtf8;
+    constructor(partialOutput, outputInvalidUtf8 = false) {
+        super("Rizin process exited before completing the active command");
+        this.partialOutput = partialOutput;
+        this.outputInvalidUtf8 = outputInvalidUtf8;
+    }
+}
+class RizinCommandCancelledError extends AnalysisCancelledError {
+    partialOutput;
+    outputInvalidUtf8;
+    constructor(partialOutput, outputInvalidUtf8, cause) {
+        super("rizin_debug_command", {
+            cause,
+            capturedOutput: {
+                stdout: partialOutput,
+                stderr: "",
+                truncated: false,
+            },
+        });
+        this.partialOutput = partialOutput;
+        this.outputInvalidUtf8 = outputInvalidUtf8;
+    }
+}
+class RizinFrameTimeoutError extends Error {
+    constructor() {
+        super("Timed out waiting for the next Rizin NUL frame");
+    }
+}
+/** Owns persistent Rizin debugger processes independently from BinarySession. */
+export class RizinDebugSessionManager {
+    #sessions = new Map();
+    #activeStarts = 0;
+    #sessionReservations = 0;
+    #environment;
+    #closingAll = false;
+    #startDrainWaiters = [];
+    #command;
+    #frameTimeoutMs;
+    #startupTimeoutMs;
+    #maxCommandOutputBytes;
+    #platform;
+    #stopProcess;
+    #spawnProcess;
+    constructor(environment = process.env, options = {}) {
+        this.#environment = { ...environment };
+        this.#command = environment.REA_RIZIN_COMMAND ?? "rizin";
+        this.#frameTimeoutMs = options.frameTimeoutMs ?? FRAME_TIMEOUT_MS;
+        this.#startupTimeoutMs = options.startupTimeoutMs ?? STARTUP_TIMEOUT_MS;
+        this.#maxCommandOutputBytes =
+            options.maxCommandOutputBytes ?? MAX_COMMAND_OUTPUT_BYTES;
+        this.#platform = options.platform ?? process.platform;
+        this.#stopProcess = options.stopProcess ?? stopOwnedDebuggerProcess;
+        this.#spawnProcess = options.spawnProcess ?? spawnOwnedProviderProcess;
+    }
+    async start(input, signal) {
+        if (this.#closingAll)
+            return err(new AnalysisInputError("start_rizin_debug_session"));
+        const occupied = this.#sessions.size + this.#sessionReservations;
+        if (occupied >= MAX_SESSIONS)
+            return err(new AnalysisResourceConstraintError("start_rizin_debug_session", "memory", "Rizin session capacity reached.", { max_sessions: MAX_SESSIONS, active_or_reserved_sessions: occupied }));
+        this.#activeStarts += 1;
+        this.#sessionReservations += 1;
+        let reserved = true;
+        const releaseReservation = () => {
+            if (!reserved)
+                return;
+            reserved = false;
+            this.#sessionReservations -= 1;
+        };
+        try {
+            return await this.#start(input, signal, releaseReservation);
+        }
+        finally {
+            releaseReservation();
+            this.#activeStarts -= 1;
+            if (this.#activeStarts === 0)
+                for (const resolve of this.#startDrainWaiters.splice(0))
+                    resolve();
+        }
+    }
+    async #start(input, signal, releaseReservation) {
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError("start_rizin_debug_session"));
+        if (this.#platform !== "linux")
+            return err(new AnalysisCapabilityUnavailableError("rizin", "start_rizin_debug_session", "Persistent Rizin debugger sessions require Linux /proc descriptor readback to verify inferior detachment and output routing."));
+        if (input.inferior_tty === undefined || input.inferior_tty.length === 0)
+            return err(new AnalysisInputError("start_rizin_debug_session"));
+        let ttyPath;
+        let ttyDevice;
+        let ttyInode;
+        try {
+            ttyPath = await realpath(input.inferior_tty);
+            const ttyHandle = await open(ttyPath, fsConstants.O_RDWR | fsConstants.O_NOCTTY | fsConstants.O_NONBLOCK);
+            try {
+                const ttyStat = await ttyHandle.stat();
+                if (!isatty(ttyHandle.fd) ||
+                    (ttyStat.mode & fsConstants.S_IFMT) !== fsConstants.S_IFCHR)
+                    throw new Error("The selected inferior_tty is not a character TTY.");
+                ttyDevice = ttyStat.dev;
+                ttyInode = ttyStat.ino;
+            }
+            finally {
+                await ttyHandle.close();
+            }
+        }
+        catch (cause) {
+            return err(new AnalysisInputError("start_rizin_debug_session", { cause }));
+        }
+        // TTY identity validation is asynchronous. Cancellation may arrive while
+        // realpath/open/stat are pending, and must prevent the debugger spawn.
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError("start_rizin_debug_session"));
+        const id = randomUUID();
+        const resolvedPath = resolve(input.path);
+        const launchProvenance = {
+            caller_selected_path: input.path,
+            resolved_path: resolvedPath,
+        };
+        const arguments_ = [
+            "-N",
+            "-0",
+            "-d",
+            "-R",
+            `stdout=${ttyPath}`,
+            "-R",
+            `stderr=${ttyPath}`,
+            "-e",
+            "dbg.exitkills=false",
+            ...(input.backend === undefined ? [] : ["-D", input.backend]),
+            resolvedPath,
+        ];
+        let launched;
+        try {
+            launched = await this.#spawnProcess({
+                command: this.#command,
+                arguments: arguments_,
+                hostEnvironment: this.#environment,
+                runId: id,
+                stdin: "pipe",
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            if (signal?.aborted)
+                return err(new AnalysisCancelledError("start_rizin_debug_session", { cause }));
+            return err(new AnalysisCapabilityUnavailableError("rizin", "start_rizin_debug_session", cause instanceof Error
+                ? cause.message
+                : "Unable to start Rizin debugger"));
+        }
+        const session = {
+            id,
+            launched,
+            launchProvenance,
+            backend: input.backend ?? null,
+            inferiorTty: ttyPath,
+            inferiorTtyDevice: ttyDevice,
+            inferiorTtyInode: ttyInode,
+            knownInferiorIdentities: new Map(),
+            inferiorInventoryComplete: false,
+            inferiorStateUnknown: () => !session.inferiorInventoryComplete,
+            verifyInferiorsEndedAfterExit: async () => {
+                if (!session.inferiorInventoryComplete)
+                    return false;
+                const ended = await verifyOwnedInferiorsEnded(session.knownInferiorIdentities.values());
+                if (ended)
+                    session.knownInferiorIdentities.clear();
+                return ended;
+            },
+            detachInferior: () => session.cleanupCommandTurnHeld
+                ? this.#detachInferiorUnlocked(session)
+                : this.#detachInferior(session),
+            cleanupCommandTurnHeld: false,
+            stopAttempt: undefined,
+            cleanupFailures: new Set(),
+            pendingCommandCount: 0,
+            invalidUtf8Observed: false,
+            closing: false,
+            supervisor: new ProviderProcessSupervisor({ process: launched.process, ownsProcessLifetime: false }, {
+                captureStdout: false,
+                maxDiagnosticBytes: MAX_DIAGNOSTIC_BYTES,
+            }),
+            frames: [],
+            frameWaiters: [],
+            history: [],
+            queuedFrameBytes: 0,
+            historyTruncated: false,
+            frameChunks: [],
+            bufferedFrameBytes: 0,
+            ready: false,
+            exited: false,
+            commandTail: Promise.resolve(),
+            protocolError: undefined,
+            commandCaptureActive: false,
+            discardingOversizedFrame: false,
+        };
+        this.#sessions.set(id, session);
+        releaseReservation();
+        launched.process.stdout?.on("data", (chunk) => this.#receive(session, Buffer.from(chunk)));
+        launched.process.stdin?.on("error", (cause) => this.#failProtocol(session, `Rizin stdin stream failed: ${cause.message}`));
+        launched.process.stdin?.once("close", () => {
+            if (!session.exited && session.protocolError === undefined)
+                this.#failProtocol(session, "Rizin stdin stream closed unexpectedly.");
+        });
+        launched.process.once("exit", () => {
+            session.exited = true;
+            for (const waiter of session.frameWaiters)
+                waiter.reject(new RizinProcessExitError(""));
+            session.frameWaiters.length = 0;
+        });
+        try {
+            await waitForFrame(session, this.#startupTimeoutMs, signal);
+            // Let process and stream lifecycle notifications queued alongside the
+            // initial frame run before publishing the session as ready.
+            await new Promise((resolve) => setImmediate(resolve));
+            if (signal?.aborted)
+                throw new AnalysisCancelledError("start_rizin_debug_session");
+            if (session.exited)
+                throw new RizinProcessExitError("Rizin exited during startup.");
+            if (session.protocolError !== undefined)
+                throw new Error(session.protocolError);
+            session.ready = true;
+            return ok({ session_id: id, backend: input.backend ?? null });
+        }
+        catch (cause) {
+            const stopped = await this.#stopDebuggerOnly(session);
+            const capturedOutput = this.#startupCapturedOutput(session);
+            if (stopped.status !== "incomplete")
+                this.#sessions.delete(id);
+            if (stopped.status === "incomplete")
+                return err(this.#retainCleanupFailure(session, "start_rizin_debug_session", stopped.reason, { cause, capturedOutput }));
+            if (signal?.aborted || cause instanceof AnalysisCancelledError)
+                return err(new AnalysisCancelledError("start_rizin_debug_session", {
+                    cause,
+                    capturedOutput,
+                }));
+            if (session.protocolError !== undefined)
+                return err(new AnalysisCapabilityUnavailableError("rizin", "start_rizin_debug_session", session.protocolError, { cause, capturedOutput }));
+            if (cause instanceof RizinProcessExitError) {
+                return err(new AnalysisCapabilityUnavailableError("rizin", "start_rizin_debug_session", cause.message, {
+                    cause,
+                    capturedOutput,
+                }));
+            }
+            return err(new AnalysisTimeoutError("start_rizin_debug_session", this.#startupTimeoutMs, { cause, capturedOutput }));
+        }
+    }
+    async execute(sessionId, command, signal) {
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined ||
+            !session.ready ||
+            session.exited ||
+            session.protocolError !== undefined ||
+            session.closing ||
+            this.#closingAll)
+            return err(new AnalysisInputError("rizin_debug_command"));
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError("rizin_debug_command"));
+        if (session.pendingCommandCount >= MAX_PENDING_COMMANDS)
+            return err(new AnalysisResourceConstraintError("rizin_debug_command", "transport", "Rizin command queue capacity reached.", {
+                max_pending_commands: MAX_PENDING_COMMANDS,
+                active_or_queued_commands: session.pendingCommandCount,
+            }));
+        session.pendingCommandCount += 1;
+        let release;
+        let acquired = false;
+        let commandSent = false;
+        const previous = session.commandTail;
+        session.commandTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        try {
+            await waitForTurn(previous, signal);
+            acquired = true;
+            if (signal?.aborted)
+                return err(new AnalysisCancelledError("rizin_debug_command"));
+            if (!session.ready ||
+                session.exited ||
+                session.closing ||
+                this.#closingAll ||
+                session.protocolError !== undefined)
+                return err(new AnalysisInputError("rizin_debug_command"));
+            if (session.frames.length > 0) {
+                const message = "Unsolicited Rizin frames arrived before a command; command output can no longer be safely correlated.";
+                this.#failProtocol(session, message);
+                return err(await this.#stopAfterProtocolFailure(session, undefined, true));
+            }
+            const marker = `__REA_COMMAND_COMPLETE_${randomUUID().replaceAll("-", "")}__`;
+            // Arbitrary debugger commands can create or replace inferiors. Discard
+            // the prior inventory before any command bytes reach the provider.
+            session.inferiorInventoryComplete = false;
+            session.knownInferiorIdentities.clear();
+            commandSent = true;
+            const stdin = session.launched.process.stdin;
+            if (stdin === null ||
+                stdin === undefined ||
+                stdin.destroyed ||
+                !stdin.writable) {
+                this.#failProtocol(session, "Rizin stdin stream is closed.");
+            }
+            else {
+                try {
+                    stdin.write(`${command}\n!echo ${marker}\n`, "utf8", (cause) => {
+                        if (cause)
+                            this.#failProtocol(session, `Rizin stdin write failed: ${cause.message}`);
+                    });
+                }
+                catch (cause) {
+                    this.#failProtocol(session, `Rizin stdin write failed: ${cause instanceof Error ? cause.message : "unknown error"}`);
+                }
+            }
+            if (session.protocolError !== undefined)
+                throw new Error(session.protocolError);
+            session.commandCaptureActive = true;
+            const captured = await waitForCommandFrames(session, marker, this.#frameTimeoutMs, signal, this.#maxCommandOutputBytes);
+            if (signal?.aborted)
+                throw new AnalysisCancelledError("rizin_debug_command");
+            let cleanupFailure;
+            if (captured.outputTruncated) {
+                // Stryker disable next-line BooleanLiteral -- `waitForCommandFrames` sets `protocolError` before reporting truncation; both detach wrappers therefore fail closed before a queued command can be awaited, so the held-tail flag cannot change this public path.
+                const stopped = await this.#stopDebuggerOnly(session, true);
+                if (stopped.status === "incomplete")
+                    cleanupFailure = stopped.reason;
+            }
+            const result = {
+                command,
+                output: captured.output,
+                output_scope: "command_and_interleaved_session_output",
+                output_truncated: captured.outputTruncated,
+                completion_status: captured.outputTruncated
+                    ? "unknown"
+                    : "complete",
+                backend: session.backend,
+                ...(captured.outputInvalidUtf8
+                    ? { output_invalid_utf8: true }
+                    : {}),
+            };
+            const evidence = createRizinCommandEvidence({
+                sessionId,
+                command,
+                result,
+                inferiorTty: session.inferiorTty,
+                launchProvenance: session.launchProvenance,
+                limitations: [
+                    "Rizin commands and debugger effects depend on the loaded IO plugin and target.",
+                    "Output contains all NUL frames through an explicit command-completion marker; backend output interleaved before that marker cannot be distinguished from command output.",
+                    ...(captured.outputTruncated
+                        ? [
+                            `The Rizin command exceeded the output or frame limit. Retained output is partial and command completion is unknown.${cleanupFailure === undefined ? " The owned debugger session was stopped." : ` The owned debugger session remains retained because cleanup could not be verified: ${cleanupFailure}`}`,
+                        ]
+                        : []),
+                    "The command is unrestricted and may access local files, the shell, network, or mutate the target.",
+                ],
+            });
+            if (cleanupFailure !== undefined)
+                return err(this.#retainCleanupFailure(session, "rizin_debug_command", cleanupFailure, {
+                    partialObservation: evidence,
+                }));
+            return ok({ result, evidence });
+        }
+        catch (cause) {
+            if (signal?.aborted || cause instanceof AnalysisCancelledError) {
+                if (!commandSent)
+                    return err(new AnalysisCancelledError("rizin_debug_command", { cause }));
+                const partialOutput = cause instanceof RizinCommandCancelledError
+                    ? cause.partialOutput
+                    : undefined;
+                const commandInvalidUtf8 = cause instanceof RizinCommandCancelledError &&
+                    cause.outputInvalidUtf8;
+                const partialEvidence = partialOutput === undefined
+                    ? undefined
+                    : createRizinCommandEvidence({
+                        sessionId,
+                        command,
+                        result: {
+                            command,
+                            output: partialOutput,
+                            output_scope: "command_and_interleaved_session_output",
+                            output_truncated: false,
+                            completion_status: "unknown",
+                            backend: session.backend,
+                            ...(commandInvalidUtf8
+                                ? { output_invalid_utf8: true }
+                                : {}),
+                        },
+                        inferiorTty: session.inferiorTty,
+                        launchProvenance: session.launchProvenance,
+                        limitations: [
+                            "The Rizin command was cancelled; collected frame output is partial and command completion is unknown.",
+                            "The owned debugger session was stopped because command output can no longer be correlated safely.",
+                            "The command is unrestricted and may access local files, the shell, network, or mutate the target.",
+                        ],
+                    });
+                session.protocolError =
+                    "A Rizin command was cancelled; the owned session was stopped because command output can no longer be correlated safely.";
+                const stopped = await this.#stopDebuggerOnly(session, true);
+                if (stopped.status === "incomplete")
+                    return err(this.#retainCleanupFailure(session, "rizin_debug_command", stopped.reason, {
+                        cause: new AnalysisCancelledError("rizin_debug_command", {
+                            cause,
+                            ...(cause instanceof RizinCommandCancelledError
+                                ? { capturedOutput: cause.capturedOutput }
+                                : {}),
+                        }),
+                        ...(partialEvidence === undefined
+                            ? {}
+                            : { partialObservation: partialEvidence }),
+                    }));
+                return err(new AnalysisCancelledError("rizin_debug_command", {
+                    cause,
+                    ...(cause instanceof RizinCommandCancelledError
+                        ? { capturedOutput: cause.capturedOutput }
+                        : {}),
+                    ...(partialEvidence === undefined
+                        ? {}
+                        : { partialObservation: partialEvidence }),
+                }));
+            }
+            if (session.protocolError !== undefined)
+                return err(await this.#stopAfterProtocolFailure(session, cause, true));
+            if (cause instanceof RizinCommandTimeoutError) {
+                session.protocolError =
+                    "Rizin command timed out before its completion marker; output correlation is no longer safe.";
+                const stopped = await this.#stopDebuggerOnly(session, true);
+                const result = {
+                    command,
+                    output: cause.partialOutput,
+                    output_scope: "command_and_interleaved_session_output",
+                    output_truncated: true,
+                    completion_status: "unknown",
+                    backend: session.backend,
+                    ...(cause.outputInvalidUtf8
+                        ? { output_invalid_utf8: true }
+                        : {}),
+                };
+                const evidence = createRizinCommandTimeoutEvidence({
+                    sessionId,
+                    command,
+                    result,
+                    inferiorTty: session.inferiorTty,
+                    cleanupFailure: stopped.status === "incomplete" ? stopped.reason : undefined,
+                    launchProvenance: session.launchProvenance,
+                });
+                if (stopped.status === "incomplete")
+                    return err(this.#retainCleanupFailure(session, "rizin_debug_command", stopped.reason, {
+                        cause,
+                        partialObservation: evidence,
+                    }));
+                return ok({ result, evidence });
+            }
+            if (cause instanceof RizinProcessExitError) {
+                const result = {
+                    command,
+                    output: cause.partialOutput,
+                    output_scope: "command_and_interleaved_session_output",
+                    output_truncated: false,
+                    completion_status: "unknown",
+                    backend: session.backend,
+                    ...(cause.outputInvalidUtf8
+                        ? { output_invalid_utf8: true }
+                        : {}),
+                };
+                const evidence = createRizinCommandEvidence({
+                    sessionId,
+                    command,
+                    result,
+                    inferiorTty: session.inferiorTty,
+                    launchProvenance: session.launchProvenance,
+                    limitations: [
+                        "Rizin exited before the command-completion marker; retained frame output is partial and command completion is unknown.",
+                        "The command is unrestricted and may access local files, the shell, network, or mutate the target.",
+                    ],
+                });
+                const stopped = await this.#stopDebuggerOnly(session, true);
+                if (stopped.status === "incomplete")
+                    return err(this.#retainCleanupFailure(session, "rizin_debug_command", stopped.reason, { cause, partialObservation: evidence }));
+                return ok({ result, evidence });
+            }
+            session.protocolError =
+                "Rizin did not return the current command-completion marker; the session was stopped to prevent late output from being attributed to a later command.";
+            const stopped = await this.#stopDebuggerOnly(session, true);
+            if (stopped.status === "incomplete")
+                return err(this.#retainCleanupFailure(session, "rizin_debug_command", stopped.reason, { cause }));
+            return err(new AnalysisTimeoutError("rizin_debug_command", this.#frameTimeoutMs, {
+                cause,
+            }));
+        }
+        finally {
+            if (acquired) {
+                session.commandCaptureActive = false;
+                session.pendingCommandCount -= 1;
+                release?.();
+            }
+            else
+                void previous.then(() => {
+                    session.pendingCommandCount -= 1;
+                    release?.();
+                });
+        }
+    }
+    status(sessionId) {
+        const session = this.#sessions.get(sessionId);
+        return session === undefined
+            ? undefined
+            : {
+                session_id: session.id,
+                state: session.exited ||
+                    session.protocolError !== undefined ||
+                    session.closing ||
+                    !session.ready
+                    ? "closed"
+                    : "ready",
+                inferior_tty: session.inferiorTty,
+                recent_output: [...session.history],
+                recent_output_truncated: session.historyTruncated,
+                diagnostics_truncated: session.supervisor.snapshot().diagnosticTruncated === true,
+                output_invalid_utf8: session.invalidUtf8Observed,
+            };
+    }
+    async close(sessionId) {
+        if (this.#closingAll)
+            return err(new AnalysisInputError("close_rizin_debug_session"));
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined)
+            return err(new AnalysisInputError("close_rizin_debug_session"));
+        session.closing = true;
+        const stopped = await this.#stopDebuggerOnly(session);
+        if (stopped.status === "incomplete")
+            return err(this.#retainCleanupFailure(session, "close_rizin_debug_session", stopped.reason));
+        this.#sessions.delete(sessionId);
+        return ok({ target_state: "unknown" });
+    }
+    async retryCleanupFailures() {
+        for (const session of this.#sessions.values()) {
+            if (session.cleanupFailures.size === 0)
+                continue;
+            const stopped = await this.#stopDebuggerOnly(session);
+            if (stopped.status === "incomplete")
+                return err([...session.cleanupFailures].at(-1) ??
+                    this.#retainCleanupFailure(session, "close_rizin_debug_session", stopped.reason));
+            this.#sessions.delete(session.id);
+        }
+        return ok(null);
+    }
+    async closeAll() {
+        this.#closingAll = true;
+        if (this.#activeStarts > 0)
+            await new Promise((resolve) => this.#startDrainWaiters.push(resolve));
+        for (const session of this.#sessions.values())
+            session.closing = true;
+        return closeOwnedDebuggerSessions(this.#sessions, (session) => this.#stopDebuggerOnly(session), "Rizin");
+    }
+    #receive(session, chunk) {
+        let offset = 0;
+        while (offset < chunk.length) {
+            const boundary = chunk.indexOf(0, offset);
+            const end = boundary < 0 ? chunk.length : boundary;
+            const nextOffset = boundary + 1;
+            if (boundary >= 0 && nextOffset <= offset) {
+                this.#failProtocol(session, "Rizin frame parser failed to advance past a NUL delimiter.");
+                return;
+            }
+            const piece = chunk.subarray(offset, end);
+            if (session.discardingOversizedFrame) {
+                if (boundary < 0)
+                    return;
+                session.discardingOversizedFrame = false;
+                this.#deliverBufferedFrame(session, true);
+                offset = nextOffset;
+                continue;
+            }
+            if (session.bufferedFrameBytes + piece.length > MAX_FRAME_BYTES) {
+                const message = "Rizin emitted an NUL frame exceeding the 16 MiB protocol limit.";
+                if (!session.commandCaptureActive) {
+                    this.#failProtocol(session, message);
+                    return;
+                }
+                session.protocolError = message;
+                session.historyTruncated = true;
+                const remainingBytes = MAX_FRAME_BYTES - session.bufferedFrameBytes;
+                if (remainingBytes > 0) {
+                    session.frameChunks.push(Buffer.from(piece.subarray(0, remainingBytes)));
+                    session.bufferedFrameBytes += remainingBytes;
+                }
+                if (boundary < 0) {
+                    session.discardingOversizedFrame = true;
+                    return;
+                }
+                this.#deliverBufferedFrame(session, true);
+                offset = nextOffset;
+                continue;
+            }
+            if (piece.length > 0) {
+                session.frameChunks.push(Buffer.from(piece));
+                session.bufferedFrameBytes += piece.length;
+            }
+            if (boundary < 0)
+                return;
+            this.#deliverBufferedFrame(session, false);
+            offset = nextOffset;
+        }
+    }
+    #deliverBufferedFrame(session, truncated) {
+        const frameBytes = Buffer.concat(session.frameChunks, session.bufferedFrameBytes);
+        session.frameChunks = [];
+        session.bufferedFrameBytes = 0;
+        const invalidUtf8 = !isUtf8(frameBytes);
+        session.invalidUtf8Observed ||= invalidUtf8;
+        this.#deliverFrame(session, { text: frameBytes.toString("utf8"), truncated, invalidUtf8 }, frameBytes.length);
+    }
+    #startupCapturedOutput(session) {
+        const output = session.supervisor.snapshot();
+        const partialFrame = session.bufferedFrameBytes === 0
+            ? ""
+            : Buffer.concat(session.frameChunks, session.bufferedFrameBytes).toString("utf8");
+        const protocolOutput = [...session.history, partialFrame]
+            .filter((frame) => frame.length > 0)
+            .join("\n");
+        const protocolBytes = Buffer.from(protocolOutput, "utf8");
+        let stdoutBytes = Math.min(protocolBytes.length, MAX_DIAGNOSTIC_BYTES);
+        while (stdoutBytes > 0 &&
+            stdoutBytes < protocolBytes.length &&
+            (protocolBytes[stdoutBytes] & 0xc0) === 0x80)
+            stdoutBytes -= 1;
+        return {
+            stdout: protocolBytes.subarray(0, stdoutBytes).toString("utf8"),
+            stderr: output.stderr.text,
+            truncated: session.historyTruncated ||
+                protocolBytes.length > stdoutBytes ||
+                output.diagnosticTruncated === true ||
+                output.stdout.observedBytes > output.stdout.bytes ||
+                output.stderr.observedBytes > output.stderr.bytes,
+        };
+    }
+    #deliverFrame(session, frame, frameBytes) {
+        const historyFrame = frameBytes > MAX_RECENT_FRAME_BYTES || frame.truncated
+            ? `${frame.text.slice(0, MAX_RECENT_FRAME_BYTES)}[recent frame truncated]`
+            : frame.text;
+        if (frameBytes > MAX_RECENT_FRAME_BYTES || frame.truncated)
+            session.historyTruncated = true;
+        session.history.push(historyFrame);
+        if (session.history.length > 64) {
+            session.history.splice(0, session.history.length - 64);
+            session.historyTruncated = true;
+        }
+        const waiter = session.frameWaiters.shift();
+        if (waiter !== undefined) {
+            waiter.resolve(frame);
+            return;
+        }
+        const queueChargeBytes = Math.max(frameBytes, MIN_QUEUED_FRAME_CHARGE_BYTES);
+        if (session.frames.length >= MAX_QUEUED_FRAMES ||
+            session.queuedFrameBytes + queueChargeBytes > MAX_QUEUED_FRAME_BYTES) {
+            this.#failProtocol(session, "Rizin produced unsolicited frames exceeding the bounded queue limit.");
+            return;
+        }
+        session.frames.push({ frame, queueChargeBytes });
+        session.queuedFrameBytes += queueChargeBytes;
+    }
+    #failProtocol(session, message) {
+        session.protocolError = message;
+        session.frameChunks = [];
+        session.bufferedFrameBytes = 0;
+        for (const waiter of session.frameWaiters)
+            waiter.reject(new Error(message));
+        session.frameWaiters.length = 0;
+    }
+    #stopDebuggerOnly(session, commandTurnHeld = false) {
+        session.closing = true;
+        if (session.stopAttempt !== undefined)
+            return session.stopAttempt;
+        session.cleanupCommandTurnHeld = commandTurnHeld;
+        session.stopAttempt = Promise.resolve()
+            .then(() => this.#stopProcess(session, "Rizin debugger", {
+            platform: this.#platform,
+        }))
+            .then((stopped) => {
+            if (stopped.status !== "incomplete") {
+                for (const failure of session.cleanupFailures)
+                    failure.resolveCleanup();
+                session.cleanupFailures.clear();
+            }
+            return stopped;
+        })
+            .finally(() => {
+            session.stopAttempt = undefined;
+        });
+        return session.stopAttempt;
+    }
+    async #detachInferior(session) {
+        if (session.exited || session.protocolError !== undefined)
+            throw new Error("Rizin protocol state is ambiguous; inferior detach is unverified.");
+        const previous = session.commandTail;
+        let release;
+        session.commandTail = new Promise((resolve) => (release = resolve));
+        await previous;
+        try {
+            return await this.#detachInferiorUnlocked(session);
+        }
+        finally {
+            release();
+        }
+    }
+    async #detachInferiorUnlocked(session) {
+        if (session.exited || session.protocolError !== undefined)
+            throw new Error("Rizin protocol state is ambiguous; inferior detach is unverified.");
+        {
+            session.inferiorInventoryComplete = false;
+            session.knownInferiorIdentities.clear();
+            const initial = parseRizinPtraceRows(await this.#runInternalCommand(session, "olj"));
+            const inferior = initial;
+            if (inferior.length === 0) {
+                session.knownInferiorIdentities.clear();
+                session.inferiorInventoryComplete = true;
+                return { status: "no-inferior" };
+            }
+            session.knownInferiorIdentities.clear();
+            for (const [, pid] of inferior) {
+                if (session.knownInferiorIdentities.has(pid))
+                    continue;
+                const startTime = await readProcStartTime(pid);
+                session.knownInferiorIdentities.set(pid, {
+                    pid,
+                    startTime,
+                });
+            }
+            session.inferiorInventoryComplete = true;
+            if (inferior.length !== 1)
+                throw new Error("Rizin reported multiple or ambiguous ptrace inferiors.");
+            const [fd, pid] = inferior[0];
+            const processStartTime = await readProcStartTime(pid);
+            await this.#verifyInferiorOutputConfiguration(session, pid);
+            await this.#runInternalCommand(session, `o- ${fd}`);
+            const after = parseRizinPtraceRows(await this.#runInternalCommand(session, "olj"));
+            if (after.some(([activeFd, activePid]) => activeFd === fd || activePid === pid) ||
+                after.length !== 0)
+                throw new Error("Rizin did not confirm that the selected inferior FD was detached.");
+            assertRizinProcessStartTimeStable(processStartTime, await readProcStartTime(pid));
+            await this.#verifyInferiorOutputConfiguration(session, pid);
+            return { status: "detached", outputSink: "durable" };
+        }
+    }
+    async #verifyInferiorOutputConfiguration(session, pid) {
+        const exitKills = (await this.#runInternalCommand(session, "e dbg.exitkills")).trim();
+        if (exitKills !== "false")
+            throw new Error("Rizin dbg.exitkills readback did not confirm false.");
+        for (const descriptor of ["1", "2"]) {
+            const descriptorPath = `/proc/${pid}/fd/${descriptor}`;
+            const destination = await readlink(descriptorPath);
+            const destinationStat = await stat(descriptorPath);
+            if (destinationStat.dev !== session.inferiorTtyDevice ||
+                destinationStat.ino !== session.inferiorTtyInode ||
+                (destinationStat.mode & fsConstants.S_IFMT) !== fsConstants.S_IFCHR ||
+                (await realpath(destination)) !== session.inferiorTty)
+                throw new Error(`Inferior descriptor ${descriptor} is not routed to the selected TTY.`);
+        }
+    }
+    async #runInternalCommand(session, command) {
+        const marker = `__REA_CLEANUP_COMPLETE_${randomUUID().replaceAll("-", "")}__`;
+        const stdin = session.launched.process.stdin;
+        if (stdin === null ||
+            stdin === undefined ||
+            stdin.destroyed ||
+            !stdin.writable)
+            throw new Error("Rizin stdin is unavailable during cleanup.");
+        stdin.write(`${command}\n!echo ${marker}\n`);
+        const captured = await waitForCommandFrames(session, marker, CLEANUP_COMMAND_TIMEOUT_MS, undefined, this.#maxCommandOutputBytes);
+        if (captured.outputTruncated)
+            throw new Error("Rizin cleanup readback was truncated.");
+        return captured.output;
+    }
+    #retainCleanupFailure(session, operation, reason, options = {}) {
+        const failure = new AnalysisCapabilityUnavailableError("rizin", operation, `The owned Rizin process could not be confirmed stopped: ${reason}`, { ...options, cleanup: { reason, resources: [session.id] } });
+        session.cleanupFailures.add(failure);
+        return failure;
+    }
+    async #stopAfterProtocolFailure(session, cause, commandTurnHeld = false) {
+        const stopped = await this.#stopDebuggerOnly(session, commandTurnHeld);
+        return stopped.status === "incomplete"
+            ? this.#retainCleanupFailure(session, "rizin_debug_command", stopped.reason, { cause })
+            : new AnalysisCapabilityUnavailableError("rizin", "rizin_debug_command", session.protocolError, { cause });
+    }
+}
+const parseRizinPtraceRows = (output) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch (cause) {
+        throw new Error("Rizin returned malformed JSON for `olj`.", { cause });
+    }
+    if (!Array.isArray(parsed))
+        throw new Error("Rizin `olj` response is not an array.");
+    const rows = [];
+    for (const row of parsed) {
+        if (typeof row !== "object" ||
+            row === null ||
+            typeof row.fd !== "number" ||
+            !Number.isSafeInteger(row.fd) ||
+            row.fd < 0 ||
+            typeof row.raised !== "boolean" ||
+            typeof row.uri !== "string")
+            throw new Error("Rizin `olj` response contains a malformed descriptor row.");
+        const uri = row.uri;
+        const match = /^ptrace:\/\/(\d+)$/u.exec(uri);
+        if (match !== null) {
+            if (row.raised !== true)
+                throw new Error("Rizin `olj` ptrace descriptor is not active.");
+            rows.push([String(row.fd), match[1]]);
+        }
+        else if (uri.startsWith("ptrace://"))
+            throw new Error("Rizin `olj` returned a malformed ptrace URI.");
+    }
+    return rows;
+};
+/** @internal Pure parser kept separately testable from live `/proc` access. */
+export const parseRizinProcStartTime = (statContents) => {
+    const commandEnd = statContents.lastIndexOf(")");
+    if (commandEnd < 0)
+        throw new Error("Inferior process identity is malformed.");
+    const fieldsAfterCommand = statContents
+        .slice(commandEnd + 1)
+        .trim()
+        .split(/\s+/u);
+    const startTime = fieldsAfterCommand[19];
+    if (startTime === undefined || !/^\d+$/u.test(startTime))
+        throw new Error("Inferior process start time could not be verified.");
+    return startTime;
+};
+/** @internal Reject a PID that changed identity during inferior detach. */
+export const assertRizinProcessStartTimeStable = (before, after) => {
+    if (after !== before)
+        throw new Error("The inferior PID disappeared or was reused during detach verification.");
+};
+const readProcStartTime = async (pid) => parseRizinProcStartTime(await readFile(`/proc/${pid}/stat`, "utf8"));
+const waitForCommandFrames = async (session, marker, timeoutMs, signal, maxCommandOutputBytes = MAX_COMMAND_OUTPUT_BYTES) => {
+    const deadline = Date.now() + timeoutMs;
+    const output = [];
+    let outputInvalidUtf8 = false;
+    const commandTimeoutError = () => createRizinCommandTimeoutError(output, outputInvalidUtf8);
+    let outputBytes = 0;
+    let frameCount = 0;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (isRizinCommandDeadlineExpired(remaining))
+            throw commandTimeoutError();
+        let received;
+        try {
+            received = await waitForFrame(session, remaining, signal, commandTimeoutError);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCancelledError)
+                throw new RizinCommandCancelledError(output.join("\n"), outputInvalidUtf8, cause);
+            if (cause instanceof RizinProcessExitError)
+                throw new RizinProcessExitError(output.join("\n"), outputInvalidUtf8);
+            throw cause;
+        }
+        outputInvalidUtf8 ||= received.invalidUtf8;
+        frameCount += 1;
+        if (frameCount > MAX_COMMAND_FRAMES) {
+            const message = "Rizin emitted more than 4096 frames for one command; the session was stopped because output correlation is ambiguous.";
+            session.protocolError = message;
+            return {
+                output: output.join("\n"),
+                outputTruncated: true,
+                outputInvalidUtf8,
+            };
+        }
+        if (received.truncated) {
+            const separatorBytes = output.length > 0 ? 1 : 0;
+            output.push(truncateUtf8(received.text, maxCommandOutputBytes - outputBytes - separatorBytes));
+            return {
+                output: output.join("\n"),
+                outputTruncated: true,
+                outputInvalidUtf8,
+            };
+        }
+        const frame = received.text;
+        const markerIndex = frame.indexOf(marker);
+        if (markerIndex >= 0) {
+            const beforeMarker = frame.slice(0, markerIndex).trimEnd();
+            if (beforeMarker.length > 0) {
+                const beforeMarkerBytes = Buffer.byteLength(beforeMarker, "utf8");
+                const separatorBytes = output.length > 0 ? 1 : 0;
+                if (outputBytes + separatorBytes + beforeMarkerBytes >
+                    maxCommandOutputBytes) {
+                    const message = "Rizin command output exceeded the 16 MiB command limit.";
+                    session.protocolError = message;
+                    const retained = truncateUtf8(beforeMarker, maxCommandOutputBytes - outputBytes - separatorBytes);
+                    if (retained.length > 0)
+                        output.push(retained);
+                    return {
+                        output: output.join("\n"),
+                        outputTruncated: true,
+                        outputInvalidUtf8,
+                    };
+                }
+                outputBytes += separatorBytes + beforeMarkerBytes;
+                output.push(beforeMarker);
+            }
+            return {
+                output: output.join("\n"),
+                outputTruncated: false,
+                outputInvalidUtf8,
+            };
+        }
+        const frameBytes = Buffer.byteLength(frame, "utf8");
+        const separatorBytes = output.length > 0 ? 1 : 0;
+        if (outputBytes + separatorBytes + frameBytes > maxCommandOutputBytes) {
+            const message = "Rizin command output exceeded the 16 MiB command limit.";
+            session.protocolError = message;
+            output.push(truncateUtf8(frame, maxCommandOutputBytes - outputBytes - separatorBytes));
+            return {
+                output: output.join("\n"),
+                outputTruncated: true,
+                outputInvalidUtf8,
+            };
+        }
+        outputBytes += separatorBytes + frameBytes;
+        output.push(frame);
+    }
+};
+const truncateUtf8 = (value, maximumBytes) => {
+    if (maximumBytes <= 0)
+        return "";
+    const bytes = Buffer.from(value, "utf8").subarray(0, maximumBytes);
+    return bytes.toString("utf8").replace(/\uFFFD$/u, "");
+};
+const waitForFrame = (session, timeoutMs, signal, timeoutError) => {
+    if (signal?.aborted)
+        return Promise.reject(new AnalysisCancelledError("rizin_debug_command"));
+    const queued = session.frames.shift();
+    if (queued !== undefined) {
+        session.queuedFrameBytes -= queued.queueChargeBytes;
+        return Promise.resolve(queued.frame);
+    }
+    if (session.exited)
+        return Promise.reject(new RizinProcessExitError(""));
+    return new Promise((resolve, reject) => {
+        // Settlement removes all three trigger paths before resolving or rejecting.
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            const index = session.frameWaiters.indexOf(waiter);
+            if (index >= 0)
+                session.frameWaiters.splice(index, 1);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new AnalysisCancelledError("rizin_debug_command"));
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(timeoutError?.() ?? new RizinFrameTimeoutError());
+        }, timeoutMs);
+        const waiter = {
+            resolve: (frame) => {
+                cleanup();
+                resolve(frame);
+            },
+            reject: (cause) => {
+                cleanup();
+                reject(cause);
+            },
+        };
+        session.frameWaiters.push(waiter);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
+};
+const waitForTurn = (previous, signal) => {
+    if (signal === undefined)
+        return previous;
+    if (signal.aborted)
+        return Promise.reject(new AnalysisCancelledError("rizin_debug_command"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new AnalysisCancelledError("rizin_debug_command"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        previous.then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        });
+    });
+};