Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(lifecycle): retain exact cleanup owners when close or prelaunch fails (#6357)

morluto7501911f1781
diff --git a/src/hopper/HopperFileOffset.ts b/src/hopper/HopperFileOffset.ts
index 453a14484..fbb6cf7f2 100644
--- a/src/hopper/HopperFileOffset.ts
+++ b/src/hopper/HopperFileOffset.ts
@@ -4,6 +4,7 @@ import { open, type FileHandle } from "node:fs/promises";
import { z } from "zod";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import {
AnalysisAccessDeniedError,
AnalysisArtifactChangedError,
@@ -12,6 +13,14 @@ import {
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";
+import {
+ RegularFileCancelled,
+ RegularFileCleanupFailure,
+ withOwnedFileHandle,
+} from "../filesystem/OwnedRegularFile.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { FileOffsetPartialObservation } from "../domain/native/fileOffsetPartialObservation.js";
@@ -36,11 +45,20 @@ const observationSchema = z.strictObject({
});
type Observation = z.infer<typeof observationSchema>;
+/** Exact descriptor owner the caller retries after a rejected source close. */
+export interface HopperFileOffsetOwnership {
+ readonly signal?: AbortSignal;
+ /** Adopt the handle whose close rejected; the caller owns later retries. */
+ readonly retainFailedClose?: (owner: OwnedFileHandle) => void;
+ /** Bind the typed cleanup marker to that same owner before it is returned. */
+ readonly onCleanupMarker?: (marker: ProviderCleanupError) => void;
+}
+
/** Bind native image-relative offsets to coordinates in the admitted source bytes. */
export async function mapHopperFileOffset(
target: BinaryTarget,
value: JsonValue,
- signal?: AbortSignal,
+ ownership?: HopperFileOffsetOwnership,
): Promise<Result<JsonValue, AnalysisError>> {
const parsed = observationSchema.safeParse(value);
if (!parsed.success)
@@ -66,90 +84,252 @@ export async function mapHopperFileOffset(
return unavailable(
"The selected database digest does not identify its original executable bytes. Open that executable to verify original-file coordinates; read_bytes still exposes the database's native bytes.",
);
- if (signal?.aborted)
- return err(
- new AnalysisCancelledError(OPERATION, {
- partialObservation: partial("Source verification was cancelled"),
- }),
- );
+ const signal = ownership?.signal;
+ if (signal?.aborted) return err(cancelled(partial, signal.reason));
+ const publish = (marker: ProviderCleanupError): ProviderCleanupError => {
+ ownership?.onCleanupMarker?.(marker);
+ return marker;
+ };
+ const verification: OffsetVerification = {
+ target,
+ observation,
+ partial,
+ unavailable,
+ signal,
+ publish,
+ withCleanup: (primary, marker) =>
+ analysisErrorWithCleanupFailure(
+ primary,
+ publish(marker),
+ OPERATION,
+ ).bindCleanupDependencies([marker]),
+ };
try {
- const captured = await snapshotFromPath(target.path, signal);
- if (!captured.ok)
- return err(
- new AnalysisArtifactChangedError(
- OPERATION,
- target.path,
- captured.error,
- {
- partialObservation: partial(captured.error),
- },
- ),
- );
- const snapshot = captured.value;
- if (signal?.aborted)
- return err(
- new AnalysisCancelledError(OPERATION, {
- partialObservation: partial("Source verification was cancelled"),
- }),
- );
- if (snapshot.sha256 !== target.sha256) {
- const reason = `Source ${target.path} differs from the admitted artifact: expected SHA-256 ${target.sha256}, observed ${snapshot.sha256}. Reopen the changed source for a new analysis identity.`;
- return err(
- new AnalysisArtifactChangedError(OPERATION, target.path, reason, {
- partialObservation: partial(reason),
- }),
- );
+ const captured = await snapshotFromPath(
+ target.path,
+ signal,
+ ownership?.retainFailedClose,
+ );
+ return coordinatesForSnapshot(verification, captured).result;
+ } catch (cause: unknown) {
+ if (cause instanceof RegularFileCleanupFailure)
+ return cleanupAfterSnapshot(verification, cause);
+ if (cause instanceof RegularFileCancelled) {
+ const captured = cause.outcome.value;
+ if (!isSourceRead(captured)) throw cause;
+ if (!captured.ok)
+ return err(
+ artifactChanged(target.path, captured.error, partial(captured.error)),
+ );
+ return err(cancelled(partial, cause.reason));
}
- const mapped = originalOffset(snapshot, observation);
- if (!mapped.ok) return unavailable(mapped.error);
- return ok({
- address: observation.address,
- file_offset: mapped.value + observation.provider_file_offset,
- provider_file_offset: observation.provider_file_offset,
- image_base_file_offset: mapped.value,
- source_path: target.path,
+ return err(sourceAccessFailure(target.path, cause, partial, signal));
+ }
+}
+
+async function snapshotFromPath(
+ path: string,
+ signal: AbortSignal | undefined,
+ retainFailedClose: HopperFileOffsetOwnership["retainFailedClose"],
+): Promise<Result<SourceSnapshot, string>> {
+ const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+ return withOwnedFileHandle(
+ path,
+ new OwnedFileHandle(handle),
+ {
+ ...(signal === undefined ? {} : { signal }),
+ ...(retainFailedClose === undefined ? {} : { retainFailedClose }),
+ },
+ async (file) => {
+ if (!(await file.stat()).isFile())
+ return err(
+ `Source ${path} is no longer a regular file. Restore the admitted executable or reopen a regular source.`,
+ );
+ return ok(await readSourceSnapshot(file, signal));
+ },
+ );
+}
+
+const isSourceRead = (
+ value: unknown,
+): value is Result<SourceSnapshot, string> =>
+ typeof value === "object" &&
+ value !== null &&
+ "ok" in value &&
+ (value.ok === true || value.ok === false);
+
+const cancelled = (
+ partial: (reason: string) => FileOffsetPartialObservation,
+ cause?: unknown,
+): AnalysisCancelledError =>
+ new AnalysisCancelledError(OPERATION, {
+ ...(cause === undefined ? {} : { cause }),
+ partialObservation: partial("Source verification was cancelled"),
+ });
+
+const artifactChanged = (
+ path: string,
+ reason: string,
+ partialObservation: FileOffsetPartialObservation,
+): AnalysisArtifactChangedError =>
+ new AnalysisArtifactChangedError(OPERATION, path, reason, {
+ partialObservation,
+ });
+
+/** Classify a failed read. A rejected close never reaches this helper. */
+const sourceAccessFailure = (
+ path: string,
+ cause: unknown,
+ partial: (reason: string) => FileOffsetPartialObservation,
+ signal: AbortSignal | undefined,
+): AnalysisError => {
+ if (
+ signal?.aborted === true ||
+ cause instanceof RegularFileOperationCancelled
+ )
+ return cancelled(
+ partial,
+ cause instanceof RegularFileOperationCancelled
+ ? cause.reason
+ : signal?.reason,
+ );
+ const reason = `Cannot verify original source bytes: ${cause instanceof Error ? cause.message : String(cause)}`;
+ const code =
+ typeof cause === "object" && cause !== null && "code" in cause
+ ? cause.code
+ : undefined;
+ if (code === "EACCES" || code === "EPERM")
+ return new AnalysisAccessDeniedError(OPERATION, path, code, {
+ cause,
+ partialObservation: partial(reason),
});
- } catch (cause: unknown) {
- if (signal?.aborted)
- return err(
- new AnalysisCancelledError(OPERATION, {
- cause,
- partialObservation: partial("Source verification was cancelled"),
- }),
- );
- const reason = `Cannot verify original source bytes: ${cause instanceof Error ? cause.message : String(cause)}`;
- const code =
- typeof cause === "object" && cause !== null && "code" in cause
- ? cause.code
- : undefined;
- if (code === "EACCES" || code === "EPERM")
- return err(
- new AnalysisAccessDeniedError(OPERATION, target.path, code, {
- cause,
- partialObservation: partial(reason),
- }),
- );
+ return new BinaryTargetError(path, reason, {
+ cause,
+ partialObservation: partial(reason),
+ });
+};
+
+const descriptorCleanup = (
+ failure: RegularFileCleanupFailure<unknown>,
+): ProviderCleanupError => {
+ const reason =
+ failure.cleanupCause instanceof Error
+ ? failure.cleanupCause.message
+ : String(failure.cleanupCause);
+ return new ProviderCleanupError(
+ "hopper",
+ [failure.path],
+ { reason },
+ { operation: OPERATION, cause: failure },
+ );
+};
+
+interface OffsetVerification {
+ readonly target: BinaryTarget;
+ readonly observation: Observation;
+ readonly partial: (reason: string) => FileOffsetPartialObservation;
+ readonly unavailable: (reason: string) => Result<JsonValue, AnalysisError>;
+ readonly signal: AbortSignal | undefined;
+ readonly withCleanup: (
+ primary: AnalysisError,
+ marker: ProviderCleanupError,
+ ) => AnalysisError;
+ readonly publish: (marker: ProviderCleanupError) => ProviderCleanupError;
+}
+
+const cleanupAfterSnapshot = (
+ verification: OffsetVerification,
+ failure: RegularFileCleanupFailure<unknown>,
+): Result<JsonValue, AnalysisError> => {
+ const { target, partial, signal, withCleanup, publish } = verification;
+ const marker = descriptorCleanup(failure);
+ if (failure.outcome.kind === "failed")
return err(
- new BinaryTargetError(target.path, reason, {
- cause,
- partialObservation: partial(reason),
- }),
+ withCleanup(
+ sourceAccessFailure(
+ target.path,
+ failure.outcome.cause,
+ partial,
+ signal,
+ ),
+ marker,
+ ),
);
- }
-}
+ if (!isSourceRead(failure.outcome.value)) throw failure;
+ const captured = failure.outcome.value;
+ if (!captured.ok)
+ return err(
+ withCleanup(
+ artifactChanged(target.path, captured.error, partial(captured.error)),
+ marker,
+ ),
+ );
+ if (signal?.aborted === true || failure.completionCancellation !== undefined)
+ return err(
+ withCleanup(
+ cancelled(
+ partial,
+ failure.completionCancellation?.reason ?? signal?.reason,
+ ),
+ marker,
+ ),
+ );
+ const verified = coordinatesForSnapshot(verification, captured);
+ if (!verified.result.ok)
+ return err(withCleanup(verified.result.error, marker));
+ const published = publish(marker);
+ published.retainPartialObservation(
+ partial(
+ "Source descriptor close failed after the admitted bytes were read",
+ ),
+ );
+ published.retainDiagnostics({
+ source_sha256: captured.value.sha256,
+ ...(verified.fileOffset === undefined
+ ? {}
+ : { file_offset: verified.fileOffset }),
+ source_identity: "verified",
+ });
+ return err(published);
+};
-async function snapshotFromPath(path: string, signal?: AbortSignal) {
- const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
- try {
- if (!(await file.stat()).isFile())
- return err(
- `Source ${path} is no longer a regular file. Restore the admitted executable or reopen a regular source.`,
- );
- return ok(await readSourceSnapshot(file, signal));
- } finally {
- await file.close();
+const coordinatesForSnapshot = (
+ verification: OffsetVerification,
+ captured: Result<SourceSnapshot, string>,
+): {
+ readonly result: Result<JsonValue, AnalysisError>;
+ readonly fileOffset?: number;
+} => {
+ const { target, observation, partial, unavailable, signal } = verification;
+ if (!captured.ok)
+ return {
+ result: err(
+ artifactChanged(target.path, captured.error, partial(captured.error)),
+ ),
+ };
+ const snapshot = captured.value;
+ if (signal?.aborted === true)
+ return { result: err(cancelled(partial, signal.reason)) };
+ if (snapshot.sha256 !== target.sha256) {
+ const reason = `Source ${target.path} differs from the admitted artifact: expected SHA-256 ${target.sha256}, observed ${snapshot.sha256}. Reopen the changed source for a new analysis identity.`;
+ return {
+ result: err(artifactChanged(target.path, reason, partial(reason))),
+ };
}
-}
+ const mapped = originalOffset(snapshot, observation);
+ if (!mapped.ok) return { result: unavailable(mapped.error) };
+ const fileOffset = mapped.value + observation.provider_file_offset;
+ return {
+ fileOffset,
+ result: ok({
+ address: observation.address,
+ file_offset: fileOffset,
+ provider_file_offset: observation.provider_file_offset,
+ image_base_file_offset: mapped.value,
+ source_path: target.path,
+ }),
+ };
+};
interface FatLayout {
readonly slices: readonly FatSliceDeclaration[];
diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.ts
index ce8c4e27c..8f2c9a4f9 100644
--- a/src/hopper/HopperProvider.ts
+++ b/src/hopper/HopperProvider.ts
@@ -22,15 +22,20 @@ import {
} from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Logger } from "pino";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
import { err, ok } from "../domain/result.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { AnalysisCleanupLeaseGroup } from "../artifacts/AnalysisCleanupLease.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
ArtifactResourceRetryFailure,
ArtifactResourceScope,
} from "../artifacts/ArtifactResourceScope.js";
+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { HopperApplicationLauncher } from "./BridgeLauncher.js";
import {
@@ -319,6 +324,17 @@ export class HopperProvider implements AnalysisProviderCandidate {
this.config.regexMatchingDeadline,
this.config.regexWorkerHeapRequest,
);
+ const sourceReads = new ArtifactResourceScope();
+ const sourceLeases = new WeakMap<OwnedFileHandle, AnalysisCleanupLease>();
+ const retainSourceDescriptor = (owner: OwnedFileHandle): void => {
+ const lease = AnalysisCleanupLease.forCloseOwner(owner, target.path);
+ sourceLeases.set(owner, lease);
+ sourceReads.retain({
+ kind: "lease",
+ resource: target.path,
+ lease,
+ });
+ };
const projectExecution = (
operation: AnalysisOperation,
normalized: JsonValue,
@@ -356,29 +372,48 @@ export class HopperProvider implements AnalysisProviderCandidate {
});
return {
execute: async (operation, parameters, options) => {
- const result =
- (operation === "search_strings" ||
- operation === "search_procedures") &&
- parameters.mode === "regex"
- ? await regexSearch.execute(operation, parameters, options)
- : await client.callTool(operation, parameters, options);
- if (!result.ok) return result;
- const mapped =
- operation === "address_to_file_offset"
- ? await mapHopperFileOffset(target, result.value, options?.signal)
- : result;
- if (!mapped.ok) return mapped;
- const inventory =
- operation === "list_names"
- ? projectHopperNameInventory(mapped.value)
- : { result: mapped.value, changed: false };
- return ok(
- projectExecution(
- operation,
- inventory.result,
- inventory.changed || mapped !== result ? result.value : null,
- ),
- );
+ try {
+ return await sourceReads.run(async () => {
+ const result =
+ (operation === "search_strings" ||
+ operation === "search_procedures") &&
+ parameters.mode === "regex"
+ ? await regexSearch.execute(operation, parameters, options)
+ : await client.callTool(operation, parameters, options);
+ if (!result.ok) return result;
+ const mapped =
+ operation === "address_to_file_offset"
+ ? await mapHopperFileOffset(target, result.value, {
+ ...(options?.signal === undefined
+ ? {}
+ : { signal: options.signal }),
+ retainFailedClose: retainSourceDescriptor,
+ onCleanupMarker: (marker) => {
+ if (!(marker.cause instanceof RegularFileCleanupFailure))
+ return;
+ sourceLeases
+ .get(marker.cause.owner)
+ ?.bindCleanupError(marker);
+ },
+ })
+ : result;
+ if (!mapped.ok) return mapped;
+ const inventory =
+ operation === "list_names"
+ ? projectHopperNameInventory(mapped.value)
+ : { result: mapped.value, changed: false };
+ return ok(
+ projectExecution(
+ operation,
+ inventory.result,
+ inventory.changed || mapped !== result ? result.value : null,
+ ),
+ );
+ });
+ } catch (cause: unknown) {
+ if (!(cause instanceof ArtifactReaderFailure)) throw cause;
+ return err(hopperSourceCleanupError(cause, operation));
+ }
},
executeIfReady: async (operation, parameters, options) => {
if (operation !== "list_documents" && operation !== "list_procedures")
@@ -418,8 +453,49 @@ export class HopperProvider implements AnalysisProviderCandidate {
operationHealthSnapshot: () => client.operationHealth(),
close: async (options) => {
await regexSearch.close();
- return client.close(options);
+ let descriptors: AnalysisError | undefined;
+ try {
+ await sourceReads.retryCleanup();
+ } catch (cause: unknown) {
+ if (!(cause instanceof ArtifactReaderFailure)) throw cause;
+ descriptors = hopperSourceCleanupError(cause, "close_binary");
+ }
+ const closed = await client.close(options);
+ if (descriptors === undefined) return closed;
+ return closed.ok
+ ? err(descriptors)
+ : err(
+ analysisErrorWithCleanupFailure(
+ closed.error,
+ descriptors,
+ "close_binary",
+ ).bindCleanupDependencies([closed.error, descriptors]),
+ );
},
};
}
}
+
+/** Report descriptor cleanup that is still owned by this Hopper client. */
+const hopperSourceCleanupError = (
+ cause: ArtifactReaderFailure,
+ operation: string,
+): AnalysisError => {
+ const leases = [
+ ...new Set(
+ cause instanceof ArtifactResourceRetryFailure
+ ? cause.cleanupLeases
+ : (cause.cleanupLeases ?? []),
+ ),
+ ];
+ const failure = new ProviderCleanupError(
+ HOPPER_PROVIDER_IDENTITY.id,
+ cause.cleanup?.resources ?? [
+ ...new Set(leases.flatMap((lease) => lease.cleanupResources ?? [])),
+ ],
+ { reason: cause.cleanup?.reason ?? cause.message },
+ { operation, cause },
+ );
+ if (leases.length > 0) new AnalysisCleanupLeaseGroup(failure, leases);
+ return failure;
+};
diff --git a/src/native/LldbCallTracer.ts b/src/native/LldbCallTracer.ts
index 47b6ddc3f..0130300c3 100644
--- a/src/native/LldbCallTracer.ts
+++ b/src/native/LldbCallTracer.ts
@@ -40,8 +40,13 @@ import {
ProviderStartupDeadline,
waitForAbortableDelay,
} from "../process/ProviderDeadline.js";
+import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
-import { resolveXcrunTool, type ResolvedTool } from "./CommandRunner.js";
+import {
+ NativeCommandFailure,
+ resolveXcrunTool,
+ type ResolvedTool,
+} from "./CommandRunner.js";
import { projectPartialNativeCalls } from "./NativeCallObservation.js";
import { LldbReadbackFiles } from "./LldbReadbackFiles.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
@@ -193,6 +198,11 @@ export class LldbCallTracer implements NativeCallTracer {
private readonly environment: NodeJS.ProcessEnv;
#tail: Promise<void> = Promise.resolve();
#pendingCleanup: RetainedLldbResources | undefined;
+ /** Resolver supervisors owned by this tracer, distinct from the shared Darwin reader. */
+ readonly #resolverCleanup = new Map<
+ ProviderProcessSupervisor,
+ ProviderCleanupError
+ >();
constructor(
environment: Readonly<NodeJS.ProcessEnv>,
private readonly launch: typeof runLldb = runLldb,
@@ -216,20 +226,12 @@ export class LldbCallTracer implements NativeCallTracer {
request: Parameters<NativeCallTracer["trace"]>[0],
signal?: AbortSignal,
): Promise<Result<NativeCallTrace, AnalysisError>> {
+ const resolverCleanup = await this.#retryResolverCleanup();
+ if (resolverCleanup !== undefined) return err(resolverCleanup);
const pendingCleanup = await this.#retryPendingCleanup();
if (pendingCleanup !== undefined) return err(pendingCleanup);
const lldb = await this.resolveTool("lldb", signal);
- if (!lldb.ok)
- return err(
- lldb.error.reason === "cancelled"
- ? new AnalysisCancelledError(OPERATION)
- : new AnalysisCapabilityUnavailableError(
- PROVIDER,
- OPERATION,
- LLDB_REQUIREMENT,
- { userMessage: LLDB_REQUIREMENT },
- ),
- );
+ if (!lldb.ok) return err(this.#discoveryFailure(lldb.error));
const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
const paths = lldbRuntimePaths(root.path);
const owner: RetainedLldbResources = {
@@ -373,7 +375,17 @@ export class LldbCallTracer implements NativeCallTracer {
}
async #close(): Promise<Result<null, AnalysisError>> {
+ const resolverCleanup = await this.#retryResolverCleanup();
const failure = await this.#retryPendingCleanup();
+ if (resolverCleanup !== undefined && failure !== undefined)
+ return err(
+ analysisErrorWithCleanupFailure(
+ resolverCleanup,
+ failure,
+ OPERATION,
+ ).bindCleanupDependencies([resolverCleanup, failure]),
+ );
+ if (resolverCleanup !== undefined) return err(resolverCleanup);
return failure === undefined ? ok(null) : err(failure);
}
@@ -445,6 +457,139 @@ export class LldbCallTracer implements NativeCallTracer {
);
}
+ /**
+ * Keep a tracer-owned resolver process for retry. A foreign helper marker
+ * stays on the preparation error and is not adopted here.
+ */
+ #retainResolverCleanup(failure: NativeCommandFailure): void {
+ const owned = [
+ ...failure.cleanupFailures.map((entry) => ({
+ owner: entry.owner,
+ marker: entry.marker,
+ reason: entry.reason,
+ resources: entry.resources,
+ })),
+ ...(failure.cleanupOwner === undefined
+ ? []
+ : [
+ {
+ owner: failure.cleanupOwner,
+ marker: failure.cleanupMarker,
+ reason:
+ failure.cleanupFailure ??
+ "LLDB resolver cleanup remains incomplete",
+ resources: [...failure.cleanupResources],
+ },
+ ]),
+ ];
+ for (const entry of owned) {
+ if (this.#resolverCleanup.has(entry.owner)) continue;
+ const marker =
+ entry.marker ??
+ new ProviderCleanupError(
+ PROVIDER,
+ entry.resources.length > 0
+ ? entry.resources
+ : ["lldb-resolver-process"],
+ { reason: entry.reason },
+ { operation: OPERATION, cause: failure },
+ );
+ this.#resolverCleanup.set(entry.owner, marker);
+ }
+ }
+
+ #discoveryFailure(failure: NativeCommandFailure): AnalysisError {
+ this.#retainResolverCleanup(failure);
+ const markers = [
+ ...new Set(
+ [
+ failure.cleanupOwner,
+ ...failure.cleanupFailures.map((entry) => entry.owner),
+ ].flatMap((owner) => {
+ if (owner === undefined) return [];
+ const marker = this.#resolverCleanup.get(owner);
+ return marker === undefined ? [] : [marker];
+ }),
+ ),
+ ];
+ const preparation = failure.preparationFailure;
+ if (preparation !== undefined)
+ return withResolverMarkers(lldbPreparationFailure(preparation), markers);
+ const cleanup =
+ markers.length === 0
+ ? undefined
+ : {
+ reason: markers
+ .map((marker) =>
+ typeof marker.diagnostics?.reason === "string"
+ ? marker.diagnostics.reason
+ : marker.message,
+ )
+ .join("; "),
+ resources: [
+ ...new Set(markers.flatMap((marker) => marker.cleanupResources)),
+ ],
+ };
+ const cleanupContext =
+ cleanup === undefined ? {} : { cause: failure, cleanup };
+ const error =
+ failure.reason === "cancelled"
+ ? new AnalysisCancelledError(OPERATION, {
+ ...(cleanup === undefined ? {} : { cleanup }),
+ ...(failure.cancellation === undefined
+ ? cleanup === undefined
+ ? {}
+ : { cause: failure }
+ : { cause: failure.cancellation.reason }),
+ })
+ : new AnalysisCapabilityUnavailableError(
+ PROVIDER,
+ OPERATION,
+ LLDB_REQUIREMENT,
+ { ...cleanupContext, userMessage: LLDB_REQUIREMENT },
+ );
+ return markers.length === 0
+ ? error
+ : error.bindCleanupDependencies(markers);
+ }
+
+ /** Retry only resolver processes this tracer spawned. */
+ async #retryResolverCleanup(): Promise<ProviderCleanupError | undefined> {
+ const retained = [...this.#resolverCleanup];
+ if (retained.length === 0) return undefined;
+ const unresolved: ProviderCleanupError[] = [];
+ for (const [owner, marker] of retained) {
+ let released = false;
+ try {
+ const stopped = await owner.stop();
+ released =
+ stopped.status !== "incomplete" && stopped.status !== "not-owned";
+ } catch {
+ released = false;
+ }
+ if (!released) {
+ unresolved.push(marker);
+ continue;
+ }
+ marker.resolveCleanup();
+ this.#resolverCleanup.delete(owner);
+ }
+ if (unresolved.length === 0) return undefined;
+ if (unresolved.length === 1) return unresolved[0];
+ return new ProviderCleanupError(
+ PROVIDER,
+ [...new Set(unresolved.flatMap((marker) => marker.cleanupResources))],
+ { reason: "LLDB resolver cleanup remains incomplete" },
+ {
+ operation: OPERATION,
+ cause: new AggregateError(
+ unresolved,
+ "LLDB resolver cleanup remains incomplete",
+ ),
+ },
+ ).bindCleanupDependencies(unresolved);
+ }
+
async #run(
lldb: ResolvedTool,
retained: RetainedLldbResources,
@@ -507,6 +652,14 @@ export class LldbCallTracer implements NativeCallTracer {
...(signal === undefined ? {} : { signal }),
},
);
+ if (exited.kind === "preparation-failed") {
+ // LLDB was never spawned. Release only this tracer's runtime and keep
+ // the shared helper marker on the preparation error.
+ retained.processStopped = true;
+ retained.targetStopped = true;
+ if (this.#pendingCleanup === retained) this.#pendingCleanup = undefined;
+ return err(lldbPreparationFailure(exited.cause));
+ }
retained.supervisor = exited.cleanupOwner;
retained.targetIdentity = exited.targetIdentity;
retained.processStopped =
@@ -1027,6 +1180,81 @@ interface RetainedLldbResources {
const errorReason = (cause: unknown): string =>
cause instanceof Error ? cause.message : String(cause);
+/**
+ * Keep command-supervisor markers on a discovery error. A preparation error
+ * that already owns the foreign helper binds the supervisors beside it.
+ * A completed preparation still reports those supervisors as cleanup.
+ */
+const withResolverMarkers = (
+ error: AnalysisError,
+ markers: readonly ProviderCleanupError[],
+): AnalysisError => {
+ if (markers.length === 0) return error;
+ if (error.cleanupIncomplete) return error.bindCleanupDependencies(markers);
+ const cleanup =
+ markers.length === 1
+ ? markers[0]
+ : new ProviderCleanupError(
+ PROVIDER,
+ [...new Set(markers.flatMap((marker) => marker.cleanupResources))],
+ { reason: "LLDB resolver cleanup remains incomplete" },
+ { operation: OPERATION },
+ ).bindCleanupDependencies(markers);
+ if (cleanup === undefined) return error;
+ return analysisErrorWithCleanupFailure(
+ error,
+ cleanup,
+ OPERATION,
+ ).bindCleanupDependencies([error, cleanup]);
+};
+
+/** Preserve compiler facts and a foreign helper marker without inventing an LLDB exit. */
+const lldbPreparationFailure = (
+ cause: DarwinProcessOwnershipInspectionError,
+): AnalysisError => {
+ const marker = cause.cleanupFailure;
+ const compiler = cause.compilerOutcome;
+ const options = {
+ cause,
+ ...(cause.capturedOutput === undefined
+ ? {}
+ : { capturedOutput: cause.capturedOutput }),
+ ...(marker === undefined
+ ? {}
+ : {
+ cleanup: {
+ reason: marker.message,
+ resources: [...marker.cleanupResources],
+ },
+ }),
+ diagnostics: {
+ phase: "process-preparation" as const,
+ tool: "lldb" as const,
+ reason: cause.message,
+ ...(compiler === undefined
+ ? {}
+ : {
+ compiler_outcome: {
+ outcome: compiler.outcome,
+ code: compiler.code,
+ signal: compiler.signal,
+ ...(compiler.timeoutMs === undefined
+ ? {}
+ : { timeout_ms: compiler.timeoutMs }),
+ },
+ }),
+ },
+ };
+ const error =
+ cause.cancellation === undefined
+ ? new ProviderAdapterError(PROVIDER, OPERATION, options)
+ : new AnalysisCancelledError(OPERATION, {
+ ...options,
+ cause: cause.cancellation.reason,
+ });
+ return marker === undefined ? error : error.bindCleanupDependencies([marker]);
+};
+
/** Root release certifies the hierarchy only after every child confirms completion. */
const releaseLldbRuntime = async (
owner: RetainedLldbResources,
@@ -1076,15 +1304,23 @@ type LldbOutcome =
| { readonly kind: "cancelled" }
| { readonly kind: "timeout" };
-type LldbExit = LldbOutcome & {
- /** False proves LLDB never started and could not have created a target. */
- readonly targetLaunched: boolean;
- readonly targetIdentity: string | undefined;
- readonly cleanupFailure: string | undefined;
- /** Internal deadline elapsed during cleanup after a physical LLDB exit. */
- readonly lateTimeout?: true;
- readonly cleanupOwner?: ProviderProcessSupervisor;
-};
+type LldbExit =
+ | (LldbOutcome & {
+ /** False proves LLDB never started and could not have created a target. */
+ readonly targetLaunched: boolean;
+ readonly targetIdentity: string | undefined;
+ readonly cleanupFailure: string | undefined;
+ /** Internal deadline elapsed during cleanup after a physical LLDB exit. */
+ readonly lateTimeout?: true;
+ readonly cleanupOwner?: ProviderProcessSupervisor;
+ })
+ | {
+ readonly kind: "preparation-failed";
+ readonly cause: DarwinProcessOwnershipInspectionError;
+ readonly targetLaunched: false;
+ readonly targetIdentity: undefined;
+ readonly cleanupFailure: undefined;
+ };
const lldbCleanupResources = (owner: RetainedLldbResources): string[] => [
...(owner.processStopped ? [] : ["lldb-process-group"]),
@@ -1228,6 +1464,18 @@ const runLldb = async (
: { kind: interruption },
);
} catch (cause: unknown) {
+ if (
+ supervisor === undefined &&
+ cause instanceof DarwinProcessOwnershipInspectionError
+ ) {
+ return {
+ kind: "preparation-failed",
+ cause,
+ targetLaunched: false,
+ targetIdentity: undefined,
+ cleanupFailure: undefined,
+ };
+ }
const interruption = deadline.interruption;
return await finish(
interruption === undefined
diff --git a/tests/boundary/providers/hopper/hopperFileOffsetClose.test.ts b/tests/boundary/providers/hopper/hopperFileOffsetClose.test.ts
new file mode 100644
index 000000000..1b7f8e313
--- /dev/null
+++ b/tests/boundary/providers/hopper/hopperFileOffsetClose.test.ts
@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import {
+ mkdir,
+ mkdtemp,
+ rm,
+ writeFile,
+ type FileHandle,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { expect, it, vi } from "vitest";
+
+import { createAnalysisProfile } from "../../../../src/domain/analysisProfile.js";
+import { AnalysisArtifactChangedError } from "../../../../src/domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js";
+import { parseConfig } from "../../../../src/config/parseConfig.js";
+import { silentLogger } from "../../../../src/logger.js";
+import { err, ok } from "../../../../src/domain/result.js";
+import { HopperClient } from "../../../../src/hopper/HopperClient.js";
+import { HopperProvider } from "../../../../src/hopper/HopperProvider.js";
+
+const state = vi.hoisted(() => ({
+ path: "",
+ fail: false,
+ code: "EIO",
+ handles: [] as Array<{ handle: FileHandle; close: () => Promise<void> }>,
+ ended: 0,
+}));
+
+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 (String(args[0]) !== state.path) return handle;
+ const close = handle.close.bind(handle);
+ state.handles.push({ handle, close });
+ const stream = handle.createReadStream.bind(handle);
+ handle.createReadStream = (options) =>
+ stream(options).on("end", () => {
+ state.ended += 1;
+ });
+ handle.close = async () => {
+ if (state.fail)
+ throw Object.assign(
+ new Error("controlled descriptor close failure"),
+ {
+ code: state.code,
+ },
+ );
+ await close();
+ };
+ return handle;
+ },
+ };
+});
+
+const observation = {
+ address: "0x1000",
+ provider_file_offset: 8,
+ provider_source_path: null,
+ provider_image_header_hex: null,
+};
+
+const clientFor = async (path: string, bytes: Buffer) => {
+ const config = parseConfig({ HOPPER_LAUNCHER_PATH: process.execPath });
+ if (!config.ok) throw config.error;
+ const provider = new HopperProvider(config.value, silentLogger, {});
+ return provider.createClient(
+ {
+ path,
+ sha256: createHash("sha256").update(bytes).digest("hex"),
+ kind: "executable",
+ format: "mach-o",
+ architecture: "arm64",
+ availableArchitectures: ["arm64"],
+ },
+ createAnalysisProfile(
+ { id: "hopper", name: "Hopper", version: "fixture" },
+ { macho_container: "thin" },
+ ),
+ );
+};
+
+it("preserves file-offset reads and retries the exact descriptor after close fails", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-hopper-file-offset-close-"));
+ const bytes = Buffer.alloc(64);
+ bytes.writeUInt32LE(0xfeedfacf, 0);
+ bytes.writeUInt32LE(0x0100000c, 4);
+ state.path = join(root, "sample");
+ await writeFile(state.path, bytes);
+ const client = await clientFor(state.path, bytes);
+ const call = vi
+ .spyOn(HopperClient.prototype, "callTool")
+ .mockResolvedValue(ok(observation));
+ try {
+ const control = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(control.ok).toBe(true);
+ if (!control.ok) return;
+ expect(control.value).toMatchObject({ result: { file_offset: 8 } });
+ expect(state.ended).toBe(1);
+ expect(state.handles[0]?.handle.fd).toBe(-1);
+
+ state.fail = true;
+ state.code = "EIO";
+ const failed = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(failed.ok).toBe(false);
+ if (failed.ok) return;
+ expect(failed.error).toBeInstanceOf(ProviderCleanupError);
+ expect(failed.error._tag).not.toBe("BinaryTargetError");
+ expect(failed.error.cleanupIncomplete).toBe(true);
+ expect(failed.error.cleanupResources).toEqual([state.path]);
+ expect(failed.error.diagnostics).toMatchObject({
+ reason: "controlled descriptor close failure",
+ file_offset: 8,
+ source_identity: "verified",
+ });
+ expect(projectAnalysisError(failed.error).code).toBe("cleanup_incomplete");
+ const owned = state.handles.at(-1);
+ if (owned === undefined) throw new Error("missing descriptor");
+ expect(owned.handle.fd).toBeGreaterThanOrEqual(0);
+ expect(state.ended).toBe(2);
+
+ const opens = state.handles.length;
+ const calls = call.mock.calls.length;
+ const blocked = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(blocked.ok).toBe(false);
+ if (blocked.ok) return;
+ expect(blocked.error.cleanupIncomplete).toBe(true);
+ expect(state.handles).toHaveLength(opens);
+ expect(call).toHaveBeenCalledTimes(calls);
+ expect(owned.handle.fd).toBeGreaterThanOrEqual(0);
+
+ const rejectedClose = await client.close();
+ expect(rejectedClose.ok).toBe(false);
+ expect(owned.handle.fd).toBeGreaterThanOrEqual(0);
+ expect(failed.error.cleanupIncomplete).toBe(true);
+
+ state.fail = false;
+ const released = await client.close();
+ expect(released.ok).toBe(true);
+ expect(owned.handle.fd).toBe(-1);
+ expect(failed.error.cleanupIncomplete).toBe(false);
+ expect(blocked.error.cleanupIncomplete).toBe(false);
+
+ state.fail = true;
+ state.code = "EPERM";
+ const denied = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(denied.ok).toBe(false);
+ if (denied.ok) return;
+ expect(denied.error).toBeInstanceOf(ProviderCleanupError);
+ expect(denied.error._tag).not.toBe("AnalysisAccessDeniedError");
+ expect(denied.error.cleanupIncomplete).toBe(true);
+ const deniedHandle = state.handles.at(-1);
+ if (deniedHandle === undefined) throw new Error("missing EPERM descriptor");
+ expect(deniedHandle.handle.fd).toBeGreaterThanOrEqual(0);
+ state.fail = false;
+ expect((await client.close()).ok).toBe(true);
+ expect(deniedHandle.handle.fd).toBe(-1);
+ expect(denied.error.cleanupIncomplete).toBe(false);
+
+ await rm(state.path);
+ await mkdir(state.path);
+ const nonregular = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(nonregular.ok).toBe(false);
+ if (nonregular.ok) return;
+ expect(nonregular.error).toBeInstanceOf(AnalysisArtifactChangedError);
+ expect(nonregular.error.cleanupIncomplete).toBe(false);
+ expect(state.handles.at(-1)?.handle.fd).toBe(-1);
+
+ state.fail = true;
+ state.code = "EIO";
+ const masked = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(masked.ok).toBe(false);
+ if (masked.ok) return;
+ expect(masked.error.cleanupPrimary).toBeInstanceOf(
+ AnalysisArtifactChangedError,
+ );
+ expect(masked.error.cleanupIncomplete).toBe(true);
+ expect(masked.error.cleanupResources).toEqual([state.path]);
+ expect(projectAnalysisError(masked.error)).toMatchObject({
+ code: "cleanup_incomplete",
+ details: {
+ diagnostics: {
+ primary_error: { code: "artifact_changed" },
+ },
+ },
+ });
+ const directory = state.handles.at(-1);
+ if (directory === undefined)
+ throw new Error("missing directory descriptor");
+ expect(directory.handle.fd).toBeGreaterThanOrEqual(0);
+ state.fail = false;
+ expect((await client.close()).ok).toBe(true);
+ expect(directory.handle.fd).toBe(-1);
+ expect(masked.error.cleanupIncomplete).toBe(false);
+ } finally {
+ call.mockRestore();
+ state.fail = false;
+ for (const entry of state.handles) await entry.close();
+ await client.close();
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+it("clears a combined Hopper close only after the descriptor and session release", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-hopper-combined-close-"));
+ const bytes = Buffer.alloc(64);
+ bytes.writeUInt32LE(0xfeedfacf, 0);
+ bytes.writeUInt32LE(0x0100000c, 4);
+ state.path = join(root, "sample");
+ state.fail = false;
+ state.code = "EIO";
+ state.ended = 0;
+ state.handles.length = 0;
+ await writeFile(state.path, bytes);
+ const client = await clientFor(state.path, bytes);
+ const call = vi
+ .spyOn(HopperClient.prototype, "callTool")
+ .mockResolvedValue(ok(observation));
+ const session = new ProviderCleanupError(
+ "hopper",
+ ["hopper-session"],
+ { reason: "controlled session close failure" },
+ { operation: "close_binary" },
+ );
+ const close = vi
+ .spyOn(HopperClient.prototype, "close")
+ .mockResolvedValue(err(session));
+ try {
+ state.fail = true;
+ const failed = await client.execute("address_to_file_offset", {
+ address: "0x1000",
+ });
+ expect(failed.ok).toBe(false);
+ const owned = state.handles.at(-1);
+ if (owned === undefined) throw new Error("missing descriptor");
+ expect(owned.handle.fd).toBeGreaterThanOrEqual(0);
+
+ const combined = await client.close();
+ expect(combined.ok).toBe(false);
+ if (combined.ok) return;
+ expect(combined.error.cleanupPrimary).toBe(session);
+ expect(combined.error.cleanupIncomplete).toBe(true);
+ expect(combined.error.cleanupResources).toEqual([
+ "hopper-session",
+ state.path,
+ ]);
+ expect(call).toHaveBeenCalledTimes(1);
+
+ session.resolveCleanup();
+ expect(session.cleanupIncomplete).toBe(false);
+ expect(combined.error.cleanupIncomplete).toBe(true);
+ expect(combined.error.cleanupResources).toEqual([state.path]);
+ expect(owned.handle.fd).toBeGreaterThanOrEqual(0);
+
+ state.fail = false;
+ close.mockResolvedValue(ok(null));
+ const released = await client.close();
+ expect(released.ok).toBe(true);
+ expect(owned.handle.fd).toBe(-1);
+ expect(combined.error.cleanupIncomplete).toBe(false);
+ expect(combined.error.cleanupResources).toEqual([]);
+ } finally {
+ call.mockRestore();
+ close.mockRestore();
+ state.fail = false;
+ for (const entry of state.handles) await entry.close();
+ await client.close();
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/tests/boundary/providers/native/lldbPrelaunchCleanup.test.ts b/tests/boundary/providers/native/lldbPrelaunchCleanup.test.ts
new file mode 100644
index 000000000..aef269c75
--- /dev/null
+++ b/tests/boundary/providers/native/lldbPrelaunchCleanup.test.ts
@@ -0,0 +1,223 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+
+import { afterEach, expect, it, vi } from "vitest";
+
+import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";
+import { nativeCallObservationInputSchema } from "../../../../src/domain/native/nativeCallObservation.js";
+import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js";
+import { err, ok } from "../../../../src/domain/result.js";
+import { NativeCommandFailure } from "../../../../src/native/CommandRunner.js";
+import { LldbCallTracer } from "../../../../src/native/LldbCallTracer.js";
+import { DarwinProcessOwnershipInspectionError } from "../../../../src/process/DarwinProcessRunTokenReader.js";
+import * as processBoundary from "../../../../src/process/ProviderProcess.js";
+
+const tool = { path: "/usr/bin/true", sha256: "b".repeat(64) };
+const request = {
+ executable: "/fixture",
+ architecture: "arm64" as const,
+ expectedSha256: "a".repeat(64),
+ input: nativeCallObservationInputSchema.parse({
+ breakpoints: [{ kind: "function", name: "main" }],
+ }),
+};
+
+const preparation = () => {
+ const marker = new ProviderCleanupError(
+ "process-ownership",
+ ["owned-helper-root"],
+ { reason: "controlled root deletion failure" },
+ );
+ const close = vi.fn(async () => {
+ marker.resolveCleanup();
+ });
+ const failure = new DarwinProcessOwnershipInspectionError(
+ "controlled compiler failure",
+ {
+ cleanupFailure: marker,
+ cleanupOwner: { close },
+ compilerOutcome: {
+ outcome: "exited",
+ code: 1,
+ signal: null,
+ stderr: "compiler failed",
+ stderrTruncated: false,
+ outputTruncated: false,
+ killed: false,
+ },
+ capturedOutput: {
+ stdout: "",
+ stderr: "compiler failed",
+ stderr_bytes: 15,
+ truncated: false,
+ },
+ },
+ );
+ return { marker, close, failure };
+};
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+it("keeps LLDB preparation facts and the foreign helper marker", async () => {
+ const prepared = preparation();
+ const launch = vi
+ .spyOn(processBoundary, "spawnOwnedProviderProcess")
+ .mockRejectedValue(prepared.failure);
+ const tracer = new LldbCallTracer({}, undefined, async () => ok(tool));
+ try {
+ const result = await tracer.trace(request);
+ expect(launch).toHaveBeenCalledTimes(1);
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(result.error.diagnostics).toMatchObject({
+ phase: "process-preparation",
+ tool: "lldb",
+ reason: "controlled compiler failure",
+ compiler_outcome: { outcome: "exited", code: 1, signal: null },
+ });
+ expect(result.error.diagnostics).not.toMatchObject({
+ reason: "LLDB exited without a usable tracer result",
+ });
+ expect(result.error.capturedOutput).toMatchObject({
+ stderr: "compiler failed",
+ stderr_bytes: 15,
+ });
+ expect(result.error.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupResources).toEqual(["owned-helper-root"]);
+ expect(projectAnalysisError(result.error).code).toBe("cleanup_incomplete");
+ expect((await tracer.close()).ok).toBe(true);
+ expect(prepared.close).not.toHaveBeenCalled();
+ expect(prepared.marker.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupIncomplete).toBe(true);
+ await prepared.close();
+ expect(prepared.marker.cleanupIncomplete).toBe(false);
+ expect(result.error.cleanupIncomplete).toBe(false);
+ } finally {
+ await tracer.close();
+ await prepared.close();
+ }
+});
+
+it("retries the tracer-owned resolver supervisor before another trace", async () => {
+ const child = Object.assign(new EventEmitter(), {
+ stdout: new PassThrough(),
+ stderr: new PassThrough(),
+ exitCode: 0,
+ signalCode: null,
+ kill: () => true,
+ });
+ let failStop = true;
+ const supervisor = new processBoundary.ProviderProcessSupervisor({
+ process: child,
+ ownsProcessLifetime: true,
+ ownership: {
+ runId: "controlled-resolver",
+ leaderPid: 46000,
+ processGroupId: 46000,
+ expectedParentPid: process.pid,
+ },
+ cleanup: async () =>
+ failStop
+ ? { cleaned: false, reason: "controlled incomplete stop" }
+ : { cleaned: true, signaled: false },
+ });
+ const stop = vi.spyOn(supervisor, "stop");
+ const marker = new ProviderCleanupError(
+ "native-macos",
+ ["owned-resolver-process"],
+ { reason: "controlled incomplete stop" },
+ );
+ const resolver = vi.fn(async () =>
+ err(
+ new NativeCommandFailure(
+ "lldb",
+ "io",
+ null,
+ { cleanupOwner: supervisor, cleanupMarker: marker },
+ null,
+ "controlled incomplete stop",
+ ["owned-resolver-process"],
+ ),
+ ),
+ );
+ const tracer = new LldbCallTracer({}, undefined, resolver);
+ try {
+ const result = await tracer.trace(request);
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError");
+ expect(result.error.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupResources).toEqual(["owned-resolver-process"]);
+ expect(projectAnalysisError(result.error).code).toBe("cleanup_incomplete");
+
+ const closed = await tracer.close();
+ expect(closed.ok).toBe(false);
+ expect(stop).toHaveBeenCalledTimes(1);
+ expect(marker.cleanupIncomplete).toBe(true);
+
+ await tracer.trace(request);
+ expect(resolver).toHaveBeenCalledTimes(1);
+ expect(stop).toHaveBeenCalledTimes(2);
+
+ failStop = false;
+ const released = await tracer.close();
+ expect(released.ok).toBe(true);
+ expect(marker.cleanupIncomplete).toBe(false);
+ expect(result.error.cleanupIncomplete).toBe(false);
+
+ const again = await tracer.trace(request);
+ expect(resolver).toHaveBeenCalledTimes(2);
+ expect(again.ok).toBe(false);
+ } finally {
+ supervisor.dispose();
+ child.stdout.destroy();
+ child.stderr.destroy();
+ await tracer.close();
+ }
+});
+
+it("keeps resolver preparation cleanup with the foreign helper", async () => {
+ const prepared = preparation();
+ const resolver = vi.fn(async () =>
+ err(
+ new NativeCommandFailure("lldb", "io", null, { cause: prepared.failure }),
+ ),
+ );
+ const tracer = new LldbCallTracer({}, undefined, resolver);
+ try {
+ const result = await tracer.trace(request);
+ expect(resolver).toHaveBeenCalledTimes(1);
+ expect(result.ok).toBe(false);
+ if (result.ok) return;
+ expect(result.error._tag).toBe("ProviderAdapterError");
+ expect(result.error.diagnostics).toMatchObject({
+ phase: "process-preparation",
+ tool: "lldb",
+ reason: "controlled compiler failure",
+ compiler_outcome: { outcome: "exited", code: 1, signal: null },
+ });
+ expect(result.error.capturedOutput).toMatchObject({
+ stderr: "compiler failed",
+ });
+ expect(result.error.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupResources).toEqual(["owned-helper-root"]);
+ expect(projectAnalysisError(result.error).code).toBe("cleanup_incomplete");
+
+ expect((await tracer.close()).ok).toBe(true);
+ expect(prepared.close).not.toHaveBeenCalled();
+ expect(prepared.marker.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupIncomplete).toBe(true);
+
+ await tracer.trace(request);
+ expect(resolver).toHaveBeenCalledTimes(2);
+
+ await prepared.close();
+ expect(prepared.marker.cleanupIncomplete).toBe(false);
+ expect(result.error.cleanupIncomplete).toBe(false);
+ } finally {
+ await tracer.close();
+ await prepared.close();
+ }
+});