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(lifecycle): retain exact cleanup owners when close or prelaunch fails (#6357)
morluto7501911f1781
diff --git a/src/hopper/HopperFileOffset.ts b/src/hopper/HopperFileOffset.tsindex 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.tsindex 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.tsindex 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 === undefineddiff --git a/tests/boundary/providers/hopper/hopperFileOffsetClose.test.ts b/tests/boundary/providers/hopper/hopperFileOffsetClose.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+ }+});