Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): preserve lifecycle ownership and failure provenance
morluto9d940c2f284c
diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.tsindex 4f3676c21..6e65230fd 100644--- a/src/ghidra/GhidraClient.ts+++ b/src/ghidra/GhidraClient.ts@@ -56,6 +56,9 @@ import {type GhidraSessionInfo,} from "./GhidraSessionValues.js";import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import { artifactFileCancellationCause } from "../artifacts/ArtifactFileOperation.js";import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";import {@@ -113,6 +116,8 @@ export class GhidraClient {#endpointPath: string | undefined;#snapshotPath: string | undefined;readonly #snapshotOwners = new Set<OwnedFileHandle>();+ readonly #fileResources = new ArtifactResourceScope();+ readonly #cleanupFailures = new Set<AnalysisError>();#targetAdmission: JsonValue | undefined;#token: string | undefined;// Retain authentication identities for diagnostics from late request settlement.@@ -193,10 +198,6 @@ export class GhidraClient {const drained = await this.#drainOutputBounded(requestOptions.signal,);- if (requestOptions.signal?.aborted === true)- return err(- this.#failure("cancelled", "Ghidra request was cancelled"),- );return err(this.#refreshProcessFailure(result.error,@@ -213,7 +214,7 @@ export class GhidraClient {this.#activeOutputCheckpoint = undefined;}},- (kind, message, cause) => this.#failure(kind, message, cause),+ this.#failure,() => this.#stopAfterActiveCancellation(),);}@@ -226,16 +227,12 @@ export class GhidraClient {if (progress !== undefined)return this.#reportStartupWait(this.start(signal), signal, progress);if (signal?.aborted === true)- return Promise.resolve(- err(this.#failure("cancelled", "Ghidra startup wait was cancelled")),- );+ return Promise.resolve(err(this.#startupWaitCancellation(signal)));if (this.#closePromise !== undefined)return waitForAbortable(this.#closePromise, signal).then((closed) =>closed === ABORTED- ? err(- this.#failure("cancelled", "Ghidra startup wait was cancelled"),- )+ ? err(this.#startupWaitCancellation(signal)): this.start(signal),(cause: unknown) =>err(@@ -284,7 +281,7 @@ export class GhidraClient {const waited = await attempt.wait(signal);if (waited.status === "completed") return waited.value;if (waited.status === "stopped" && !waited.value.ok) return waited.value;- return err(this.#failure("cancelled", "Ghidra startup wait was cancelled"));+ return err(this.#startupWaitCancellation(signal));}/** Wait for abandoned startup cleanup before retrying under the new caller. */@@ -293,15 +290,10 @@ export class GhidraClient {signal: AbortSignal | undefined,): Promise<GhidraStartResult> {const signalAborted = (): boolean => signal?.aborted === true;- if (signalAborted())- return err(- this.#failure("cancelled", "Ghidra startup wait was cancelled"),- );+ if (signalAborted()) return err(this.#startupWaitCancellation(signal));const waited = await waitForAbortable(attempt.promise, signal);if (waited === ABORTED || (waited.ok && signalAborted()))- return err(- this.#failure("cancelled", "Ghidra startup wait was cancelled"),- );+ return err(this.#startupWaitCancellation(signal));if (waited.ok || waited.error.cleanupFailure !== undefined) return waited;return this.start(signal);}@@ -497,6 +489,18 @@ export class GhidraClient {}}+ /** This waiter owns its cancellation reason, independently of shared startup. */+ #startupWaitCancellation(+ signal: AbortSignal | undefined,+ ): GhidraSessionError {+ return this.#failure(+ "cancelled",+ "Ghidra startup wait was cancelled",+ signal?.reason,+ signal === undefined ? {} : { cancellation: { reason: signal.reason } },+ );+ }+/** Stop the owned process group and remove all project/runtime artifacts. */async close(): Promise<Result<null, AnalysisError>> {try {@@ -526,10 +530,16 @@ export class GhidraClient {#cleanupError(cause: unknown): AnalysisError {if (cause instanceof AnalysisError && cause.cleanupIncomplete) return cause;- return new ProviderCleanupError(+ const failure = new ProviderCleanupError("ghidra",[...(this.#process === undefined ? [] : ["ghidra-process"]),+ ...(cause instanceof ArtifactReaderFailure+ ? (cause.cleanup?.resources ?? [])+ : []),+ ...(this.#snapshotOwners.size === 0+ ? []+ : [this.#snapshotPath ?? "Ghidra snapshot descriptor"]),...[this.#runtimeRoot, this.#socketRoot].flatMap((root) =>root === undefined ? [] : [root.path],),@@ -540,6 +550,8 @@ export class GhidraClient {},{ cause },);+ this.#cleanupFailures.add(failure);+ return failure;}async #startupFailure(@@ -547,37 +559,28 @@ export class GhidraClient {deadline?: ProviderStartupDeadline,): Promise<GhidraStartResult> {await this.#drainOutputBounded(deadline?.signal);- if (deadline?.interruption === "cancelled")- primary = this.#interruptionFailure(deadline, primary.cause);- primary = this.#failure(primary.kind, primary.message, primary.cause, {- ...(primary.timeoutMs === undefined- ? {}- : { timeoutMs: primary.timeoutMs }),- ...(primary.remoteCode === undefined- ? {}- : { remoteCode: primary.remoteCode }),- });+ const refreshed = this.#failure(+ primary.kind,+ primary.message,+ primary.cause,+ {+ ...(primary.cancellation === undefined+ ? {}+ : { cancellation: primary.cancellation }),+ ...(primary.timeoutMs === undefined+ ? {}+ : { timeoutMs: primary.timeoutMs }),+ ...(primary.remoteCode === undefined+ ? {}+ : { remoteCode: primary.remoteCode }),+ },+ );+ primary = primary.withDiagnostics(refreshed.diagnostics, refreshed.message);try {await this.#cleanup();return err(primary);} catch (cause: unknown) {- return err(- new GhidraSessionError(- primary.kind,- primary.message,- primary.diagnostics,- {- ...(primary.cause === undefined ? {} : { cause: primary.cause }),- ...(primary.timeoutMs === undefined- ? {}- : { timeoutMs: primary.timeoutMs }),- ...(primary.remoteCode === undefined- ? {}- : { remoteCode: primary.remoteCode }),- cleanupFailure: this.#cleanupError(cause),- },- ),- );+ return err(primary.withCleanupFailure(this.#cleanupError(cause)));}}@@ -638,8 +641,7 @@ export class GhidraClient {}async #start(signal: AbortSignal): Promise<GhidraStartResult> {- if (signal.aborted)- return err(this.#failure("cancelled", "Ghidra startup was cancelled"));+ if (signal.aborted) return err(this.#startupWaitCancellation(signal));if (this.#hasOwnedResources())return err(this.#failure("protocol", "Ghidra client is already started"));this.#lastDiagnostics = {};@@ -673,7 +675,8 @@ export class GhidraClient {this.#socket !== undefined ||this.#runtimeRoot !== undefined ||this.#socketRoot !== undefined ||- this.#snapshotOwners.size > 0+ this.#snapshotOwners.size > 0 ||+ this.#fileResources.hasPending);}@@ -715,18 +718,29 @@ export class GhidraClient {this.#options.targetPath,this.#runtimeRoot.path,this.#options.targetSha256,- { signal: deadline.signal, platform: this.#options.platform },+ {+ signal: deadline.signal,+ platform: this.#options.platform,+ resourceScope: this.#fileResources,+ },);this.#snapshotPath = snapshot.path;this.#targetAdmission = snapshot.admission;} catch (cause: unknown) {- if (deadline.signal.aborted) return this.#startupInterrupted(deadline);- const failure = this.#failure(- "start",- "Ghidra target snapshot failed admission",- cause,- );- return this.#startupFailure(failure, deadline);+ const failure =+ cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"+ ? this.#interruptionFailure(+ deadline,+ artifactFileCancellationCause(cause),+ )+ : this.#failure(+ "start",+ "Ghidra target snapshot failed admission",+ cause,+ );+ // Snapshot finalization has settled and no launcher exists yet. Preserve+ // its producer outcome rather than reclassifying from a later deadline.+ return this.#startupFailure(failure);}if (deadline.signal.aborted) return this.#startupInterrupted(deadline);this.#token = randomBytes(32).toString("hex");@@ -838,6 +852,7 @@ export class GhidraClient {const connected = await connectGhidraSocket({endpoint,deadline,+ resourceScope: this.#fileResources,failure: this.#failure,isClosed: () => this.#closing,processExited: () => this.#process?.observedExit() !== undefined,@@ -960,6 +975,7 @@ export class GhidraClient {this.#lastDiagnostics = this.#diagnostics();this.#process = undefined;this.#launch = undefined;+ await this.#fileResources.retryCleanup();for (const owner of this.#snapshotOwners) {await owner.close();this.#snapshotOwners.delete(owner);@@ -976,6 +992,8 @@ export class GhidraClient {this.#runId = undefined;this.#responseBuffer.reset();if (forcedStopFailure !== undefined) throw forcedStopFailure.cause;+ for (const failure of this.#cleanupFailures) failure.resolveCleanup();+ this.#cleanupFailures.clear();} finally {this.#closing = false;}@@ -1008,8 +1026,8 @@ export class GhidraClient {});}}- if (leftovers.length > 0)- throw new ProviderCleanupError(+ if (leftovers.length > 0) {+ const failure = new ProviderCleanupError("ghidra",leftovers.map(({ path }) => path),{@@ -1020,6 +1038,9 @@ export class GhidraClient {},{ cause: firstCause },);+ this.#cleanupFailures.add(failure);+ throw failure;+ }}#redactAuthentication(value: string, incomplete = false): string {@@ -1088,7 +1109,9 @@ export class GhidraClient {cause,);return deadline.interruption === "cancelled"- ? this.#failure("cancelled", "Ghidra startup was cancelled", cause)+ ? this.#failure("cancelled", "Ghidra startup was cancelled", cause, {+ cancellation: { reason: deadline.signal.reason },+ }): this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {timeoutMs: deadline.timeoutMs,});@@ -1156,38 +1179,20 @@ export class GhidraClient {const snapshot = owner.snapshot();const scoped = owner.snapshotOutputSince(checkpoint);const incomplete = drainIncomplete || !scoped.complete;- return new GhidraSessionError(- failure.kind,- failure.message,- {- ...failure.diagnostics,- exit_code: snapshot.exitCode ?? null,- exit_signal: snapshot.signal ?? null,- diagnostic_truncated:- snapshot.diagnosticTruncated === true || incomplete,- output_incomplete:- snapshot.outputIncomplete === true || drainIncomplete,- stdout: ghidraDiagnosticStream(snapshot.stdout, token),- stderr: ghidraDiagnosticStream(snapshot.stderr, token),- failure_output: {- stdout: ghidraDiagnosticStream(scoped.snapshot.stdout, token),- stderr: ghidraDiagnosticStream(scoped.snapshot.stderr, token),- complete: scoped.complete && !drainIncomplete,- },- },- {- ...(failure.cause === undefined ? {} : { cause: failure.cause }),- ...(failure.timeoutMs === undefined- ? {}- : { timeoutMs: failure.timeoutMs }),- ...(failure.remoteCode === undefined- ? {}- : { remoteCode: failure.remoteCode }),- ...(failure.cleanupFailure === undefined- ? {}- : { cleanupFailure: failure.cleanupFailure }),+ return failure.withDiagnostics({+ ...failure.diagnostics,+ exit_code: snapshot.exitCode ?? null,+ exit_signal: snapshot.signal ?? null,+ diagnostic_truncated: snapshot.diagnosticTruncated === true || incomplete,+ output_incomplete: snapshot.outputIncomplete === true || drainIncomplete,+ stdout: ghidraDiagnosticStream(snapshot.stdout, token),+ stderr: ghidraDiagnosticStream(snapshot.stderr, token),+ failure_output: {+ stdout: ghidraDiagnosticStream(scoped.snapshot.stdout, token),+ stderr: ghidraDiagnosticStream(scoped.snapshot.stderr, token),+ complete: scoped.complete && !drainIncomplete,},- );+ });}#drainOutputBounded(signal?: AbortSignal): Promise<boolean> {diff --git a/src/ghidra/GhidraClientStartup.ts b/src/ghidra/GhidraClientStartup.tsindex e90a373fe..80267d1d7 100644--- a/src/ghidra/GhidraClientStartup.ts+++ b/src/ghidra/GhidraClientStartup.ts@@ -4,8 +4,7 @@ import type { ProviderStartupDeadline } from "../process/ProviderDeadline.js";import type { GhidraRequestOptions } from "./GhidraClientTypes.js";import type {GhidraSessionError,- GhidraSessionErrorOptions,- GhidraSessionFailureKind,+ GhidraSessionFailureFactory,} from "./GhidraSessionError.js";import type { GhidraSessionInfo } from "./GhidraSessionValues.js";@@ -20,12 +19,7 @@ export interface GhidraStartupHandshakeOptions {readonly parseSessionInfo: (value: JsonValue,) => Result<GhidraSessionInfo, GhidraSessionError>;- readonly failure: (- kind: GhidraSessionFailureKind,- message: string,- cause?: unknown,- options?: Pick<GhidraSessionErrorOptions, "timeoutMs" | "remoteCode">,- ) => GhidraSessionError;+ readonly failure: GhidraSessionFailureFactory;readonly startupTimeoutMs: number;}@@ -42,9 +36,11 @@ export async function completeGhidraStartupHandshake(},);if (!ping.ok) {- const failure = options.deadline.signal.aborted- ? interruptionFailure(options)- : ping.error;+ const failure =+ ping.error.kind === "cancelled" &&+ options.deadline.interruption !== undefined+ ? interruptionFailure(options)+ : ping.error;return err(failure);}const parsed = options.parseSessionInfo(ping.value);@@ -64,7 +60,12 @@ const interruptionFailure = (options: GhidraStartupHandshakeOptions,): GhidraSessionError =>options.deadline.interruption === "cancelled"- ? options.failure("cancelled", "Ghidra startup was cancelled")+ ? options.failure(+ "cancelled",+ "Ghidra startup was cancelled",+ options.deadline.signal.reason,+ { cancellation: { reason: options.deadline.signal.reason } },+ ): options.failure("timeout", "Ghidra startup deadline elapsed", undefined, {timeoutMs: options.startupTimeoutMs,});diff --git a/src/ghidra/GhidraClientWire.ts b/src/ghidra/GhidraClientWire.tsindex 77d0781a3..86db6f14b 100644--- a/src/ghidra/GhidraClientWire.ts+++ b/src/ghidra/GhidraClientWire.ts@@ -7,8 +7,7 @@ import type { PendingOperations } from "../process/PendingOperations.js";import type { GhidraRequestOptions } from "./GhidraClientTypes.js";import type {GhidraSessionError,- GhidraSessionErrorOptions,- GhidraSessionFailureKind,+ GhidraSessionFailureFactory,} from "./GhidraSessionError.js";/** Dependencies needed to write one authenticated line and await its reply. */@@ -21,12 +20,7 @@ export interface GhidraWireOptions {Result<JsonValue, GhidraSessionError>>;readonly logger: Logger;- readonly failure: (- kind: GhidraSessionFailureKind,- message: string,- cause?: unknown,- options?: Pick<GhidraSessionErrorOptions, "timeoutMs" | "remoteCode">,- ) => GhidraSessionError;+ readonly failure: GhidraSessionFailureFactory;}/** Owns the socket write and pending-reply lifecycle for one bridge session. */@@ -50,9 +44,7 @@ export class GhidraWire {this.#options.failure("process", "Ghidra bridge is unavailable"),);if (options.signal?.aborted === true)- return err(- this.#options.failure("cancelled", "Ghidra request was cancelled"),- );+ return err(this.#cancelled(options.signal));const id = this.#options.nextId();if (options.timeoutMs !== undefined && options.timeoutMs <= 0)return err(@@ -80,8 +72,7 @@ export class GhidraWire {),}),...(options.signal === undefined ? {} : { signal: options.signal }),- cancelledValue: () =>- err(this.#options.failure("cancelled", "Ghidra request was cancelled")),+ cancelledValue: () => err(this.#cancelled(options.signal)),});socket.write(`${JSON.stringify({ id, token, method, params })}\n`,@@ -106,4 +97,12 @@ export class GhidraWire {);return result;}+ #cancelled(signal: AbortSignal | undefined): GhidraSessionError {+ return this.#options.failure(+ "cancelled",+ "Ghidra request was cancelled",+ signal?.reason,+ signal === undefined ? {} : { cancellation: { reason: signal.reason } },+ );+ }}diff --git a/src/ghidra/GhidraJavaLaunch.ts b/src/ghidra/GhidraJavaLaunch.tsindex 94639d015..5bd95303f 100644--- a/src/ghidra/GhidraJavaLaunch.ts+++ b/src/ghidra/GhidraJavaLaunch.ts@@ -2,6 +2,7 @@ import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import { dirname, join } from "node:path";import {execFileOutput,+ ExecFileOutputCancelledError,execFileOutputFailure,type ExecFileOutputFailure,} from "../process/ExecFileOutput.js";@@ -18,19 +19,24 @@ type LaunchSupportOutcome = Omit<export class GhidraLaunchSupportError extends Error {readonly outcome: LaunchSupportOutcome | undefined;+ readonly cancellation: { readonly reason: unknown } | undefined;constructor(phase: LaunchSupportPhase, cause: unknown) {super(`Ghidra LaunchSupport ${phase} failed`, { cause });this.name = "GhidraLaunchSupportError";+ this.cancellation =+ cause instanceof ExecFileOutputCancelledError+ ? { reason: cause.cause }+ : undefined;const outcome = execFileOutputFailure(cause);this.outcome =outcome === undefined? undefined: {...outcome,- killed: outcome.code === "ABORT_ERR" ? null : outcome.killed,+ killed: this.cancellation === undefined ? outcome.killed : null,outputTruncated:- outcome.code === "ABORT_ERR" ? null : outcome.outputTruncated,+ this.cancellation === undefined ? outcome.outputTruncated : null,};}}diff --git a/src/ghidra/GhidraLauncher.ts b/src/ghidra/GhidraLauncher.tsindex 125f40df5..ac093c716 100644--- a/src/ghidra/GhidraLauncher.ts+++ b/src/ghidra/GhidraLauncher.ts@@ -17,6 +17,9 @@ import {WindowsBatchCommandError,} from "../process/WindowsBatchCommand.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";import { err, ok, type Result } from "../domain/result.js";import type { AnalysisCapturedOutput } from "../domain/analysisErrorBase.js";@@ -27,6 +30,7 @@ import {cleanupOwnedProcessGroup,cleanupWindowsProcessTree,type ProcessCleanupResult,+ type ProcessCleanupFailure,} from "../process/ProcessOwnership.js";import {type ProviderProcessLaunch,@@ -88,27 +92,65 @@ export interface GhidraLauncher {): Promise<Result<GhidraLaunch, GhidraLaunchError | AnalysisCancelledError>>;}+/** A rollback attempt failed without releasing its process owner. */+export type GhidraLaunchRollbackFailure =+ | { readonly kind: "incomplete"; readonly result: ProcessCleanupFailure }+ | { readonly kind: "rejected"; readonly cause: unknown };+/** Local launch failure retained as the cause of a provider-neutral error. */export class GhidraLaunchError extends Error {readonly #partialLaunch: GhidraLaunch | undefined;readonly #capturedOutput: AnalysisCapturedOutput | undefined;readonly launchSupport: readonly GhidraLaunchSupportDiagnostic[];+ readonly rollbackFailure: GhidraLaunchRollbackFailure | undefined;+ readonly cleanupFailure: AnalysisError | undefined;constructor(message: string,options?: ErrorOptions & {readonly partialLaunch?: GhidraLaunch;+ readonly rollbackFailure?: GhidraLaunchRollbackFailure;+ readonly cleanupFailure?: AnalysisError;readonly capturedOutput?: AnalysisCapturedOutput;readonly launchSupport?: readonly GhidraLaunchSupportDiagnostic[];},) {- const { partialLaunch, capturedOutput, launchSupport, ...errorOptions } =- options ?? {};+ const {+ partialLaunch,+ capturedOutput,+ launchSupport,+ rollbackFailure,+ cleanupFailure,+ ...errorOptions+ } = options ?? {};super(message, errorOptions);this.name = "GhidraLaunchError";this.#partialLaunch = partialLaunch;- this.#capturedOutput =- capturedOutput === undefined ? undefined : { ...capturedOutput };+ this.rollbackFailure = rollbackFailure;+ const inherited =+ errorOptions.cause instanceof DarwinProcessOwnershipInspectionError ||+ errorOptions.cause instanceof GhidraLaunchError+ ? errorOptions.cause.cleanupFailure+ : errorOptions.cause instanceof AnalysisError &&+ errorOptions.cause.cleanupIncomplete+ ? errorOptions.cause+ : undefined;+ this.cleanupFailure =+ cleanupFailure === undefined+ ? inherited+ : inherited === undefined || inherited === cleanupFailure+ ? cleanupFailure+ : analysisErrorWithCleanupFailure(+ inherited,+ cleanupFailure,+ ).bindCleanupDependencies([inherited, cleanupFailure]);+ const output =+ capturedOutput ??+ (errorOptions.cause instanceof DarwinProcessOwnershipInspectionError ||+ errorOptions.cause instanceof GhidraLaunchError+ ? errorOptions.cause.capturedOutput+ : undefined);+ this.#capturedOutput = output === undefined ? undefined : { ...output };this.launchSupport = (launchSupport ?? []).map((output) => ({ ...output }));}@@ -133,12 +175,20 @@ export class GhidraLaunchError extends Error {const ghidraLaunchCommandOutput = (cause: unknown,): AnalysisCapturedOutput | undefined => {+ if (cause instanceof DarwinProcessOwnershipInspectionError)+ return cause.capturedOutput;const failure = execFileOutputFailure(cause);if (failure === undefined) return undefined;return {stdout: failure.stdout,stderr: failure.stderr,truncated: failure.outputTruncated,+ ...(failure.stdoutBytes === undefined+ ? {}+ : { stdout_bytes: failure.stdoutBytes }),+ ...(failure.stderrBytes === undefined+ ? {}+ : { stderr_bytes: failure.stderrBytes }),exit_code: typeof failure.code === "number" ? failure.code : null,signal: failure.signal,};@@ -410,21 +460,34 @@ export class GhidraHeadlessLauncher implements GhidraLauncher {},);const primary = isAborted(options.signal)- ? new AnalysisCancelledError("open_binary", { cause: launchFailure })+ ? new AnalysisCancelledError("open_binary", {+ cause: launchFailure,+ ...(launchFailure.cleanupFailure === undefined+ ? {}+ : {+ cleanup: {+ reason: launchFailure.cleanupFailure.message,+ resources: launchFailure.cleanupFailure.cleanupResources,+ },+ }),+ }).bindCleanupDependencies(+ launchFailure.cleanupFailure === undefined+ ? []+ : [launchFailure.cleanupFailure],+ ): launchFailure;if (started === undefined) return err(primary);- let cleanupFailure: unknown;- try {- const cleanup = await cleanupStartedProcess(started, platform);- if (!cleanup.cleaned)- cleanupFailure = new Error(- `Ghidra process cleanup was incomplete: ${cleanup.reason}`,- );- } catch (failure: unknown) {- cleanupFailure = failure;- }- if (cleanupFailure !== undefined) {+ const cleanupOwner = started;+ const rollback = await Promise.resolve()+ .then(() => cleanupStartedProcess(cleanupOwner, platform))+ .then(+ (result): Result<null, GhidraLaunchRollbackFailure> =>+ result.cleaned ? ok(null) : err({ kind: "incomplete", result }),+ (cause: unknown): Result<null, GhidraLaunchRollbackFailure> =>+ err({ kind: "rejected", cause }),+ );+ if (!rollback.ok) {const partialLaunch = ownedGhidraLaunch(started,paths,@@ -440,11 +503,20 @@ export class GhidraHeadlessLauncher implements GhidraLauncher {`${primaryMessage}; process cleanup remains incomplete`,{cause: new AggregateError(- [primary, cleanupFailure],+ [+ primary,+ rollback.error.kind === "rejected"+ ? rollback.error.cause+ : rollback.error.result,+ ],"Ghidra launch rollback did not release its process",{ cause: primary },),partialLaunch,+ rollbackFailure: rollback.error,+ ...(launchFailure.cleanupFailure === undefined+ ? {}+ : { cleanupFailure: launchFailure.cleanupFailure }),launchSupport,...(capturedOutput === undefined ? {} : { capturedOutput }),},diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex 327fcd17c..ab7124743 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -1,4 +1,5 @@import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { artifactFilePrimaryFailure } from "../artifacts/ArtifactFileOperation.js";import { fileURLToPath } from "node:url";import { GHIDRA_BRIDGE_SOURCES } from "./GhidraBridgeSources.js";@@ -1059,7 +1060,7 @@ const projectSessionError = (primary,failure.cleanupFailure,operation,- );+ ).bindCleanupDependencies([primary, failure.cleanupFailure]);};const projectPrimarySessionError = (@@ -1069,18 +1070,19 @@ const projectPrimarySessionError = (health?: ProviderOperationHealth,): AnalysisError => {const context = { cause: failure, diagnostics: failure.diagnostics };- if (failure.cause instanceof AnalysisAccessDeniedError)+ const physicalCause = artifactFilePrimaryFailure(failure.cause);+ if (physicalCause instanceof AnalysisAccessDeniedError)return new AnalysisAccessDeniedError(operation,- failure.cause.path,- failure.cause.systemCode,+ physicalCause.path,+ physicalCause.systemCode,context,);- if (failure.cause instanceof AnalysisArtifactChangedError)+ if (physicalCause instanceof AnalysisArtifactChangedError)return new AnalysisArtifactChangedError(operation,- failure.cause.path,- failure.cause.reason,+ physicalCause.path,+ physicalCause.reason,context,);if (@@ -1095,7 +1097,13 @@ const projectPrimarySessionError = (failure.kind === "cancelled" ||(failure.kind === "remote" && failure.remoteCode === "decompile_cancelled"))- return new AnalysisCancelledError(operation, context);+ return new AnalysisCancelledError(operation, {+ ...context,+ cause:+ failure.cancellation === undefined+ ? failure+ : failure.cancellation.reason,+ });if (failure.kind === "analysis_timeout")return new AnalysisTimeoutError(operation,diff --git a/src/ghidra/GhidraRequestQueue.test.ts b/src/ghidra/GhidraRequestQueue.test.tsindex 1be5007e2..a8b470c3c 100644--- a/src/ghidra/GhidraRequestQueue.test.ts+++ b/src/ghidra/GhidraRequestQueue.test.ts@@ -1,9 +1,12 @@-import { describe, expect, it } from "vitest";+import { describe, expect, it, vi } from "vitest";-import { err, ok } from "../domain/result.js";+import { err, ok, type Result } from "../domain/result.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { GhidraRequestQueue } from "./GhidraRequestQueue.js";-import { bindGhidraSessionFailure } from "./GhidraSessionError.js";+import {+ bindGhidraSessionFailure,+ GhidraSessionError,+} from "./GhidraSessionError.js";const failure = bindGhidraSessionFailure(() => ({target_path: "/tmp/queue-fixture",@@ -103,7 +106,11 @@ describe("Ghidra request queue cancellation", () => {const queue = new GhidraRequestQueue(async () => {await completed;- return err(failure("cancelled", "Request cancelled"));+ return err(+ failure("cancelled", "Request cancelled", undefined, {+ cancellation: { reason: null },+ }),+ );},failure,() => Promise.resolve(err(cleanupFailure)),@@ -122,6 +129,7 @@ describe("Ghidra request queue cancellation", () => {});if (result.ok) throw new Error("Expected cancellation");expect(result.error.cleanupFailure).toBe(cleanupFailure);+ expect(result.error.cancellation).toEqual({ reason: null });await expect(queued).resolves.toMatchObject({ok: false,error: { kind: "process" },@@ -143,6 +151,7 @@ describe("Ghidra request queue cancellation", () => {"cancelled","Request cancelled",cancellationCause,+ { cancellation: { reason: cancellationCause } },);let release: (() => void) | undefined;const completed = new Promise<void>((resolve) => {@@ -175,7 +184,11 @@ describe("Ghidra request queue cancellation", () => {});if (result.ok) throw new Error("Expected cancellation");expect(result.error.cause).toBe(cancellationCause);- expect(result.error.cleanupFailure).toBeUndefined();+ expect(result.error.cancellation?.reason).toBe(cancellationCause);+ expect(result.error.cleanupFailure).toMatchObject({+ cleanupIncomplete: true,+ cause,+ });},);@@ -201,3 +214,242 @@ describe("Ghidra request queue cancellation", () => {await expect(active).resolves.toEqual(err(original));});});++const deferred = <Value>() => {+ let resolve!: (value: Value) => void;+ let reject!: (cause: unknown) => void;+ const promise = new Promise<Value>((accept, fail) => {+ resolve = accept;+ reject = fail;+ });+ return { promise, resolve, reject };+};+type ExecutionResult = Result<null, GhidraSessionError>;+type CleanupResult = Result<null, ProviderCleanupError>;+const nextTurn = () => new Promise<void>((resolve) => setImmediate(resolve));++it("joins a completed response with cancellation cleanup before reporting cancellation", async () => {+ const execution = deferred<ExecutionResult>();+ const cleanup = deferred<CleanupResult>();+ const stop = vi.fn(() => cleanup.promise);+ const controller = new AbortController();+ const queue = new GhidraRequestQueue(() => execution.promise, failure, stop);+ let settled = false;+ const pending = queue+ .run("active", {}, { signal: controller.signal })+ .then((result) => {+ settled = true;+ return result;+ });+ execution.resolve(ok(null));+ controller.abort(null);+ await nextTurn();+ expect(settled).toBe(false);+ cleanup.resolve(ok(null));+ const result = await pending;+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "cancelled", cancellation: { reason: null } },+ });+ expect(stop).toHaveBeenCalledTimes(1);+});++it("awaits active cancellation cleanup when execution rejects", async () => {+ const execution = deferred<ExecutionResult>();+ const cleanup = deferred<CleanupResult>();+ const cause = new Error("executor rejected");+ const cleanupFailure = new ProviderCleanupError(+ "ghidra",+ ["owned-runtime"],+ {},+ );+ const controller = new AbortController();+ const queue = new GhidraRequestQueue(+ () => execution.promise,+ failure,+ () => cleanup.promise,+ );+ let settled = false;+ const pending = queue+ .run("active", {}, { signal: controller.signal })+ .then((result) => {+ settled = true;+ return result;+ });+ controller.abort(null);+ execution.reject(cause);+ await nextTurn();+ expect(settled).toBe(false);+ cleanup.resolve(err(cleanupFailure));+ const result = await pending;+ if (result.ok) throw new Error("Expected execution failure");+ expect(result.error).toMatchObject({ kind: "protocol", cause });+ expect(result.error.cleanupFailure).toBe(cleanupFailure);+});++it("normalizes a synchronous executor rejection and drains the next request", async () => {+ const cause = new Error("synchronous execution rejected");+ const queue = new GhidraRequestQueue(+ (method) => {+ if (method === "first") throw cause;+ return Promise.resolve(ok(null));+ },+ failure,+ () => Promise.resolve(ok(null)),+ );+ const result: unknown = await queue+ .run("first", {}, {})+ .catch((failure: unknown) => failure);+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "protocol", cause },+ });+ await expect(queue.run("second", {}, {})).resolves.toEqual(ok(null));+});++it.each([null, "caller stopped", new Error("caller stopped")])(+ "retains the exact queued cancellation reason %j",+ async (reason) => {+ const controller = new AbortController();+ const execution = deferred<ExecutionResult>();+ const queue = new GhidraRequestQueue(+ () => execution.promise,+ failure,+ () => Promise.resolve(ok(null)),+ );+ const active = queue.run("active", {}, {});+ const queued = queue.run("queued", {}, { signal: controller.signal });+ controller.abort(reason);+ const result = await queued;+ execution.resolve(ok(null));+ await active;+ if (result.ok) throw new Error("Expected queued cancellation");+ expect(result.error.cancellation?.reason).toBe(reason);+ },+);++it.each([null, "caller stopped", new Error("caller stopped")])(+ "retains the exact pre-admission cancellation reason %j",+ async (reason) => {+ const controller = new AbortController();+ controller.abort(reason);+ const execute = vi.fn(() => Promise.resolve(ok(null)));+ const queue = new GhidraRequestQueue(execute, failure, () =>+ Promise.resolve(ok(null)),+ );+ const result = await queue.run("active", {}, { signal: controller.signal });+ if (result.ok) throw new Error("Expected pre-admission cancellation");+ expect(result.error.cancellation?.reason).toBe(reason);+ expect(execute).not.toHaveBeenCalled();+ },+);++it.each(["return", "throw"] as const)(+ "captures cleanup rejection before execution can %s",+ async (stage) => {+ const execution = deferred<ExecutionResult>();+ const cleanup = deferred<CleanupResult>();+ const cause = new Error("early cleanup rejection");+ const original = failure("remote", "Observed operation failure");+ const controller = new AbortController();+ const queue = new GhidraRequestQueue(+ () => execution.promise,+ failure,+ () => cleanup.promise,+ );+ let settled = false;+ const pending = queue+ .run("active", {}, { signal: controller.signal })+ .then((result) => {+ settled = true;+ return result;+ });+ controller.abort(null);+ cleanup.reject(cause);+ await nextTurn();+ expect(settled).toBe(false);+ if (stage === "return") execution.resolve(err(original));+ else execution.reject(original);+ const result = await pending;+ if (result.ok) throw new Error("Expected operation and cleanup failure");+ expect(result.error.kind).toBe("remote");+ expect(result.error.cleanupFailure).toMatchObject({+ cleanupIncomplete: true,+ cause,+ });+ },+);++it("retains cleanup uncertainty when the cancellation cleanup callback throws synchronously", async () => {+ const execution = deferred<ExecutionResult>();+ const cause = new Error("synchronous cleanup rejection");+ const controller = new AbortController();+ const queue = new GhidraRequestQueue(+ () => execution.promise,+ failure,+ () => {+ throw cause;+ },+ );+ const pending = queue.run("active", {}, { signal: controller.signal });+ controller.abort(null);+ execution.resolve(ok(null));+ const result = await pending;+ if (result.ok) throw new Error("Expected unconfirmed cancellation cleanup");+ expect(result.error).toMatchObject({+ kind: "cancelled",+ cancellation: { reason: null },+ cleanupFailure: { cleanupIncomplete: true, cause },+ });+});++it.each([+ { order: "execution-first", execution: "returned" },+ { order: "cancellation-first", execution: "returned" },+ { order: "execution-first", execution: "rejected" },+ { order: "cancellation-first", execution: "rejected" },+])(+ "tracks both cleanup owners through $execution execution and $order retry",+ async ({ order, execution }) => {+ const executionCleanup = new ProviderCleanupError(+ "ghidra",+ ["execution-owner"],+ {},+ );+ const cancellationCleanup = new ProviderCleanupError(+ "ghidra",+ ["cancellation-owner"],+ {},+ );+ const primary = new GhidraSessionError(+ "remote",+ "Operation failed",+ {},+ { cleanupFailure: executionCleanup },+ );+ const controller = new AbortController();+ const queue = new GhidraRequestQueue(+ () =>+ execution === "returned"+ ? Promise.resolve(err(primary))+ : Promise.reject(primary),+ failure,+ () => Promise.resolve(err(cancellationCleanup)),+ );+ const pending = queue.run("active", {}, { signal: controller.signal });+ controller.abort(null);+ const result = await pending;+ if (result.ok || result.error.cleanupFailure === undefined)+ throw new Error("Expected both cleanup owners");+ const aggregate = result.error.cleanupFailure;+ expect(aggregate.cleanupIncomplete).toBe(true);+ const owners =+ order === "execution-first"+ ? [executionCleanup, cancellationCleanup]+ : [cancellationCleanup, executionCleanup];+ owners[0]?.resolveCleanup();+ expect(aggregate.cleanupIncomplete).toBe(true);+ owners[1]?.resolveCleanup();+ expect(aggregate.cleanupIncomplete).toBe(false);+ },+);diff --git a/src/ghidra/GhidraRequestQueue.ts b/src/ghidra/GhidraRequestQueue.tsindex 0b03d448a..eca4b6924 100644--- a/src/ghidra/GhidraRequestQueue.ts+++ b/src/ghidra/GhidraRequestQueue.ts@@ -1,10 +1,11 @@+import { ProviderCleanupError } from "../domain/providerCleanupError.js";import type { AnalysisError } from "../domain/analysisErrorBase.js";import type { JsonValue } from "../domain/jsonValue.js";import { err, type Result } from "../domain/result.js";import type { GhidraRequestOptions } from "./GhidraClientTypes.js";import {GhidraSessionError,- type GhidraSessionFailureKind,+ type GhidraSessionFailureFactory,} from "./GhidraSessionError.js";/** Result settled by one queued Ghidra Program request. */@@ -15,13 +16,6 @@ export type GhidraRequestExecutor = (parameters: JsonValue,options: GhidraRequestOptions,) => Promise<GhidraQueuedRequestResult>;-/** Bind queue failures to the owning client's live diagnostics. */-export type GhidraQueueFailureFactory = (- kind: GhidraSessionFailureKind,- message: string,- cause?: unknown,-) => GhidraSessionError;-/** Stop the provider session when an admitted operation is cancelled. */export type GhidraActiveCancellationHandler = () => Promise<Result<null, AnalysisError>@@ -43,7 +37,7 @@ export class GhidraRequestQueue {constructor(private readonly execute: GhidraRequestExecutor,- private readonly failure: GhidraQueueFailureFactory,+ private readonly failure: GhidraSessionFailureFactory,private readonly onActiveCancellation: GhidraActiveCancellationHandler,) {}@@ -56,19 +50,14 @@ export class GhidraRequestQueue {if (this.#closedFailure !== undefined)return Promise.resolve(err(this.#closedFailure));if (options.signal?.aborted === true)- return Promise.resolve(- err(this.failure("cancelled", "Ghidra request was cancelled")),- );+ return Promise.resolve(err(this.#cancelled(options.signal)));return new Promise((resolve) => {let entry: QueuedRequest;const onAbort =options.signal === undefined? undefined: () =>- this.#rejectQueued(- entry,- err(this.failure("cancelled", "Ghidra request was cancelled")),- );+ this.#rejectQueued(entry, err(this.#cancelled(options.signal)));entry = {method,parameters,@@ -103,67 +92,99 @@ export class GhidraRequestQueue {if (entry === undefined) return;this.#release(entry);if (entry.options.signal?.aborted === true) {- entry.resolve(- err(this.failure("cancelled", "Ghidra request was cancelled")),- );+ entry.resolve(err(this.#cancelled(entry.options.signal)));this.#drain();return;}this.#active = true;- let executionSettled = false;- let activeCancellation: Promise<Result<null, AnalysisError>> | undefined;- const onAbort =- entry.options.signal === undefined- ? undefined- : () => {- if (executionSettled) return;- this.failQueued(- this.failure(- "process",- "Ghidra session closed after active request cancellation",- ),- );- activeCancellation = this.onActiveCancellation();- };- if (onAbort !== undefined)- entry.options.signal?.addEventListener("abort", onAbort, { once: true });- void this.execute(entry.method, entry.parameters, entry.options)- .then(async (result) => {- if (activeCancellation !== undefined) {- const primary = result.ok- ? this.failure("cancelled", "Ghidra request was cancelled")- : result.error;- try {- const cleanup = await activeCancellation;- if (!cleanup.ok)- result = err(this.#withCleanupFailure(primary, cleanup.error));- } catch (cause: unknown) {- result = err(this.#withUnexpectedCleanupRejection(primary, cause));- }- }- executionSettled = true;- entry.resolve(result);- })- .catch((cause: unknown) => {- executionSettled = true;- entry.resolve(- err(- this.failure(- "protocol",- "Ghidra serial request execution rejected unexpectedly",- cause,- ),- ),- );- })+ void this.#executeEntry(entry)+ .then(entry.resolve).finally(() => {- if (entry.options.signal !== undefined && onAbort !== undefined)- entry.options.signal.removeEventListener("abort", onAbort);this.#active = false;if (this.#closedFailure === undefined) this.#drain();});}+ async #executeEntry(+ entry: QueuedRequest,+ ): Promise<GhidraQueuedRequestResult> {+ let cancellation:+ | {+ readonly failure: GhidraSessionError;+ readonly cleanup: Promise<+ | {+ readonly kind: "returned";+ readonly value: Result<null, AnalysisError>;+ }+ | { readonly kind: "rejected"; readonly cause: unknown }+ >;+ }+ | undefined;+ const onAbort = (): void => {+ this.failQueued(+ this.failure(+ "process",+ "Ghidra session closed after active request cancellation",+ ),+ );+ cancellation = {+ failure: this.#cancelled(entry.options.signal),+ // Capture rejection immediately, including a synchronous callback throw.+ // Execution and finalization may settle in either order.+ cleanup: Promise.resolve()+ .then(() => this.onActiveCancellation())+ .then(+ (value) => ({ kind: "returned", value }),+ (cause: unknown) => ({ kind: "rejected", cause }),+ ),+ };+ };+ entry.options.signal?.addEventListener("abort", onAbort, { once: true });+ try {+ let result: GhidraQueuedRequestResult;+ try {+ result = await this.execute(+ entry.method,+ entry.parameters,+ entry.options,+ );+ } catch (cause: unknown) {+ result = err(+ cause instanceof GhidraSessionError+ ? cause+ : this.failure(+ "protocol",+ "Ghidra serial request execution rejected unexpectedly",+ cause,+ ),+ );+ }+ if (cancellation === undefined) return result;+ const primary = result.ok ? cancellation.failure : result.error;+ const cleanup = await cancellation.cleanup;+ if (cleanup.kind === "rejected")+ return err(+ this.#withUnexpectedCleanupRejection(primary, cleanup.cause),+ );+ return err(+ cleanup.value.ok+ ? primary+ : primary.withCleanupFailure(cleanup.value.error),+ );+ } finally {+ entry.options.signal?.removeEventListener("abort", onAbort);+ }+ }++ #cancelled(signal: AbortSignal | undefined): GhidraSessionError {+ return this.failure(+ "cancelled",+ "Ghidra request was cancelled",+ signal?.reason,+ signal === undefined ? {} : { cancellation: { reason: signal.reason } },+ );+ }+#rejectQueued(entry: QueuedRequest, result: GhidraQueuedRequestResult): void {const index = this.#queue.indexOf(entry);if (index < 0) return;@@ -172,50 +193,25 @@ export class GhidraRequestQueue {entry.resolve(result);}- #withCleanupFailure(- primary: GhidraSessionError,- cleanupFailure: AnalysisError,- ): GhidraSessionError {- return new GhidraSessionError(- primary.kind,- primary.message,- primary.diagnostics,- {- ...(primary.cause === undefined ? {} : { cause: primary.cause }),- ...(primary.timeoutMs === undefined- ? {}- : { timeoutMs: primary.timeoutMs }),- ...(primary.remoteCode === undefined- ? {}- : { remoteCode: primary.remoteCode }),- cleanupFailure,- },- );- }-#withUnexpectedCleanupRejection(primary: GhidraSessionError,cause: unknown,): GhidraSessionError {const described = this.failure(primary.kind, primary.message, cause);const rejection = described.diagnostics.failure_cause;- return new GhidraSessionError(- primary.kind,- primary.message,+ const cleanupFailure = new ProviderCleanupError(+ "ghidra",+ ["Ghidra cancellation cleanup"],{- ...primary.diagnostics,+ reason: "Cancellation cleanup rejected before release was confirmed",unexpected_cleanup_rejection: rejection ?? { type: typeof cause },},- {- ...(primary.cause === undefined ? {} : { cause: primary.cause }),- ...(primary.timeoutMs === undefined- ? {}- : { timeoutMs: primary.timeoutMs }),- ...(primary.remoteCode === undefined- ? {}- : { remoteCode: primary.remoteCode }),- },+ { cause },);+ return primary.withCleanupFailure(cleanupFailure, {+ ...primary.diagnostics,+ unexpected_cleanup_rejection: rejection ?? { type: typeof cause },+ });}#release(entry: QueuedRequest): void {diff --git a/src/ghidra/GhidraSessionError.test.ts b/src/ghidra/GhidraSessionError.test.tsindex 874ef6a11..bede4f5ed 100644--- a/src/ghidra/GhidraSessionError.test.ts+++ b/src/ghidra/GhidraSessionError.test.ts@@ -1,7 +1,11 @@import { expect, it } from "vitest";import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";-import { bindGhidraSessionFailure } from "./GhidraSessionError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import {+ GhidraSessionError,+ bindGhidraSessionFailure,+} from "./GhidraSessionError.js";import { GhidraLaunchError } from "./GhidraLauncher.js";it("reports truncated cyclic causes in serializable diagnostics", () => {@@ -115,3 +119,105 @@ it("bounds compiler stderr after explicit redaction at UTF-8 boundaries", () =>expect(failureCause.compiler_outcome.stderr).not.toContain(sensitiveValue);expect(failureCause.compiler_outcome.stderr).not.toContain("\uFFFD");});++it.each([null, undefined, new Error("original cause")])(+ "keeps owned facts and cause omission distinct while diagnostics change (%j)",+ (cause) => {+ const cleanup = new ProviderCleanupError("ghidra", ["owned-file"], {});+ const original = new GhidraSessionError(+ "remote",+ "Observed failure",+ { stage: "first" },+ {+ cause,+ timeoutMs: 19,+ remoteCode: "original",+ cancellation: { reason: null },+ cleanupFailure: cleanup,+ },+ );+ const refreshed = original.withDiagnostics(+ { stage: "last" },+ "Refreshed public failure",+ );+ expect(refreshed.message).toBe("Refreshed public failure");+ expect(refreshed.cause).toBe(cause);+ expect(Object.hasOwn(refreshed, "cause")).toBe(true);+ expect(refreshed).toMatchObject({+ kind: "remote",+ timeoutMs: 19,+ remoteCode: "original",+ cancellation: { reason: null },+ diagnostics: { stage: "last" },+ });+ expect(refreshed.cleanupFailure).toBe(cleanup);+ cleanup.resolveCleanup();+ expect(refreshed.cleanupFailure?.cleanupIncomplete).toBe(false);+ expect(+ Object.hasOwn(+ new GhidraSessionError("start", "No cause").withDiagnostics({}),+ "cause",+ ),+ ).toBe(false);+ },+);++it("preserves the compiler root cleanup dependency through launch and session projection", () => {+ const cleanup = new ProviderCleanupError(+ "process-ownership",+ ["/owned/helper-root"],+ { reason: "controlled cleanup failure" },+ );+ const compiler = new DarwinProcessOwnershipInspectionError(+ "compiler failed",+ { cleanupFailure: cleanup },+ );+ const launch = new GhidraLaunchError("launch failed", { cause: compiler });+ const session = bindGhidraSessionFailure(() => ({}))(+ "start",+ launch.message,+ launch,+ );+ expect(session.cleanupFailure).toBe(cleanup);+ cleanup.resolveCleanup();+ expect(session.cleanupFailure?.cleanupIncomplete).toBe(false);+});++it("retains compiler raw output counts through nested launch errors without inferring missing counts", () => {+ const capturedOutput = {+ stdout: "compiler stdout",+ stderr: "�",+ stdout_bytes: 15,+ stderr_bytes: 1,+ truncated: false,+ exit_code: 7,+ signal: null,+ };+ const compiler = new DarwinProcessOwnershipInspectionError(+ "compiler failure",+ { capturedOutput },+ );+ const launch = new GhidraLaunchError("launch failure", { cause: compiler });+ const rollback = new GhidraLaunchError("rollback failure", { cause: launch });+ const project = bindGhidraSessionFailure(() => ({}));+ expect(+ project("start", "startup failure", rollback).diagnostics,+ ).toMatchObject({+ failure_cause: {+ launch_outcome: capturedOutput,+ cause: { launch_outcome: capturedOutput },+ },+ });+ const unknownCounts = new GhidraLaunchError("unknown counts", {+ capturedOutput: {+ stdout: "x".repeat(12000),+ stderr: "�",+ truncated: false,+ },+ });+ const serialized = JSON.stringify(+ project("start", "startup failure", unknownCounts).diagnostics,+ );+ expect(serialized).not.toContain("stdout_bytes");+ expect(serialized).not.toContain("stderr_bytes");+});diff --git a/src/ghidra/GhidraSessionError.ts b/src/ghidra/GhidraSessionError.tsindex 9f4abfb52..4de4807c8 100644--- a/src/ghidra/GhidraSessionError.ts+++ b/src/ghidra/GhidraSessionError.ts@@ -1,4 +1,5 @@-import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";import type { JsonValue } from "../domain/jsonValue.js";import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";import { boundedUtf8Text } from "../process/boundedUtf8Text.js";@@ -26,6 +27,7 @@ export type GhidraSessionFailureKind =/** Additional structured context for a Ghidra session failure. */export interface GhidraSessionErrorOptions extends ErrorOptions {+ readonly cancellation?: { readonly reason: unknown };readonly timeoutMs?: number;readonly remoteCode?: string;readonly cleanupFailure?: AnalysisError;@@ -37,6 +39,7 @@ export class GhidraSessionError extends Error {readonly timeoutMs: number | undefined;readonly remoteCode: string | undefined;readonly cleanupFailure: AnalysisError | undefined;+ readonly cancellation: { readonly reason: unknown } | undefined;constructor(readonly kind: GhidraSessionFailureKind,@@ -50,6 +53,46 @@ export class GhidraSessionError extends Error {this.timeoutMs = options.timeoutMs;this.remoteCode = options.remoteCode;this.cleanupFailure = options.cleanupFailure;+ this.cancellation = options.cancellation;+ }++ /** Refresh diagnostics without discarding owned failure or cleanup facts. */+ withDiagnostics(+ diagnostics: Readonly<Record<string, JsonValue>>,+ message = this.message,+ ): GhidraSessionError {+ return this.#copy(diagnostics, this.cleanupFailure, message);+ }++ /** Join cleanup uncertainty, following both exact owners through later retry. */+ withCleanupFailure(+ cleanup: AnalysisError,+ diagnostics = this.diagnostics,+ ): GhidraSessionError {+ const combined =+ this.cleanupFailure === undefined || this.cleanupFailure === cleanup+ ? cleanup+ : analysisErrorWithCleanupFailure(+ this.cleanupFailure,+ cleanup,+ ).bindCleanupDependencies([this.cleanupFailure, cleanup]);+ return this.#copy(diagnostics, combined);+ }++ #copy(+ diagnostics: Readonly<Record<string, JsonValue>>,+ cleanupFailure: AnalysisError | undefined,+ message = this.message,+ ): GhidraSessionError {+ return new GhidraSessionError(this.kind, message, diagnostics, {+ ...(Object.hasOwn(this, "cause") ? { cause: this.cause } : {}),+ ...(this.cancellation === undefined+ ? {}+ : { cancellation: this.cancellation }),+ ...(this.timeoutMs === undefined ? {} : { timeoutMs: this.timeoutMs }),+ ...(this.remoteCode === undefined ? {} : { remoteCode: this.remoteCode }),+ ...(cleanupFailure === undefined ? {} : { cleanupFailure }),+ });}}@@ -61,6 +104,7 @@ const createGhidraSessionError = (failure: {readonly cause?: unknown;readonly timeoutMs?: number;readonly remoteCode?: string;+ readonly cancellation?: { readonly reason: unknown };readonly redact: (value: string, incomplete?: boolean) => string;}): GhidraSessionError =>new GhidraSessionError(@@ -78,6 +122,9 @@ const createGhidraSessionError = (failure: {}),},{+ ...(failure.cancellation === undefined+ ? {}+ : { cancellation: failure.cancellation }),...(failure.cause === undefined ? {} : { cause: failure.cause }),...(failure.timeoutMs === undefined? {}@@ -98,9 +145,12 @@ export const bindGhidraSessionFailure =kind: GhidraSessionFailureKind,message: string,cause?: unknown,- options: Pick<GhidraSessionErrorOptions, "timeoutMs" | "remoteCode"> = {},- ): GhidraSessionError =>- createGhidraSessionError({+ options: Pick<+ GhidraSessionErrorOptions,+ "timeoutMs" | "remoteCode" | "cancellation"+ > = {},+ ): GhidraSessionError => {+ const failure = createGhidraSessionError({kind,message: redact(message),diagnostics: {@@ -113,6 +163,22 @@ export const bindGhidraSessionFailure =...(cause === undefined ? {} : { cause }),...options,});+ const cleanup =+ cause instanceof DarwinProcessOwnershipInspectionError ||+ cause instanceof GhidraLaunchError+ ? cause.cleanupFailure+ : cause instanceof AnalysisError && cause.cleanupIncomplete+ ? cause+ : undefined;+ return cleanup === undefined+ ? failure+ : failure.withCleanupFailure(cleanup);+ };++/** Canonical factory contract shared by session lifecycle owners. */+export type GhidraSessionFailureFactory = ReturnType<+ typeof bindGhidraSessionFailure+>;const describeCause = (cause: unknown,@@ -157,6 +223,7 @@ const describeErrorCause = (...causeCommandOutcome(cause, redact),...causeCompilerOutcome(cause, redact),...causeLaunchOutcome(cause, redact),+ ...causeLaunchRollback(cause, redact, depth),...nestedErrorCause(cause, redact, depth),};};@@ -257,6 +324,101 @@ const boundedCompilerField = (return { value: bounded.text, truncated: bounded.truncated };};+/** Project the producer's tagged rollback facts independently of the primary cause. */+const causeLaunchRollback = (+ cause: Error,+ redact: (value: string, incomplete?: boolean) => string,+ depth: number,+): Record<string, JsonValue> => {+ if (+ !(cause instanceof GhidraLaunchError) ||+ cause.rollbackFailure === undefined+ )+ return {};+ const rollback = cause.rollbackFailure;+ if (rollback.kind === "rejected")+ return {+ rollback_failure: {+ kind: rollback.kind,+ ...(depth >= MAX_CAUSE_DEPTH+ ? { cause_truncated: true }+ : { cause: describeCause(rollback.cause, redact, depth + 1) }),+ },+ };+ const result = rollback.result;+ const reason = boundedUtf8Text(+ redact(result.reason),+ MAX_CAUSE_MESSAGE_BYTES,+ );+ const diagnostic = (value: string | undefined): Record<string, JsonValue> => {+ if (value === undefined) return {};+ const bounded = boundedUtf8Text(redact(value), MAX_CAUSE_MESSAGE_BYTES);+ return {+ diagnostic: bounded.text,+ ...(bounded.truncated ? { diagnostic_truncated: true } : {}),+ };+ };+ // Share one member-evidence budget, matching a retained launcher-command stream.+ // Keep the complete typed result on GhidraLaunchError for the process owner.+ let remainingBytes = GHIDRA_LAUNCH_COMMAND_OUTPUT_BYTES;+ const members = <Member>(+ values: readonly Member[],+ project: (value: Member) => JsonValue,+ ): { readonly rows: JsonValue[]; readonly omitted: number } => {+ const rows: JsonValue[] = [];+ for (const value of values) {+ const row = project(value);+ const bytes =+ Buffer.byteLength(JSON.stringify(row)) + (rows.length === 0 ? 0 : 1);+ if (bytes > remainingBytes) break;+ remainingBytes -= bytes;+ rows.push(row);+ }+ return { rows, omitted: values.length - rows.length };+ };+ const failures =+ result.failures === undefined+ ? undefined+ : members(result.failures, (failure) => ({+ pid: failure.pid,+ reason: failure.reason,+ ...diagnostic(failure.diagnostic),+ }));+ const unverified =+ result.unverified === undefined+ ? undefined+ : members(result.unverified, (member) => ({+ pid: member.pid,+ ...diagnostic(member.diagnostic),+ }));+ return {+ rollback_failure: {+ kind: rollback.kind,+ result: {+ cleaned: false,+ reason: reason.text,+ ...(reason.truncated ? { reason_truncated: true } : {}),+ ...(failures === undefined+ ? {}+ : {+ failures: failures.rows,+ ...(failures.omitted === 0+ ? {}+ : { failures_omitted: failures.omitted }),+ }),+ ...(unverified === undefined+ ? {}+ : {+ unverified: unverified.rows,+ ...(unverified.omitted === 0+ ? {}+ : { unverified_omitted: unverified.omitted }),+ }),+ },+ },+ };+};+/** Retain a launch failure's launcher command outcome in its cause envelope. */const causeLaunchOutcome = (cause: Error,@@ -292,12 +454,12 @@ const causeLaunchOutcome = (stdout: stdout.text,stderr: stderr.text,truncated,- ...(truncated- ? {- stdout_bytes: Buffer.byteLength(output.stdout),- stderr_bytes: Buffer.byteLength(output.stderr),- }- : {}),+ ...(output.stdout_bytes === undefined+ ? {}+ : { stdout_bytes: output.stdout_bytes }),+ ...(output.stderr_bytes === undefined+ ? {}+ : { stderr_bytes: output.stderr_bytes }),...(output.exit_code === undefined? {}: { exit_code: output.exit_code }),diff --git a/src/ghidra/GhidraSocketConnection.ts b/src/ghidra/GhidraSocketConnection.tsindex ce204d546..6124fd434 100644--- a/src/ghidra/GhidraSocketConnection.ts+++ b/src/ghidra/GhidraSocketConnection.ts@@ -1,11 +1,11 @@+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import { createConnection, type Socket } from "node:net";import { err, ok, type Result } from "../domain/result.js";import type { ProviderStartupDeadline } from "../process/ProviderDeadline.js";import {GhidraSessionError,- type GhidraSessionErrorOptions,- type GhidraSessionFailureKind,+ type GhidraSessionFailureFactory,} from "./GhidraSessionError.js";import {type GhidraConnectTarget,@@ -23,13 +23,9 @@ interface GhidraSocketHandlers {/** Inputs needed to poll and attach one authenticated bridge socket. */export interface GhidraSocketConnectOptions {readonly endpoint: GhidraEndpoint;+ readonly resourceScope: ArtifactResourceScope;readonly deadline: ProviderStartupDeadline;- readonly failure: (- kind: GhidraSessionFailureKind,- message: string,- cause?: unknown,- options?: Pick<GhidraSessionErrorOptions, "timeoutMs" | "remoteCode">,- ) => GhidraSessionError;+ readonly failure: GhidraSessionFailureFactory;readonly isClosed: () => boolean;readonly processExited: () => boolean;readonly startupTimeoutMs: number;@@ -70,8 +66,18 @@ export const connectGhidraSocket = async (return err(options.failure("process", "Ghidra exited before bridge startup"),);- const observed = await observeGhidraEndpoint(options.endpoint);- if (!observed.ok) return observed;+ const observed = await observeGhidraEndpoint(options.endpoint, {+ signal: options.deadline.signal,+ resourceScope: options.resourceScope,+ });+ if (!observed.ok) {+ if (+ observed.error.kind !== "cancelled" ||+ options.deadline.interruption === undefined+ )+ return observed;+ return err(interruptionFailure(options, observed.error));+ }if (observed.value === null) {if ((await options.deadline.wait(50)) === "aborted")return err(interruptionFailure(options));@@ -135,6 +141,7 @@ const connectGhidraSocketOnce = ("cancelled","Ghidra bridge connection was cancelled",{ endpoint: target },+ { cause: signal.reason, cancellation: { reason: signal.reason } },),),);@@ -147,9 +154,17 @@ const connectGhidraSocketOnce = (const interruptionFailure = (options: GhidraSocketConnectOptions,-): GhidraSessionError =>- options.deadline.interruption === "cancelled"- ? options.failure("cancelled", "Ghidra startup was cancelled")- : options.failure("timeout", "Ghidra startup deadline elapsed", undefined, {- timeoutMs: options.startupTimeoutMs,- });+ cause?: GhidraSessionError,+): GhidraSessionError => {+ const failure =+ options.deadline.interruption === "cancelled"+ ? options.failure("cancelled", "Ghidra startup was cancelled", cause, {+ cancellation: { reason: options.deadline.signal.reason },+ })+ : options.failure("timeout", "Ghidra startup deadline elapsed", cause, {+ timeoutMs: options.startupTimeoutMs,+ });+ return cause?.cleanupFailure === undefined+ ? failure+ : failure.withCleanupFailure(cause.cleanupFailure);+};diff --git a/src/ghidra/GhidraTargetSnapshot.ts b/src/ghidra/GhidraTargetSnapshot.tsindex b6447bc75..c6846bfc5 100644--- a/src/ghidra/GhidraTargetSnapshot.ts+++ b/src/ghidra/GhidraTargetSnapshot.ts@@ -1,16 +1,29 @@import { createHash } from "node:crypto";-import { constants } from "node:fs";-import { open, rm, type FileHandle } from "node:fs/promises";+import { open } from "node:fs/promises";import { extname, join } from "node:path";-import { Transform } from "node:stream";-import { pipeline } from "node:stream/promises";+import {+ withArtifactRegularFile,+ withArtifactFileHandle,+ assertArtifactReadActive,+ mapArtifactFileFailure,+} from "../artifacts/ArtifactFileOperation.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";+import {+ NonRegularFileReadError,+ sameRegularFileState,+} from "../filesystem/RegularFile.js";import type { JsonValue } from "../domain/jsonValue.js";import {AnalysisArtifactChangedError,AnalysisAccessDeniedError,} from "../domain/analysisErrorCore.js";-import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import {+ WindowsSnapshotCancelledError,+ windowsPrivateRuntime,+} from "../windows/WindowsPrivateRuntime.js";/** Immutable target copy admitted to one ephemeral Ghidra import. */export interface GhidraTargetSnapshot {@@ -27,6 +40,7 @@ export const createGhidraTargetSnapshot = async (options: {readonly signal?: AbortSignal;readonly platform?: NodeJS.Platform;+ readonly resourceScope?: ArtifactResourceScope;} = {},): Promise<GhidraTargetSnapshot> => {if (!/^[a-f0-9]{64}$/u.test(expectedSha256))@@ -37,11 +51,20 @@ export const createGhidraTargetSnapshot = async (`target-${expectedSha256.slice(0, 12)}${suffix}`,);if ((options.platform ?? process.platform) === "win32") {- const observed = await windowsPrivateRuntime(runtimeRoot).snapshot(- sourcePath,- `target-${expectedSha256.slice(0, 12)}${suffix}`,- options.signal,- );+ const observed = await windowsPrivateRuntime(runtimeRoot)+ .snapshot(+ sourcePath,+ `target-${expectedSha256.slice(0, 12)}${suffix}`,+ options.signal,+ )+ .catch((cause: unknown) => {+ if (cause instanceof WindowsSnapshotCancelledError)+ throw new ArtifactReaderFailure("cancelled", cause.message, {+ cause,+ cancellation: { reason: cause.reason },+ });+ throw cause;+ });if (observed.sha256 !== expectedSha256)throw new AnalysisArtifactChangedError("open_binary",@@ -54,73 +77,94 @@ export const createGhidraTargetSnapshot = async (admission: { source: observed.source, snapshot: observed.snapshot },};}- let source: FileHandle | undefined;- let destination: FileHandle | undefined;+ const resources = options.resourceScope ?? new ArtifactResourceScope();try {- source = await openSnapshotSource(sourcePath);- if (!(await source.stat()).isFile())- throw new AnalysisArtifactChangedError(- "open_binary",+ return await resources.run(() =>+ withArtifactRegularFile(sourcePath,- "The selected Ghidra source is no longer a regular file",- );- destination = await open(snapshotPath, "wx", 0o600);- await destination.chmod(0o600);- const hash = createHash("sha256");- const digest = new Transform({- transform(chunk: unknown, _encoding, done) {- if (!Buffer.isBuffer(chunk)) {- done(new TypeError("Ghidra snapshot stream must contain bytes"));- return;- }- hash.update(chunk);- done(null, chunk);- },- });- await pipeline(- source.createReadStream(),- digest,- destination.createWriteStream(),- options.signal === undefined ? {} : { signal: options.signal },+ resources,+ options.signal,+ async (source) => {+ const initial = await source.stat({ bigint: true });+ assertArtifactReadActive(options.signal);+ return await withArtifactFileHandle(+ snapshotPath,+ await open(snapshotPath, "wx", 0o600),+ resources,+ options.signal,+ async (destination) => {+ await destination.chmod(0o600);+ const hash = createHash("sha256");+ const input = readArtifactFileChunks(source, {+ end: initial.size,+ signal: options.signal,+ });+ for await (const chunk of input) {+ assertArtifactReadActive(options.signal);+ // writeFile completes the entire supplied chunk at the current+ // descriptor offset. Only this owner closes either descriptor.+ await destination.writeFile(chunk);+ hash.update(chunk);+ assertArtifactReadActive(options.signal);+ }+ const coverage = input.readCoverage();+ const observed = hash.digest("hex");+ const after = await source.stat({ bigint: true });+ if (+ coverage.kind !== "complete" ||+ coverage.bytes !== initial.size ||+ !sameRegularFileState(initial, after) ||+ observed !== expectedSha256+ )+ throw new AnalysisArtifactChangedError(+ "open_binary",+ sourcePath,+ `Ghidra target snapshot digest or source identity changed: expected ${expectedSha256}, observed ${observed}`,+ );+ assertArtifactReadActive(options.signal);+ return { path: snapshotPath, sha256: observed };+ },+ );+ },+ "follow",+ ),);- const observedSha256 = hash.digest("hex");- if (observedSha256 !== expectedSha256)- throw new AnalysisArtifactChangedError(- "open_binary",- sourcePath,- `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`,- );- return { path: snapshotPath, sha256: observedSha256 };} catch (cause: unknown) {- if (destination !== undefined)- await rm(snapshotPath, { force: true }).catch((cause: unknown) => {- // best-effort cleanup: snapshot removal must not mask the copy failure.- void cause;- });- throw cause;- } finally {- await Promise.all([source?.close(), destination?.close()]);+ // The private runtime owns partial snapshot entries. Its owner removes the+ // tree after every retained descriptor settles; do not unlink a raw name.+ throw mapArtifactFileFailure(cause, classifySnapshotFailure);}};-const openSnapshotSource = async (path: string): Promise<FileHandle> => {- try {- // A path replaced by a FIFO must not block startup before its type is checked.- return await open(path, constants.O_RDONLY | constants.O_NONBLOCK);- } catch (cause: unknown) {- const code =- cause instanceof Error && "code" in cause ? cause.code : undefined;- if (code === "EACCES" || code === "EPERM")- throw new AnalysisAccessDeniedError("open_binary", path, code, { cause });- if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")- throw new AnalysisArtifactChangedError(- "open_binary",- path,- `The selected Ghidra source could not be opened (${code})`,- { cause },- );- throw cause;- }+const classifySnapshotFailure = (cause: unknown): unknown => {+ if (cause instanceof NonRegularFileReadError)+ return new AnalysisArtifactChangedError(+ "open_binary",+ cause.path,+ "The selected Ghidra source is no longer a regular file",+ { cause },+ );+ if (!(cause instanceof Error) || !("code" in cause)) return cause;+ const path =+ "path" in cause && typeof cause.path === "string"+ ? cause.path+ : "Ghidra snapshot file";+ if (cause.code === "EACCES" || cause.code === "EPERM")+ return new AnalysisAccessDeniedError("open_binary", path, cause.code, {+ cause,+ });+ if (+ cause.code === "ENOENT" ||+ cause.code === "ENOTDIR" ||+ cause.code === "ELOOP"+ )+ return new AnalysisArtifactChangedError(+ "open_binary",+ path,+ `The selected Ghidra file could not be opened (${cause.code})`,+ { cause },+ );+ return cause;};const safeExtension = (path: string): string => {diff --git a/src/ghidra/GhidraTransport.ts b/src/ghidra/GhidraTransport.tsindex 1315a61c6..e59454af5 100644--- a/src/ghidra/GhidraTransport.ts+++ b/src/ghidra/GhidraTransport.ts@@ -1,12 +1,25 @@-import { access, open } from "node:fs/promises";+import { access, lstat } from "node:fs/promises";import { join } from "node:path";+import { z } from "zod";import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";-import { readWindowsPrivateRuntimeFile } from "../windows/WindowsPrivateRuntime.js";-import { err, ok, type Result } from "../domain/result.js";-import { GhidraSessionError } from "./GhidraSessionError.js";-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import {+ assertArtifactReadActive,+ artifactFilePrimaryFailure,+ artifactFileCancellationCause,+ bindArtifactFileCleanup,+ withArtifactRegularFile,+} from "../artifacts/ArtifactFileOperation.js";+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";+import { sameRegularFileState } from "../filesystem/RegularFile.js";+import {+ GhidraSessionError,+ bindGhidraSessionFailure,+} from "./GhidraSessionError.js";/** Local bridge transports used by the current Ghidra session. */export type GhidraTransportKind = "unix-socket" | "authenticated-loopback-tcp";@@ -53,107 +66,144 @@ export type GhidraConnectTarget =| { readonly path: string }| { readonly host: "127.0.0.1"; readonly port: number };-/** Observe a ready endpoint, returning null while its bridge is not listening. */+const tcpEndpointSchema = z.strictObject({+ host: z.literal("127.0.0.1"),+ port: z.number().int().min(1).max(65_535),+});+// ReaGhidraBridge.serveTcp publishes compact Gson JSON followed by one newline.+// Both fields are fixed ASCII, and the bound includes the longest legal port.+const MAX_TCP_ENDPOINT_BYTES = Buffer.byteLength(+ JSON.stringify({ host: "127.0.0.1", port: 65_535 }) + "\n",+);++/** Observe one endpoint under the same file owner as its startup and finalization. */export const observeGhidraEndpoint = async (endpoint: GhidraEndpoint,+ options: {+ readonly signal?: AbortSignal;+ readonly resourceScope?: ArtifactResourceScope;+ } = {},): Promise<Result<GhidraConnectTarget | null, GhidraSessionError>> => {- if (endpoint.transport === "unix-socket") {- try {- await access(endpoint.path);- return ok({ path: endpoint.path });- } catch (cause: unknown) {- return isMissing(cause)- ? ok(null)- : err(- endpointFailure(+ const resources = options.resourceScope ?? new ArtifactResourceScope();+ try {+ const target = await resources.run(async () => {+ assertArtifactReadActive(options.signal);+ if (endpoint.transport === "unix-socket") {+ await access(endpoint.path);+ assertArtifactReadActive(options.signal);+ return { path: endpoint.path };+ }+ if (process.platform === "win32") {+ const encoded = readWindowsPrivateRuntimeFile(endpoint.path);+ assertArtifactReadActive(options.signal);+ return parseTcpEndpoint(endpoint, encoded);+ }+ return withArtifactRegularFile(+ endpoint.path,+ resources,+ options.signal,+ async (file) => {+ const initial = await file.stat({ bigint: true });+ assertArtifactReadActive(options.signal);+ if (initial.size > BigInt(MAX_TCP_ENDPOINT_BYTES))+ throw endpointFailure(endpoint,- "Ghidra socket observation failed",- cause,- ),+ "Ghidra TCP endpoint is invalid",+ new ArtifactReaderFailure(+ "limit",+ `Ghidra endpoint record exceeds its compact publication bound (${initial.size} > ${MAX_TCP_ENDPOINT_BYTES} bytes)`,+ ),+ );+ const input = readArtifactFileChunks(file, {+ end: initial.size,+ signal: options.signal,+ });+ const chunks: Buffer[] = [];+ for await (const chunk of input) chunks.push(Buffer.from(chunk));+ const coverage = input.readCoverage();+ const after = await file.stat({ bigint: true });+ const named = await lstat(endpoint.path, { bigint: true }).catch(+ (cause: unknown) => {+ throw endpointFailure(+ endpoint,+ "Ghidra TCP endpoint changed during observation",+ cause,+ );+ },);- }- }- if (process.platform === "win32") {- try {- return parseTcpEndpoint(- endpoint,- readWindowsPrivateRuntimeFile(endpoint.path),- );- } catch (cause: unknown) {- return isMissing(cause) || isWindowsEndpointWriterBusy(cause)- ? ok(null)- : err(- endpointFailure(+ if (+ coverage.kind !== "complete" ||+ coverage.bytes !== initial.size ||+ !sameRegularFileState(initial, after) ||+ !sameRegularFileState(initial, named)+ )+ throw endpointFailure(endpoint,- "Ghidra endpoint observation failed",- cause,- ),- );- }- }- let handle;- try {- handle = await open(endpoint.path, "r");- } catch (cause: unknown) {- return isMissing(cause)- ? ok(null)- : err(- endpointFailure(+ "Ghidra TCP endpoint changed during observation",+ );+ assertArtifactReadActive(options.signal);+ return parseTcpEndpoint(endpoint,- "Ghidra endpoint observation failed",- cause,- ),- );- }- try {- const encoded = await handle.readFile("utf8");- if (encoded.length === 0)- return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid"));- return parseTcpEndpoint(endpoint, encoded);+ Buffer.concat(chunks).toString("utf8"),+ );+ },+ );+ });+ return ok(target);} catch (cause: unknown) {- return err(endpointFailure(endpoint, "Ghidra endpoint read failed", cause));- } finally {- await handle.close();+ if (+ isMissing(cause) ||+ (process.platform === "win32" && isWindowsEndpointWriterBusy(cause))+ )+ return ok(null);+ return err(observationFailure(endpoint, cause));}};const parseTcpEndpoint = (endpoint: GhidraEndpoint,encoded: string,-): Result<GhidraConnectTarget, GhidraSessionError> => {+): GhidraConnectTarget => {try {- const value: unknown = JSON.parse(encoded);- if (- typeof value !== "object" ||- value === null ||- Array.isArray(value) ||- !hasExactKeys(value, ["host", "port"]) ||- value.host !== "127.0.0.1" ||- !Number.isSafeInteger(value.port) ||- typeof value.port !== "number" ||- value.port < 1 ||- value.port > 65_535- )- return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid"));- return ok({ host: "127.0.0.1", port: value.port });+ return tcpEndpointSchema.parse(JSON.parse(encoded));} catch (cause: unknown) {- return err(- endpointFailure(endpoint, "Ghidra TCP endpoint is invalid", cause),- );+ throw endpointFailure(endpoint, "Ghidra TCP endpoint is invalid", cause);}};-const hasExactKeys = (- value: object,- expected: readonly string[],-): value is Record<string, unknown> => {- const keys = Object.keys(value).sort((left, right) =>- compareUnicodeCodePoints(left, right),- );- return (- keys.length === expected.length &&- keys.every((key, index) => key === expected[index])- );+const observationFailure = (+ endpoint: GhidraEndpoint,+ cause: unknown,+): GhidraSessionError => {+ const primary = artifactFilePrimaryFailure(cause);+ let failure =+ primary instanceof GhidraSessionError+ ? primary+ : cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"+ ? bindGhidraSessionFailure(() => ({+ transport: endpoint.transport,+ endpoint_path: endpoint.path,+ }))("cancelled", "Ghidra endpoint observation was cancelled", cause, {+ cancellation: { reason: artifactFileCancellationCause(cause) },+ })+ : endpointFailure(+ endpoint,+ "Ghidra endpoint observation failed",+ primary,+ );+ if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {+ const cleanup = new ProviderCleanupError(+ "ghidra",+ cause.cleanup.resources,+ {+ reason: "Ghidra endpoint descriptor cleanup remains incomplete",+ },+ { cause },+ );+ bindArtifactFileCleanup(cause, cleanup);+ failure = failure.withCleanupFailure(cleanup);+ }+ return failure;};const endpointFailure = (@@ -161,16 +211,10 @@ const endpointFailure = (message: string,cause?: unknown,): GhidraSessionError =>- new GhidraSessionError(- "start",- message,- {- transport: endpoint.transport,- endpoint_path: endpoint.path,- ...(cause instanceof Error ? { error: cause.message } : {}),- },- cause instanceof Error ? { cause } : undefined,- );+ bindGhidraSessionFailure(() => ({+ transport: endpoint.transport,+ endpoint_path: endpoint.path,+ }))("start", message, cause);const isMissing = (cause: unknown): boolean =>cause instanceof Error && "code" in cause && cause.code === "ENOENT";diff --git a/src/process/DarwinProcessRunTokenReader.ts b/src/process/DarwinProcessRunTokenReader.tsindex 79e9d9c11..d8dce5bb3 100644--- a/src/process/DarwinProcessRunTokenReader.ts+++ b/src/process/DarwinProcessRunTokenReader.ts@@ -9,6 +9,13 @@ import {DEFAULT_SWIFTC_COMPILE_TIMEOUT_MS,providerStartupTimeoutSchema,} from "../config/providerStartupTimeout.js";+import { err, ok, type Result } from "../domain/result.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import type {+ AnalysisCapturedOutput,+ AnalysisError,+} from "../domain/analysisErrorBase.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import { safeParseJson } from "../domain/safeJson.js";import { boundedUtf8Text } from "./boundedUtf8Text.js";import { execFileOutput, execFileOutputFailure } from "./ExecFileOutput.js";@@ -108,15 +115,56 @@ export class DarwinProcessOwnershipInspectionError extends Error {message: string,options?: ErrorOptions & {readonly compilerOutcome?: DarwinCompilerOutcome;+ readonly capturedOutput?: AnalysisCapturedOutput;+ readonly cleanupFailure?: AnalysisError;+ readonly cancellation?: { readonly reason: unknown };},) {- const { compilerOutcome, ...errorOptions } = options ?? {};+ const {+ compilerOutcome,+ capturedOutput,+ cleanupFailure,+ cancellation,+ ...errorOptions+ } = options ?? {};super(message, errorOptions);this.name = "DarwinProcessOwnershipInspectionError";this.compilerOutcome = compilerOutcome;+ this.capturedOutput = capturedOutput;+ this.cleanupFailure = cleanupFailure;+ this.cancellation = cancellation;}readonly compilerOutcome: DarwinCompilerOutcome | undefined;+ readonly capturedOutput: AnalysisCapturedOutput | undefined;+ readonly cleanupFailure: AnalysisError | undefined;+ readonly cancellation: { readonly reason: unknown } | undefined;++ /** Preserve the physical preparation failure while following the exact cleanup owner. */+ withCleanupFailure(+ cleanup: AnalysisError,+ ): DarwinProcessOwnershipInspectionError {+ const combined =+ this.cleanupFailure === undefined || this.cleanupFailure === cleanup+ ? cleanup+ : analysisErrorWithCleanupFailure(+ this.cleanupFailure,+ cleanup,+ ).bindCleanupDependencies([this.cleanupFailure, cleanup]);+ return new DarwinProcessOwnershipInspectionError(this.message, {+ ...(Object.hasOwn(this, "cause") ? { cause: this.cause } : {}),+ ...(this.compilerOutcome === undefined+ ? {}+ : { compilerOutcome: this.compilerOutcome }),+ ...(this.capturedOutput === undefined+ ? {}+ : { capturedOutput: this.capturedOutput }),+ cleanupFailure: combined,+ ...(this.cancellation === undefined+ ? {}+ : { cancellation: this.cancellation }),+ });+ }}/** Explicit, bounded outcome from compiling REA's Darwin ownership helper. */@@ -130,22 +178,28 @@ export interface DarwinCompilerOutcome {readonly code: string | number | null;readonly signal: string | null;readonly stderr: string;- readonly stderrBytes: number;+ readonly stderrBytes?: number;readonly stderrTruncated: boolean;readonly outputTruncated: boolean;readonly killed: boolean;readonly timeoutMs?: number;}-const MAX_COMPILER_STDERR_BYTES = 8 * 1024;+const MAX_COMPILER_OUTPUT_BYTES = 8 * 1024;-const compilerOutcome = (+const compilerFailureFacts = (cause: unknown,timeoutMs: number,-): DarwinCompilerOutcome | undefined => {+):+ | {+ readonly outcome: DarwinCompilerOutcome;+ readonly capturedOutput: AnalysisCapturedOutput;+ }+ | undefined => {const failure = execFileOutputFailure(cause);if (failure === undefined) return undefined;- const stderr = boundedUtf8Text(failure.stderr, MAX_COMPILER_STDERR_BYTES);+ const stderr = boundedUtf8Text(failure.stderr, MAX_COMPILER_OUTPUT_BYTES);+ const stdout = boundedUtf8Text(failure.stdout, MAX_COMPILER_OUTPUT_BYTES);const outcome =failure.code === "ETIMEDOUT"? "timed_out"@@ -157,15 +211,33 @@ const compilerOutcome = (? "spawn_failed": "failed";return {- outcome,- code: failure.code,- signal: failure.signal,- stderr: stderr.text,- stderrBytes: Buffer.byteLength(failure.stderr, "utf8"),- stderrTruncated: stderr.truncated,- outputTruncated: failure.outputTruncated,- killed: failure.killed,- ...(outcome === "timed_out" ? { timeoutMs } : {}),+ outcome: {+ outcome,+ code: failure.code,+ signal: failure.signal,+ stderr: stderr.text,+ ...(failure.stderrBytes === undefined+ ? {}+ : { stderrBytes: failure.stderrBytes }),+ stderrTruncated: stderr.truncated,+ outputTruncated: failure.outputTruncated,+ killed: failure.killed,+ ...(outcome === "timed_out" ? { timeoutMs } : {}),+ },+ capturedOutput: {+ stdout: stdout.text,+ stderr: stderr.text,+ truncated:+ stdout.truncated || stderr.truncated || failure.outputTruncated,+ ...(failure.stdoutBytes === undefined+ ? {}+ : { stdout_bytes: failure.stdoutBytes }),+ ...(failure.stderrBytes === undefined+ ? {}+ : { stderr_bytes: failure.stderrBytes }),+ exit_code: typeof failure.code === "number" ? failure.code : null,+ signal: failure.signal,+ },};};@@ -188,7 +260,8 @@ const compilerInspectionError = (timeoutMs: number,compiler: DarwinProcessReaderCompiler,): DarwinProcessOwnershipInspectionError => {- const outcome = compilerOutcome(cause, timeoutMs);+ const facts = compilerFailureFacts(cause, timeoutMs);+ const outcome = facts?.outcome;const code = outcome?.code ?? "unknown";const description = compilerOutcomeDescription(outcome, code);const launcher =@@ -214,14 +287,27 @@ const compilerInspectionError = (`${prefix} (${description})${suffix}`,{cause,- ...(outcome === undefined ? {} : { compilerOutcome: outcome }),+ ...(facts === undefined+ ? {}+ : {+ compilerOutcome: facts.outcome,+ capturedOutput: facts.capturedOutput,+ }),},);};+/** One allocated helper root, including its shared finalization and live cleanup status. */+interface ProcessReaderRoot {+ readonly path: string;+ cleanupPromise?: Promise<void> | undefined;+ cleanupAnchor?: ProviderCleanupError | undefined;+}+interface ProcessReaderCompilation {readonly controller: AbortController;- promise: Promise<string>;+ promise: Promise<Result<string, unknown>>;+ primaryFailure?: { readonly cause: unknown };waiters: number;aborting: boolean;settled: boolean;@@ -239,25 +325,32 @@ const isExpectedAbort = (cause: unknown, signal: AbortSignal): boolean =>(cause === signal.reason ||(cause instanceof Error && cause.name === "AbortError"));+type CompilationWaitOutcome =+ | { readonly kind: "completed"; readonly result: Result<string, unknown> }+ | { readonly kind: "cancelled"; readonly reason: unknown };+const waitForCompilation = async (- promise: Promise<string>,+ operation: ProcessReaderCompilation,signal: AbortSignal | undefined,-): Promise<string> => {- if (signal === undefined) return promise;- if (signal.aborted) throw abortReason(signal);- return new Promise((resolve, reject) => {+): Promise<CompilationWaitOutcome> => {+ if (signal === undefined)+ return { kind: "completed", result: await operation.promise };+ return new Promise((resolve) => {let completed = false;- const finish = (callback: () => void) => {+ const finish = (outcome: CompilationWaitOutcome) => {if (completed) return;completed = true;signal.removeEventListener("abort", onAbort);- callback();+ resolve(outcome);+ };+ const onAbort = () => {+ // Finalization belongs to an already observed physical failure.+ if (operation.primaryFailure !== undefined) return;+ finish({ kind: "cancelled", reason: signal.reason });};- const onAbort = () => finish(() => reject(abortReason(signal)));signal.addEventListener("abort", onAbort, { once: true });- promise.then(- (value) => finish(() => resolve(value)),- (cause: unknown) => finish(() => reject(cause)),+ void operation.promise.then((result) =>+ finish({ kind: "completed", result }),);if (signal.aborted) onAbort();});@@ -294,7 +387,7 @@ export const createDarwinProcessRunTokenReader = (};const compilerTimeoutMs = resolveSwiftcCompileTimeoutMs(options);const moduleCachePath = options.moduleCachePath ?? "";- let root: string | undefined;+ let root: ProcessReaderRoot | undefined;let executable: string | undefined;let compilation: ProcessReaderCompilation | undefined;let closePromise: Promise<void> | undefined;@@ -302,19 +395,48 @@ export const createDarwinProcessRunTokenReader = (let exitCleanupInstalled = false;const cleanupAtExit = () => {- if (root !== undefined) rmSync(root, { recursive: true, force: true });+ if (root !== undefined) rmSync(root.path, { recursive: true, force: true });};- const cleanupRoot = async (target = root): Promise<void> => {- if (target === undefined) return;- await rm(target, { recursive: true, force: true });- if (root !== target) return;- root = undefined;- executable = undefined;- if (exitCleanupInstalled) process.removeListener("exit", cleanupAtExit);- exitCleanupInstalled = false;+ const cleanupRoot = (target = root): Promise<void> => {+ if (target === undefined) return Promise.resolve();+ target.cleanupPromise ??= Promise.resolve()+ .then(async () => {+ try {+ await rm(target.path, { recursive: true, force: true });+ } catch (cause: unknown) {+ const failure = new ProviderCleanupError(+ "process-ownership",+ [target.path],+ {+ reason:+ "The Darwin ownership helper root remains owned until removal succeeds.",+ },+ { cause, operation: "prepare_owned_process" },+ );+ if (target.cleanupAnchor === undefined)+ target.cleanupAnchor = failure;+ else failure.bindCleanupDependencies([target.cleanupAnchor]);+ throw failure;+ }+ target.cleanupAnchor?.resolveCleanup();+ target.cleanupAnchor = undefined;+ if (root !== target) return;+ root = undefined;+ executable = undefined;+ if (exitCleanupInstalled) process.removeListener("exit", cleanupAtExit);+ exitCleanupInstalled = false;+ })+ .catch((cause: unknown) => {+ target.cleanupPromise = undefined;+ throw cause;+ });+ return target.cleanupPromise;};- const runCompilation = async (signal: AbortSignal): Promise<string> => {- let operationRoot: string | undefined;+ const runCompilation = async (+ operation: ProcessReaderCompilation,+ ): Promise<string> => {+ const signal = operation.controller.signal;+ let operationRoot: ProcessReaderRoot | undefined;try {if (compiler.kind === "swiftc" &&@@ -324,15 +446,17 @@ export const createDarwinProcessRunTokenReader = ("Direct Darwin helper compilation requires absolute REA_DARWIN_SWIFTC_PATH and SDKROOT paths selecting a compatible installed Swift compiler and macOS SDK.",);}- operationRoot = await mkdtemp(join(tmpdir(), "rea-process-token-"));+ operationRoot = {+ path: await mkdtemp(join(tmpdir(), "rea-process-token-")),+ };root = operationRoot;process.once("exit", cleanupAtExit);exitCleanupInstalled = true;if (signal.aborted || closed) throw abortReason(signal);- const output = join(operationRoot, "reader");+ const output = join(operationRoot.path, "reader");// swiftc keeps intermediate objects under TMPDIR, so keep them inside// the root that cleanup removes.- const compilerTemporary = join(operationRoot, "tmp");+ const compilerTemporary = join(operationRoot.path, "tmp");await mkdir(compilerTemporary);const compilerEnvironment: NodeJS.ProcessEnv = {...process.env,@@ -367,10 +491,21 @@ export const createDarwinProcessRunTokenReader = (executable = output;return output;} catch (cause: unknown) {- const ownsRoot = operationRoot !== undefined && root === operationRoot;+ operation.primaryFailure = { cause };if (operationRoot !== undefined) {- if (ownsRoot) await cleanupRoot(operationRoot);- else await rm(operationRoot, { recursive: true, force: true });+ try {+ await cleanupRoot(operationRoot);+ } catch (cleanup: unknown) {+ if (!(cleanup instanceof ProviderCleanupError)) throw cleanup;+ const primary =+ cause instanceof DarwinProcessOwnershipInspectionError+ ? cause+ : new DarwinProcessOwnershipInspectionError(+ "Darwin process ownership helper preparation failed",+ { cause },+ );+ throw primary.withCleanupFailure(cleanup);+ }}throw cause;}@@ -380,10 +515,13 @@ export const createDarwinProcessRunTokenReader = (const controller = new AbortController();const operation: ProcessReaderCompilation = {controller,- promise: runCompilation(controller.signal).finally(() => {- operation.settled = true;- if (compilation === operation) compilation = undefined;- }),+ promise: Promise.resolve()+ .then(() => runCompilation(operation))+ .then(ok, err)+ .finally(() => {+ operation.settled = true;+ if (compilation === operation) compilation = undefined;+ }),waiters: 0,aborting: false,settled: false,@@ -405,30 +543,48 @@ export const createDarwinProcessRunTokenReader = (}let operation = compilation;if (operation?.aborting === true) {- try {- await waitForCompilation(operation.promise, signal);- } catch (cause: unknown) {- if (signal !== undefined && isExpectedAbort(cause, signal))- throw cause;- }+ const waited = await waitForCompilation(operation, signal);+ if (waited.kind === "cancelled") throw waited.reason;+ if (+ !waited.result.ok &&+ waited.result.error instanceof+ DarwinProcessOwnershipInspectionError &&+ waited.result.error.cleanupFailure !== undefined+ )+ throw waited.result.error;continue;}operation ??= beginCompilation();operation.waiters += 1;- try {- return await waitForCompilation(operation.promise, signal);- } finally {- operation.waiters -= 1;+ const waited = await waitForCompilation(operation, signal);+ operation.waiters -= 1;+ if (+ operation.waiters === 0 &&+ !operation.settled &&+ !operation.aborting+ ) {+ operation.aborting = true;+ operation.controller.abort();+ const finalized = await operation.promise;if (- operation.waiters === 0 &&- !operation.settled &&- !operation.aborting+ waited.kind === "cancelled" &&+ !finalized.ok &&+ finalized.error instanceof DarwinProcessOwnershipInspectionError &&+ finalized.error.cleanupFailure !== undefined) {- operation.aborting = true;- operation.controller.abort();- await operation.promise.catch(() => undefined);+ throw new DarwinProcessOwnershipInspectionError(+ "Darwin process ownership helper preparation was cancelled",+ {+ cause: waited.reason,+ cancellation: { reason: waited.reason },+ cleanupFailure: finalized.error.cleanupFailure,+ },+ );}}+ if (waited.kind === "cancelled") throw waited.reason;+ if (!waited.result.ok) throw waited.result.error;+ return waited.result.value;}};@@ -538,7 +694,7 @@ export const createDarwinProcessRunTokenReader = (if (operation !== undefined && !operation.settled) {operation.aborting = true;operation.controller.abort();- await operation.promise.catch(() => undefined);+ await operation.promise;}await cleanupRoot();})().catch((cause: unknown) => {diff --git a/src/process/ExecFileOutput.test.ts b/src/process/ExecFileOutput.test.tsindex 7d7905cc1..a385d8071 100644--- a/src/process/ExecFileOutput.test.ts+++ b/src/process/ExecFileOutput.test.ts@@ -105,10 +105,18 @@ describe("execFileOutput", () => {}),).rejects.toMatchObject({ killed: true });});+});- it.skipIf(process.platform === "win32")(- "stops an aborted process with the caller's signal and settles after it exits",- async () => {+describe("execFileOutput cancellation lifecycle", () => {+ it+ .skipIf(process.platform === "win32")+ .each([+ null,+ "stop after readiness",+ new Error("stop after readiness"),+ ] as const)(+ "stops an aborted process with exact %s reason and settles after it exits",+ async (reason) => {const directory = await createTestTempDirectory("rea-exec-stop-");const ready = join(directory, "ready");const stopped = join(directory, "stopped");@@ -134,11 +142,18 @@ describe("execFileOutput", () => {}),);const readyObserved = await waitForFile(ready);- controller.abort();+ controller.abort(reason);const outcome = await execution;expect(readyObserved).toBe(true);- expect(outcome?.cause).toMatchObject({ name: "AbortError" });+ expect(outcome?.cause).toMatchObject({+ name: "AbortError",+ _tag: "ExecFileOutputCancelledError",+ });+ if (!(outcome?.cause instanceof Error))+ throw new Error("Expected cancellation failure");+ expect(outcome.cause.cause).toBe(reason);+ expect(execFileOutputFailure(outcome.cause)).toBeDefined();expect(outcome?.stoppedBeforeSettling).toBe("SIGINT");},);@@ -313,3 +328,71 @@ describe("execFileOutput failure metadata", () => {});});});++describe("execFileOutput cancellation provenance", () => {+ it.each([null, "caller stopped", new Error("caller stopped")] as const)(+ "retains producer cancellation and exact %s reason",+ async (reason) => {+ const controller = new AbortController();+ controller.abort(reason);+ const failure: unknown = await execFileOutput(+ "/must-not-start-after-cancellation",+ [],+ {+ signal: controller.signal,+ stopSignal: "SIGTERM",+ },+ ).catch((cause: unknown) => cause);+ expect(failure).toMatchObject({+ _tag: "ExecFileOutputCancelledError",+ code: "ABORT_ERR",+ name: "AbortError",+ });+ if (!(failure instanceof Error))+ throw new Error("Expected owned cancellation");+ expect(failure.cause).toBe(reason);+ },+ );+ it("keeps a completed command failure when its consumer later aborts", async () => {+ const controller = new AbortController();+ const failure: unknown = await execFileOutput(+ process.execPath,+ ["-e", "process.exitCode=7"],+ {+ signal: controller.signal,+ stopSignal: "SIGTERM",+ },+ ).catch((cause: unknown) => {+ controller.abort(null);+ return cause;+ });+ expect(failure).toMatchObject({ code: 7 });+ expect(failure).not.toHaveProperty("_tag", "ExecFileOutputCancelledError");+ });+});++it.each([+ null,+ "native callback stopped",+ new Error("native callback stopped"),+] as const)(+ "normalizes Node callback cancellation with exact %s reason",+ async (reason) => {+ const controller = new AbortController();+ controller.abort(reason);+ const failure: unknown = await execFileOutput(+ process.execPath,+ ["-e", "process.exit(0)"],+ {+ signal: controller.signal,+ },+ ).catch((cause: unknown) => cause);+ expect(failure).toMatchObject({+ _tag: "ExecFileOutputCancelledError",+ code: "ABORT_ERR",+ });+ if (!(failure instanceof Error))+ throw new Error("Expected Node callback cancellation");+ expect(failure.cause).toBe(reason);+ },+);diff --git a/src/process/ExecFileOutput.ts b/src/process/ExecFileOutput.tsindex b51f6e6ae..2e80e337a 100644--- a/src/process/ExecFileOutput.ts+++ b/src/process/ExecFileOutput.ts@@ -21,14 +21,16 @@ type ExecFileOutputOptions = Omit</** How long a stopped process may take to exit before it is killed. */const STOP_GRACE_MS = 5_000;-const abortError = (signal: AbortSignal): Error => {- const error = new Error("The operation was aborted", {- cause: signal.reason,- });- error.name = "AbortError";- Reflect.set(error, "code", "ABORT_ERR");- return error;-};+/** Cancellation observed by the command owner, with the caller's exact reason. */+export class ExecFileOutputCancelledError extends Error {+ readonly _tag = "ExecFileOutputCancelledError";+ readonly code = "ABORT_ERR";++ constructor(reason: unknown) {+ super("The operation was aborted", { cause: reason });+ this.name = "AbortError";+ }+}/*** A command stopped at its timeout can still exit cleanly, so the timeout is@@ -133,7 +135,7 @@ export const execFileBytes = (return;}if (stopSignal !== undefined && signal?.aborted === true) {- reject(abortError(signal));+ reject(new ExecFileOutputCancelledError(signal.reason));return;}let stopped: "abort" | "timeout" | undefined;@@ -162,10 +164,12 @@ export const execFileBytes = (clearTimeout(grace);const failure =stopped === "abort" && signal !== undefined- ? abortError(signal)+ ? new ExecFileOutputCancelledError(signal.reason): stopped === "timeout" && timeout !== undefined? timeoutError(command, timeout, error)- : error;+ : error?.name === "AbortError" && error.code === "ABORT_ERR"+ ? new ExecFileOutputCancelledError(error.cause)+ : error;if (failure !== null) {Reflect.set(failure, "stdout", stdout.toString("utf8"));Reflect.set(failure, "stderr", stderr.toString("utf8"));diff --git a/src/process/capture/ProcessCaptureError.test.ts b/src/process/capture/ProcessCaptureError.test.tsnew file mode 100644index 000000000..2eaa56b6a--- /dev/null+++ b/src/process/capture/ProcessCaptureError.test.ts@@ -0,0 +1,157 @@+import { expect, it } from "vitest";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";+import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";+import {+ normalizeCaptureFailure,+ ProcessCaptureError,+} from "./ProcessCaptureError.js";+import { resolveProcessResult } from "./ProcessCaptureLifecycle.js";++const cleanupReport = {+ owned_process_group: { state: "not_required" as const, reason: null },+ terminal_renderer: { state: "not_required" as const, reason: null },+ temporary_root: { state: "cleaned" as const, reason: null },+};+const fixture = () => {+ const cleanup = new ProviderCleanupError(+ "process-ownership",+ ["/owned/helper-root"],+ { reason: "controlled removal failure" },+ );+ const compiler = new DarwinProcessOwnershipInspectionError(+ "compiler failed",+ {+ cleanupFailure: cleanup,+ capturedOutput: {+ stdout: "observed stdout",+ stderr: "controlled compiler diagnostic",+ truncated: false,+ stdout_bytes: 15,+ stderr_bytes: 30,+ exit_code: 7,+ signal: null,+ },+ compilerOutcome: {+ outcome: "exited",+ code: 7,+ signal: null,+ stderr: "controlled compiler diagnostic",+ stderrBytes: 30,+ stderrTruncated: false,+ outputTruncated: false,+ killed: false,+ },+ },+ );+ const error = normalizeCaptureFailure(compiler, undefined);+ if (!(error instanceof ProcessCaptureError))+ throw new Error("Expected normalized capture failure");+ return { cleanup, compiler, error };+};++it("preserves the compiler output and live cleanup owner at capture normalization", () => {+ const { cleanup, compiler, error } = fixture();+ expect(error.cause).toBe(compiler);+ expect(error).toMatchObject({+ cleanupIncomplete: true,+ cleanupResources: ["/owned/helper-root"],+ capturedOutput: { stderr: "controlled compiler diagnostic", exit_code: 7 },+ });+ expect(projectAnalysisError(error)).toMatchObject({+ code: "cleanup_incomplete",+ });+ cleanup.resolveCleanup();+ expect(error.cleanupIncomplete).toBe(false);+ expect(error.capturedOutput?.exit_code).toBe(7);+});++it("retains compiler facts and cleanup dependency through capture finalization", () => {+ const { cleanup, error } = fixture();+ let finalized: unknown;+ try {+ resolveProcessResult(undefined, error, cleanupReport);+ } catch (cause: unknown) {+ finalized = cause;+ }+ expect(finalized).toBeInstanceOf(ProcessCaptureError);+ expect(finalized).toMatchObject({+ cleanupIncomplete: true,+ capturedOutput: { stderr: "controlled compiler diagnostic", exit_code: 7 },+ cleanupReport,+ });+ cleanup.resolveCleanup();+ expect(finalized).toMatchObject({ cleanupIncomplete: false });+});++it("does not recreate unresolved cleanup after the exact owner already confirmed retry", () => {+ const { cleanup, compiler } = fixture();+ cleanup.resolveCleanup();+ const normalized = normalizeCaptureFailure(compiler, undefined);+ expect(normalized).toMatchObject({+ cleanupIncomplete: false,+ capturedOutput: { exit_code: 7 },+ });+});++it("keeps later capture cleanup unresolved after compiler cleanup succeeds", () => {+ const { cleanup, error } = fixture();+ let finalized: unknown;+ try {+ resolveProcessResult(undefined, error, {+ ...cleanupReport,+ temporary_root: {+ state: "failed",+ reason: "capture root removal denied",+ },+ });+ } catch (cause: unknown) {+ finalized = cause;+ }+ expect(finalized).toMatchObject({+ cleanupIncomplete: true,+ capturedOutput: { exit_code: 7 },+ cleanupResources: expect.arrayContaining([+ "/owned/helper-root",+ "temporary_root",+ ]),+ });+ cleanup.resolveCleanup();+ expect(finalized).toMatchObject({ cleanupIncomplete: true });+});++it.each(["compiler first", "capture first"] as const)(+ "keeps both cleanup owners through %s retry",+ (order) => {+ const { cleanup, error } = fixture();+ const captureCleanup = new ProviderCleanupError(+ "process-capture",+ ["/owned/capture-root"],+ { reason: "controlled capture root failure" },+ );+ const finalized = error.withFinalization({+ cleanupFailure: captureCleanup,+ cleanupReport,+ });+ const first = order === "compiler first" ? cleanup : captureCleanup;+ const second = order === "compiler first" ? captureCleanup : cleanup;+ first.resolveCleanup();+ expect(finalized.cleanupIncomplete).toBe(true);+ second.resolveCleanup();+ expect(finalized.cleanupIncomplete).toBe(false);+ expect(finalized.capturedOutput?.exit_code).toBe(7);+ },+);++it("does not infer captured stdout from partial compiler diagnostics", () => {+ const { compiler } = fixture();+ const partial = new DarwinProcessOwnershipInspectionError(+ "partial diagnostics",+ {+ compilerOutcome: compiler.compilerOutcome!,+ },+ );+ expect(normalizeCaptureFailure(partial, undefined)).toMatchObject({+ capturedOutput: undefined,+ });+});diff --git a/src/process/capture/ProcessCaptureError.ts b/src/process/capture/ProcessCaptureError.tsindex 7cf6f2705..6d13c8f75 100644--- a/src/process/capture/ProcessCaptureError.ts+++ b/src/process/capture/ProcessCaptureError.ts@@ -12,7 +12,6 @@ interface ProcessCaptureErrorOptions extends AnalysisErrorOptions {readonly userMessage?: string;readonly userCategory?: "cancelled";readonly reason?: "capture_failed" | "cleanup_incomplete" | "cancelled";- readonly cleanupResources?: readonly string[];readonly executionFailure?: string;readonly partialObservation?: PartialProcessCaptureObservation;readonly cleanupReport?: ProcessCaptureCleanupReport;@@ -25,8 +24,6 @@ export class ProcessCaptureError extends AnalysisError {override readonly userMessage: string | undefined;override readonly userCategory: "cancelled" | undefined;readonly reason: NonNullable<ProcessCaptureErrorOptions["reason"]>;- override readonly cleanupIncomplete: boolean;- override readonly cleanupResources: readonly string[];override readonly executionFailure: string | undefined;override readonly partialObservation:| PartialProcessCaptureObservation@@ -40,12 +37,58 @@ export class ProcessCaptureError extends AnalysisError {this.reason =options?.reason ??(options?.userCategory === "cancelled" ? "cancelled" : "capture_failed");- this.cleanupIncomplete = this.reason === "cleanup_incomplete";- this.cleanupResources = options?.cleanupResources ?? [];+ this.cleanupIncomplete ||= this.reason === "cleanup_incomplete";this.executionFailure = options?.executionFailure ?? message;this.partialObservation = options?.partialObservation;this.cleanupReport = options?.cleanupReport;}++ /** Add final capture observations while preserving primary facts and cleanup ownership. */+ withFinalization(+ options: Pick<+ ProcessCaptureErrorOptions,+ "executionFailure" | "partialObservation" | "cleanupReport"+ > & { readonly cleanupFailure?: AnalysisError },+ ): ProcessCaptureError {+ const secondary = options.cleanupFailure;+ const resources = [+ ...new Set([+ ...this.cleanupResources,+ ...(secondary?.cleanupResources ?? []),+ ]),+ ];+ const executionFailure = this.executionFailure ?? options.executionFailure;+ const partialObservation =+ this.partialObservation ?? options.partialObservation;+ const cleanupReport = this.cleanupReport ?? options.cleanupReport;+ return new ProcessCaptureError(this.message, {+ ...(Object.hasOwn(this, "cause") ? { cause: this.cause } : {}),+ ...(this.userMessage === undefined+ ? {}+ : { userMessage: this.userMessage }),+ ...(this.userCategory === undefined+ ? {}+ : { userCategory: this.userCategory }),+ reason: this.reason,+ ...(this.diagnostics === undefined+ ? {}+ : { diagnostics: this.diagnostics }),+ ...(this.capturedOutput === undefined+ ? {}+ : { capturedOutput: this.capturedOutput }),+ ...(secondary === undefined+ ? this.cleanup === undefined+ ? {}+ : { cleanup: this.cleanup }+ : { cleanup: { reason: secondary.message, resources } }),+ ...(executionFailure === undefined ? {} : { executionFailure }),+ ...(partialObservation === undefined ? {} : { partialObservation }),+ ...(cleanupReport === undefined ? {} : { cleanupReport }),+ }).bindCleanupDependencies([+ this,+ ...(secondary === undefined ? [] : [secondary]),+ ]);+ }}/** Return one non-recursive, domain-neutral summary of an execution failure. */@@ -73,26 +116,26 @@ export const normalizeCaptureFailure = (): unknown => {if (cause instanceof ProcessCaptureError) return cause;if (cause instanceof DarwinProcessOwnershipInspectionError) {- const compiler = cause.compilerOutcome;- return new ProcessCaptureError(cause.message, {+ const normalized = new ProcessCaptureError(cause.message, {cause,- ...(compiler === undefined+ ...(cause.cancellation === undefined+ ? {}+ : { userCategory: "cancelled" as const, reason: "cancelled" as const }),+ ...(cause.cleanupFailure === undefined? {}: {- capturedOutput: {- stdout: "",- stderr: compiler.stderr,- truncated: compiler.stderrTruncated || compiler.outputTruncated,- stderr_bytes: compiler.stderrBytes,- exit_code:- compiler.outcome === "exited" &&- typeof compiler.code === "number"- ? compiler.code- : null,- signal: compiler.signal,+ cleanup: {+ reason: cause.cleanupFailure.message,+ resources: cause.cleanupFailure.cleanupResources,},}),+ ...(cause.capturedOutput === undefined+ ? {}+ : { capturedOutput: cause.capturedOutput }),});+ return cause.cleanupFailure === undefined+ ? normalized+ : normalized.bindCleanupDependencies([cause.cleanupFailure]);}if (signal?.aborted === true &&diff --git a/src/process/capture/ProcessCaptureLifecycle.ts b/src/process/capture/ProcessCaptureLifecycle.tsindex d7ab6afbf..b92a156dd 100644--- a/src/process/capture/ProcessCaptureLifecycle.ts+++ b/src/process/capture/ProcessCaptureLifecycle.ts@@ -1435,39 +1435,34 @@ export const resolveProcessResult = (outcome.state === "failed" || outcome.state === "unverified",).map(([resource]) => resource);- throw new ProcessCaptureError(cleanupFailure, {+ const cleanupError = new ProcessCaptureError(cleanupFailure, {cause: executionFailure,reason: "cleanup_incomplete",- cleanupResources,+ cleanup: { reason: cleanupFailure, resources: cleanupResources },...(executionFailureReason === undefined? {}: { executionFailure: executionFailureReason }),...(partialObservation === undefined ? {} : { partialObservation }),cleanupReport: cleanup,});+ if (executionFailure instanceof ProcessCaptureError)+ throw executionFailure.withFinalization({+ ...(executionFailureReason === undefined+ ? {}+ : { executionFailure: executionFailureReason }),+ ...(partialObservation === undefined ? {} : { partialObservation }),+ cleanupReport: cleanup,+ cleanupFailure: cleanupError,+ });+ throw cleanupError;}if (executionFailure instanceof ProcessCaptureError) {- const retainedExecutionFailure =- executionFailure.executionFailure ?? executionFailureReason;- const retainedPartialObservation =- executionFailure.partialObservation ?? partialObservation;- throw new ProcessCaptureError(executionFailure.message, {- cause: executionFailure,- ...(executionFailure.userMessage === undefined- ? {}- : { userMessage: executionFailure.userMessage }),- ...(executionFailure.userCategory === undefined- ? {}- : { userCategory: executionFailure.userCategory }),- reason: executionFailure.reason,- cleanupResources: executionFailure.cleanupResources,- ...(retainedExecutionFailure === undefined- ? {}- : { executionFailure: retainedExecutionFailure }),- ...(retainedPartialObservation === undefined+ throw executionFailure.withFinalization({+ ...(executionFailureReason === undefined? {}- : { partialObservation: retainedPartialObservation }),- cleanupReport: executionFailure.cleanupReport ?? cleanup,+ : { executionFailure: executionFailureReason }),+ ...(partialObservation === undefined ? {} : { partialObservation }),+ cleanupReport: cleanup,});}if (executionFailure !== undefined) {diff --git a/src/process/capture/ProcessHarness.ts b/src/process/capture/ProcessHarness.tsindex 017050803..5a1697d38 100644--- a/src/process/capture/ProcessHarness.ts+++ b/src/process/capture/ProcessHarness.ts@@ -910,7 +910,10 @@ export const captureProcessScenario = async (: new ProcessCaptureError("process capture lifecycle failed", {cause,reason: "cleanup_incomplete",- cleanupResources: ["process_capture_lifecycle"],+ cleanup: {+ reason: "process capture lifecycle failed",+ resources: ["process_capture_lifecycle"],+ },...(executionFailure === undefined ? {} : { executionFailure }),}),);diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.tsindex 8053abf66..7c992112d 100644--- a/src/server/registerSessionTools.ts+++ b/src/server/registerSessionTools.ts@@ -314,7 +314,10 @@ export const registerSessionTools = ({cause,reason: "cleanup_incomplete",- cleanupResources: ["process_capture_resources"],+ cleanup: {+ reason: "process capture cleanup remains incomplete",+ resources: ["process_capture_resources"],+ },executionFailure:cause instanceof Error? cause.message || cause.namediff --git a/tests/boundary/process/darwinProcessRunTokenReader.test.ts b/tests/boundary/process/darwinProcessRunTokenReader.test.tsindex 9f377440c..cd8df2436 100644--- a/tests/boundary/process/darwinProcessRunTokenReader.test.ts+++ b/tests/boundary/process/darwinProcessRunTokenReader.test.ts@@ -1351,3 +1351,55 @@ const stopNodeChild = async (child: ChildProcess) => {child.kill("SIGKILL");await exited;};++it.skipIf(process.platform === "win32").each([+ {+ name: "invalid UTF-8",+ stdout: "owned compiler stdout",+ stderrHex: "ff",+ stderrBytes: 1,+ truncated: false,+ },+ {+ name: "bounded stdout",+ stdout: "x".repeat(12000),+ stderrHex: "61",+ stderrBytes: 1,+ truncated: true,+ },+])(+ "retains original output facts for $name compiler failures",+ async ({ stdout, stderrHex, stderrBytes, truncated }) => {+ const directory = await createTestTempDirectory(+ "rea-compiler-output-facts-",+ );+ const executable = join(directory, "compiler");+ await writeFile(+ executable,+ `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(stdout)}); process.stderr.write(Buffer.from(${JSON.stringify(stderrHex)}, "hex")); process.exitCode=7;\n`,+ { mode: 0o755 },+ );+ const reader = createDarwinProcessRunTokenReader({+ compiler: { kind: "xcrun", executable },+ });+ try {+ const failure = await preparationFailure(reader);+ expect(failure.compilerOutcome?.stderrBytes).toBe(stderrBytes);+ expect(failure.capturedOutput).toEqual({+ stdout: stdout.slice(0, 8192),+ stderr: Buffer.from(stderrHex, "hex").toString("utf8"),+ stdout_bytes: Buffer.byteLength(stdout),+ stderr_bytes: stderrBytes,+ truncated,+ exit_code: 7,+ signal: null,+ });+ const normalized = normalizeCaptureFailure(failure, undefined);+ if (!(normalized instanceof ProcessCaptureError))+ throw new Error("Expected capture failure");+ expect(normalized.capturedOutput).toEqual(failure.capturedOutput);+ } finally {+ await reader.close();+ }+ },+);diff --git a/tests/boundary/process/processCli.test.ts b/tests/boundary/process/processCli.test.tsindex 3da9205f6..4d4987436 100644--- a/tests/boundary/process/processCli.test.ts+++ b/tests/boundary/process/processCli.test.ts@@ -158,7 +158,7 @@ describe("process CLI evidence validation", () => {const projected = projectProcessCliError(new ProcessCaptureError("cleanup incomplete", {reason: "cleanup_incomplete",- cleanupResources: ["owned_process_group"],+ cleanup: { reason, resources: ["owned_process_group"] },cleanupReport: {owned_process_group: { state: "unverified", reason },terminal_renderer: { state: "cleaned", reason: null },diff --git a/tests/boundary/providers/ghidra/ghidraClient.test.ts b/tests/boundary/providers/ghidra/ghidraClient.test.tsindex 61967a940..af14a7db8 100644--- a/tests/boundary/providers/ghidra/ghidraClient.test.ts+++ b/tests/boundary/providers/ghidra/ghidraClient.test.ts@@ -11,13 +11,17 @@ import pino from "pino";import type { Logger } from "pino";import type { ProgressUpdate } from "../../../../src/application/ProgressReporter.js";-import { ok } from "../../../../src/domain/result.js";+import { err, ok } from "../../../../src/domain/result.js";+import * as GhidraTransport from "../../../../src/ghidra/GhidraTransport.js";import { GhidraClient } from "../../../../src/ghidra/GhidraClient.js";import { ProviderRunLineage } from "../../../../src/process/ProviderRunLineage.js";import { PrivateRuntimeRoot } from "../../../../src/process/PrivateRuntimeRoot.js";import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js";import { GHIDRA_PROCESS_DIAGNOSTIC_BYTES } from "../../../../src/ghidra/GhidraDiagnostics.js";-import { GhidraHeadlessLauncher } from "../../../../src/ghidra/GhidraLauncher.js";+import {+ GhidraHeadlessLauncher,+ GhidraLaunchError,+} from "../../../../src/ghidra/GhidraLauncher.js";import type { GhidraDiagnostic } from "../../../../src/ghidra/GhidraClientTypes.js";import type {GhidraLaunchSession,@@ -1258,7 +1262,7 @@ describe("GhidraClient process output drain before startup failure", () => {});});- it("keeps caller cancellation primary when cancellation wins during output drain", async () => {+ it("preserves an observed process exit when cancellation interrupts diagnostic drain", async () => {const { launcher, finishOutput } = preExitedProcessLauncher({output: oomeOutput,closeOutput: true,@@ -1279,7 +1283,11 @@ describe("GhidraClient process output drain before startup failure", () => {expect(result.ok).toBe(false);if (result.ok) return;- expect(result.error.kind).toBe("cancelled");+ expect(result.error.kind).toBe("process");+ expect(result.error.diagnostics).toMatchObject({+ exit_code: 73,+ output_incomplete: true,+ });});});@@ -1598,3 +1606,163 @@ it("bounds retries when loopback preauthentication keeps failing", async () => {true,);});++it.each([null, "caller stopped", new Error("caller stopped")])(+ "preserves exact active and queued request cancellation reasons %j",+ async (reason) => {+ const launcher = new FixtureLauncher("hang_tools");+ const client = clientFor(launcher);+ await expect(client.start()).resolves.toMatchObject({ ok: true });+ const activeController = new AbortController();+ const active = client.callTool(+ "procedure_pseudo_code",+ { document: null, procedure: "fixture_main" },+ { signal: activeController.signal },+ );+ await vi.waitFor(() =>+ expect(launcher.requests).toContain("procedure_pseudo_code"),+ );+ const queuedController = new AbortController();+ const queued = client.callTool(+ "procedure_info",+ {},+ { signal: queuedController.signal },+ );+ queuedController.abort(reason);+ const queuedResult = await queued;+ activeController.abort(reason);+ const activeResult = await active;+ for (const result of [queuedResult, activeResult]) {+ if (result.ok) throw new Error("Expected request cancellation");+ expect(result.error.kind).toBe("cancelled");+ expect(result.error.cancellation?.reason).toBe(reason);+ }+ expect(await waitForExit(launcher.processes[0])).toBe(true);+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({+ code: "ENOENT",+ });+ },+);++it("preserves the observed protocol failure when cancellation interrupts request diagnostic drain", async () => {+ const controller = new AbortController();+ let abortScheduled = false;+ const logger = pino(+ {+ level: "warn",+ hooks: {+ logMethod(args, method) {+ const fields = args[0];+ if (+ typeof fields === "object" &&+ fields !== null &&+ "method" in fields &&+ fields.method === "list_procedures" &&+ !abortScheduled+ ) {+ abortScheduled = true;+ setImmediate(() => controller.abort(null));+ }+ method.apply(this, args);+ },+ },+ },+ { write: () => {} },+ );+ const launcher = new FixtureLauncher("old_oom_then_malformed");+ const client = clientFor(launcher, { logger });+ await expect(client.start()).resolves.toMatchObject({ ok: true });+ await expect(client.callTool("list_documents", {})).resolves.toMatchObject({+ ok: true,+ });+ const result = await client.callTool(+ "list_procedures",+ {},+ { signal: controller.signal },+ );+ expect(abortScheduled).toBe(true);+ if (result.ok) throw new Error("Expected protocol failure");+ expect(result.error.kind).toBe("protocol");+ expect(result.error.diagnostics).toMatchObject({+ failure_output: { complete: false },+ });+ expect(await waitForExit(launcher.processes[0])).toBe(true);+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({+ code: "ENOENT",+ });+});++it.each([null, "caller stopped", new Error("caller stopped")])(+ "retains the exact reason during startup endpoint polling %j",+ async (reason) => {+ const observed = vi.spyOn(GhidraTransport, "observeGhidraEndpoint");+ onTestFinished(() => observed.mockRestore());+ const launcher = new FixtureLauncher("silent");+ const client = clientFor(launcher, { startupTimeoutMs: 10000 });+ const controller = new AbortController();+ const pending = client.start(controller.signal);+ await vi.waitFor(() => expect(observed).toHaveBeenCalled());+ controller.abort(reason);+ const result = await pending;+ if (result.ok) throw new Error("Expected startup cancellation");+ expect(result.error.kind).toBe("cancelled");+ expect(result.error.cancellation?.reason).toBe(reason);+ expect(await waitForExit(launcher.processes[0])).toBe(true);+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({+ code: "ENOENT",+ });+ },+);++it("preserves a handshake protocol error observed before the final startup caller cancels", async () => {+ const controller = new AbortController();+ let cancelled = false;+ const logger = pino(+ {+ level: "warn",+ hooks: {+ logMethod(args, method) {+ const fields = args[0];+ if (+ typeof fields === "object" &&+ fields !== null &&+ "method" in fields &&+ fields.method === "ping" &&+ !cancelled+ ) {+ cancelled = true;+ controller.abort(null);+ }+ method.apply(this, args);+ },+ },+ },+ { write: () => {} },+ );+ const launcher = new FixtureLauncher("malformed");+ const client = clientFor(launcher, { logger });+ const result = await client.start(controller.signal);+ expect(cancelled).toBe(true);+ if (result.ok) throw new Error("Expected handshake protocol failure");+ expect(result.error.kind).toBe("protocol");+ expect(await waitForExit(launcher.processes[0])).toBe(true);+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({+ code: "ENOENT",+ });+});++it("redacts the transport credential when refreshing startup diagnostics", async () => {+ let token = "";+ const client = clientFor({+ launch: async (session) => {+ token = session.token;+ return err(new GhidraLaunchError(`Launcher refused ${token}`));+ },+ });+ const result = await client.start();+ if (result.ok) throw new Error("Expected launcher refusal");+ expect(token.length).toBeGreaterThan(0);+ expect(result.error.message).toContain("[REDACTED]");+ expect(result.error.message).not.toContain(token);+ expect(JSON.stringify(result.error.diagnostics)).not.toContain(token);+});diff --git a/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts b/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.tsindex 3a5a7c719..1c74da203 100644--- a/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts+++ b/tests/boundary/providers/ghidra/ghidraJavaLaunch.test.ts@@ -505,3 +505,50 @@ describe.skipIf(process.platform === "win32")();},);++it.each([null, "caller stopped", new Error("caller stopped")] as const)(+ "retains the helper producer's exact %s cancellation reason",+ async (reason) => {+ const { ghidraJavaLaunch, GhidraLaunchSupportError } =+ await import("../../../../src/ghidra/GhidraJavaLaunch.js");+ const controller = new AbortController();+ controller.abort(reason);+ const failure: unknown = await ghidraJavaLaunch({+ platform: process.platform,+ analyzeHeadlessPath: "/unused-ghidra/support/analyzeHeadless",+ homeRoot: "/unused-runtime/home",+ tempRoot: "/unused-runtime/tmp",+ arguments: [],+ environment: {},+ signal: controller.signal,+ onStderr: () => {+ throw new Error("An aborted probe must not produce output");+ },+ }).catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(GhidraLaunchSupportError);+ if (!(failure instanceof GhidraLaunchSupportError))+ throw new Error("Expected helper failure");+ expect(failure.cancellation?.reason).toBe(reason);+ expect(failure.outcome).toBeUndefined();+ },+);++it("does not infer helper cancellation from an arbitrary failure's display code", async () => {+ const { GhidraLaunchSupportError } =+ await import("../../../../src/ghidra/GhidraJavaLaunch.js");+ const cause = Object.assign(new Error("ordinary failure"), {+ code: "ABORT_ERR",+ stdout: "out",+ stderr: "err",+ killed: true,+ outputTruncated: true,+ });+ const failure = new GhidraLaunchSupportError("-envvars", cause);+ expect(failure.cancellation).toBeUndefined();+ expect(failure.outcome).toMatchObject({+ killed: true,+ outputTruncated: true,+ stdout: "out",+ stderr: "err",+ });+});diff --git a/tests/process-global/darwinCompilerCleanup.test.ts b/tests/process-global/darwinCompilerCleanup.test.tsnew file mode 100644index 000000000..667d1c71c--- /dev/null+++ b/tests/process-global/darwinCompilerCleanup.test.ts@@ -0,0 +1,288 @@+import { createHash } from "node:crypto";+import { access, readFile, writeFile } from "node:fs/promises";+import { dirname, join } from "node:path";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++const fault = vi.hoisted(() => ({+ roots: new Set<string>(),+ blocked: true,+ failure: new Error("controlled helper-root removal failure"),+ abort: undefined as AbortController | undefined,+ attempts: 0,+ gate: undefined as (() => Promise<void>) | undefined,+}));+vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ mkdtemp: async (...args: Parameters<typeof actual.mkdtemp>) => {+ const root = await actual.mkdtemp(...args);+ if (+ typeof root === "string" &&+ String(args[0]).includes("rea-process-token-")+ )+ fault.roots.add(root);+ return root;+ },+ rm: async (...args: Parameters<typeof actual.rm>) => {+ if (typeof args[0] === "string" && fault.roots.has(args[0])) {+ fault.attempts += 1;+ await fault.gate?.();+ if (!fault.blocked) return actual.rm(...args);+ fault.abort?.abort(null);+ throw fault.failure;+ }+ return actual.rm(...args);+ },+ };+});++import {+ createDarwinProcessRunTokenReader,+ DarwinProcessOwnershipInspectionError,+} from "../../src/process/DarwinProcessRunTokenReader.js";+import { GhidraClient } from "../../src/ghidra/GhidraClient.js";+import { GhidraHeadlessLauncher } from "../../src/ghidra/GhidraLauncher.js";+import { captureProcessScenario } from "../../src/process/capture/ProcessHarness.js";+import { processScenarioSchema } from "../../src/domain/process/processScenario.js";+import { systemProcessOwnershipHost } from "../../src/process/ProcessOwnershipObservation.js";+import { ghidraFixturePath } from "../boundary/providers/ghidra/ghidraClient.fixture.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+let releaseCleanup: (() => void) | undefined;+const clients: GhidraClient[] = [];+const readers: ReturnType<typeof createDarwinProcessRunTokenReader>[] = [];+beforeEach(() => {+ fault.blocked = true;+ fault.abort = undefined;+ fault.roots.clear();+ fault.attempts = 0;+ fault.gate = undefined;+});+afterEach(async () => {+ releaseCleanup?.();+ releaseCleanup = undefined;+ fault.blocked = false;+ fault.abort = undefined;+ fault.gate = undefined;+ vi.restoreAllMocks();+ for (const client of clients.splice(0)) await client.close();+ for (const reader of readers.splice(0)) await reader.close();+});++const fixture = async (mode: "fail" | "active" = "fail") => {+ const directory = await createTestTempDirectory(+ "rea-compiler-cleanup-fixture-",+ );+ const compiler = join(directory, "compiler");+ await writeFile(+ compiler,+ mode === "fail"+ ? "#!/usr/bin/env node\nprocess.stdout.write('owned compiler stdout'); process.stderr.write('controlled compiler failure\\n'); process.exitCode=7;\n"+ : `#!/usr/bin/env node+const fs = require('node:fs');+process.on('SIGINT', () => process.exit(0));+fs.writeFileSync(${JSON.stringify(join(directory, "ready"))}, 'ready');+setInterval(() => {}, 1000);+`,+ { mode: 0o755 },+ );+ const reader = createDarwinProcessRunTokenReader({+ compiler: { kind: "xcrun", executable: compiler },+ });+ readers.push(reader);+ return { reader, readyPath: join(directory, "ready") };+};++it+ .skipIf(process.platform === "win32")+ .each(["ordinary", "cancel during cleanup"] as const)(+ "preserves the compiler failure through %s and resolves retained cleanup on retry",+ async (mode) => {+ const { reader } = await fixture();+ const controller = new AbortController();+ if (mode === "cancel during cleanup") fault.abort = controller;+ const failure: unknown = await reader+ .prepare(controller.signal)+ .catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(DarwinProcessOwnershipInspectionError);+ expect(failure).toMatchObject({+ compilerOutcome: {+ outcome: "exited",+ code: 7,+ stderr: "controlled compiler failure\n",+ },+ cleanupFailure: { cleanupIncomplete: true, cause: fault.failure },+ });+ if (!(failure instanceof DarwinProcessOwnershipInspectionError))+ throw new Error("Expected primary compiler failure");+ const root = [...fault.roots][0];+ if (root === undefined) throw new Error("Expected owned compiler root");+ await expect(access(root)).resolves.toBeUndefined();+ fault.blocked = false;+ await reader.close();+ await expect(access(root)).rejects.toMatchObject({ code: "ENOENT" });+ expect(failure).toMatchObject({+ cleanupFailure: { cleanupIncomplete: false },+ compilerOutcome: { code: 7 },+ });+ },+);++it+ .skipIf(process.platform === "win32")+ .each(["two retries", "retry and close"] as const)(+ "shares retained root cleanup during %s",+ async (mode) => {+ const { reader } = await fixture();+ const original: unknown = await reader+ .prepare()+ .catch((cause: unknown) => cause);+ expect(original).toMatchObject({+ cleanupFailure: { cleanupIncomplete: true },+ });+ let release: (() => void) | undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ releaseCleanup = resolve;+ });+ fault.gate = () => gate;+ fault.blocked = false;+ const before = fault.attempts;+ const first = reader.prepare().catch((cause: unknown) => cause);+ const second =+ mode === "two retries"+ ? reader.prepare().catch((cause: unknown) => cause)+ : reader.close();+ await vi.waitFor(() => expect(fault.attempts).toBe(before + 1));+ await new Promise((resolve) => setImmediate(resolve));+ expect(fault.attempts).toBe(before + 1);+ release?.();+ await Promise.all([first, second]);+ expect(original).toMatchObject({+ cleanupFailure: { cleanupIncomplete: false },+ });+ },+);++it+ .skipIf(process.platform === "win32")+ .each([null, "stop preparation", new Error("stop preparation")] as const)(+ "joins final cleanup after the last waiter cancels with exact %s reason",+ async (reason) => {+ const { reader, readyPath } = await fixture("active");+ const controller = new AbortController();+ const preparation = reader+ .prepare(controller.signal)+ .catch((cause: unknown) => cause);+ await vi.waitFor(async () =>+ expect(await readFile(readyPath, "utf8")).toBe("ready"),+ );+ const root = [...fault.roots][0];+ if (root === undefined) throw new Error("Expected helper root");+ controller.abort(reason);+ const failure: unknown = await preparation;+ expect(failure).toBeInstanceOf(DarwinProcessOwnershipInspectionError);+ if (!(failure instanceof DarwinProcessOwnershipInspectionError))+ throw new Error("Expected retained cleanup failure");+ expect(failure.cause).toBe(reason);+ expect(failure.cancellation?.reason).toBe(reason);+ expect(failure.cleanupFailure?.cleanupIncomplete).toBe(true);+ fault.blocked = false;+ await reader.close();+ expect(failure.cleanupFailure?.cleanupIncomplete).toBe(false);+ await expect(access(root)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.skipIf(process.platform === "win32")(+ "Ghidra startup retains the compiler root until that owner confirms cleanup",+ async () => {+ const { reader, readyPath } = await fixture();+ const fixtureRoot = dirname(readyPath);+ const launcher = new GhidraHeadlessLauncher({+ configurationDirectoryName: "ghidra_12.1.4_PUBLIC",+ environment: {},+ analyzeHeadlessPath: join(fixtureRoot, "support", "analyzeHeadless"),+ javaHome: join(fixtureRoot, "jdk"),+ bridgeScriptPath: join(fixtureRoot, "ReaGhidraBridge.java"),+ javaLaunch: async () => ({+ command: process.execPath,+ arguments: [],+ environment: {},+ }),+ spawnProcess: async () => {+ await reader.prepare();+ throw new Error("unexpected compilation success");+ },+ });+ const client = new GhidraClient({+ launcher,+ targetPath: ghidraFixturePath,+ targetSha256: createHash("sha256")+ .update(await readFile(ghidraFixturePath))+ .digest("hex"),+ providerVersion: "test",+ profileDigest: "b".repeat(64),+ startupTimeoutMs: 10000,+ });+ clients.push(client);+ const result = await client.start();+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "start", cleanupFailure: { cleanupIncomplete: true } },+ });+ if (result.ok) throw new Error("Expected startup compiler failure");+ expect(result.error.diagnostics).toMatchObject({+ failure_cause: {+ launch_outcome: {+ stdout: "owned compiler stdout",+ stdout_bytes: 21,+ stderr_bytes: 28,+ exit_code: 7,+ },+ cause: { compiler_outcome: { code: 7 } },+ },+ });+ await client.close();+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(true);+ fault.blocked = false;+ await reader.close();+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(false);+ },+);++it.skipIf(process.platform === "win32")(+ "capture boundary retains compiler output and follows the actual helper cleanup retry",+ async () => {+ const { reader } = await fixture();+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async (signal) => {+ await reader.prepare(signal);+ },+ );+ const result = await captureProcessScenario(+ processScenarioSchema.parse({ executable: process.execPath }),+ undefined,+ "linux",+ {},+ );+ expect(result).toMatchObject({+ ok: false,+ error: {+ cleanupIncomplete: true,+ capturedOutput: {+ exit_code: 7,+ stdout: "owned compiler stdout",+ stdout_bytes: 21,+ stderr_bytes: 28,+ stderr: "controlled compiler failure\n",+ },+ },+ });+ if (result.ok) throw new Error("Expected capture preparation failure");+ fault.blocked = false;+ await reader.close();+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(result.error.capturedOutput?.exit_code).toBe(7);+ },+);diff --git a/tests/process-global/ghidraEndpointLifetime.test.ts b/tests/process-global/ghidraEndpointLifetime.test.tsnew file mode 100644index 000000000..c7807b9fc--- /dev/null+++ b/tests/process-global/ghidraEndpointLifetime.test.ts@@ -0,0 +1,359 @@+import { execFile } from "node:child_process";+import { createHash } from "node:crypto";+import { promisify } from "node:util";+import { pathToFileURL } from "node:url";+import {+ access,+ readFile,+ rename,+ writeFile,+ type FileHandle,+} from "node:fs/promises";+import { basename, join } from "node:path";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++const fault = vi.hoisted(() => ({+ path: "",+ matchEndpoints: false,+ reads: 0,+ handles: [] as FileHandle[],+ blocked: false,+ abortClose: undefined as AbortController | undefined,+ readFailure: undefined as Error | undefined,+ abortRead: undefined as AbortController | undefined,+ readGate: undefined as (() => Promise<void>) | undefined,+}));+vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ open: async (...args: Parameters<typeof actual.open>) => {+ const handle = await actual.open(...args);+ if (+ args[0] !== fault.path &&+ !(+ fault.matchEndpoints &&+ typeof args[0] === "string" &&+ basename(args[0]) === "bridge-endpoint.json"+ )+ )+ return handle;+ fault.handles.push(handle);+ const close = handle.close.bind(handle);+ handle.close = async () => {+ fault.abortClose?.abort(null);+ if (fault.blocked) throw new Error("controlled endpoint close failure");+ await close();+ };+ const read = handle.read.bind(handle);+ handle.read = (async (...values: unknown[]) => {+ fault.reads += 1;+ await fault.readGate?.();+ if (fault.readFailure !== undefined) {+ fault.abortRead?.abort(null);+ throw fault.readFailure;+ }+ return await Reflect.apply(read, handle, values);+ }) as FileHandle["read"];+ const readFile = handle.readFile.bind(handle);+ handle.readFile = (async (...values: unknown[]) => {+ fault.reads += 1;+ await fault.readGate?.();+ if (fault.readFailure !== undefined) {+ fault.abortRead?.abort(null);+ throw fault.readFailure;+ }+ return await Reflect.apply(readFile, handle, values);+ }) as FileHandle["readFile"];+ return handle;+ },+ };+});++import { ArtifactResourceScope } from "../../src/artifacts/ArtifactResourceScope.js";+import { observeGhidraEndpoint } from "../../src/ghidra/GhidraTransport.js";+import { GhidraClient } from "../../src/ghidra/GhidraClient.js";+import {+ GhidraFixtureLauncher,+ ghidraFixturePath,+} from "../boundary/providers/ghidra/ghidraClient.fixture.js";+import { waitForExit } from "../support/process/processFixture.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";++const clients: GhidraClient[] = [];+const operations: Promise<unknown>[] = [];+let releaseRead: (() => void) | undefined;+beforeEach(() => {+ fault.path = "";+ fault.matchEndpoints = false;+ fault.reads = 0;+ fault.handles = [];+ fault.blocked = false;+ fault.abortClose = undefined;+ fault.readFailure = undefined;+ fault.abortRead = undefined;+ fault.readGate = undefined;+});+afterEach(async () => {+ fault.blocked = false;+ fault.abortClose = undefined;+ fault.readFailure = undefined;+ fault.abortRead = undefined;+ releaseRead?.();+ releaseRead = undefined;+ await Promise.allSettled(operations.splice(0));+ for (const client of clients.splice(0)) await client.close();+ for (const handle of fault.handles)+ if (handle.fd !== -1) await handle.close();+});++const fixture = async (text = '{"host":"127.0.0.1","port":49152}\n') => {+ const root = await createTestTempDirectory("rea-endpoint-lifetime-");+ fault.path = join(root, "bridge-endpoint.json");+ await writeFile(fault.path, text);+ return {+ endpoint: {+ transport: "authenticated-loopback-tcp" as const,+ path: fault.path,+ },+ resources: new ArtifactResourceScope(),+ };+};++it.skipIf(process.platform === "win32").each(["valid", "invalid"] as const)(+ "retains the exact descriptor and %s endpoint outcome after close failure",+ async (kind) => {+ const { endpoint, resources } = await fixture(+ kind === "valid" ? undefined : "{",+ );+ fault.blocked = true;+ const result = await observeGhidraEndpoint(endpoint, {+ resourceScope: resources,+ });+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "start", cleanupFailure: { cleanupIncomplete: true } },+ });+ if (result.ok) throw new Error("Expected typed endpoint failure");+ const failure = result.error;+ if (kind === "invalid")+ expect(failure.message).toBe("Ghidra TCP endpoint is invalid");+ expect(fault.handles[0]?.fd).not.toBe(-1);+ expect(resources.hasPending).toBe(true);+ fault.blocked = false;+ await resources.retryCleanup();+ expect(fault.handles[0]?.fd).toBe(-1);+ expect(failure.cleanupFailure?.cleanupIncomplete).toBe(false);+ },+);++it.skipIf(process.platform === "win32")(+ "observes exact null cancellation during the endpoint's final close",+ async () => {+ const { endpoint, resources } = await fixture();+ const controller = new AbortController();+ fault.abortClose = controller;+ const result = await observeGhidraEndpoint(endpoint, {+ resourceScope: resources,+ signal: controller.signal,+ });+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "cancelled", cancellation: { reason: null } },+ });+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ },+);++it.skipIf(process.platform === "win32").each(["released", "failed"] as const)(+ "preserves endpoint IO failure during cancellation and %s close",+ async (closing) => {+ const { endpoint, resources } = await fixture();+ const controller = new AbortController();+ const cause = Object.assign(new Error("controlled endpoint EIO"), {+ code: "EIO",+ });+ fault.readFailure = cause;+ fault.abortRead = controller;+ fault.blocked = closing === "failed";+ const result = await observeGhidraEndpoint(endpoint, {+ resourceScope: resources,+ signal: controller.signal,+ });+ if (result.ok) throw new Error("Expected IO failure");+ expect(result.error.kind).toBe("start");+ expect(result.error.cause).toBe(cause);+ if (closing === "failed")+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(true);+ fault.blocked = false;+ await resources.retryCleanup();+ expect(result.error.cleanupFailure?.cleanupIncomplete ?? false).toBe(false);+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ },+);++it.skipIf(process.platform === "win32")(+ "keeps endpoint observation admitted until its read and close finish",+ async () => {+ const { endpoint, resources } = await fixture();+ let entered: (() => void) | undefined;+ const observed = new Promise<void>((resolve) => {+ entered = resolve;+ });+ const gate = new Promise<void>((resolve) => {+ releaseRead = resolve;+ });+ fault.readGate = async () => {+ entered?.();+ await gate;+ };+ const pending = observeGhidraEndpoint(endpoint, {+ resourceScope: resources,+ });+ operations.push(pending);+ await observed;+ let closed = false;+ const closing = resources.close().then(() => {+ closed = true;+ });+ operations.push(closing);+ await new Promise<void>((resolve) => setImmediate(resolve));+ expect(closed).toBe(false);+ releaseRead?.();+ await expect(pending).resolves.toMatchObject({ ok: true });+ await closing;+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ },+);++it+ .skipIf(process.platform === "win32")+ .each(["completed", "cancelled"] as const)(+ "preserves endpoint and provider cleanup owners through %s startup and retry",+ async (kind) => {+ const launcher = new GhidraFixtureLauncher();+ const controller = new AbortController();+ fault.matchEndpoints = true;+ fault.blocked = true;+ if (kind === "cancelled") fault.abortClose = controller;+ const client = new GhidraClient({+ launcher,+ targetPath: ghidraFixturePath,+ targetSha256: createHash("sha256")+ .update(await readFile(ghidraFixturePath))+ .digest("hex"),+ transport: "authenticated-loopback-tcp",+ providerVersion: "12.1.4",+ profileDigest: "a".repeat(64),+ startupTimeoutMs: 5000,+ });+ clients.push(client);+ const result = await client.start(controller.signal);+ if (result.ok) throw new Error("Expected endpoint finalization failure");+ expect(result.error.kind).toBe(+ kind === "cancelled" ? "cancelled" : "start",+ );+ if (kind === "cancelled")+ expect(result.error.cancellation?.reason).toBe(null);+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(true);+ expect(result.error.cleanupFailure?.cleanupResources).toContain(+ launcher.endpointPaths[0],+ );+ expect(fault.handles.some((handle) => handle.fd !== -1)).toBe(true);+ fault.blocked = false;+ fault.abortClose = undefined;+ await expect(client.close()).resolves.toEqual({ ok: true, value: null });+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(false);+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ const child = launcher.processes[0];+ if (child === undefined)+ throw new Error("Expected admitted fixture process");+ expect(await waitForExit(child, 5000)).toBe(true);+ await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({+ code: "ENOENT",+ });+ },+);++it.skipIf(process.platform === "win32")(+ "rejects endpoint pathname replacement instead of reporting readiness",+ async () => {+ const { endpoint, resources } = await fixture();+ fault.readGate = async () => {+ fault.readGate = undefined;+ await rename(endpoint.path, endpoint.path + ".old");+ await writeFile(endpoint.path, '{"host":"127.0.0.1","port":49153}\n');+ };+ await expect(+ observeGhidraEndpoint(endpoint, { resourceScope: resources }),+ ).resolves.toMatchObject({+ ok: false,+ error: {+ kind: "start",+ message: "Ghidra TCP endpoint changed during observation",+ },+ });+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ },+);++it.skipIf(process.platform === "win32")(+ "rejects an oversized endpoint before reading its contents",+ async () => {+ const { endpoint, resources } = await fixture(" ".repeat(65537));+ await expect(+ observeGhidraEndpoint(endpoint, { resourceScope: resources }),+ ).resolves.toMatchObject({+ ok: false,+ error: { kind: "start", cause: { reason: "limit" } },+ });+ expect(fault.reads).toBe(0);+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ },+);++it.skipIf(process.platform === "win32")(+ "rejects a FIFO endpoint through the compiled observer without a writer",+ async () => {+ const { endpoint } = await fixture();+ await rename(endpoint.path, endpoint.path + ".old");+ await promisify(execFile)("mkfifo", [endpoint.path]);+ const module = pathToFileURL(+ join(process.cwd(), "dist/ghidra/GhidraTransport.js"),+ ).href;+ const script = `+ const { observeGhidraEndpoint } = await import(${JSON.stringify(module)});+ const result = await observeGhidraEndpoint({ transport: "authenticated-loopback-tcp", path: process.argv[1] });+ if (result.ok) throw new Error("Unexpected FIFO readiness");+ process.stdout.write(JSON.stringify({ kind: result.error.kind, code: result.error.cause.code }));+ `;+ const result = await promisify(execFile)(+ process.execPath,+ ["--input-type=module", "--eval", script, endpoint.path],+ { timeout: 5000 },+ );+ expect(JSON.parse(result.stdout)).toEqual({+ kind: "start",+ code: "ENOTFILE",+ });+ },+);++it+ .skipIf(process.platform === "win32")+ .each([null, "caller stopped", new Error("caller stopped")])(+ "rejects pre-aborted endpoint admission with exact reason %j",+ async (reason) => {+ const { endpoint, resources } = await fixture();+ const controller = new AbortController();+ controller.abort(reason);+ const result = await observeGhidraEndpoint(endpoint, {+ resourceScope: resources,+ signal: controller.signal,+ });+ if (result.ok) throw new Error("Expected pre-admission cancellation");+ expect(result.error.kind).toBe("cancelled");+ expect(result.error.cancellation?.reason).toBe(reason);+ expect(fault.handles).toEqual([]);+ },+);diff --git a/tests/process-global/ghidraImportSnapshotLifetime.test.ts b/tests/process-global/ghidraImportSnapshotLifetime.test.tsnew file mode 100644index 000000000..c4e81fb5b--- /dev/null+++ b/tests/process-global/ghidraImportSnapshotLifetime.test.ts@@ -0,0 +1,390 @@+import { createHash } from "node:crypto";+import { mkdir, readFile, writeFile, type FileHandle } from "node:fs/promises";+import { basename, join } from "node:path";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++const fault = vi.hoisted(() => ({+ source: "",+ handles: [] as FileHandle[],+ blocked: new Set<FileHandle>(),+ blockSource: false,+ controller: undefined as AbortController | undefined,+ readFailure: undefined as Error | undefined,+ writeFailure: undefined as Error | undefined,+ blockDestination: false,+ abortDestinationClose: false,+ destinations: [] as FileHandle[],+ onClose: undefined as ((handle: FileHandle) => Promise<void>) | undefined,+}));+vi.mock("node:fs/promises", async (importOriginal) => {+ const original = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...original,+ open: async (...args: Parameters<typeof original.open>) => {+ const handle = await original.open(...args);+ const source = args[0] === fault.source;+ const destination =+ fault.source !== "" &&+ args[1] === "wx" &&+ typeof args[0] === "string" &&+ basename(args[0]).startsWith("target-");+ if (!source && !destination) return handle;+ if (source) {+ fault.handles.push(handle);+ if (fault.blockSource) fault.blocked.add(handle);+ const read = handle.read.bind(handle);+ handle.read = (async (...readArgs: unknown[]) => {+ if (fault.readFailure !== undefined) {+ fault.controller?.abort(null);+ throw fault.readFailure;+ }+ return await Reflect.apply(read, handle, readArgs);+ }) as FileHandle["read"];+ } else {+ fault.destinations.push(handle);+ if (fault.blockDestination) fault.blocked.add(handle);+ const write = handle.writeFile.bind(handle);+ handle.writeFile = async (...writeArgs) => {+ if (fault.writeFailure !== undefined) {+ fault.controller?.abort(null);+ throw fault.writeFailure;+ }+ return await write(...writeArgs);+ };+ }+ const close = handle.close.bind(handle);+ handle.close = async () => {+ await fault.onClose?.(handle);+ if (source || fault.abortDestinationClose)+ fault.controller?.abort(null);+ if (fault.blocked.has(handle))+ throw new Error("controlled Ghidra import descriptor close failure");+ await close();+ };+ return handle;+ },+ };+});++import { createGhidraTargetSnapshot } from "../../src/ghidra/GhidraTargetSnapshot.js";+import {+ ArtifactFileCleanupFailure,+ bindArtifactFileCleanup,+} from "../../src/artifacts/ArtifactFileOperation.js";+import { ArtifactResourceScope } from "../../src/artifacts/ArtifactResourceScope.js";+import { ProviderCleanupError } from "../../src/domain/providerCleanupError.js";+import { GhidraClient } from "../../src/ghidra/GhidraClient.js";+import { GhidraProvider } from "../../src/ghidra/GhidraProvider.js";+import { ghidraProfileInstallationHost } from "../../src/ghidra/GhidraInstallation.fixture.js";+import { parseConfig } from "../../src/config/parseConfig.js";+import { parseBinaryTarget } from "../../src/application/BinaryTargetResolver.js";+import { elf } from "../../src/domain/binaryTarget.fixture.js";+import { silentLogger } from "../../src/logger.js";+import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js";+import type { AnalysisClient } from "../../src/application/AnalysisProvider.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";++beforeEach(() => {+ fault.source = "";+ fault.handles = [];+ fault.blocked.clear();+ fault.blockSource = false;+ fault.controller = undefined;+ fault.readFailure = undefined;+ fault.writeFailure = undefined;+ fault.blockDestination = false;+ fault.abortDestinationClose = false;+ fault.destinations = [];+ fault.onClose = undefined;+});++it.each(["read", "write"] as const)(+ "retains an existing %s IO failure when the final startup caller cancels",+ async (stage) => {+ const { client, launches } = await providerFixture();+ const controller = new AbortController();+ fault.controller = controller;+ const cause = Object.assign(new Error(`controlled ${stage} EIO`), {+ code: "EIO",+ });+ if (stage === "read") fault.readFailure = cause;+ else fault.writeFailure = cause;+ const result = await client.execute(+ "health",+ {},+ { signal: controller.signal },+ );+ if (result.ok) throw new Error("Expected existing IO failure");+ expect(result.error).toMatchObject({+ _tag: "ProviderAdapterError",+ cleanupIncomplete: false,+ diagnostics: { failure_kind: "start" },+ });+ expect(result.error.cause).toMatchObject({ kind: "start", cause });+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ expect(fault.destinations.every((handle) => handle.fd === -1)).toBe(true);+ expect(launches()).toBe(0);+ },+);+const clients: AnalysisClient[] = [];+afterEach(async () => {+ fault.blocked.clear();+ fault.controller = undefined;+ fault.onClose = undefined;+ for (const client of clients.splice(0)) await client.close();+ for (const handle of [...fault.handles, ...fault.destinations])+ if (handle.fd !== -1) await handle.close();+});++const fixture = async () => {+ const root = await createTestTempDirectory("rea-ghidra-import-lifetime-");+ const path = join(root, "source.bin");+ const runtime = join(root, "runtime");+ await mkdir(runtime);+ const bytes = Buffer.from("committed Ghidra import bytes");+ await writeFile(path, bytes);+ fault.source = path;+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ return { path, runtime, sha256 };+};++it.each(["completed", "mismatch"] as const)(+ "retains the exact source descriptor and %s import outcome when close fails",+ async (kind) => {+ const { path, runtime, sha256 } = await fixture();+ fault.blockSource = true;+ const failure = await createGhidraTargetSnapshot(+ path,+ runtime,+ kind === "completed" ? sha256 : "0".repeat(64),+ { platform: "linux" },+ ).catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(ArtifactFileCleanupFailure);+ if (!(failure instanceof ArtifactFileCleanupFailure))+ throw new Error("Expected exact descriptor outcome and cleanup owner");+ expect(failure.fileCleanupFailure.owner.handle).toBe(fault.handles[0]);+ expect(failure.fileCleanupFailure.outcome).toMatchObject(+ kind === "completed"+ ? { kind: "completed", value: { sha256 } }+ : { kind: "failed", cause: { _tag: "AnalysisArtifactChangedError" } },+ );+ fault.blocked.clear();+ await failure.cleanupLease.release();+ expect(fault.handles[0]?.fd).toBe(-1);+ },+);++it("retains the exact caller reason when cancelled during import descriptor close", async () => {+ const { path, runtime, sha256 } = await fixture();+ const controller = new AbortController();+ fault.controller = controller;+ await expect(+ createGhidraTargetSnapshot(path, runtime, sha256, {+ platform: "linux",+ signal: controller.signal,+ }),+ ).rejects.toMatchObject({+ reason: "cancelled",+ cancellation: { reason: null },+ });+});++it("waits for mixed finalization and resolves cleanup only after both exact descriptors release", async () => {+ const { path, runtime, sha256 } = await fixture();+ fault.blockSource = true;+ fault.blockDestination = true;+ let release: () => void = () => {};+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ let entered = false;+ fault.onClose = async (handle) => {+ if (fault.destinations.includes(handle)) {+ entered = true;+ await gate;+ }+ };+ const resources = new ArtifactResourceScope();+ let settled = false;+ const running = createGhidraTargetSnapshot(path, runtime, sha256, {+ platform: "linux",+ resourceScope: resources,+ }).catch((cause: unknown) => {+ settled = true;+ return cause;+ });+ try {+ await expect.poll(() => entered).toBe(true);+ expect(settled).toBe(false);+ release();+ const failure = await running;+ expect(failure).toBeInstanceOf(ArtifactFileCleanupFailure);+ if (!(failure instanceof ArtifactFileCleanupFailure))+ throw new Error("Expected outer source owner");+ const physical = failure.fileCleanupFailure.outcome;+ if (+ physical.kind !== "failed" ||+ !(physical.cause instanceof ArtifactFileCleanupFailure)+ )+ throw new Error("Expected nested destination owner");+ const destination = physical.cause;+ expect(failure.fileCleanupFailure.owner.handle).toBe(fault.handles[0]);+ expect(destination.fileCleanupFailure.owner.handle).toBe(+ fault.destinations[0],+ );+ expect(failure.cleanupLeases).toHaveLength(2);+ const projected = new ProviderCleanupError(+ "ghidra",+ failure.cleanup?.resources ?? [],+ { reason: "controlled mixed cleanup" },+ );+ bindArtifactFileCleanup(failure, projected);+ fault.blocked.delete(fault.destinations[0]!);+ await destination.cleanupLease.release();+ expect(projected.cleanupIncomplete).toBe(true);+ fault.blocked.clear();+ await resources.close();+ expect(projected.cleanupIncomplete).toBe(false);+ } finally {+ release();+ await running;+ fault.blocked.clear();+ await resources.close();+ }+});++const providerFixture = async () => {+ const { path } = await fixture();+ fault.source = "";+ await writeFile(path, elf(2, 1, 62));+ const target = await parseBinaryTarget(path);+ if (!target.ok) throw target.error;+ const config = parseConfig({ GHIDRA_INSTALL_DIR: "/simulated-ghidra" });+ if (!config.ok) throw config.error;+ let launches = 0;+ const provider = new GhidraProvider(+ config.value,+ silentLogger,+ {},+ ghidraProfileInstallationHost,+ (options) =>+ new GhidraClient({+ ...options,+ launcher: {+ launch: async () => {+ launches += 1;+ throw new Error("Snapshot failure must prevent engine launch");+ },+ },+ }),+ );+ const resolved = await provider.resolveAnalysisProfile(target.value);+ if (!resolved.ok || resolved.value.profile === null)+ throw new Error("Expected simulated profile admission");+ const client = provider.createClient(target.value, resolved.value.profile);+ clients.push(client);+ fault.source = path;+ return { client, path, launches: () => launches };+};++it.each([null, "caller reason", new Error("caller cancellation")])(+ "preserves pre-admission startup cancellation reason: %s",+ async (reason) => {+ const { client, launches } = await providerFixture();+ const controller = new AbortController();+ controller.abort(reason);+ const result = await client.execute(+ "health",+ {},+ { signal: controller.signal },+ );+ if (result.ok) throw new Error("Expected cancelled admission");+ expect(result.error).toMatchObject({ _tag: "AnalysisCancelledError" });+ expect(result.error.cause).toBe(reason);+ expect(fault.handles).toHaveLength(0);+ expect(launches()).toBe(0);+ },+);++it.each([+ "mismatch",+ "denied",+ "cancelled",+ "cancelled_after_failed_close",+] as const)(+ "preserves public %s classification and live cleanup recovery",+ async (kind) => {+ const { client, path, launches } = await providerFixture();+ fault.blockSource = true;+ fault.blockDestination = true;+ const controller = new AbortController();+ if (kind === "mismatch")+ await writeFile(path, "changed after target admission");+ if (kind === "denied")+ fault.readFailure = Object.assign(+ new Error("controlled source permission failure"),+ { code: "EACCES", path },+ );+ if (kind.startsWith("cancelled")) fault.controller = controller;+ if (kind === "cancelled") fault.abortDestinationClose = true;+ const result = await client.execute(+ "health",+ {},+ { signal: controller.signal },+ );+ if (result.ok) throw new Error("Expected failed snapshot admission");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ diagnostics: {+ primary_error: {+ code:+ kind === "mismatch"+ ? "artifact_changed"+ : kind === "denied"+ ? "access_denied"+ : kind === "cancelled"+ ? "cancelled"+ : "execution_failure",+ },+ },+ },+ });+ if (kind === "cancelled") {+ expect(result.error.cause).toBeInstanceOf(AggregateError);+ if (!(result.error.cause instanceof AggregateError))+ throw new Error("Expected composed primary");+ expect(result.error.cause.cause).toMatchObject({+ _tag: "AnalysisCancelledError",+ cause: null,+ });+ }+ const close = await client.close();+ expect(close.ok).toBe(false);+ fault.blocked.clear();+ await expect(client.close()).resolves.toMatchObject({ ok: true });+ expect(result.error.cleanupIncomplete).toBe(false);+ if (!close.ok) expect(close.error.cleanupIncomplete).toBe(false);+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+ expect(launches()).toBe(0);+ },+);++it("copies every byte across chunk boundaries through the destination owner", async () => {+ const { path, runtime } = await fixture();+ const bytes = Buffer.alloc(256 * 1024 + 37);+ for (let index = 0; index < bytes.length; index++)+ bytes[index] = (index * 37 + Math.floor(index / 65536)) % 251;+ await writeFile(path, bytes);+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ const snapshot = await createGhidraTargetSnapshot(path, runtime, sha256, {+ platform: "linux",+ });+ expect(await readFile(snapshot.path)).toEqual(bytes);+ expect(snapshot.sha256).toBe(sha256);+ expect(+ [...fault.handles, ...fault.destinations].every(+ (handle) => handle.fd === -1,+ ),+ ).toBe(true);+});diff --git a/tests/process-global/ghidraLaunchRollback.test.ts b/tests/process-global/ghidraLaunchRollback.test.tsnew file mode 100644index 000000000..f894f30ae--- /dev/null+++ b/tests/process-global/ghidraLaunchRollback.test.ts@@ -0,0 +1,304 @@+import { createHash, randomUUID } from "node:crypto";+import { access, readFile } from "node:fs/promises";+import { join } from "node:path";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++const fault = vi.hoisted(() => ({+ failure: new Error("controlled manifest failure"),+}));+vi.mock("write-file-atomic", async (importOriginal) => {+ const actual = await importOriginal<{+ default: typeof import("write-file-atomic");+ }>();+ return {+ default: async (...args: Parameters<typeof actual.default>) => {+ if (typeof args[0] === "string" && args[0].endsWith("/ownership.json"))+ throw fault.failure;+ return actual.default(...args);+ },+ };+});++import {+ GhidraHeadlessLauncher,+ GhidraLaunchError,+ type GhidraLaunchSession,+} from "../../src/ghidra/GhidraLauncher.js";+import { bindGhidraSessionFailure } from "../../src/ghidra/GhidraSessionError.js";+import { GhidraClient } from "../../src/ghidra/GhidraClient.js";+import {+ spawnOwnedProviderProcess,+ type SpawnedOwnedProviderProcess,+} from "../../src/process/ProviderProcess.js";+import {+ cleanupOwnedProcessGroup,+ type ProcessCleanupFailure,+} from "../../src/process/ProcessOwnership.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+import { ghidraFixturePath } from "../boundary/providers/ghidra/ghidraClient.fixture.js";++const owners: SpawnedOwnedProviderProcess[] = [];+const clients: GhidraClient[] = [];+let denyCleanup = true;+beforeEach(() => {+ denyCleanup = true;+});+afterEach(async () => {+ denyCleanup = false;+ for (const client of clients.splice(0)) await client.close();+ for (const owner of owners.splice(0))+ expect(await cleanupOwnedProcessGroup(owner.ownership)).toMatchObject({+ cleaned: true,+ });+});++const incomplete: ProcessCleanupFailure = {+ cleaned: false,+ reason: "mixed fixture outcomes",+ failures: [+ {+ pid: 123,+ reason: "process-identity-unavailable",+ diagnostic: "controlled identity uncertainty",+ },+ ],+ unverified: [{ pid: 456, diagnostic: "controlled observation unavailable" }],+};+const fixture = async (rollback: () => Promise<ProcessCleanupFailure>) => {+ const root = await createTestTempDirectory("rea-launch-rollback-");+ const launcher = new GhidraHeadlessLauncher({+ configurationDirectoryName: "ghidra_12.1.4_PUBLIC",+ environment: {},+ platform: process.platform,+ analyzeHeadlessPath: join(root, "support", "analyzeHeadless"),+ javaHome: join(root, "jdk"),+ bridgeScriptPath: join(root, "ReaGhidraBridge.java"),+ javaLaunch: async () => ({+ command: process.execPath,+ arguments: ["-e", "setInterval(()=>{},1000)"],+ environment: {},+ }),+ spawnProcess: async (options) => {+ const spawned = await spawnOwnedProviderProcess(options);+ owners.push(spawned);+ return {+ ...spawned,+ cleanup: () =>+ denyCleanup+ ? rollback()+ : cleanupOwnedProcessGroup(spawned.ownership),+ };+ },+ });+ const session: GhidraLaunchSession = {+ runtimeRoot: root,+ transport: "unix-socket",+ endpointPath: join(root, "bridge.sock"),+ token: "fixture-token",+ runId: randomUUID(),+ targetPath: join(root, "unused-target"),+ targetSha256: "a".repeat(64),+ providerVersion: "test",+ profileDigest: "b".repeat(64),+ };+ return { launcher, session };+};++it+ .skipIf(process.platform === "win32")+ .each([undefined, new Error("rollback rejected")] as const)(+ "retains the process owner after rollback rejects with %s",+ async (rejection) => {+ const { launcher, session } = await fixture(async () => {+ throw rejection;+ });+ const result = await launcher.launch(session);+ expect(result.ok).toBe(false);+ if (result.ok || !(result.error instanceof GhidraLaunchError))+ throw new Error("Expected launch failure");+ expect(result.error.partialLaunch).toBeDefined();+ expect(result.error).toMatchObject({+ rollbackFailure: { kind: "rejected", cause: rejection },+ });+ expect(owners[0]?.process.exitCode).toBeNull();+ denyCleanup = false;+ expect(await result.error.partialLaunch?.cleanup?.()).toMatchObject({+ cleaned: true,+ });+ },+);++it.skipIf(process.platform === "win32")(+ "retains structured mixed-member rollback evidence through session projection",+ async () => {+ const { launcher, session } = await fixture(async () => incomplete);+ const result = await launcher.launch(session);+ if (result.ok || !(result.error instanceof GhidraLaunchError))+ throw new Error("Expected launch failure");+ expect(result.error.partialLaunch).toBeDefined();+ expect(result.error).toMatchObject({+ rollbackFailure: { kind: "incomplete", result: incomplete },+ });+ const projected = bindGhidraSessionFailure(() => ({}))(+ "start",+ result.error.message,+ result.error,+ );+ expect(projected.diagnostics).toMatchObject({+ failure_cause: {+ rollback_failure: { kind: "incomplete", result: incomplete },+ },+ });+ denyCleanup = false;+ expect(await result.error.partialLaunch?.cleanup?.()).toMatchObject({+ cleaned: true,+ });+ },+);++it.skipIf(process.platform === "win32")(+ "client adopts a rejected rollback owner and retries before removing its runtime",+ async () => {+ const { launcher } = await fixture(async () => {+ throw undefined;+ });+ const target = await readFile(ghidraFixturePath);+ let runtimeRoot: string | undefined;+ const client = new GhidraClient({+ launcher: {+ launch: (session, options) => {+ runtimeRoot = session.runtimeRoot;+ return launcher.launch(session, options);+ },+ },+ targetPath: ghidraFixturePath,+ targetSha256: createHash("sha256").update(target).digest("hex"),+ providerVersion: "test",+ profileDigest: "b".repeat(64),+ startupTimeoutMs: 5000,+ });+ clients.push(client);+ const result = await client.start();+ expect(result).toMatchObject({+ ok: false,+ error: { kind: "start", cleanupFailure: { cleanupIncomplete: true } },+ });+ if (result.ok) throw new Error("Expected failed startup");+ expect(owners[0]?.process.exitCode).toBeNull();+ if (runtimeRoot === undefined)+ throw new Error("Expected admitted runtime root");+ await expect(access(runtimeRoot)).resolves.toBeUndefined();+ denyCleanup = false;+ expect(await client.close()).toMatchObject({ ok: true });+ expect(result.error.cleanupFailure?.cleanupIncomplete).toBe(false);+ await expect(access(runtimeRoot)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.skipIf(process.platform === "win32")(+ "retains synchronous rollback rejection and the earlier failure during cancellation",+ async () => {+ const controller = new AbortController();+ const { launcher, session } = await fixture(() => {+ controller.abort(null);+ throw undefined;+ });+ const result = await launcher.launch(session, {+ signal: controller.signal,+ });+ if (result.ok || !(result.error instanceof GhidraLaunchError))+ throw new Error("Expected launch failure");+ expect(result.error.rollbackFailure).toEqual({+ kind: "rejected",+ cause: undefined,+ });+ expect(result.error.cause).toBeInstanceOf(AggregateError);+ if (!(result.error.cause instanceof AggregateError))+ throw new Error("Expected composite failure");+ expect(result.error.cause.errors[0]).toMatchObject({+ cause: fault.failure,+ });+ expect(result.error.cause.errors[1]).toBeUndefined();+ expect(result.error.partialLaunch).toBeDefined();+ denyCleanup = false;+ expect(await result.error.partialLaunch?.cleanup?.()).toMatchObject({+ cleaned: true,+ });+ },+);++it("bounds and redacts rollback evidence with explicit truncation", () => {+ const value = "sensitive-transport-token";+ const result: ProcessCleanupFailure = {+ cleaned: false,+ reason: value + "x".repeat(4096),+ failures: [+ {+ pid: 1,+ reason: "run-token-mismatch",+ diagnostic: value + "y".repeat(4096),+ },+ ],+ unverified: [{ pid: 2, diagnostic: value + "z".repeat(4096) }],+ };+ const launch = new GhidraLaunchError("primary", {+ rollbackFailure: { kind: "incomplete", result },+ });+ const projected = bindGhidraSessionFailure(+ () => ({}),+ (text) => text.replaceAll(value, "[REDACTED]"),+ )("start", "primary", launch);+ expect(JSON.stringify(projected.diagnostics)).not.toContain(value);+ expect(projected.diagnostics).toMatchObject({+ failure_cause: {+ rollback_failure: {+ result: {+ reason_truncated: true,+ failures: [{ diagnostic_truncated: true }],+ unverified: [{ diagnostic_truncated: true }],+ },+ },+ },+ });+});++it("bounds aggregate member evidence and retains complete producer facts", () => {+ const rows = Array.from({ length: 500 }, (_, pid) => ({+ pid,+ diagnostic: "\u0001".repeat(2000),+ }));+ const result: ProcessCleanupFailure = {+ cleaned: false,+ reason: "many controlled members",+ failures: rows.map((row) => ({+ ...row,+ reason: "process-identity-unavailable" as const,+ })),+ unverified: rows,+ };+ const launch = new GhidraLaunchError("primary", {+ rollbackFailure: { kind: "incomplete", result },+ });+ const projected = bindGhidraSessionFailure(() => ({}))(+ "start",+ "primary",+ launch,+ );+ const cause = projected.diagnostics["failure_cause"] as {+ rollback_failure: {+ result: {+ failures: unknown[];+ unverified: unknown[];+ failures_omitted?: number;+ unverified_omitted?: number;+ };+ };+ };+ const output = cause.rollback_failure.result;+ expect(output.failures.length + (output.failures_omitted ?? 0)).toBe(500);+ expect(output.unverified.length + (output.unverified_omitted ?? 0)).toBe(500);+ expect(Buffer.byteLength(JSON.stringify(projected.diagnostics))).toBeLessThan(+ 10 * 1024,+ );+ expect(launch.rollbackFailure).toEqual({ kind: "incomplete", result });+});