From ff6467ca97b3e5d70b9945bf15f49b90ec67ac77 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 07:33:16 +0800 Subject: [PATCH] feat(debuggers): name why an owned debugger stop is incomplete (#11517) * feat(debuggers): name why an owned debugger stop is incomplete Owned debugger stop results carry a cleanup code; retained Rizin and GDB cleanup failures project it as details.diagnostics.debugger_cleanup, close-all failures carry it, and GDB detach refusals name multiple inferiors, a missing durable output sink, unknown inferior state or a changed inferior TTY. GdbSessionManagerCoverage asserts the codes instead of reason prose. * fix(debuggers): put the cleanup code on every returned failure incompleteStopFacts builds the cleanup observation and debugger_cleanup diagnostic together, so GDB startup, cancellation and timeout failures carry the code; Rizin's composed cleanup failure retains it at its top level; and one-shot debug commands report debugger_cleanup_codes from the close-all failure. --- docs/reverse-engineering-tools.md | 2 + src/domain/debuggerSessionErrors.ts | 51 +++++++++++ src/gdb/GdbSessionManager.ts | 89 ++++++++++++------- src/process/OwnedDebuggerSessionRegistry.ts | 6 +- src/process/ownedDebuggerCleanupError.ts | 59 ++++++++++-- src/process/ownedDebuggerSession.ts | 78 ++++++++++++++-- src/rizin/RizinDebugSessionManager.ts | 21 ++--- .../boundary/cli/gdbStartupCleanupCli.test.ts | 1 + .../cli/reverseEngineeringCommands.test.ts | 14 ++- tests/boundary/mcp/gdbCancellationMcp.test.ts | 1 + .../mcp/rizinStoppedSessionMcp.test.ts | 14 ++- .../process/ownedDebuggerSession.test.ts | 38 +++++++- .../GdbSessionManagerCoverage.test.ts | 64 ++++++++++--- .../GdbSessionReviewRegressions.test.ts | 10 ++- .../RizinDebugSessionCoverage.fixtures.ts | 6 +- .../RizinDebugSessionCoverage.part1.test.ts | 8 +- .../RizinDebugSessionCoverage.part3.test.ts | 40 +++++++-- ...RizinDebugSessionReviewRegressions.test.ts | 1 + .../providers/RizinInferiorTty.test.ts | 6 +- 19 files changed, 416 insertions(+), 93 deletions(-) diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.md index 1082f37e04..10a5be9e8d 100644 --- a/docs/reverse-engineering-tools.md +++ b/docs/reverse-engineering-tools.md @@ -100,6 +100,8 @@ Session status retains up to 64 recent protocol frames. Each history entry keeps A Rizin or GDB session stops accepting commands when REA stops it, for example after an output or frame limit, a command deadline, cancellation or a protocol failure, or when the debugger process exits. REA keeps the stopped session and the first reason it observed until `close_rizin_debug_session` or `close_gdb_session` releases it, including after a retried cleanup succeeds. `rizin_debug_session_status` and `gdb_session_status` then report `state: "closed"` with that reason in `closed_reason` and its code in `closed_reason_code`: `input-stream-failure`, `output-correlation-failure`, `command-deadline`, `command-cancelled`, `server-shutdown`, `close-requested`, `process-exited` or `stopped`. A later `rizin_debug_command` or `gdb_console` on the session fails with `capability_unavailable`; `details.reason` carries the same reason and `details.diagnostics.session_stop` the same code (when that failure also left cleanup incomplete and REA reports `cleanup_incomplete`, the stopping failure and its code are under `details.diagnostics.primary_error`), and the remediation is to close the session and start a new one. A `session_id` that this server never returned, or that close already released, fails with `invalid_request` instead. +When REA cannot confirm that an owned Rizin or GDB process stopped, it keeps the session for cleanup retry and the failure carries `details.diagnostics.debugger_cleanup`: `output-unsettled`, `detach-pending`, `inferior-disposition-unverified`, `inferior-identity-unverified`, `windows-stop-unsafe`, `detach-unsupported`, `detach-timeout`, `detach-unconfirmed`, `inferior-state-unknown`, `multiple-inferiors`, `no-durable-output-sink`, `inferior-tty-changed`, `detach-failed`, `process-did-not-exit` or `stop-failed`. For example, closing a GDB session whose debugger exited before its inferior was detached or confirmed absent reports `inferior-disposition-unverified`, and a GDB session with several live inferiors reports `multiple-inferiors` when REA closes every session. The code is on the returned failure itself, including startup failures, cancellations and composed `cleanup_incomplete` results. When `rea debug-with-gdb` or `rea debug-with-rizin` cannot confirm its final cleanup, `details.diagnostics.debugger_cleanup_codes` lists the codes beside `retained_debugger_pids`. + ### Debugger launch settings GDB and Rizin share these settings in the environment that launches REA: diff --git a/src/domain/debuggerSessionErrors.ts b/src/domain/debuggerSessionErrors.ts index 3fdae6e068..24d8a382e3 100644 --- a/src/domain/debuggerSessionErrors.ts +++ b/src/domain/debuggerSessionErrors.ts @@ -83,6 +83,57 @@ export const stoppedDebuggerSessionError = ( }, ); +/** + * Why REA could not confirm an owned debugger process stopped, so it retains + * the session for cleanup retry: + * - `output-unsettled`: the process leader exited, but inherited output + * streams (or the Windows Job Object) did not settle or could not be checked. + * - `detach-pending`: an inferior detach was still running when the debugger exited. + * - `inferior-disposition-unverified`: the debugger exited before the inferior + * was detached or confirmed absent, and no owner proof shows it ended. + * - `inferior-identity-unverified`: the inferior's process identity could not + * be read after the debugger exited. + * - `windows-stop-unsafe`: stopping the debugger on Windows could also end its inferior. + * - `detach-unsupported`: the provider has no detach capability. + * - `detach-timeout`: detach did not complete within its fixed allowance. + * - `detach-unconfirmed`: the provider confirmed neither no inferior nor a + * detach with a durable output sink. + * - `inferior-state-unknown`: the debugger could not report a complete, + * synchronized inferior list. + * - `multiple-inferiors`: automatic detach supports only one inferior. + * - `no-durable-output-sink`: no durable inferior output sink was verified, so + * detaching the live inferior is refused. + * - `inferior-tty-changed`: the debugger no longer reports the caller-selected inferior TTY. + * - `detach-failed`: the detach request failed or was not confirmed. + * - `process-did-not-exit`: the debugger did not exit after direct termination. + * - `stop-failed`: the stop attempt itself failed. + */ +export const DEBUGGER_CLEANUP_INCOMPLETE_CODES = [ + "output-unsettled", + "detach-pending", + "inferior-disposition-unverified", + "inferior-identity-unverified", + "windows-stop-unsafe", + "detach-unsupported", + "detach-timeout", + "detach-unconfirmed", + "inferior-state-unknown", + "multiple-inferiors", + "no-durable-output-sink", + "inferior-tty-changed", + "detach-failed", + "process-did-not-exit", + "stop-failed", +] as const; +export type DebuggerCleanupIncompleteCode = + (typeof DEBUGGER_CLEANUP_INCOMPLETE_CODES)[number]; + +/** A debugger stop REA could not confirm: its code and explanation. */ +export interface DebuggerCleanupIncomplete { + readonly code: DebuggerCleanupIncompleteCode; + readonly reason: string; +} + export const RIZIN_DEBUG_SESSION_TOOLS = { providerId: "rizin", name: "Rizin", diff --git a/src/gdb/GdbSessionManager.ts b/src/gdb/GdbSessionManager.ts index 96d8c4bd8e..98662775a2 100644 --- a/src/gdb/GdbSessionManager.ts +++ b/src/gdb/GdbSessionManager.ts @@ -70,6 +70,8 @@ import { debuggerResourceConstraintError, fixedDeadlineGuidance, readLinuxProcessStartTime, + OwnedDebuggerDetachFailure, + incompleteStopFacts, stopOwnedDebuggerProcess, type OwnedDebuggerDetachResult, type OwnedInferiorIdentity, @@ -884,17 +886,20 @@ export class GdbSessionManager { const cleanupFailure = this.#sessions.retainCleanupFailure( session, "start_gdb_session", - stopped.reason, + stopped, { cause }, ); const retainCleanup = (failure: T): T => failure.bindCleanupDependencies([cleanupFailure], { cleanupResources: [session.id], }); - const cleanup = { reason: stopped.reason, resources: [session.id] }; + const { cleanup, diagnostics } = incompleteStopFacts(stopped, [ + session.id, + ]); const detailsWithoutCause = { capturedOutput, cleanup, + diagnostics, ...(startupEvidence === undefined ? {} : { partialObservation: startupEvidence }), @@ -930,7 +935,10 @@ export class GdbSessionManager { ? details : { ...details, - diagnostics: { session_stop: session.protocolError.code }, + diagnostics: { + ...diagnostics, + session_stop: session.protocolError.code, + }, }, ), ), @@ -1143,7 +1151,7 @@ export class GdbSessionManager { this.#sessions.retainCleanupFailure( session, "gdb_console", - stopped.reason, + stopped, { cause, partialObservation: evidence, @@ -1344,7 +1352,7 @@ export class GdbSessionManager { this.#sessions.retainCleanupFailure( session, "close_gdb_session", - stopped.reason, + stopped, ), ); this.#sessions.remove(session); @@ -1369,7 +1377,7 @@ export class GdbSessionManager { this.#sessions.retainCleanupFailure( session, "close_gdb_session", - stopped.reason, + stopped, ), ); this.#sessions.remove(session); @@ -1721,15 +1729,15 @@ export class GdbSessionManager { : stop.reason, { cause, - diagnostics: { session_stop: stop.code }, ...(stopped.status === "incomplete" - ? { - cleanup: { - reason: stopped.reason, - resources: [session.id], - }, - } + ? incompleteStopFacts(stopped, [session.id]) : {}), + diagnostics: { + session_stop: stop.code, + ...(stopped.status === "incomplete" + ? incompleteStopFacts(stopped, [session.id]).diagnostics + : {}), + }, ...(partialObservation === undefined ? {} : { partialObservation }), }, ); @@ -1746,14 +1754,18 @@ export class GdbSessionManager { ): Promise { if (session.noInferiorVerified) return { status: "no-inferior" }; if (session.exited) - throw new Error("GDB exited before inferior state could be verified."); + throw new OwnedDebuggerDetachFailure( + "inferior-state-unknown", + "GDB exited before inferior state could be verified.", + ); // A new MI inspection replaces the old snapshot. If this read is // incomplete, malformed, or reports multiple inferiors, no earlier PID // can stand in for the current unknown inventory. session.knownInferiorIdentities.clear(); // Queue reservations have not sent MI requests and do not affect synchronization. if (session.protocolError !== undefined || session.pending.size > 0) - throw new Error( + throw new OwnedDebuggerDetachFailure( + "inferior-state-unknown", "GDB MI state is not synchronized; inferior state is unknown.", ); const groups = await this.#request( @@ -1765,7 +1777,10 @@ export class GdbSessionManager { groups.output_truncated || !parseGdbMiDoneRecord(groups.mi).ok ) - throw new Error("GDB could not confirm its inferior state."); + throw new OwnedDebuggerDetachFailure( + "inferior-state-unknown", + "GDB could not confirm its inferior state.", + ); const inferiorPids = gdbThreadGroupPids(groups.mi); if (inferiorPids?.length === 0) { session.knownInferiorIdentities.clear(); @@ -1774,13 +1789,18 @@ export class GdbSessionManager { } session.noInferiorVerified = false; if (inferiorPids?.length !== 1) - throw new Error( - inferiorPids === undefined - ? "GDB returned an unknown recursive inferior list." - : "GDB reports multiple inferiors; automatic detach cannot be confirmed safely.", - ); + throw inferiorPids === undefined + ? new OwnedDebuggerDetachFailure( + "inferior-state-unknown", + "GDB returned an unknown recursive inferior list.", + ) + : new OwnedDebuggerDetachFailure( + "multiple-inferiors", + "GDB reports multiple inferiors; automatic detach cannot be confirmed safely.", + ); if (!session.inferiorTtyVerified) - throw new Error( + throw new OwnedDebuggerDetachFailure( + "no-durable-output-sink", "GDB cannot detach the live inferior because no durable output sink was verified at session startup.", ); const observedTty = await this.#request(session, "-inferior-tty-show"); @@ -1791,7 +1811,8 @@ export class GdbSessionManager { miStringField(observedTty.mi, "inferior_tty_terminal") !== session.inferiorTty ) - throw new Error( + throw new OwnedDebuggerDetachFailure( + "inferior-tty-changed", "GDB no longer reports the caller-selected inferior TTY; detachment cannot be confirmed safely.", ); await this.#verifyInferiorOutputSink( @@ -1809,7 +1830,10 @@ export class GdbSessionManager { detached.output_truncated || !parseGdbMiDoneRecord(detached.mi).ok ) - throw new Error("GDB did not confirm inferior detachment."); + throw new OwnedDebuggerDetachFailure( + "detach-failed", + "GDB did not confirm inferior detachment.", + ); session.knownInferiorIdentities.clear(); // The sole recursively inventoried inferior is now detached. Retain this // fact for owned shutdown even if the MI transport becomes unavailable. @@ -1960,7 +1984,7 @@ export class GdbSessionManager { pending.reject( new AnalysisTimeoutError(operation, acceptedDeadline.value, { cause: timeout, - cleanup: { reason: stopped.reason, resources: [session.id] }, + ...incompleteStopFacts(stopped, [session.id]), partialObservation: evidence, ...copiedTimeoutGuidance(timeout), }), @@ -1975,10 +1999,10 @@ export class GdbSessionManager { `GDB command output could not be correlated and its owned process could not be confirmed stopped: ${stopped.reason}`, { cause: timeout, - diagnostics: { session_stop: stop.code }, - cleanup: { - reason: stopped.reason, - resources: [session.id], + ...incompleteStopFacts(stopped, [session.id]), + diagnostics: { + session_stop: stop.code, + ...incompleteStopFacts(stopped, [session.id]).diagnostics, }, partialObservation: evidence, }, @@ -2067,15 +2091,12 @@ export class GdbSessionManager { const cleanupFailure = this.#sessions.retainCleanupFailure( session, "gdb_console", - stopped.reason, + stopped, { cause: cancellation }, ); pending.reject( cancelledBy("gdb_console", carriedReason(signal?.reason), { - cleanup: { - reason: stopped.reason, - resources: [session.id], - }, + ...incompleteStopFacts(stopped, [session.id]), partialObservation: evidence, }).bindCleanupDependencies([cleanupFailure], { cleanupResources: [session.id], diff --git a/src/process/OwnedDebuggerSessionRegistry.ts b/src/process/OwnedDebuggerSessionRegistry.ts index 622ae390ec..1fcedf7834 100644 --- a/src/process/OwnedDebuggerSessionRegistry.ts +++ b/src/process/OwnedDebuggerSessionRegistry.ts @@ -3,6 +3,7 @@ import type { AnalysisErrorOptions, } from "../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../domain/result.js"; +import type { DebuggerCleanupIncomplete } from "../domain/debuggerSessionErrors.js"; import { AnalysisCleanupRelease } from "../domain/analysisCleanupRelease.js"; import { AnalysisCancelledError, @@ -188,6 +189,7 @@ export class OwnedDebuggerSessionRegistry< .then(() => this.#options.stopProcess(session)) .catch((cause: unknown): OwnedDebuggerStopResult => ({ status: "incomplete", + code: "stop-failed", reason: `${this.#options.stopFailurePrefix}: ${errorMessage(cause)}`, })) .then((stopped) => { @@ -220,7 +222,7 @@ export class OwnedDebuggerSessionRegistry< retainCleanupFailure( session: Session, operation: string, - reason: string, + stopped: DebuggerCleanupIncomplete, options: AnalysisErrorOptions = {}, ): AnalysisError { return this.retain( @@ -231,7 +233,7 @@ export class OwnedDebuggerSessionRegistry< displayName: this.#options.displayName, }, operation, - reason, + stopped, [session.id], options, ), diff --git a/src/process/ownedDebuggerCleanupError.ts b/src/process/ownedDebuggerCleanupError.ts index 20460a5d76..2857288e68 100644 --- a/src/process/ownedDebuggerCleanupError.ts +++ b/src/process/ownedDebuggerCleanupError.ts @@ -1,3 +1,8 @@ +import type { + DebuggerCleanupIncomplete, + DebuggerCleanupIncompleteCode, +} from "../domain/debuggerSessionErrors.js"; + /** Closing all sessions could not confirm that these debuggers stopped. */ export class OwnedDebuggerCleanupError extends AggregateError { /** Process IDs when cleanup gave up. Observations, not lasting proof of identity. */ @@ -13,31 +18,69 @@ export class OwnedDebuggerCleanupError extends AggregateError { } } -/** Retained debugger process IDs anywhere in a composed cleanup failure. */ -export const retainedDebuggerProcessIds = ( +/** One owned debugger whose stop could not be confirmed, naming why. */ +export class OwnedDebuggerStopFailure extends Error { + readonly code: DebuggerCleanupIncompleteCode; + constructor(stop: DebuggerCleanupIncomplete) { + super(stop.reason); + this.name = "OwnedDebuggerStopFailure"; + this.code = stop.code; + } +} + +/** Visit every error in a composed cleanup failure once. */ +const visitCleanupFailure = ( cause: unknown, -): readonly number[] => { - const found = new Set(); + onError: (error: Error) => void, +): void => { const visited = new WeakSet(); const visit = (node: unknown): void => { if (typeof node !== "object" || node === null || visited.has(node)) return; visited.add(node); - if (node instanceof OwnedDebuggerCleanupError) - for (const pid of node.retainedProcessIds) found.add(pid); + if (node instanceof Error) onError(node); if (node instanceof AggregateError) for (const error of node.errors) visit(error); if (node instanceof Error) visit(node.cause); }; visit(cause); +}; + +/** Retained debugger process IDs anywhere in a composed cleanup failure. */ +export const retainedDebuggerProcessIds = ( + cause: unknown, +): readonly number[] => { + const found = new Set(); + visitCleanupFailure(cause, (error) => { + if (error instanceof OwnedDebuggerCleanupError) + for (const pid of error.retainedProcessIds) found.add(pid); + }); + return [...found]; +}; + +/** Why each unconfirmed debugger stop in a composed cleanup failure is incomplete. */ +export const debuggerCleanupCodes = ( + cause: unknown, +): readonly DebuggerCleanupIncompleteCode[] => { + const found = new Set(); + visitCleanupFailure(cause, (error) => { + if (error instanceof OwnedDebuggerStopFailure) found.add(error.code); + }); return [...found]; }; /** Log or diagnostic fields naming those processes; empty when none are known. */ export const retainedDebuggerDiagnostics = ( cause: unknown, -): { readonly retained_debugger_pids?: number[] } => { +): { + readonly retained_debugger_pids?: number[]; + readonly debugger_cleanup_codes?: DebuggerCleanupIncompleteCode[]; +} => { const pids = retainedDebuggerProcessIds(cause); - return pids.length === 0 ? {} : { retained_debugger_pids: [...pids] }; + const codes = debuggerCleanupCodes(cause); + return { + ...(pids.length === 0 ? {} : { retained_debugger_pids: [...pids] }), + ...(codes.length === 0 ? {} : { debugger_cleanup_codes: [...codes] }), + }; }; /** What a caller must do once REA ends with these debuggers unconfirmed. */ diff --git a/src/process/ownedDebuggerSession.ts b/src/process/ownedDebuggerSession.ts index ebf5a5b301..c459c0b9a8 100644 --- a/src/process/ownedDebuggerSession.ts +++ b/src/process/ownedDebuggerSession.ts @@ -19,14 +19,42 @@ import type { AnalysisErrorOptions, } from "../domain/analysisErrorBase.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { + DebuggerCleanupIncomplete, + DebuggerCleanupIncompleteCode, +} from "../domain/debuggerSessionErrors.js"; import { parseLinuxProcessStat } from "./LinuxProcessStat.js"; -import { OwnedDebuggerCleanupError } from "./ownedDebuggerCleanupError.js"; +import { + OwnedDebuggerCleanupError, + OwnedDebuggerStopFailure, +} from "./ownedDebuggerCleanupError.js"; import { errorMessage } from "../kernel/errorMessage.js"; /** Result of terminating one debugger process owned by this application. */ export type OwnedDebuggerStopResult = | { readonly status: "stopped" | "already_exited" } - | { readonly status: "incomplete"; readonly reason: string }; + | ({ readonly status: "incomplete" } & DebuggerCleanupIncomplete); + +/** + * A provider's refusal or failure to detach its inferior, naming why. Other + * detach errors are reported as `detach-failed`. + */ +export class OwnedDebuggerDetachFailure extends Error { + constructor( + readonly code: Extract< + DebuggerCleanupIncompleteCode, + | "inferior-state-unknown" + | "multiple-inferiors" + | "no-durable-output-sink" + | "inferior-tty-changed" + | "detach-failed" + >, + message: string, + ) { + super(message); + this.name = "OwnedDebuggerDetachFailure"; + } +} const RUNTIME_DEBUGGER_SETTINGS = { [DEBUGGER_COMMAND_DEADLINE_SETTING]: "debugger.command_deadline_ms", @@ -142,14 +170,38 @@ export const debuggerResourceConstraintError = ( * cancellation stays a cancellation with the caller's reason instead of * becoming a capability refusal for the target. */ +/** + * The cleanup observation and diagnostic an incomplete stop adds to any error + * that reports it. The code projects as `details.diagnostics.debugger_cleanup`. + */ +export const incompleteStopFacts = ( + { code, reason }: DebuggerCleanupIncomplete, + resources: readonly string[], +): { + readonly cleanup: { readonly reason: string; readonly resources: string[] }; + readonly diagnostics: { + readonly debugger_cleanup: DebuggerCleanupIncompleteCode; + }; +} => ({ + cleanup: { reason, resources: [...resources] }, + diagnostics: { debugger_cleanup: code }, +}); + export const retainedDebuggerCleanupFailure = ( debugger_: { readonly provider: string; readonly displayName: string }, operation: string, - reason: string, + { code, reason }: DebuggerCleanupIncomplete, resources: readonly string[], - options: AnalysisErrorOptions = {}, + callerOptions: AnalysisErrorOptions = {}, ): AnalysisError => { - const cleanup = { reason, resources: [...resources] }; + const { cleanup, diagnostics } = incompleteStopFacts( + { code, reason }, + resources, + ); + const options: AnalysisErrorOptions = { + ...callerOptions, + diagnostics: { ...callerOptions.diagnostics, ...diagnostics }, + }; const primary = options.cause; if (primary instanceof AnalysisCancelledError) return new AnalysisCancelledError(operation, { @@ -315,6 +367,7 @@ const finishExitedDebuggerSession = async ( if (!(await session.supervisor.waitForOutputClose(1_000))) { return { status: "incomplete", + code: "output-unsettled", reason: platform === "win32" ? `Owned ${debuggerName} process leader exited, but its Windows Job Object still has active descendants or has not reported settlement.` @@ -324,6 +377,7 @@ const finishExitedDebuggerSession = async ( } catch (cause: unknown) { return { status: "incomplete", + code: "output-unsettled", reason: platform === "win32" ? `Owned ${debuggerName} Windows Job Object settlement could not be verified: ${errorMessage(cause)}` @@ -350,6 +404,7 @@ export const stopOwnedDebuggerProcess = async ( if (detachAttempts.has(session)) return { status: "incomplete", + code: "detach-pending", reason: `Owned ${debuggerName} inferior detach is still pending after the process exited.`, }; const detachOutcome = detachOutcomes.get(session); @@ -361,12 +416,14 @@ export const stopOwnedDebuggerProcess = async ( if ((await session.verifyInferiorsEndedAfterExit?.()) !== true) return { status: "incomplete", + code: "inferior-disposition-unverified", reason: `Owned ${debuggerName} inferior disposition was not verified before the debugger exited, and no owner proof confirms the identified inferior processes have ended.`, }; detachOutcomes.set(session, "inferior-ended"); } catch (cause: unknown) { return { status: "incomplete", + code: "inferior-identity-unverified", reason: `Owned ${debuggerName} inferior process identity could not be verified after debugger exit: ${errorMessage(cause)}`, }; } @@ -381,6 +438,7 @@ export const stopOwnedDebuggerProcess = async ( if (platform === "win32") return { status: "incomplete", + code: "windows-stop-unsafe", reason: `Owned ${debuggerName} process cannot be stopped safely on Windows because job termination can also terminate its inferior processes.`, }; // Admission remains closed once cleanup starts. A verified detach is an @@ -393,6 +451,7 @@ export const stopOwnedDebuggerProcess = async ( detachOutcomes.set(session, "unconfirmed"); return { status: "incomplete", + code: "detach-unsupported", reason: `Owned ${debuggerName} inferior detach cannot be verified because the provider has no detach capability.`, }; } @@ -403,12 +462,14 @@ export const stopOwnedDebuggerProcess = async ( if (detached === undefined) return { status: "incomplete", + code: "detach-timeout", reason: `Owned ${debuggerName} inferior detach was not verified within ${String(DETACH_TIMEOUT_MS)} ms. This release has no runtime override.`, }; if (!isVerifiedDetachResult(detached)) { detachOutcomes.set(session, "unconfirmed"); return { status: "incomplete", + code: "detach-unconfirmed", reason: `Owned ${debuggerName} provider did not confirm no inferior or detachment with a durable output sink.`, }; } @@ -416,6 +477,10 @@ export const stopOwnedDebuggerProcess = async ( } catch (cause: unknown) { return { status: "incomplete", + code: + cause instanceof OwnedDebuggerDetachFailure + ? cause.code + : "detach-failed", reason: `Owned ${debuggerName} inferior detach could not be verified: ${errorMessage(cause)}`, }; } @@ -433,6 +498,7 @@ export const stopOwnedDebuggerProcess = async ( ); return { status: "incomplete", + code: "process-did-not-exit", reason: `Owned ${debuggerName} process did not exit after direct termination.`, }; } @@ -487,7 +553,7 @@ export const closeOwnedDebuggerSessions = async < ); retained.push(session); } else if (settled.value.status === "incomplete") { - failures.push(new Error(settled.value.reason)); + failures.push(new OwnedDebuggerStopFailure(settled.value)); retained.push(session); } else if (sessions.get(key) === session) sessions.delete(key); } diff --git a/src/rizin/RizinDebugSessionManager.ts b/src/rizin/RizinDebugSessionManager.ts index c8973c16e4..abe357cba5 100644 --- a/src/rizin/RizinDebugSessionManager.ts +++ b/src/rizin/RizinDebugSessionManager.ts @@ -66,6 +66,7 @@ import { debuggerAdmissionRecovery, debuggerResourceConstraintError, fixedDeadlineGuidance, + incompleteStopFacts, stopOwnedDebuggerProcess, readLinuxProcessStartTime, verifyOwnedInferiorsEnded, @@ -1219,7 +1220,7 @@ export class RizinDebugSessionManager { this.#sessions.retainCleanupFailure( session, "close_rizin_debug_session", - stopped.reason, + stopped, ), ); this.#sessions.remove(session); @@ -1699,7 +1700,7 @@ export class RizinDebugSessionManager { this.#sessions.retainCleanupFailure( session, "rizin_debug_command", - stopped.reason, + stopped, { partialObservation: observation.evidence, ...(stop === undefined @@ -1723,24 +1724,20 @@ export class RizinDebugSessionManager { }); if (stopped.status !== "incomplete") return primary; if (primary instanceof AnalysisCancelledError) - return this.#sessions.retainCleanupFailure( - session, - operation, - stopped.reason, - { - cause: primary, - }, - ); + return this.#sessions.retainCleanupFailure(session, operation, stopped, { + cause: primary, + }); const cleanup = this.#sessions.retainCleanupFailure( session, operation, - stopped.reason, + stopped, ); + // The composed failure names why cleanup is incomplete at its own top level. const composed = analysisErrorWithCleanupDependencies( primary, cleanup, operation, - ); + ).retainDiagnostics(incompleteStopFacts(stopped, [session.id]).diagnostics); return this.#sessions.retain(session, composed); } diff --git a/tests/boundary/cli/gdbStartupCleanupCli.test.ts b/tests/boundary/cli/gdbStartupCleanupCli.test.ts index f4966c0d67..6327be0a23 100644 --- a/tests/boundary/cli/gdbStartupCleanupCli.test.ts +++ b/tests/boundary/cli/gdbStartupCleanupCli.test.ts @@ -279,6 +279,7 @@ it.each(["incomplete", "interrupt", "control"] as const)( if (mode === "incomplete" && !recovering) return { status: "incomplete", + code: "stop-failed", reason: "synthetic stop remains pending", }; child.kill("SIGTERM"); diff --git a/tests/boundary/cli/reverseEngineeringCommands.test.ts b/tests/boundary/cli/reverseEngineeringCommands.test.ts index c5ca9dcbdd..df006c20c0 100644 --- a/tests/boundary/cli/reverseEngineeringCommands.test.ts +++ b/tests/boundary/cli/reverseEngineeringCommands.test.ts @@ -602,6 +602,12 @@ it.each([false, true])( }, ); +/** The one-shot command reports the retained debugger and why its stop is unconfirmed. */ +const retainedRizinCleanup = { + retained_debugger_pids: [4242], + debugger_cleanup_codes: ["stop-failed"], +}; + it.each(["incomplete", "interrupt", "control"] as const)( "reports final Rizin cleanup %s as a typed outcome", async (mode) => { @@ -696,7 +702,11 @@ it.each(["incomplete", "interrupt", "control"] as const)( abortedAtCleanupEnd = signal?.aborted === true; await closeOwnedDebuggerSessions( sessions, - async () => ({ status: "incomplete", reason: "stop unconfirmed" }), + async () => ({ + status: "incomplete", + code: "stop-failed", + reason: "stop unconfirmed", + }), "Rizin", ); }); @@ -733,7 +743,7 @@ it.each(["incomplete", "interrupt", "control"] as const)( details: { cleanup: "incomplete", resources: ["fixture-session"], - diagnostics: { retained_debugger_pids: [4242] }, + diagnostics: retainedRizinCleanup, partial_observation: { operation: "rizin_debug_command", parameters: { session_id: "fixture-session" }, diff --git a/tests/boundary/mcp/gdbCancellationMcp.test.ts b/tests/boundary/mcp/gdbCancellationMcp.test.ts index 849400b493..20e69ff41a 100644 --- a/tests/boundary/mcp/gdbCancellationMcp.test.ts +++ b/tests/boundary/mcp/gdbCancellationMcp.test.ts @@ -77,6 +77,7 @@ process.stdin.on("data", (chunk) => { if (stopCalls === 1) return { status: "incomplete", + code: "stop-failed", reason: "simulated startup stop uncertainty", }; const stopped = await stopOwnedDebuggerProcess(session, name); diff --git a/tests/boundary/mcp/rizinStoppedSessionMcp.test.ts b/tests/boundary/mcp/rizinStoppedSessionMcp.test.ts index 81ea4a813b..26b799362a 100644 --- a/tests/boundary/mcp/rizinStoppedSessionMcp.test.ts +++ b/tests/boundary/mcp/rizinStoppedSessionMcp.test.ts @@ -53,7 +53,11 @@ test.each([ stopProcess: async (session) => { stops += 1; if (cleanupRetry && stops === 1) - return { status: "incomplete", reason: "injected stop pending" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "injected stop pending", + }; if (session.exited) return { status: "already_exited" }; await session.detachInferior?.(); injected.control.exit(); @@ -95,9 +99,11 @@ test.each([ command, }); if (cleanupRetry) - expect(parseMcpToolError(stopping).error.code).toBe( - "cleanup_incomplete", - ); + expect(parseMcpToolError(stopping).error).toMatchObject({ + code: "cleanup_incomplete", + // The returned failure names why cleanup is incomplete at its top level. + details: { diagnostics: { debugger_cleanup: "stop-failed" } }, + }); else expect(stopping.isError).not.toBe(true); // The next call retries retained cleanup first, then refuses the diff --git a/tests/boundary/process/ownedDebuggerSession.test.ts b/tests/boundary/process/ownedDebuggerSession.test.ts index 70d901b081..a3810cc680 100644 --- a/tests/boundary/process/ownedDebuggerSession.test.ts +++ b/tests/boundary/process/ownedDebuggerSession.test.ts @@ -283,6 +283,7 @@ it("retains process supervision after an incomplete stop and disposes after a re }); expect(first).toEqual({ status: "incomplete", + code: "process-did-not-exit", reason: "Owned GDB process did not exit after direct termination.", }); expect(disposals).toBe(0); @@ -327,6 +328,7 @@ it("refuses Windows job-backed debugger termination before signaling", async () stopOwnedDebuggerProcess(session, "GDB", { platform: "win32" }), ).resolves.toEqual({ status: "incomplete", + code: "windows-stop-unsafe", reason: expect.stringMatching( /Windows.*job termination.*inferior processes/i, ), @@ -361,6 +363,7 @@ it("retains an already-exited Windows session while its job has descendants", as expect(result).toEqual({ status: "incomplete", + code: "output-unsettled", reason: expect.stringMatching( /leader exited.*Windows Job Object.*active descendants.*settlement/i, ), @@ -395,6 +398,7 @@ it("retains an exited POSIX session while descendants still hold its output stre expect(result).toEqual({ status: "incomplete", + code: "output-unsettled", reason: expect.stringMatching( /leader exited.*output streams.*open.*settlement/i, ), @@ -453,6 +457,7 @@ it.each([ expect(result).toEqual({ status: "incomplete", + code: "output-unsettled", reason: expectedReason, }); expect(disposals).toBe(0); @@ -480,6 +485,7 @@ it("does not signal an active debugger when its provider cannot detach the infer expect(result).toEqual({ status: "incomplete", + code: "detach-unsupported", reason: expect.stringMatching( /inferior detach.*cannot be verified.*no detach capability/i, ), @@ -509,6 +515,7 @@ it("preserves a non-Error provider detach rejection and does not signal the debu expect(result).toEqual({ status: "incomplete", + code: "detach-failed", reason: expect.stringMatching( /inferior detach.*could not be verified.*detach state unknown/i, ), @@ -540,6 +547,7 @@ it("does not signal a POSIX debugger when provider detach cannot be verified", a expect(result).toEqual({ status: "incomplete", + code: "detach-failed", reason: "Owned GDB inferior detach could not be verified: MI detach failed", }); expect(signals).toEqual([]); @@ -575,6 +583,7 @@ it("retains an exited debugger after provider detach failed", async () => { await stopOwnedDebuggerProcess(session, "GDB", { platform: "linux" }), ).toEqual({ status: "incomplete", + code: "detach-failed", reason: "Owned GDB inferior detach could not be verified: MI detach failed", }); @@ -698,6 +707,7 @@ it("fails closed when detach lacks durable output sink confirmation", async () = expect(result).toEqual({ status: "incomplete", + code: "detach-unconfirmed", reason: expect.stringMatching( /did not confirm no inferior or detachment.*durable output sink/i, ), @@ -749,6 +759,7 @@ it("retains an owned debugger when inferior detach does not settle", async () => await vi.advanceTimersByTimeAsync(1_000); expect(await attempt).toEqual({ status: "incomplete", + code: "detach-timeout", reason: expect.stringMatching( /inferior detach.*not verified.*1000 ms.*no runtime override/i, ), @@ -759,6 +770,7 @@ it("retains an owned debugger when inferior detach does not settle", async () => await vi.advanceTimersByTimeAsync(1_000); expect(await retry).toEqual({ status: "incomplete", + code: "detach-timeout", reason: expect.stringMatching( /inferior detach.*not verified.*1000 ms.*no runtime override/i, ), @@ -1369,12 +1381,21 @@ it("removes stopped sessions and retains incomplete sessions when closing all", sessions, async (session) => session.id === "incomplete" - ? { status: "incomplete", reason: "process remains alive" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "process remains alive", + } : { status: "stopped" }, "GDB", ), ).rejects.toMatchObject({ - errors: [expect.objectContaining({ message: "process remains alive" })], + errors: [ + expect.objectContaining({ + code: "stop-failed", + message: "process remains alive", + }), + ], }); expect([...sessions.keys()]).toEqual(["incomplete"]); }); @@ -1429,7 +1450,11 @@ it("settles every stop and retains rejected sessions while removing successful o if (session.id === "rejected") throw new Error("signal failed"); if (session.id === "string-rejected") throw "string rejection"; if (session.id === "incomplete") - return { status: "incomplete", reason: "still alive" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "still alive", + }; return { status: "stopped" }; }, "GDB", @@ -1468,7 +1493,11 @@ it("stops retained sessions holding the host and names them, leaving stopped pee async (session) => { if (session === stopped) return { status: "stopped" }; if (session === rejected) throw new Error("signal failed"); - return { status: "incomplete", reason: "still alive" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "still alive", + }; }, "Rizin", ).catch((cause: unknown) => cause); @@ -1496,6 +1525,7 @@ it("holds the host again while retrying a retained session and leaves it held on session.supervisor.unref.mockImplementation(() => order.push("unref")); let stopResult: OwnedDebuggerStopResult = { status: "incomplete", + code: "stop-failed", reason: "still alive", }; const stop = async () => { diff --git a/tests/boundary/providers/GdbSessionManagerCoverage.test.ts b/tests/boundary/providers/GdbSessionManagerCoverage.test.ts index 2c90a2ce4a..6e57a0b589 100644 --- a/tests/boundary/providers/GdbSessionManagerCoverage.test.ts +++ b/tests/boundary/providers/GdbSessionManagerCoverage.test.ts @@ -30,7 +30,10 @@ import { import { DEFAULT_DEBUGGER_MAX_COMMAND_OUTPUT_BYTES } from "../../../src/domain/analysisResourceLimits.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { runWithAnalysisOperationSnapshot } from "../../../src/domain/analysisOperationSnapshot.js"; -import { stopOwnedDebuggerProcess } from "../../../src/process/ownedDebuggerSession.js"; +import { + stopOwnedDebuggerProcess, + type OwnedDebuggerStopResult, +} from "../../../src/process/ownedDebuggerSession.js"; import { parseLinuxProcessStat } from "../../../src/process/LinuxProcessStat.js"; import { answerFakeGdbStartup, @@ -528,6 +531,7 @@ it("preserves cancellation and cleanup details when startup stop is uncertain", return stopCalls === 1 ? { status: "incomplete", + code: "stop-failed", reason: "simulated startup cancellation cleanup uncertainty", } : stopOwnedDebuggerProcess(session, name); @@ -575,6 +579,7 @@ it("keeps manager-close cancellation primary when caller abort arrives during st } return { status: "incomplete", + code: "stop-failed", reason: "held fake cleanup remains uncertain", }; }, @@ -773,6 +778,7 @@ it.each(["close", "retryCleanupFailures"] as const)( await stopHeld; return { status: "incomplete", + code: "stop-failed", reason: "simulated cleanup uncertainty", }; } @@ -867,6 +873,7 @@ it.each([ ? { status: "stopped" } : { status: "incomplete", + code: "stop-failed", reason: "Inferior disposition is unresolved.", }; }, @@ -1044,6 +1051,7 @@ it.each(["error", "close"] as const)( expect(failed.ok).toBe(false); if (!failed.ok) { expect(failed.error.diagnostics).toEqual({ + debugger_cleanup: "inferior-state-unknown", session_stop: "input-stream-failure", }); // The stream's own error stays in the diagnosis. @@ -1128,6 +1136,7 @@ it("retains partial GDB command Evidence while an inherited writer remains", asy const manager = managerWithFakeSpawner(fake.spawnProcess, { stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: writerActive ? "an inherited output writer remains active" : "the owned GDB process was not confirmed stopped", @@ -1264,6 +1273,7 @@ it("reports incomplete stop if GDB exits while close waits in the serialized que const manager = managerWithFakeSpawner(fake.spawnProcess, { stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "GDB exited before queued close could verify cleanup", }), }); @@ -1369,6 +1379,7 @@ it("does not infer detached state when the inferior verifier observes an exited } return { status: "incomplete", + code: "stop-failed", reason: "the inferior state remained unknown", }; }, @@ -1415,7 +1426,9 @@ it("retains the GDB session while an unknown descendant holds output after leade expect(firstClose.ok).toBe(false); if (!firstClose.ok) { expect(firstClose.error.cleanupIncomplete).toBe(true); - expect(firstClose.error.message).toMatch(/inferior disposition/i); + expect(firstClose.error.diagnostics).toMatchObject({ + debugger_cleanup: "inferior-disposition-unverified", + }); } expect(manager.status(started.value.session_id)).toBeDefined(); await writeFile(tty, "descendant sentinel after GDB leader exit\n"); @@ -1444,7 +1457,9 @@ it("retries close after an exited GDB's inherited output streams settle", async const firstClose = await manager.close(started.value.session_id); expect(firstClose.ok).toBe(false); if (!firstClose.ok) - expect(firstClose.error.message).toMatch(/inferior disposition/i); + expect(firstClose.error.diagnostics).toMatchObject({ + debugger_cleanup: "inferior-disposition-unverified", + }); expect(manager.status(started.value.session_id)).toBeDefined(); child.closeInheritedOutput(); @@ -1456,7 +1471,7 @@ it("retries close after an exited GDB's inherited output streams settle", async }); it("shares a single stop attempt across concurrent closes after GDB exits", async () => { - let resolveStop!: (result: { status: "incomplete"; reason: string }) => void; + let resolveStop!: (result: OwnedDebuggerStopResult) => void; let stopCalls = 0; const fake = createFakeSpawner(); const manager = managerWithFakeSpawner(fake.spawnProcess, { @@ -1465,6 +1480,7 @@ it("shares a single stop attempt across concurrent closes after GDB exits", asyn if (stopCalls > 1) return { status: "incomplete", + code: "stop-failed", reason: "shared stop attempt is uncertain", }; return await new Promise((resolve) => { @@ -1482,6 +1498,7 @@ it("shares a single stop attempt across concurrent closes after GDB exits", asyn expect(stopCalls).toBe(1); resolveStop({ status: "incomplete", + code: "stop-failed", reason: "shared stop attempt is uncertain", }); @@ -1808,7 +1825,11 @@ it("retains ownership when GDB startup fails before its prompt and stop is incom stopCalls += 1; if (stopCalls === 1) { retainedSessionId = (session as typeof session & { id: string }).id; - return { status: "incomplete", reason: "simulated stop uncertainty" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "simulated stop uncertainty", + }; } return stopOwnedDebuggerProcess(session, name); }, @@ -1858,6 +1879,7 @@ it.each([ return stopCalls === 1 ? { status: "incomplete", + code: "stop-failed", reason: "simulated startup stop uncertainty", } : stopOwnedDebuggerProcess(session, name); @@ -1883,6 +1905,10 @@ it.each([ expect(started.error.cleanup).toMatchObject({ reason: "simulated startup stop uncertainty", }); + // The returned startup failure itself names why cleanup is incomplete. + expect(started.error.diagnostics).toMatchObject({ + debugger_cleanup: "stop-failed", + }); expect(started.error.cleanupIncomplete).toBe(true); const [sessionId] = started.error.cleanupResources; if (sessionId === undefined) @@ -2034,6 +2060,7 @@ it("retains startup timeout without partial evidence when cleanup is uncertain", return stopCalls === 1 ? { status: "incomplete", + code: "stop-failed", reason: "simulated startup timeout cleanup uncertainty", } : stopOwnedDebuggerProcess(session, name); @@ -2072,6 +2099,7 @@ it("maps startup command timeout and preserves initial no-inferior evidence when detachResult = await debuggerSession.detachInferior(); return { status: "incomplete", + code: "stop-failed", reason: "simulated startup cleanup uncertainty", }; }, @@ -2166,6 +2194,7 @@ it("keeps the stop code on a startup stream failure whose cleanup is incomplete" const manager = managerWithFakeSpawner(fake.spawnProcess, { stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "simulated startup stop uncertainty", }), }); @@ -3056,7 +3085,7 @@ it("does not detach a live inferior when no durable TTY was selected", async () await expect(manager.closeAll()).rejects.toMatchObject({ errors: [ expect.objectContaining({ - message: expect.stringMatching(/durable output sink/i), + code: "no-durable-output-sink", }), ], }); @@ -3078,7 +3107,7 @@ it("retains ownership without signaling when recursive MI reports multiple infer await expect(manager.closeAll()).rejects.toMatchObject({ errors: [ expect.objectContaining({ - message: expect.stringMatching(/multiple inferiors/iu), + code: "multiple-inferiors", }), ], }); @@ -3153,7 +3182,7 @@ it("retains ownership and sends no signal when MI state is saturated or unknown" await expect(manager.closeAll()).rejects.toMatchObject({ errors: [ expect.objectContaining({ - message: expect.stringMatching(/inferior detach/i), + code: "inferior-state-unknown", }), ], }); @@ -3197,7 +3226,9 @@ it("retains ownership without signaling when detach confirmation fails", async ( const manager = managerWithFakeSpawner(fake.spawnProcess); const started = await expectGdbSessionStarted(manager); - await expect(manager.closeAll()).rejects.toThrow(/did not stop cleanly/i); + await expect(manager.closeAll()).rejects.toMatchObject({ + errors: [expect.objectContaining({ code: "inferior-state-unknown" })], + }); expect(manager.status(started.value.session_id)?.state).toBe("closed"); expect(fake.children[0]?.killSignals).toEqual([]); @@ -3215,7 +3246,9 @@ it("closes with unknown target state when MI cannot confirm thread groups", asyn const closed = await manager.close(started.value.session_id); expect(closed.ok).toBe(false); if (!closed.ok) { - expect(closed.error.message).toContain("inferior state"); + expect(closed.error.diagnostics).toMatchObject({ + debugger_cleanup: "inferior-state-unknown", + }); expect(closed.error._tag).toBe("AnalysisCapabilityUnavailableError"); } expect(manager.status(started.value.session_id)).toBeDefined(); @@ -3294,7 +3327,11 @@ it("retains a session when closing cannot confirm the debugger process stopped", stopProcess: async (session, name) => { stopCalls += 1; if (stopCalls === 1) - return { status: "incomplete", reason: "simulated close uncertainty" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "simulated close uncertainty", + }; return stopOwnedDebuggerProcess(session, name); }, }); @@ -3319,6 +3356,7 @@ it("retains an exited GDB session when provider stop verification is incomplete" const manager = managerWithFakeSpawner(fake.spawnProcess, { stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "simulated exited debugger cleanup uncertainty", }), }); @@ -3421,6 +3459,7 @@ it("keeps a cancelled startup a cancellation when a cleanup retry reports it aga const manager = managerWithFakeSpawner(fake.spawnProcess, { stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "stop unconfirmed", }), }); @@ -4077,6 +4116,7 @@ it.each(["incomplete", "rejected"] as const)( throw new Error("simulated protocol stop uncertainty"); return { status: "incomplete", + code: "stop-failed", reason: "simulated protocol stop uncertainty", }; } @@ -4111,6 +4151,7 @@ it.each(["incomplete", "rejected"] as const)( expect(failed.ok).toBe(false); if (!failed.ok) { expect(failed.error.diagnostics).toEqual({ + debugger_cleanup: "stop-failed", session_stop: "input-stream-failure", }); expect(failed.error.message).toContain( @@ -4217,6 +4258,7 @@ it("reports command timeout when an incomplete stop cannot confirm process exit" if (stopCalls === 1) return { status: "incomplete", + code: "stop-failed", reason: "simulated timeout stop uncertainty", }; return stopOwnedDebuggerProcess(session, name); diff --git a/tests/boundary/providers/GdbSessionReviewRegressions.test.ts b/tests/boundary/providers/GdbSessionReviewRegressions.test.ts index a317625a40..4327cadb7c 100644 --- a/tests/boundary/providers/GdbSessionReviewRegressions.test.ts +++ b/tests/boundary/providers/GdbSessionReviewRegressions.test.ts @@ -277,7 +277,11 @@ process.stdin.on("data", (chunk) => { environment: { REA_GDB_COMMAND: provider }, stopProcess: async (session) => { retainedSessionId = session.id; - return { status: "incomplete", reason: "startup cleanup is retained" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "startup cleanup is retained", + }; }, }); managers.push(manager); @@ -656,6 +660,7 @@ setTimeout(() => process.exit(0), 250); }, stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "simulated incomplete stop", }), }); @@ -927,6 +932,7 @@ setTimeout(() => process.exit(0), 500); environment: { REA_GDB_COMMAND: provider }, stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "test cleanup", }), }); @@ -1041,6 +1047,7 @@ setInterval(() => {}, 1000); ? stopOwnedDebuggerProcess(session, name, options) : { status: "incomplete", + code: "stop-failed", reason: "fixture-owned process awaits test teardown", }, }); @@ -1225,6 +1232,7 @@ setTimeout(() => process.exit(0), 250); environment: { REA_GDB_COMMAND: provider }, stopProcess: async () => ({ status: "incomplete", + code: "stop-failed", reason: "simulated debugger cleanup failure", }), }); diff --git a/tests/boundary/providers/RizinDebugSessionCoverage.fixtures.ts b/tests/boundary/providers/RizinDebugSessionCoverage.fixtures.ts index a24b38fb6d..ddcf793c45 100644 --- a/tests/boundary/providers/RizinDebugSessionCoverage.fixtures.ts +++ b/tests/boundary/providers/RizinDebugSessionCoverage.fixtures.ts @@ -40,7 +40,11 @@ export const incompleteStop: typeof stopOwnedDebuggerProcess = async ( name, ) => { await stopOwnedDebuggerProcess(session, name); - return { status: "incomplete", reason: "injected stop uncertainty" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "injected stop uncertainty", + }; }; export const abortOnCheck = ( diff --git a/tests/boundary/providers/RizinDebugSessionCoverage.part1.test.ts b/tests/boundary/providers/RizinDebugSessionCoverage.part1.test.ts index 26cd7d41f3..55faf1bfa0 100644 --- a/tests/boundary/providers/RizinDebugSessionCoverage.part1.test.ts +++ b/tests/boundary/providers/RizinDebugSessionCoverage.part1.test.ts @@ -281,6 +281,7 @@ it stopMode === "is uncertain" ? async () => ({ status: "incomplete", + code: "stop-failed", reason: "injected stop uncertainty", }) : async () => ({ status: "stopped" }); @@ -343,7 +344,11 @@ it.skipIf(process.platform === "win32")( const fixture = createRizinCoverageHarness({ stopOwnedProcess: async (supervisor) => failCleanup - ? { status: "incomplete", reason: "injected fixture stop failure" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "injected fixture stop failure", + } : supervisor.stop(), }); const provider = await fixture.makeProvider( @@ -434,6 +439,7 @@ it.skipIf(process.platform === "win32")( session.launched.process.kill("SIGTERM"); return { status: "incomplete", + code: "stop-failed", reason: "first stop result is uncertain", }; } diff --git a/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts b/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts index 196ea9a96a..e81cf65202 100644 --- a/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts +++ b/tests/boundary/providers/RizinDebugSessionCoverage.part3.test.ts @@ -234,7 +234,11 @@ it.skipIf(process.platform === "win32").each([false, true])( { stopProcess: async () => incomplete - ? { status: "incomplete", reason: "injected stop uncertainty" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "injected stop uncertainty", + } : { status: "stopped" }, }, { REA_DEBUGGER_COMMAND_DEADLINE_MS: "1000" }, @@ -381,7 +385,11 @@ it const { manager, started } = await startInjected(injected.spawnProcess, { stopProcess: async () => retained - ? { status: "incomplete", reason: "owned stop pending" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "owned stop pending", + } : { status: "stopped" }, }); if (!started.ok) throw started.error; @@ -434,7 +442,11 @@ it.skipIf(process.platform === "win32").each([false, true])( injected.control.exit(); return { status: "stopped" }; } catch (cause) { - return { status: "incomplete", reason: String(cause) }; + return { + status: "incomplete", + code: "stop-failed", + reason: String(cause), + }; } }, }, @@ -530,7 +542,11 @@ it.skipIf(process.platform === "win32").each([ await debuggerFinalCleanup.hold(); } return incomplete && stopping - ? { status: "incomplete", reason: "stop settlement pending" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "stop settlement pending", + } : { status: "stopped" }; }, }, @@ -601,7 +617,11 @@ it.skipIf(process.platform === "win32")( injected.control.exit(); return { status: "stopped" }; } catch (cause) { - return { status: "incomplete", reason: String(cause) }; + return { + status: "incomplete", + code: "stop-failed", + reason: String(cause), + }; } }, }, @@ -660,7 +680,11 @@ it.skipIf(process.platform === "win32").each([false, true])( stopProcess: async () => { controller.abort(reason); return incomplete && retained - ? { status: "incomplete", reason: "stop settlement pending" } + ? { + status: "incomplete", + code: "stop-failed", + reason: "stop settlement pending", + } : { status: "stopped" }; }, }, @@ -682,6 +706,10 @@ it.skipIf(process.platform === "win32").each([false, true])( expect(primary.secondaryFailures[0]?.cause).toBe(reason); expect(result.error.cleanupIncomplete).toBe(incomplete); if (incomplete) { + // The composed failure names why cleanup is incomplete at its top level. + expect(result.error.diagnostics).toMatchObject({ + debugger_cleanup: "stop-failed", + }); retained = false; await manager.closeAll(); expect(result.error.cleanupIncomplete).toBe(false); diff --git a/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts b/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts index 134016568c..9fdd543edf 100644 --- a/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts +++ b/tests/boundary/providers/RizinDebugSessionReviewRegressions.test.ts @@ -929,6 +929,7 @@ process.stdin.on("data", (chunk) => { } return { status: "incomplete", + code: "stop-failed", reason: "owned output writer is still active", }; }, diff --git a/tests/boundary/providers/RizinInferiorTty.test.ts b/tests/boundary/providers/RizinInferiorTty.test.ts index b1f4dbac42..e031f14ae3 100644 --- a/tests/boundary/providers/RizinInferiorTty.test.ts +++ b/tests/boundary/providers/RizinInferiorTty.test.ts @@ -334,7 +334,11 @@ it.skipIf(process.platform !== "linux")( } catch { // This fixture verifies the manager's fail-closed read path only. } - return { status: "incomplete", reason: "unreachable" }; + return { + status: "incomplete", + code: "stop-failed", + reason: "unreachable", + }; }, }, );