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.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 07:33:16 +08:00
1 parent af0db09605
commit ff6467ca97
19 files changed
+416 -93

No files matched your search

+51 -8
View File
@@ -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<number>();
onError: (error: Error) => void,
): void => {
const visited = new WeakSet<object>();
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<number>();
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<DebuggerCleanupIncompleteCode>();
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. */