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(hopper): own Mach-O preparation through cleanup retry
morlutob231c28cf64c
diff --git a/scripts/verify-real-hopper-deadlines.mjs b/scripts/verify-real-hopper-deadlines.mjsindex 11e071431..31b2d856f 100644--- a/scripts/verify-real-hopper-deadlines.mjs+++ b/scripts/verify-real-hopper-deadlines.mjs@@ -6,6 +6,8 @@ import { fileURLToPath } from "node:url";import { firstProcedureAddress } from "../dist/application/RealHopperAssertions.js";import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";+import { ArtifactResourceScope } from "../dist/artifacts/ArtifactResourceScope.js";+import { AnalysisCleanupLease } from "../dist/artifacts/AnalysisCleanupLease.js";import { resolveHopperAnalysisProfile } from "../dist/hopper/HopperAnalysisProfile.js";import { HopperApplicationLauncher } from "../dist/hopper/BridgeLauncher.js";import { HopperClient } from "../dist/hopper/HopperClient.js";@@ -26,6 +28,16 @@ const root = await realpath(await mkdtemp(join(tmpdir(), "rea-hopper-deadlines-")),);const target = join(root, "deadline-fixture");+const profileResources = new ArtifactResourceScope();+const profileResourceScope = {+ retain: (owner, resource) =>+ profileResources.retain({+ kind: "lease",+ resource,+ lease: AnalysisCleanupLease.forCloseOwner(owner, resource),+ }),+ run: (operation) => profileResources.run(operation),+};let client;let primaryFailure;try {@@ -39,6 +51,7 @@ try {launcherPath,loaderArgsOverride: [],provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope: profileResourceScope,});if (!resolved.ok) throw resolved.error;const profile = resolved.value.profile;@@ -138,15 +151,28 @@ try {primaryFailure = cause;throw cause;} finally {+ let cleanupFailure;if (client !== undefined) {const closed = await client.close();- if (!closed.ok)- throw primaryFailure === undefined- ? closed.error+ if (!closed.ok) cleanupFailure = closed.error;+ }+ try {+ await profileResources.close();+ } catch (cause) {+ cleanupFailure =+ cleanupFailure === undefined+ ? cause: new AggregateError(- [primaryFailure, closed.error],- "Hopper verification and cleanup failed",+ [cleanupFailure, cause],+ "Hopper profile and client cleanup failed",);}await rm(root, { recursive: true, force: true });+ if (cleanupFailure !== undefined)+ throw primaryFailure === undefined+ ? cleanupFailure+ : new AggregateError(+ [primaryFailure, cleanupFailure],+ "Hopper verification and cleanup failed",+ );}diff --git a/src/application/LinuxHopperPublisher.ts b/src/application/LinuxHopperPublisher.tsindex 8acbefec9..eb63d578e 100644--- a/src/application/LinuxHopperPublisher.ts+++ b/src/application/LinuxHopperPublisher.ts@@ -7,7 +7,11 @@ import {ArtifactResourceScope,type ArtifactResourceOwner,} from "../artifacts/ArtifactResourceScope.js";-import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import type { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";+import {+ ArtifactReaderFailure,+ artifactPrimaryCleanupLeases,+} from "../artifacts/ArtifactReader.js";import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";import { err, ok, type Result } from "../domain/result.js";import {@@ -1061,12 +1065,17 @@ export class LinuxHopperPublisher {export const retryLinuxHopperPublisherCleanup = async (): Promise<void> => {const causes: unknown[] = [];const observations = [];+ const cleanupLeases = new Set<AnalysisCleanupLease>();+ let cleanupLeaseAuthorityKnown = true;for (const scope of pendingCleanup) {try {await scope.close();pendingCleanup.delete(scope);} catch (cause: unknown) {causes.push(cause);+ const leases = artifactPrimaryCleanupLeases(cause);+ if (leases === undefined) cleanupLeaseAuthorityKnown = false;+ else for (const lease of leases) cleanupLeases.add(lease);observations.push(ArtifactReaderFailure.cleanupObservation(cause,@@ -1088,6 +1097,9 @@ export const retryLinuxHopperPublisherCleanup = async (): Promise<void> => {{cause: new AggregateError(causes, "Hopper publisher cleanup failures"),cleanup,+ cleanupLeases: cleanupLeaseAuthorityKnown+ ? [...cleanupLeases]+ : undefined,},);}diff --git a/src/domain/apple/machoTargetSelection.ts b/src/domain/apple/machoTargetSelection.tsnew file mode 100644index 000000000..f492bc2a0--- /dev/null+++ b/src/domain/apple/machoTargetSelection.ts@@ -0,0 +1,79 @@+import { z } from "zod";++import type { AnalysisProfileCommitment } from "../analysisProfile.js";+import type { BinaryArchitecture } from "../binaryTargetTypes.js";++/** Provider-neutral observed identity of one Mach-O image selected from a source. */+export const machoTargetSelectionSchema = z+ .strictObject({+ kind: z.literal("macho-selected-image-v1"),+ container: z.enum(["thin", "fat"]),+ offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),+ byte_length: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),+ cpu_type: z.number().int().nonnegative().max(0xffff_ffff),+ /** Keep the complete raw subtype, including capability bits. */+ cpu_subtype: z.number().int().nonnegative().max(0xffff_ffff),+ container_table_sha256: z+ .string()+ .regex(/^[a-f0-9]{64}$/u)+ .nullable(),+ })+ .superRefine((selection, context) => {+ if (+ (selection.container === "thin" &&+ (selection.offset !== 0 ||+ selection.container_table_sha256 !== null)) ||+ (selection.container === "fat" &&+ selection.container_table_sha256 === null)+ )+ context.addIssue({+ code: "custom",+ message: "Invalid Mach-O container identity",+ });+ });++export type MachoTargetSelection = z.infer<typeof machoTargetSelectionSchema>;++/** Read only the provider-neutral fact committed by an analysis profile. */+export const profileMachoTargetSelection = (+ profile: AnalysisProfileCommitment | undefined,+): MachoTargetSelection | undefined => {+ const raw = profile?.parameters.target_selection;+ if (raw === undefined) return undefined;+ const parsed = machoTargetSelectionSchema.safeParse(raw);+ return parsed.success ? parsed.data : undefined;+};++/** Confirm the selected header's CPU family agrees with the caller's request. */+export const machoTargetSelectionMatchesArchitecture = (+ selection: MachoTargetSelection,+ architecture: BinaryArchitecture,+): boolean => {+ const cpuType: Partial<Record<BinaryArchitecture, number>> = {+ x86: 7,+ x86_64: 0x01000007,+ arm: 12,+ arm64: 0x0100000c,+ };+ return cpuType[architecture] === selection.cpu_type;+};++/** Confirm the parser-observed container agrees with the target's declared format. */+export const machoTargetSelectionMatchesFormat = (+ selection: MachoTargetSelection,+ format: "mach-o" | "mach-o-universal",+): boolean => selection.container === (format === "mach-o" ? "thin" : "fat");++/** Exact range and raw CPU identity equality; null is never treated as a match. */+export const sameMachoTargetSelection = (+ left: MachoTargetSelection | undefined,+ right: MachoTargetSelection | undefined,+): boolean =>+ left !== undefined &&+ right !== undefined &&+ left.container === right.container &&+ left.offset === right.offset &&+ left.byte_length === right.byte_length &&+ left.cpu_type === right.cpu_type &&+ left.cpu_subtype === right.cpu_subtype &&+ left.container_table_sha256 === right.container_table_sha256;diff --git a/src/domain/hopperErrors.ts b/src/domain/hopperErrors.tsindex c5bb75c86..935dd1b48 100644--- a/src/domain/hopperErrors.ts+++ b/src/domain/hopperErrors.ts@@ -60,8 +60,14 @@ export class HopperTimeoutError extends HopperError {export class HopperCancelledError extends HopperError {readonly _tag = "HopperCancelledError";- constructor() {- super("Hopper operation was cancelled");+ constructor(+ cause?: unknown,+ options: Omit<AnalysisErrorOptions, "cause"> = {},+ ) {+ super(+ "Hopper operation was cancelled",+ cause === undefined ? options : { ...options, cause },+ );}}@@ -167,7 +173,7 @@ export class HopperStartError extends HopperError {readonly launchRejection: HopperLaunchRejection | undefined;constructor(- options?: ErrorOptions & {+ options?: AnalysisErrorOptions & {readonly userMessage?: string;readonly ownerRunId?: string;readonly launcherFailure?: HopperLauncherOutcome;diff --git a/src/hopper/BridgeLauncher.ts b/src/hopper/BridgeLauncher.tsindex 8e48b5e2a..99431606f 100644--- a/src/hopper/BridgeLauncher.ts+++ b/src/hopper/BridgeLauncher.ts@@ -10,7 +10,13 @@ import {} from "../domain/hopperErrors.js";import { err, ok, type Result } from "../domain/result.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";-import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import {+ ArtifactReaderFailure,+ artifactPrimaryCleanupLeases,+} from "../artifacts/ArtifactReader.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { AnalysisCleanupLeaseGroup } from "../artifacts/AnalysisCleanupLease.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";import { execFileOutput } from "../process/ExecFileOutput.js";import {@@ -27,6 +33,7 @@ import {import {prepareHopperMachOImage,type HopperMachOImage,+ type HopperMachOImageFileSystem,} from "./HopperMachOImage.js";import {@@ -42,6 +49,19 @@ import { retryLinuxHopperPublisherCleanup } from "../application/LinuxHopperPublconst execFileAsync = promisify(execFile);const HOPPER_BACKGROUND_STARTUP_MS = 5_000;+const bindRetainedArtifactCleanup = (+ error: AnalysisError,+ cause: unknown,+): void => {+ const leases = artifactPrimaryCleanupLeases(cause);+ if (leases !== undefined && leases.length > 0) {+ new AnalysisCleanupLeaseGroup(error, leases);+ return;+ }+ if (cause instanceof AnalysisError && cause.cleanupIncomplete)+ error.bindCleanupDependencies([cause]);+};+/** Coordinates for one private bridge session. */export interface BridgeSession {readonly directory: string;@@ -115,6 +135,7 @@ export type HopperApplicationLauncherOptions =});export interface HopperApplicationLauncherDependencies {+ readonly imageFileSystem?: HopperMachOImageFileSystem;readonly verifyNativeHelper?: typeof verifyMacHopperNativeHelper;readonly verifyLinuxLauncher?: typeof inspectLinuxHopperLauncher;readonly retryPublisherCleanup?: typeof retryLinuxHopperPublisherCleanup;@@ -143,35 +164,71 @@ export interface HopperApplicationLauncherDependencies {* macOS LaunchServices may create or reuse.*/export class HopperApplicationLauncher implements BridgeLauncher {+ readonly #preparedImageResources = new ArtifactResourceScope();+constructor(readonly options: HopperApplicationLauncherOptions,readonly dependencies: HopperApplicationLauncherDependencies = {},) {}async cleanup(): Promise<Result<null, ProviderCleanupError>> {- if (!usesLinuxDemo(this.options)) return ok(null);+ const failures: ProviderCleanupError[] = [];try {- await (- this.dependencies.retryPublisherCleanup ??- retryLinuxHopperPublisherCleanup- )();- return ok(null);+ await this.#preparedImageResources.retryCleanup();} catch (cause: unknown) {const observation = ArtifactReaderFailure.cleanupObservation(cause,- "hopper-publisher-verification",+ this.#preparedImageResources.cleanupResources,);- return err(- new ProviderCleanupError(+ const failure = new ProviderCleanupError(+ "hopper",+ observation.resources,+ { reason: observation.reason },+ { cause },+ );+ bindRetainedArtifactCleanup(failure, cause);+ failures.push(failure);+ }+ if (usesLinuxDemo(this.options)) {+ try {+ await (+ this.dependencies.retryPublisherCleanup ??+ retryLinuxHopperPublisherCleanup+ )();+ } catch (cause: unknown) {+ const observation = ArtifactReaderFailure.cleanupObservation(+ cause,+ "hopper-publisher-verification",+ );+ const failure = new ProviderCleanupError("hopper",observation.resources,- {- reason: observation.reason,- },+ { reason: observation.reason },{ cause },- ),- );+ );+ bindRetainedArtifactCleanup(failure, cause);+ failures.push(failure);+ }}+ if (failures.length === 0) return ok(null);+ if (failures.length === 1) return err(failures[0]!);+ const resources = [+ ...new Set(failures.flatMap((failure) => failure.cleanupResources)),+ ];+ const failure = new ProviderCleanupError(+ "hopper",+ resources,+ {+ reason: failures.map((failure) => failure.message).join("; "),+ },+ {+ cause: new AggregateError(+ failures,+ "Hopper image and publisher cleanup remain incomplete",+ ),+ },+ );+ return err(failure.bindCleanupDependencies(failures));}async launch(@@ -189,14 +246,39 @@ export class HopperApplicationLauncher implements BridgeLauncher {let leaseTransferred = false;try {let loadedPath = this.options.targetPath;- if (this.options.preparedImage !== undefined) {- const prepared = await prepareHopperMachOImage(- this.options.targetPath,- this.options.preparedImage.sourceSha256,- this.options.preparedImage.image,- join(session.directory, "image.macho"),- options.signal,- );+ const preparedImage = this.options.preparedImage;+ if (preparedImage !== undefined) {+ let prepared: Awaited<ReturnType<typeof prepareHopperMachOImage>>;+ try {+ prepared = await this.#preparedImageResources.run(() =>+ prepareHopperMachOImage(+ this.options.targetPath,+ preparedImage.sourceSha256,+ preparedImage.image,+ join(session.directory, "image.macho"),+ {+ ...(options.signal === undefined+ ? {}+ : { signal: options.signal }),+ resourceScope: this.#preparedImageResources,+ ...(this.dependencies.imageFileSystem === undefined+ ? {}+ : { fileSystem: this.dependencies.imageFileSystem }),+ },+ ),+ );+ } catch (cause: unknown) {+ const failure = new HopperStartError({+ cause,+ userMessage: `Previous Hopper image cleanup remains incomplete: ${cause instanceof Error ? cause.message : String(cause)}`,+ cleanup: {+ reason: cause instanceof Error ? cause.message : String(cause),+ resources: this.#preparedImageResources.cleanupResources,+ },+ });+ bindRetainedArtifactCleanup(failure, cause);+ return err(failure);+ }if (!prepared.ok) return prepared;loadedPath = prepared.value;}diff --git a/src/hopper/HopperAnalysisProfile.test.ts b/src/hopper/HopperAnalysisProfile.test.tsindex e5b574504..247ac99d0 100644--- a/src/hopper/HopperAnalysisProfile.test.ts+++ b/src/hopper/HopperAnalysisProfile.test.ts@@ -1,15 +1,33 @@import { createHash } from "node:crypto";+import { PassThrough } from "node:stream";import { writeFile } from "node:fs/promises";import { join } from "node:path";-import { expect, it } from "vitest";+import { afterEach, expect, it, vi } from "vitest";+vi.mock("node:fs", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs")>();+ return {+ ...actual,+ createReadStream: vi.fn(actual.createReadStream),+ };+});++import { createReadStream } from "node:fs";++import { createInspectionResources } from "../../tests/fixtures/inspectionResources.js";import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";import {hopperLoaderArgsForTarget,resolveHopperAnalysisProfile,} from "./HopperAnalysisProfile.js";+let inspectionResources = createInspectionResources();+afterEach(async () => {+ await inspectionResources.close();+ inspectionResources = createInspectionResources();+});+it("routes physical universal Mach-O containers through Hopper's FAT loader", () => {const result = hopperLoaderArgsForTarget({@@ -72,6 +90,7 @@ it("prepares a verified thin arm64e slice for a FAT32 system container", async (launcherPath: path,loaderArgsOverride: [],provider: { id: "hopper", name: "Hopper Disassembler", version: null },+ resourceScope: inspectionResources.owner,},);if (!result.ok) throw new Error(result.error.message);@@ -85,9 +104,227 @@ it("prepares a verified thin arm64e slice for a FAT32 system container", async (cpu_type: 0x0100000c,cpu_subtype: 0x80000002,},+ target_selection: {+ kind: "macho-selected-image-v1",+ container: "fat",+ offset: arm64eOffset,+ byte_length: 64,+ cpu_type: 0x0100000c,+ cpu_subtype: 0x80000002,+ container_table_sha256: expect.any(String),+ },loader: {source: "derived",arguments: ["-l", "Mach-O", "--aarch64"],},});});++it("commits a thin header selection only for derived Hopper loader arguments", async () => {+ const directory = await createTestTempDirectory("rea-hopper-thin-profile-");+ const thin = Buffer.alloc(64);+ thin.writeUInt32LE(0xfeedfacf, 0);+ thin.writeUInt32LE(0x0100000c, 4);+ thin.writeUInt32LE(0x80000002, 8);+ const path = join(directory, "arm64e.macho");+ await writeFile(path, thin);+ const target = {+ path,+ sha256: createHash("sha256").update(thin).digest("hex"),+ kind: "executable" as const,+ format: "mach-o" as const,+ architecture: "arm64" as const,+ availableArchitectures: ["arm64" as const],+ };+ const provider = {+ id: "hopper",+ name: "Hopper Disassembler",+ version: null,+ };+ const resolved = await resolveHopperAnalysisProfile(target, {+ launcherPath: path,+ loaderArgsOverride: [],+ provider,+ resourceScope: inspectionResources.owner,+ });+ if (!resolved.ok) throw new Error(resolved.error.message);+ expect(resolved.value.profile?.parameters.target_selection).toEqual({+ kind: "macho-selected-image-v1",+ container: "thin",+ offset: 0,+ byte_length: 64,+ cpu_type: 0x0100000c,+ cpu_subtype: 0x80000002,+ container_table_sha256: null,+ });+ expect(resolved.value.profile?.parameters.prepared_image).toEqual({+ method: "thin_verified_copy",+ byte_length: thin.length,+ cpu_type: 0x0100000c,+ cpu_subtype: 0x80000002,+ });++ const overridden = await resolveHopperAnalysisProfile(target, {+ launcherPath: path,+ loaderArgsOverride: ["-l", "Mach-O"],+ provider,+ resourceScope: inspectionResources.owner,+ });+ if (!overridden.ok) throw new Error(overridden.error.message);+ expect(overridden.value.profile?.parameters).not.toHaveProperty(+ "target_selection",+ );++ const changedSameSize = Buffer.from(thin);+ changedSameSize.writeUInt8(+ changedSameSize.readUInt8(changedSameSize.length - 1) ^ 1,+ changedSameSize.length - 1,+ );+ await writeFile(path, changedSameSize);+ const staleAdmission = await resolveHopperAnalysisProfile(target, {+ launcherPath: path,+ loaderArgsOverride: [],+ provider,+ resourceScope: inspectionResources.owner,+ });+ expect(staleAdmission.ok).toBe(false);+ if (staleAdmission.ok) throw new Error("stale thin admission was accepted");+ expect(staleAdmission.error.message).toContain(+ "Thin Mach-O source changed after target admission",+ );+});++it("keeps a read failure primary when cancellation arrives with the stream error", async () => {+ const path = "/fixture/arm64.macho";+ const target = {+ path,+ sha256: "a".repeat(64),+ kind: "executable" as const,+ format: "mach-o" as const,+ architecture: "arm64" as const,+ availableArchitectures: ["arm64" as const],+ };+ const controller = new AbortController();+ const reason = { request: "cancel-after-read-error" };+ const physicalFailure = new Error("fixture read failure");+ const stream = new PassThrough();+ vi.mocked(createReadStream).mockReturnValueOnce(+ stream as unknown as ReturnType<typeof createReadStream>,+ );+ stream.once("error", () => controller.abort(reason));++ const resolving = resolveHopperAnalysisProfile(target, {+ launcherPath: "/fixture/hopper",+ loaderArgsOverride: [],+ provider: { id: "hopper", name: "Hopper", version: null },+ resourceScope: inspectionResources.owner,+ signal: controller.signal,+ });+ stream.destroy(physicalFailure);++ const result = await resolving;+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("A failed header read was accepted");+ expect(result.error._tag).toBe("BinaryTargetError");+ expect(result.error.cause).toBe(physicalFailure);+});++it("retains the exact caller reason when the owned header stream is aborted", async () => {+ const controller = new AbortController();+ const reason = { request: "cancel-header-read" };+ const stream = new PassThrough();+ vi.mocked(createReadStream).mockReturnValueOnce(+ stream as unknown as ReturnType<typeof createReadStream>,+ );+ const resolving = resolveHopperAnalysisProfile(+ {+ path: "/fixture/arm64.macho",+ sha256: "a".repeat(64),+ kind: "executable",+ format: "mach-o",+ architecture: "arm64",+ availableArchitectures: ["arm64"],+ },+ {+ launcherPath: "/fixture/hopper",+ loaderArgsOverride: [],+ provider: { id: "hopper", name: "Hopper", version: null },+ resourceScope: inspectionResources.owner,+ signal: controller.signal,+ },+ );+ controller.abort(reason);++ const result = await resolving;+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("An aborted header read was accepted");+ expect(result.error._tag).toBe("AnalysisCancelledError");+ expect(result.error.cause).toBe(reason);+});++it("keeps failed Mach-O preflight cleanup attached to the supplied profile owner", async () => {+ const directory = await createTestTempDirectory("rea-hopper-profile-owner-");+ const sourcePath = join(directory, "source.macho");+ const bytes = Buffer.alloc(100_000, 0x5a);+ bytes.writeUInt32BE(0xfeedfacf, 0);+ bytes.writeUInt32BE(0x0100000c, 4);+ bytes.writeUInt32BE(0x80000002, 8);+ await writeFile(sourcePath, bytes);+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ const actualFs =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ const actualNodeFs =+ await vi.importActual<typeof import("node:fs")>("node:fs");+ vi.mocked(createReadStream).mockReset();+ vi.mocked(createReadStream).mockImplementation(actualNodeFs.createReadStream);+ const closeFailure = new Error("profile preflight close failure");+ let allowClose = false;+ const imageFileSystem = {+ open: async (...args: Parameters<typeof actualFs.open>) => {+ const handle = await actualFs.open(...args);+ const closeHandle = handle.close.bind(handle);+ Object.defineProperty(handle, "close", {+ configurable: true,+ value: async (): Promise<void> => {+ if (!allowClose) throw closeFailure;+ await closeHandle();+ },+ });+ return handle;+ },+ };+ const owner = inspectionResources;++ const resolved = await resolveHopperAnalysisProfile(+ {+ path: sourcePath,+ sha256,+ kind: "executable",+ format: "mach-o",+ architecture: "arm64",+ availableArchitectures: ["arm64"],+ },+ {+ launcherPath: sourcePath,+ loaderArgsOverride: [],+ provider: { id: "hopper", name: "Hopper", version: null },+ resourceScope: owner.owner,+ imageFileSystem,+ },+ );++ expect(resolved.ok).toBe(false);+ if (resolved.ok) throw new Error("Failed preflight cleanup was accepted");+ expect(resolved.error._tag).toBe("BinaryTargetError");+ expect(resolved.error.cause).toBe(closeFailure);+ expect(resolved.error.cleanupIncomplete).toBe(true);+ expect(resolved.error.cleanupResources).toEqual([+ `hopper-macho-preflight:${sourcePath}`,+ ]);++ allowClose = true;+ await owner.close();+ expect(resolved.error.cleanupIncomplete).toBe(false);+});diff --git a/src/hopper/HopperAnalysisProfile.ts b/src/hopper/HopperAnalysisProfile.tsindex 26fb390f5..d94d5d9cd 100644--- a/src/hopper/HopperAnalysisProfile.ts+++ b/src/hopper/HopperAnalysisProfile.ts@@ -3,6 +3,7 @@ import { createReadStream } from "node:fs";import type {AnalysisProfileResolution,+ RetainedResourceScope,ProviderIdentity,} from "../application/AnalysisProvider.js";import { createAnalysisProfile } from "../domain/analysisProfile.js";@@ -19,11 +20,16 @@ import {} from "../domain/analysisErrorCore.js";import { BinaryTargetError } from "../domain/configurationErrors.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";-import type { AnalysisError } from "../domain/analysisErrorBase.js";+import {+ machoTargetSelectionSchema,+ type MachoTargetSelection,+} from "../domain/apple/machoTargetSelection.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";import { err, ok, type Result } from "../domain/result.js";import {resolveHopperMachOImage,+ type HopperMachOImageResolutionFileSystem,type HopperMachOImage,} from "./HopperMachOImage.js";@@ -31,6 +37,8 @@ interface HopperProfileOptions {readonly launcherPath: string;readonly loaderArgsOverride: readonly string[];readonly provider: ProviderIdentity;+ readonly resourceScope: RetainedResourceScope;+ readonly imageFileSystem?: HopperMachOImageResolutionFileSystem;readonly signal?: AbortSignal;}@@ -38,6 +46,25 @@ interface HopperProfileOptions {export const resolveHopperAnalysisProfile = async (target: BinaryTarget,options: HopperProfileOptions,+): Promise<Result<AnalysisProfileResolution, AnalysisError>> => {+ try {+ return await options.resourceScope.run(() =>+ resolveHopperAnalysisProfileInScope(target, options),+ );+ } catch (cause: unknown) {+ return err(+ cause instanceof AnalysisError+ ? cause+ : new ProviderAdapterError("hopper", "resolve_analysis_profile", {+ cause,+ }),+ );+ }+};++const resolveHopperAnalysisProfileInScope = async (+ target: BinaryTarget,+ options: HopperProfileOptions,): Promise<Result<AnalysisProfileResolution, AnalysisError>> => {if (target.kind !== "executable" && target.kind !== "database")return ok({ profile: null });@@ -54,13 +81,41 @@ export const resolveHopperAnalysisProfile = async (let preparedImage: HopperMachOImage | undefined;if (target.kind === "executable" &&- (machoContainer === "fat64" || machoContainer === "fat32") &&+ machoContainer !== undefined &&options.loaderArgsOverride.length === 0) {- const resolved = await resolveHopperMachOImage(target, options.signal);+ const resolved = await resolveHopperMachOImage(target, {+ resourceScope: options.resourceScope,+ ...(options.signal === undefined ? {} : { signal: options.signal }),+ ...(options.imageFileSystem === undefined+ ? {}+ : { fileSystem: options.imageFileSystem }),+ });if (!resolved.ok) return resolved;preparedImage = resolved.value;}+ let targetSelection: MachoTargetSelection | undefined;+ if (preparedImage?.method === "thin_verified_copy") {+ targetSelection = machoTargetSelectionSchema.parse({+ kind: "macho-selected-image-v1",+ container: "thin",+ offset: 0,+ byte_length: preparedImage.byte_length,+ cpu_type: preparedImage.cpu_type,+ cpu_subtype: preparedImage.cpu_subtype,+ container_table_sha256: null,+ });+ } else if (preparedImage !== undefined) {+ targetSelection = machoTargetSelectionSchema.parse({+ kind: "macho-selected-image-v1",+ container: "fat",+ offset: preparedImage.source_offset,+ byte_length: preparedImage.byte_length,+ cpu_type: preparedImage.cpu_type,+ cpu_subtype: preparedImage.cpu_subtype,+ container_table_sha256: preparedImage.container_table_sha256,+ });+ }const derived = hopperLoaderArgsForTarget(target,preparedImage === undefined ? machoContainer : "thin",@@ -93,6 +148,9 @@ export const resolveHopperAnalysisProfile = async (...(preparedImage === undefined? {}: { prepared_image: { ...preparedImage } }),+ ...(targetSelection === undefined+ ? {}+ : { target_selection: targetSelection }),loader: {source:options.loaderArgsOverride.length === 0@@ -189,17 +247,23 @@ const readMachoMagic = async (signal?: AbortSignal,): Promise<Result<number, AnalysisError>> => {if (signalIsAborted(signal))- return err(new AnalysisCancelledError("open_binary"));+ return err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ );const stream = createReadStream(path, { start: 0, end: 3 });+ const abortError = new Error("Caller cancelled Mach-O header read");const onAbort = (): void => {- stream.destroy();+ stream.destroy(abortError);};signal?.addEventListener("abort", onAbort, { once: true });+ if (signal?.aborted) onAbort();try {const chunks: Buffer[] = [];for await (const chunk of stream) chunks.push(Buffer.from(chunk));if (signalIsAborted(signal))- return err(new AnalysisCancelledError("open_binary"));+ return err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ );const bytes = Buffer.concat(chunks);return bytes.length === 4? ok(bytes.readUInt32BE(0))@@ -210,8 +274,10 @@ const readMachoMagic = async (),);} catch (cause: unknown) {- return signalIsAborted(signal)- ? err(new AnalysisCancelledError("open_binary"))+ return cause === abortError+ ? err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ ): err(new BinaryTargetError(path,@@ -229,23 +295,31 @@ const sha256File = async (signal: AbortSignal | undefined,): Promise<Result<string | undefined, AnalysisCancelledError>> => {if (signalIsAborted(signal))- return err(new AnalysisCancelledError("open_binary"));+ return err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ );const stream = createReadStream(path);+ const abortError = new Error("Caller cancelled launcher fingerprint read");const onAbort = (): void => {- stream.destroy();+ stream.destroy(abortError);};signal?.addEventListener("abort", onAbort, { once: true });+ if (signal?.aborted) onAbort();try {const hash = createHash("sha256");for await (const chunk of stream) hash.update(chunk);return signalIsAborted(signal)- ? err(new AnalysisCancelledError("open_binary"))+ ? err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ ): ok(hash.digest("hex"));} catch (cause: unknown) {- // best-effort cleanup: unreadable targets mean no digest; abort still cancels.- void cause;- return signalIsAborted(signal)- ? err(new AnalysisCancelledError("open_binary"))+ // Physical fingerprint failures are best-effort; only our own abort+ // sentinel turns this optional observation into caller cancellation.+ return cause === abortError+ ? err(+ new AnalysisCancelledError("open_binary", { cause: signal?.reason }),+ ): ok(undefined);} finally {signal?.removeEventListener("abort", onAbort);diff --git a/src/hopper/HopperMachOImage.copyLifecycle.test.ts b/src/hopper/HopperMachOImage.copyLifecycle.test.tsnew file mode 100644index 000000000..2da4c55d4--- /dev/null+++ b/src/hopper/HopperMachOImage.copyLifecycle.test.ts@@ -0,0 +1,342 @@+import { createHash } from "node:crypto";+import { writeFile } from "node:fs/promises";+import { join } from "node:path";++import { afterEach, expect, it, vi } from "vitest";++import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { createInspectionResources } from "../../tests/fixtures/inspectionResources.js";+import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import { BinaryTargetError } from "../domain/configurationErrors.js";+import {+ HopperCancelledError,+ HopperStartError,+} from "../domain/hopperErrors.js";+import {+ prepareHopperMachOImage,+ resolveHopperMachOImage as resolveHopperMachOImageWithOwner,+} from "./HopperMachOImage.js";++let inspectionResources = createInspectionResources();+afterEach(async () => {+ await inspectionResources.close();+ inspectionResources = createInspectionResources();+});++const resolveHopperMachOImage = (+ target: Parameters<typeof resolveHopperMachOImageWithOwner>[0],+) =>+ resolveHopperMachOImageWithOwner(target, {+ resourceScope: inspectionResources.owner,+ });++type NativeFs = typeof import("node:fs/promises");+type NativeFilePath = Parameters<NativeFs["open"]>[0];++const createFileSystemWithCloseHook = async (+ onClose: (path: NativeFilePath, close: () => Promise<void>) => Promise<void>,+ onRead?: () => Promise<unknown>,+) => {+ const actualFs = await vi.importActual<NativeFs>("node:fs/promises");+ return {+ open: async (...args: Parameters<NativeFs["open"]>) => {+ const handle = await actualFs.open(...args);+ const path = args[0];+ const closeHandle = handle.close.bind(handle);+ Object.defineProperty(handle, "close", {+ configurable: true,+ value: () => onClose(path, closeHandle),+ });+ if (onRead !== undefined) {+ Object.defineProperty(handle, "read", {+ configurable: true,+ value: onRead,+ });+ }+ return handle;+ },+ };+};++const prepareWithChunkWriteFailure = (+ fixture: Awaited<ReturnType<typeof createThinCopyFixture>>,+ cause: Error,+ options: Omit<Parameters<typeof prepareHopperMachOImage>[4], "observer">,+) =>+ prepareHopperMachOImage(+ fixture.sourcePath,+ fixture.sha256,+ fixture.image,+ fixture.destination,+ {+ ...options,+ observer: {+ afterChunkWritten: async () => {+ throw cause;+ },+ },+ },+ );++it("keeps an observer failure primary and closes real source handles", async () => {+ const fixture = await createThinCopyFixture("rea-hopper-copy-primary-");+ const writeFailure = new Error("controlled copy observer failure");+ const prepared = await prepareWithChunkWriteFailure(fixture, writeFailure, {+ resourceScope: new ArtifactResourceScope(),+ });++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("A failed copy was accepted");+ expect(prepared.error.cause).toBe(writeFailure);+ expect(prepared.error.cleanupIncomplete).toBe(false);+});++it("keeps a copy failure primary while retaining and retrying a real source handle", async () => {+ const fixture = await createThinCopyFixture("rea-hopper-copy-cleanup-");++ const firstCloseFailure = new Error("source close is not confirmed");+ let allowSourceClose = false;+ let sourceCloseAttempts = 0;+ let outputCloseAttempts = 0;+ const fileSystem = await createFileSystemWithCloseHook(+ async (path, close) => {+ if (path === fixture.sourcePath) {+ sourceCloseAttempts += 1;+ if (!allowSourceClose) throw firstCloseFailure;+ } else {+ outputCloseAttempts += 1;+ }+ await close();+ },+ );+ const resourceScope = new ArtifactResourceScope();+ const writeFailure = new Error("controlled copy observer failure");+ const prepared = await prepareWithChunkWriteFailure(fixture, writeFailure, {+ resourceScope,+ fileSystem,+ });++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("A failed copy was accepted");+ expect(prepared.error.cause).toBe(writeFailure);+ expect(prepared.error.cleanupIncomplete).toBe(true);+ expect(prepared.error.cleanupResources).toEqual([+ `hopper-image-source:${fixture.sourcePath}`,+ ]);+ expect(outputCloseAttempts).toBe(1);+ expect(sourceCloseAttempts).toBe(2);++ allowSourceClose = true;+ await resourceScope.retryCleanup();+ expect(sourceCloseAttempts).toBe(3);+ expect(prepared.error.cause).toBe(writeFailure);+ expect(prepared.error.cleanupIncomplete).toBe(false);+});++it("keeps an output-close failure primary when cancellation first arrives during source close", async () => {+ const fixture = await createThinCopyFixture("rea-hopper-late-close-abort-");+ const controller = new AbortController();+ const reason = { request: "abort-during-source-close" };+ const outputCloseFailure = new Error("destination close failed first");+ let allowOutputClose = false;+ const fileSystem = await createFileSystemWithCloseHook(+ async (path, close) => {+ if (path === fixture.destination && !allowOutputClose)+ throw outputCloseFailure;+ await close();+ if (path === fixture.sourcePath) controller.abort(reason);+ },+ );+ const resourceScope = new ArtifactResourceScope();++ const prepared = await prepareHopperMachOImage(+ fixture.sourcePath,+ fixture.sha256,+ fixture.image,+ fixture.destination,+ { fileSystem, resourceScope, signal: controller.signal },+ );++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("Failed output closure was accepted");+ expect(prepared.error).toBeInstanceOf(HopperStartError);+ expect(prepared.error.cause).toBe(outputCloseFailure);+ expect(prepared.error.cause).not.toBe(reason);+ expect(prepared.error.cleanupIncomplete).toBe(true);+ expect(prepared.error.cleanupResources).toEqual([+ `hopper-prepared-image:${fixture.destination}`,+ ]);++ allowOutputClose = true;+ await resourceScope.retryCleanup();+ expect(prepared.error.cleanupIncomplete).toBe(false);+});++it("keeps cancellation observed before close primary and retains an output-close failure", async () => {+ const fixture = await createThinCopyFixture("rea-hopper-cancel-close-error-");+ const controller = new AbortController();+ const reason = { request: "abort-before-close" };+ const outputCloseFailure = new Error("destination close failed");+ let allowOutputClose = false;+ const fileSystem = await createFileSystemWithCloseHook(+ async (path, close) => {+ if (path === fixture.destination && !allowOutputClose)+ throw outputCloseFailure;+ await close();+ },+ );+ const resourceScope = new ArtifactResourceScope();++ const prepared = await prepareHopperMachOImage(+ fixture.sourcePath,+ fixture.sha256,+ fixture.image,+ fixture.destination,+ {+ fileSystem,+ resourceScope,+ signal: controller.signal,+ observer: {+ afterChunkWritten: async () => controller.abort(reason),+ },+ },+ );++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("Cancelled copy was accepted");+ expect(prepared.error).toBeInstanceOf(HopperCancelledError);+ expect(prepared.error.cause).toBe(reason);+ expect(prepared.error.cleanupIncomplete).toBe(true);+ expect(prepared.error.cleanupResources).toEqual([+ `hopper-prepared-image:${fixture.destination}`,+ ]);+ expect(+ prepared.error.secondaryFailures.some(+ (failure) => failure.cause === outputCloseFailure,+ ),+ ).toBe(true);++ allowOutputClose = true;+ await resourceScope.retryCleanup();+ expect(prepared.error.cleanupIncomplete).toBe(false);+});++it("preserves a physical preflight read failure and retains the handle after close fails", async () => {+ const fixture = await createThinCopyFixture(+ "rea-hopper-preflight-read-close-",+ );+ const readFailure = new Error("controlled preflight read failure");+ const closeFailure = new Error("controlled preflight close failure");+ let allowClose = false;+ let closeAttempts = 0;+ const fileSystem = await createFileSystemWithCloseHook(+ async (_path, close) => {+ closeAttempts += 1;+ if (!allowClose) throw closeFailure;+ await close();+ },+ async () => {+ throw readFailure;+ },+ );+ const owner = inspectionResources;++ const result = await resolveHopperMachOImageWithOwner(fixture.target, {+ resourceScope: owner.owner,+ fileSystem,+ });++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Read failure was accepted");+ expect(result.error).toBeInstanceOf(BinaryTargetError);+ expect(result.error.cause).toBe(readFailure);+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(result.error.cleanupResources).toEqual([+ `hopper-macho-preflight:${fixture.sourcePath}`,+ ]);+ expect(result.error.secondaryFailures).toHaveLength(1);+ expect(result.error.secondaryFailures[0]?.cleanupIncomplete).toBe(true);+ expect(closeAttempts).toBe(1);++ allowClose = true;+ await owner.close();+ expect(closeAttempts).toBe(2);+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(result.error.secondaryFailures[0]?.cleanupIncomplete).toBe(false);+});++it("retains exact cancellation during preflight close without replacing its close failure", async () => {+ const fixture = await createThinCopyFixture(+ "rea-hopper-preflight-close-cancel-",+ );+ const controller = new AbortController();+ const reason = { request: "abort-during-preflight-close" };+ const closeFailure = new Error("controlled preflight close failure");+ let allowClose = false;+ let closeAttempts = 0;+ const fileSystem = await createFileSystemWithCloseHook(+ async (_path, close) => {+ closeAttempts += 1;+ if (!allowClose) {+ controller.abort(reason);+ throw closeFailure;+ }+ await close();+ },+ );+ const owner = inspectionResources;++ const result = await resolveHopperMachOImageWithOwner(fixture.target, {+ resourceScope: owner.owner,+ fileSystem,+ signal: controller.signal,+ });++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Close failure was accepted");+ expect(result.error).toBeInstanceOf(BinaryTargetError);+ expect(result.error.cause).toBe(closeFailure);+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(result.error.secondaryFailures).toHaveLength(1);+ expect(result.error.secondaryFailures[0]).toBeInstanceOf(+ AnalysisCancelledError,+ );+ expect(result.error.secondaryFailures[0]?.cause).toBe(reason);++ allowClose = true;+ await owner.close();+ expect(closeAttempts).toBe(2);+ expect(result.error.cleanupIncomplete).toBe(false);+});++const createThinCopyFixture = async (prefix: string) => {+ const directory = await createTestTempDirectory(prefix);+ const bytes = Buffer.alloc(100_000, 0x5a);+ bytes.writeUInt32BE(0xfeedfacf, 0);+ bytes.writeUInt32BE(0x0100000c, 4);+ bytes.writeUInt32BE(0x80000002, 8);+ const sourcePath = join(directory, "source.macho");+ const destination = join(directory, "image.macho");+ await writeFile(sourcePath, bytes);+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ const target = {+ path: sourcePath,+ sha256,+ kind: "executable" as const,+ format: "mach-o" as const,+ architecture: "arm64" as const,+ availableArchitectures: ["arm64"] as const,+ };+ const resolved = await resolveHopperMachOImage({+ ...target,+ });+ if (!resolved.ok) throw resolved.error;+ return {+ sourcePath,+ destination,+ sha256,+ target,+ image: resolved.value,+ };+};diff --git a/src/hopper/HopperMachOImage.test.ts b/src/hopper/HopperMachOImage.test.tsindex e4f81ec6a..0e509b5e5 100644--- a/src/hopper/HopperMachOImage.test.ts+++ b/src/hopper/HopperMachOImage.test.ts@@ -1,15 +1,26 @@import { createHash } from "node:crypto";-import { chmod, readFile, writeFile } from "node:fs/promises";+import {+ access,+ chmod,+ mkdir,+ readFile,+ readdir,+ writeFile,+} from "node:fs/promises";import { join } from "node:path";-import { expect, it } from "vitest";+import { afterEach, expect, it, vi } from "vitest";+import { createInspectionResources } from "../../tests/fixtures/inspectionResources.js";import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { BinaryTargetError } from "../domain/configurationErrors.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import {prepareHopperMachOImage,- resolveHopperMachOImage,+ resolveHopperMachOImage as resolveHopperMachOImageWithOwner,} from "./HopperMachOImage.js";+import { HopperApplicationLauncher } from "./BridgeLauncher.js";const CPU_TYPES = { x86_64: 0x01000007, arm64: 0x0100000c } as const;const FAT32_ALIGNMENT = 12;@@ -105,6 +116,19 @@ const requireResolved = (return result.value;};+let inspectionResources = createInspectionResources();+afterEach(async () => {+ await inspectionResources.close();+ inspectionResources = createInspectionResources();+});++const resolveHopperMachOImage = (+ target: Parameters<typeof resolveHopperMachOImageWithOwner>[0],+) =>+ resolveHopperMachOImageWithOwner(target, {+ resourceScope: inspectionResources.owner,+ });+it.skipIf(process.platform === "win32" || process.getuid?.() === 0)("reports a FAT64 source that became unreadable as a host read denial",async () => {@@ -152,7 +176,7 @@ it("rejects an ELF target before attempting FAT source preparation", async () =>expect(result.error).toMatchObject({_tag: "BinaryTargetError",path,- reason: "Hopper FAT image preparation requires a Mach-O target",+ reason: "Hopper image preparation requires a Mach-O target",});});@@ -214,7 +238,7 @@ it("fails closed when capability variants share the preferred arm64e base", asynconst result = await resolveHopperMachOImage(fat32Target(path, fixture, "arm64"),);- if (result.ok || result.error._tag !== "BinaryTargetError")+ if (result.ok || !(result.error instanceof BinaryTargetError))throw new Error("Expected ambiguous FAT selection to return a BinaryTargetError",);@@ -351,6 +375,7 @@ it("copies exactly the selected FAT32 slice bytes and verifies the source", asyntarget.sha256,resolved,destination,+ { resourceScope: new ArtifactResourceScope() },);if (!prepared.ok) throw new Error(prepared.error.userMessage);const arm64eOffset = fixture.sliceOffsets[1]!;@@ -361,6 +386,197 @@ it("copies exactly the selected FAT32 slice bytes and verifies the source", asynexpect(await readFile(destination)).toEqual(copied);});+it("retains the caller reason when a FAT copy is cancelled after its final write", async () => {+ const directory = await createTestTempDirectory("rea-hopper-fat-cancel-");+ const fixture = buildFat32Container([+ { cpuType: CPU_TYPES.arm64, cpuSubtype: ARM64E },+ ]);+ const path = await writeFixture(directory, "system.fat", fixture);+ const target = fat32Target(path, fixture, "arm64");+ const image = requireResolved(await resolveHopperMachOImage(target));+ const destination = join(directory, "image.macho");+ const controller = new AbortController();+ const reason = { request: "cancel-after-fat-write" };+ const prepared = await prepareHopperMachOImage(+ path,+ target.sha256,+ image,+ destination,+ {+ resourceScope: new ArtifactResourceScope(),+ signal: controller.signal,+ observer: {+ afterChunkWritten: async (copiedBytes) => {+ expect(copiedBytes).toBe(FAT32_SLICE_SIZE);+ controller.abort(reason);+ },+ },+ },+ );++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("Cancelled FAT copy was accepted");+ expect(prepared.error._tag).toBe("HopperCancelledError");+ expect(prepared.error.cause).toBe(reason);+ // The private session directory remains the owner of partial output.+ await expect(readFile(destination)).resolves.toEqual(+ fixture.container.subarray(+ fixture.sliceOffsets[0],+ fixture.sliceOffsets[0]! + FAT32_SLICE_SIZE,+ ),+ );+});++it("retains a failed prepared-image close through launcher cleanup and blocks another launch", async () => {+ const directory = await createTestTempDirectory("rea-hopper-copy-close-");+ const bytes = thinFixture();+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ const actualFs =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ const firstCloseFailure = new Error("first close attempt failed");+ const retryCloseFailure = new Error("cleanup retry failed");+ let allowClose = false;+ let sourceCloseAttempts = 0;+ const imageFileSystem = {+ open: async (...arguments_: Parameters<typeof actualFs.open>) => {+ const handle = await actualFs.open(...arguments_);+ if (arguments_[0] !== path) return handle;+ const sourceClose = async (): Promise<void> => {+ sourceCloseAttempts += 1;+ if (!allowClose && sourceCloseAttempts === 1) throw firstCloseFailure;+ if (!allowClose) throw retryCloseFailure;+ await handle.close();+ };+ return new Proxy(handle, {+ get(targetHandle, property) {+ if (property === "close") return sourceClose;+ const value = Reflect.get(targetHandle, property, targetHandle);+ return typeof value === "function" ? value.bind(targetHandle) : value;+ },+ });+ },+ };++ const sessionDirectory = join(directory, "session");+ await mkdir(sessionDirectory);+ const launcher = new HopperApplicationLauncher(+ {+ environment: {},+ launcherPath: join(directory, "hopper"),+ targetPath: path,+ targetKind: "executable",+ loaderArgs: ["-l", "Mach-O", "--aarch64"],+ bridgeScriptPath: join(directory, "bridge.py"),+ preparedImage: { image, sourceSha256: target.sha256 },+ launchMode: "native",+ },+ { platform: "linux", imageFileSystem },+ );+ const initial = await launcher.launch({+ directory: sessionDirectory,+ socketPath: join(sessionDirectory, "bridge.sock"),+ token: "fixture-token",+ runId: "fixture-run-1",+ });+ expect(initial.ok).toBe(false);+ if (initial.ok) throw new Error("A copy with failed close was accepted");+ expect(initial.error._tag).toBe("HopperStartError");+ expect(initial.error.cause).toBe(firstCloseFailure);+ expect(initial.error.cleanupIncomplete).toBe(true);+ expect(initial.error.cleanupResources).toEqual([+ `hopper-image-source:${path}`,+ ]);+ const blocked = await launcher.launch({+ directory: sessionDirectory,+ socketPath: join(sessionDirectory, "bridge.sock"),+ token: "fixture-token",+ runId: "fixture-run-2",+ });+ expect(blocked.ok).toBe(false);+ if (blocked.ok) throw new Error("A launch bypassed retained file cleanup");+ expect(blocked.error.cleanupIncomplete).toBe(true);+ expect(blocked.error.cleanupResources).toEqual([+ `hopper-image-source:${path}`,+ ]);+ expect(sourceCloseAttempts).toBe(3);++ const cleanupPending = await launcher.cleanup();+ expect(cleanupPending.ok).toBe(false);+ if (cleanupPending.ok)+ throw new Error("Cleanup without release was reported successful");+ expect(cleanupPending.error.cleanupIncomplete).toBe(true);+ expect(cleanupPending.error.cleanupResources).toEqual([+ `hopper-image-source:${path}`,+ ]);+ expect(sourceCloseAttempts).toBe(4);++ allowClose = true;+ await expect(launcher.cleanup()).resolves.toEqual({ ok: true, value: null });+ expect(initial.error.cleanupIncomplete).toBe(false);+ expect(blocked.error.cleanupIncomplete).toBe(false);+ expect(cleanupPending.error.cleanupIncomplete).toBe(false);+ await expect(+ readFile(join(sessionDirectory, "image.macho")),+ ).resolves.toEqual(bytes);+});++it("observes caller cancellation that arrives during final source-handle cleanup", async () => {+ const directory = await createTestTempDirectory(+ "rea-hopper-copy-close-cancel-",+ );+ const bytes = thinFixture();+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ const controller = new AbortController();+ const reason = { request: "cancel-during-final-close" };+ const actualFs =+ await vi.importActual<typeof import("node:fs/promises")>(+ "node:fs/promises",+ );+ const fileSystem = {+ open: async (...arguments_: Parameters<typeof actualFs.open>) => {+ const handle = await actualFs.open(...arguments_);+ if (arguments_[0] !== path) return handle;+ const closeHandle = handle.close.bind(handle);+ Object.defineProperty(handle, "close", {+ configurable: true,+ value: async (): Promise<void> => {+ controller.abort(reason);+ await closeHandle();+ },+ });+ return handle;+ },+ };++ const prepared = await prepareHopperMachOImage(+ path,+ target.sha256,+ image,+ join(directory, "image.macho"),+ {+ resourceScope: new ArtifactResourceScope(),+ signal: controller.signal,+ fileSystem,+ },+ );++ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("Finalization cancellation was ignored");+ expect(prepared.error._tag).toBe("HopperCancelledError");+ expect(prepared.error.cause).toBe(reason);+ await expect(readFile(join(directory, "image.macho"))).resolves.toEqual(+ bytes,+ );+});+it("rejects FAT32 preparation when the source table changed after resolution", async () => {const directory = await createTestTempDirectory("rea-hopper-fat32-race-");const fixture = buildFat32Container([@@ -379,8 +595,186 @@ it("rejects FAT32 preparation when the source table changed after resolution", atarget.sha256,resolved,destination,+ { resourceScope: new ArtifactResourceScope() },);if (prepared.ok)throw new Error("A mutated FAT32 source passed verification");expect(prepared.error.userMessage).toMatch(/no longer agrees/u);});++const thinFixture = (): Buffer => {+ const image = Buffer.alloc(64, 0x5a);+ image.writeUInt32BE(0xfeedfacf, 0);+ image.writeUInt32BE(CPU_TYPES.arm64, 4);+ image.writeUInt32BE(ARM64E_WITH_CAPABILITIES, 8);+ return image;+};++const thinTarget = (path: string, bytes: Buffer) => ({+ path,+ sha256: createHash("sha256").update(bytes).digest("hex"),+ kind: "executable" as const,+ format: "mach-o" as const,+ architecture: "arm64" as const,+ availableArchitectures: ["arm64"] as const,+});++it("copies an admitted thin Mach-O through the owned verified-image path", async () => {+ const directory = await createTestTempDirectory("rea-hopper-thin-copy-");+ const bytes = thinFixture();+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ expect(image).toEqual({+ method: "thin_verified_copy",+ byte_length: bytes.length,+ cpu_type: CPU_TYPES.arm64,+ cpu_subtype: ARM64E_WITH_CAPABILITIES,+ });++ const destination = join(directory, "private", "image.macho");+ await mkdir(join(directory, "private"));+ const prepared = await prepareHopperMachOImage(+ path,+ target.sha256,+ image,+ destination,+ { resourceScope: new ArtifactResourceScope() },+ );+ if (!prepared.ok) throw new Error(prepared.error.userMessage);+ expect(prepared.value).toBe(destination);+ expect(await readFile(destination)).toEqual(bytes);+ expect(target.path).toBe(path);+});++it("does not launch a thin selection when its admitted source changes before copy", async () => {+ const directory = await createTestTempDirectory("rea-hopper-thin-race-");+ const bytes = thinFixture();+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ const changed = Buffer.from(bytes);+ changed.writeUInt8(+ changed.readUInt8(changed.length - 1) ^ 1,+ changed.length - 1,+ );+ await writeFile(path, changed);++ const sessionDirectory = join(directory, "session");+ await mkdir(sessionDirectory);+ const launcher = new HopperApplicationLauncher(+ {+ environment: process.env,+ launcherPath: join(directory, "hopper"),+ targetPath: path,+ targetKind: "executable",+ loaderArgs: ["-l", "Mach-O", "--aarch64"],+ bridgeScriptPath: join(directory, "bridge.py"),+ preparedImage: { image, sourceSha256: target.sha256 },+ launchMode: "native",+ },+ { platform: "linux" },+ );+ const launched = await launcher.launch({+ directory: sessionDirectory,+ socketPath: join(sessionDirectory, "bridge.sock"),+ token: "fixture-token",+ runId: "fixture-run",+ });+ expect(launched.ok).toBe(false);+ if (launched.ok) throw new Error("Changed source reached Hopper launch");+ expect(launched.error.userMessage).toContain(+ "no longer agrees with its admitted digest, size, or selected header",+ );+ await expect(+ access(join(sessionDirectory, "bootstrap.py")),+ ).rejects.toMatchObject({+ code: "ENOENT",+ });+ // The session directory remains the cleanup owner for partial private output.+ await expect(readdir(sessionDirectory)).resolves.toContain("image.macho");+});++it("keeps caller cancellation primary after verified thin-image preparation", async () => {+ const directory = await createTestTempDirectory("rea-hopper-thin-cancel-");+ const bytes = thinFixture();+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ const controller = new AbortController();+ controller.abort(new Error("caller cancellation"));+ const prepared = await prepareHopperMachOImage(+ path,+ target.sha256,+ image,+ join(directory, "image.macho"),+ { resourceScope: new ArtifactResourceScope(), signal: controller.signal },+ );+ expect(prepared).toMatchObject({+ ok: false,+ error: { _tag: "HopperCancelledError" },+ });+});++it("retains an owned partial thin image and exact cancellation reason after a write", async () => {+ const directory = await createTestTempDirectory("rea-hopper-thin-partial-");+ const bytes = Buffer.alloc(2 * 1024 * 1024, 0x5a);+ bytes.writeUInt32BE(0xfeedfacf, 0);+ bytes.writeUInt32BE(CPU_TYPES.arm64, 4);+ bytes.writeUInt32BE(ARM64E_WITH_CAPABILITIES, 8);+ const path = join(directory, "source.macho");+ await writeFile(path, bytes);+ const target = thinTarget(path, bytes);+ const image = requireResolved(await resolveHopperMachOImage(target));+ const sessionDirectory = join(directory, "session");+ await mkdir(sessionDirectory);+ const destination = join(sessionDirectory, "image.macho");+ const controller = new AbortController();+ const reason = { owner: "caller", request: 44 };+ let releaseWrite: (() => void) | undefined;+ let announceWrite: ((copiedBytes: number) => void) | undefined;+ const writeGate = new Promise<void>((resolve) => {+ releaseWrite = resolve;+ });+ const firstWrite = new Promise<number>((resolve) => {+ announceWrite = resolve;+ });+ const preparing = prepareHopperMachOImage(+ path,+ target.sha256,+ image,+ destination,+ {+ resourceScope: new ArtifactResourceScope(),+ signal: controller.signal,+ observer: {+ afterChunkWritten: async (copiedBytes) => {+ announceWrite?.(copiedBytes);+ await writeGate;+ },+ },+ },+ );++ const copiedBytes = await firstWrite;+ const partial = await readFile(destination);+ expect(partial.byteLength).toBe(copiedBytes);+ expect(copiedBytes).toBeGreaterThan(0);+ expect(copiedBytes).toBeLessThan(bytes.length);+ controller.abort(reason);+ const finishWrite = releaseWrite;+ if (finishWrite === undefined)+ throw new Error("Copy barrier was not created");+ finishWrite();++ const prepared = await preparing;+ expect(prepared.ok).toBe(false);+ if (prepared.ok) throw new Error("Cancelled partial copy was accepted");+ expect(prepared.error._tag).toBe("HopperCancelledError");+ expect(prepared.error.cause).toBe(reason);+ await expect(readFile(destination)).resolves.toEqual(partial);+ await expect(access(destination)).resolves.toBeUndefined();+});diff --git a/src/hopper/HopperMachOImage.ts b/src/hopper/HopperMachOImage.tsindex 4b0a48cf5..0c746b507 100644--- a/src/hopper/HopperMachOImage.ts+++ b/src/hopper/HopperMachOImage.ts@@ -2,9 +2,17 @@ import { createHash } from "node:crypto";import { open, type FileHandle } from "node:fs/promises";import { z } from "zod";+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import {+ AnalysisCleanupLease,+ AnalysisCleanupLeaseGroup,+} from "../artifacts/AnalysisCleanupLease.js";+import type { RetainedResourceScope } from "../application/AnalysisProvider.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";import { BinaryTargetError } from "../domain/configurationErrors.js";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";import {readFatSliceDeclarations,validateFatSlice,@@ -17,13 +25,29 @@ import {HopperStartError,} from "../domain/hopperErrors.js";import { err, ok, type Result } from "../domain/result.js";+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";-/** Stable source coordinates committed before preparing an owned thin image. */-export const hopperMachOImageSchema = z.strictObject({- method: z.union([- z.literal("fat32_thin_slice"),- z.literal("fat64_thin_slice"),- ]),+/** Narrow file-opening dependency for the owned prepared-image copy. */+export interface HopperMachOImageFileSystem {+ readonly open: typeof open;+}++export interface HopperMachOImageCopyDependencies {+ /** Persistent owner that can retry any retained descriptor cleanup. */+ readonly resourceScope: ArtifactResourceScope;+ readonly fileSystem?: HopperMachOImageFileSystem;+}++export interface HopperMachOImagePreparationOptions extends HopperMachOImageCopyDependencies {+ readonly signal?: AbortSignal;+ readonly observer?: HopperMachOImageCopyObserver;+}++const defaultHopperMachOImageFileSystem: HopperMachOImageFileSystem = { open };++const hopperFatMachOImageSchema = z.strictObject({+ method: z.enum(["fat32_thin_slice", "fat64_thin_slice"]),architecture_count: z.number().int().min(1).max(128),container_table_sha256: z.string().regex(/^[a-f0-9]{64}$/u),source_offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),@@ -32,15 +56,50 @@ export const hopperMachOImageSchema = z.strictObject({cpu_subtype: z.number().int().nonnegative(),});+const hopperThinMachOImageSchema = z.strictObject({+ method: z.literal("thin_verified_copy"),+ byte_length: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),+ cpu_type: z.number().int().nonnegative(),+ cpu_subtype: z.number().int().nonnegative(),+});++/** Stable source coordinates committed before preparing an owned thin image. */+export const hopperMachOImageSchema = z.discriminatedUnion("method", [+ hopperFatMachOImageSchema,+ hopperThinMachOImageSchema,+]);+export type HopperMachOImage = z.infer<typeof hopperMachOImageSchema>;+type HopperMachOImageResolutionError =+ | BinaryTargetError+ | AnalysisCancelledError;++/** Controlled checkpoint for deterministic interruption of a real copy. */+export interface HopperMachOImageCopyObserver {+ readonly afterChunkWritten?: (copiedBytes: number) => Promise<void>;+}++/** Filesystem access used by the admitted Mach-O preflight. */+export interface HopperMachOImageResolutionFileSystem {+ readonly open: typeof open;+}++export interface HopperMachOImageResolutionOptions {+ readonly resourceScope: RetainedResourceScope;+ readonly signal?: AbortSignal;+ readonly fileSystem?: HopperMachOImageResolutionFileSystem;+}-/** Validate the selected FAT slice without depending on Apple's lipo tool. */+const defaultHopperMachOImageResolutionFileSystem: HopperMachOImageResolutionFileSystem =+ {+ open,+ };++/** Validate the selected Mach-O image without depending on Apple's lipo tool. */export const resolveHopperMachOImage = async (target: BinaryTarget & { readonly kind: "executable" },- signal?: AbortSignal,-): Promise<- Result<HopperMachOImage, BinaryTargetError | AnalysisCancelledError>-> => {+ options: HopperMachOImageResolutionOptions,+): Promise<Result<HopperMachOImage, AnalysisError>> => {const invalid = (reason: string, cause?: unknown) =>err(new BinaryTargetError(@@ -49,129 +108,349 @@ export const resolveHopperMachOImage = async (cause === undefined ? undefined : { cause },),);- if (signal?.aborted) return err(new AnalysisCancelledError("open_binary"));+ if (options.signal?.aborted)+ return err(+ new AnalysisCancelledError("open_binary", {+ cause: options.signal.reason,+ }),+ );if (target.format !== "mach-o" && target.format !== "mach-o-universal")- return invalid("Hopper FAT image preparation requires a Mach-O target");- let file: FileHandle;+ return invalid("Hopper image preparation requires a Mach-O target");+ let opened: FileHandle;try {- file = await open(target.path, "r");+ opened = await (+ options.fileSystem ?? defaultHopperMachOImageResolutionFileSystem+ ).open(target.path, "r");} catch (cause: unknown) {// Keep the OS error so a read-permission denial reports access_denied.return invalid(- `Cannot read FAT source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`,+ `Cannot read Mach-O source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`,cause,);}+ return inspectAndFinalizeHopperMachOImage(+ target,+ new OwnedFileHandle(opened),+ options,+ );+};++const inspectAndFinalizeHopperMachOImage = async (+ target: BinaryTarget & { readonly kind: "executable" },+ owner: OwnedFileHandle,+ options: HopperMachOImageResolutionOptions,+): Promise<Result<HopperMachOImage, AnalysisError>> => {+ let result: Result<HopperMachOImage, HopperMachOImageResolutionError>;try {- const read = async (offset: number, length: number): Promise<Buffer> => {- const bytes = Buffer.alloc(length);- const { bytesRead } = await file.read(bytes, 0, length, offset);- return bytes.subarray(0, bytesRead);- };- const header = await read(0, 8);- const magic = header.length === 8 ? header.readUInt32BE(0) : 0;- const isFatMagic = [- 0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca,- ].includes(magic);- if (!isFatMagic)- return invalid(- "FAT source header changed before Hopper image preparation",- );- const wide = magic === 0xcafebabf || magic === 0xbfbafeca;- const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;- const entrySize = wide ? 32 : 20;- const count = littleEndian- ? header.readUInt32LE(4)- : header.readUInt32BE(4);- const size = (await file.stat()).size;- const tableEnd = 8 + count * entrySize;- if (count === 0 || count > 128 || tableEnd > size)- return invalid(- "FAT architecture table is truncated or exceeds the supported 128 entries",+ result = await inspectHopperMachOImage(+ target,+ owner.handle,+ options.signal,+ );+ } catch (cause: unknown) {+ result =+ cause instanceof BinaryTargetError ||+ cause instanceof AnalysisCancelledError+ ? err(cause)+ : err(+ new BinaryTargetError(+ target.path,+ `Cannot validate Mach-O image: ${cause instanceof Error ? cause.message : String(cause)}`,+ { cause },+ ),+ );+ }+ const cancellationBeforeClose = options.signal?.aborted === true;+ let closeOutcome:+ | { readonly kind: "closed" }+ | { readonly kind: "failed"; readonly cause: unknown };+ try {+ await owner.close();+ closeOutcome = { kind: "closed" };+ } catch (cause: unknown) {+ closeOutcome = { kind: "failed", cause };+ }+ if (closeOutcome.kind === "closed") {+ if (result.ok && options.signal?.aborted)+ return err(+ new AnalysisCancelledError("open_binary", {+ cause: options.signal.reason,+ }),);- const table = await read(8, count * entrySize);- const parsed = readFatSliceDeclarations(table, {- count,- wide,- littleEndian,+ return result;+ }+ return retainHopperPreflightCloseFailure({+ target,+ owner,+ resourceScope: options.resourceScope,+ result,+ cancellationBeforeClose,+ signal: options.signal,+ closeFailure: closeOutcome.cause,+ });+};++const retainHopperPreflightCloseFailure = (options: {+ readonly target: BinaryTarget & { readonly kind: "executable" };+ readonly owner: OwnedFileHandle;+ readonly resourceScope: RetainedResourceScope;+ readonly result: Result<HopperMachOImage, HopperMachOImageResolutionError>;+ readonly cancellationBeforeClose: boolean;+ readonly signal: AbortSignal | undefined;+ readonly closeFailure: unknown;+}): Result<HopperMachOImage, AnalysisError> => {+ const resource = `hopper-macho-preflight:${options.target.path}`;+ const lease = AnalysisCleanupLease.forCloseOwner(options.owner, resource);+ options.resourceScope.retain(+ {+ close: () => lease.release(),+ get cleanupResources() {+ return lease.cleanupResources;+ },+ },+ resource,+ );+ const cleanup = {+ reason:+ options.closeFailure instanceof Error+ ? options.closeFailure.message+ : String(options.closeFailure),+ resources: [resource],+ };+ const cancellationIsPrimary =+ (!options.result.ok &&+ options.result.error instanceof AnalysisCancelledError) ||+ (options.result.ok && options.cancellationBeforeClose);+ let failure: AnalysisError;+ let closeIsPrimary = false;+ if (!options.result.ok) {+ failure =+ options.result.error instanceof BinaryTargetError+ ? new BinaryTargetError(+ options.result.error.path,+ options.result.error.reason,+ {+ ...(options.result.error.cause === undefined+ ? {}+ : { cause: options.result.error.cause }),+ ...(options.result.error.constraint === undefined+ ? {}+ : { constraint: options.result.error.constraint }),+ cleanup,+ },+ )+ : new AnalysisCancelledError("open_binary", {+ cause: options.result.error.cause,+ cleanup,+ });+ } else if (options.cancellationBeforeClose) {+ failure = new AnalysisCancelledError("open_binary", {+ cause: options.signal?.reason,+ cleanup,});- if (parsed.status === "malformed") return invalid(parsed.reason);- const cpuTypes = { x86: 7, x86_64: 0x1000007, arm: 12, arm64: 0x100000c };- const matches = [];- const ranges = [];- for (const slice of parsed.slices) {+ } else {+ failure = new BinaryTargetError(+ options.target.path,+ "Could not confirm closure of the Mach-O preflight handle",+ { cause: options.closeFailure, cleanup },+ );+ closeIsPrimary = true;+ }+ const cleanupError = new ProviderCleanupError(+ "hopper",+ [resource],+ { reason: cleanup.reason },+ {+ cause: options.closeFailure,+ operation: "resolve_analysis_profile",+ },+ );+ if (!closeIsPrimary) {+ lease.bindCleanupError(cleanupError);+ failure.retainSecondaryFailure(cleanupError);+ }+ if (options.signal?.aborted && !cancellationIsPrimary)+ failure.retainSecondaryFailure(+ new AnalysisCancelledError("open_binary", {+ cause: options.signal.reason,+ }),+ );+ new AnalysisCleanupLeaseGroup(failure, [lease]);+ return err(failure);+};++const inspectHopperMachOImage = async (+ target: BinaryTarget & { readonly kind: "executable" },+ file: FileHandle,+ signal: AbortSignal | undefined,+): Promise<Result<HopperMachOImage, HopperMachOImageResolutionError>> => {+ const invalid = (reason: string, cause?: unknown) =>+ err(+ new BinaryTargetError(+ target.path,+ reason,+ cause === undefined ? undefined : { cause },+ ),+ );+ const read = async (offset: number, length: number): Promise<Buffer> => {+ const bytes = Buffer.alloc(length);+ const { bytesRead } = await file.read(bytes, 0, length, offset);+ return bytes.subarray(0, bytesRead);+ };+ const header = await read(0, 8);+ const magic = header.length === 8 ? header.readUInt32BE(0) : 0;+ if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic)) {+ if (target.format !== "mach-o")+ return invalid("Thin Mach-O source disagrees with its admitted format");+ const prefix = Buffer.alloc(12);+ const hash = createHash("sha256");+ let prefixLength = 0;+ let size = 0;+ for await (const chunk of readFileHandleChunks(file, {+ ...(signal === undefined ? {} : { signal }),+ cancellationFailure: (reason) =>+ new AnalysisCancelledError("open_binary", { cause: reason }),+ })) {if (signal?.aborted)- return err(new AnalysisCancelledError("open_binary"));- const rangeError = validateFatSlice(slice, size, tableEnd);- if (rangeError !== null) return invalid(rangeError);- if (wide) {- const reserved = littleEndian- ? table.readUInt32LE(slice.index * 32 + 28)- : table.readUInt32BE(slice.index * 32 + 28);- if (reserved !== 0)- return invalid(- `FAT64 architecture ${slice.index} has a nonzero reserved field`,- );- }- if (slice.size < 12)- return invalid(- `FAT architecture ${slice.index} has a truncated Mach-O header`,- );- const embedded = await read(slice.offset, 12);- if (embedded.length !== 12)- return invalid(`FAT architecture ${slice.index} became truncated`);- const thinMagic = embedded.readUInt32BE(0);- if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))- return invalid(- `FAT architecture ${slice.index} does not contain a Mach-O image`,+ return err(+ new AnalysisCancelledError("open_binary", {+ cause: signal.reason,+ }),);- const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;- const identity = {- cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),- cpuSubtype: little- ? embedded.readUInt32LE(8)- : embedded.readUInt32BE(8),- };- const identityError = validateFatSlice(slice, size, tableEnd, identity);- if (identityError !== null) return invalid(identityError);- ranges.push(slice);- if (slice.cpuType === cpuTypes[target.architecture]) matches.push(slice);- }- ranges.sort((a, b) => a.offset - b.offset);- for (let index = 1; index < ranges.length; index++) {- const previous = ranges[index - 1];- const current = ranges[index];- if (- previous !== undefined &&- current !== undefined &&- current.offset < previous.offset + previous.size- )- return invalid("FAT slices overlap");+ const bytes = Buffer.from(chunk);+ hash.update(bytes);+ size += bytes.length;+ if (!Number.isSafeInteger(size))+ return invalid("Thin Mach-O exceeds exact selection coordinates");+ const copied = Math.min(prefix.length - prefixLength, bytes.length);+ if (copied > 0) {+ bytes.copy(prefix, prefixLength, 0, copied);+ prefixLength += copied;+ }}- const selected = selectHopperSlice(matches, target.architecture);- if (selected === undefined)+ if (signal?.aborted)+ return err(+ new AnalysisCancelledError("open_binary", { cause: signal.reason }),+ );+ if (prefixLength !== prefix.length)+ return invalid("Thin Mach-O header is truncated");+ const observedSha256 = hash.digest("hex");+ if (observedSha256 !== target.sha256)return invalid(- `FAT selection for ${target.architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`,+ `Thin Mach-O source changed after target admission: expected SHA-256 ${target.sha256}, observed ${observedSha256}`,);+ const little = magic === 0xcefaedfe || magic === 0xcffaedfe;+ const headerMagic = prefix.readUInt32BE(0);+ if (headerMagic !== magic)+ return invalid("Thin Mach-O header changed during profile resolution");return ok({- method: wide ? "fat64_thin_slice" : "fat32_thin_slice",- architecture_count: count,- container_table_sha256: createHash("sha256")- .update(header)- .update(table)- .digest("hex"),- source_offset: selected.offset,- byte_length: selected.size,- cpu_type: selected.cpuType,- cpu_subtype: selected.cpuSubtype,+ method: "thin_verified_copy",+ byte_length: size,+ cpu_type: little ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4),+ cpu_subtype: little ? prefix.readUInt32LE(8) : prefix.readUInt32BE(8),});- } catch (cause: unknown) {+ }+ const isFatMagic = [0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca].includes(+ magic,+ );+ if (!isFatMagic)+ return invalid(+ "Mach-O source header changed before Hopper image preparation",+ );+ const wide = magic === 0xcafebabf || magic === 0xbfbafeca;+ const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;+ const entrySize = wide ? 32 : 20;+ const count = littleEndian ? header.readUInt32LE(4) : header.readUInt32BE(4);+ const size = (await file.stat()).size;+ const tableEnd = 8 + count * entrySize;+ if (count === 0 || count > 128 || tableEnd > size)return invalid(- `Cannot validate FAT image: ${cause instanceof Error ? cause.message : String(cause)}`,+ "FAT architecture table is truncated or exceeds the supported 128 entries",);- } finally {- await file.close();+ const table = await read(8, count * entrySize);+ const parsed = readFatSliceDeclarations(table, {+ count,+ wide,+ littleEndian,+ });+ if (parsed.status === "malformed") return invalid(parsed.reason);+ if (+ target.architecture !== "x86" &&+ target.architecture !== "x86_64" &&+ target.architecture !== "arm" &&+ target.architecture !== "arm64"+ )+ return invalid("Hopper cannot select the admitted Mach-O architecture");+ const architecture = target.architecture;+ const cpuTypes = { x86: 7, x86_64: 0x1000007, arm: 12, arm64: 0x100000c };+ const matches = [];+ const ranges = [];+ for (const slice of parsed.slices) {+ if (signal?.aborted)+ return err(+ new AnalysisCancelledError("open_binary", { cause: signal.reason }),+ );+ const rangeError = validateFatSlice(slice, size, tableEnd);+ if (rangeError !== null) return invalid(rangeError);+ if (wide) {+ const reserved = littleEndian+ ? table.readUInt32LE(slice.index * 32 + 28)+ : table.readUInt32BE(slice.index * 32 + 28);+ if (reserved !== 0)+ return invalid(+ `FAT64 architecture ${slice.index} has a nonzero reserved field`,+ );+ }+ if (slice.size < 12)+ return invalid(+ `FAT architecture ${slice.index} has a truncated Mach-O header`,+ );+ const embedded = await read(slice.offset, 12);+ if (embedded.length !== 12)+ return invalid(`FAT architecture ${slice.index} became truncated`);+ const thinMagic = embedded.readUInt32BE(0);+ if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))+ return invalid(+ `FAT architecture ${slice.index} does not contain a Mach-O image`,+ );+ const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;+ const identity = {+ cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),+ cpuSubtype: little ? embedded.readUInt32LE(8) : embedded.readUInt32BE(8),+ };+ const identityError = validateFatSlice(slice, size, tableEnd, identity);+ if (identityError !== null) return invalid(identityError);+ ranges.push(slice);+ if (slice.cpuType === cpuTypes[architecture]) matches.push(slice);+ }+ ranges.sort((a, b) => a.offset - b.offset);+ for (let index = 1; index < ranges.length; index++) {+ const previous = ranges[index - 1];+ const current = ranges[index];+ if (+ previous !== undefined &&+ current !== undefined &&+ current.offset < previous.offset + previous.size+ )+ return invalid("FAT slices overlap");}+ const selected = selectHopperSlice(matches, architecture);+ if (selected === undefined)+ return invalid(+ `FAT selection for ${architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`,+ );+ return ok({+ method: wide ? "fat64_thin_slice" : "fat32_thin_slice",+ architecture_count: count,+ container_table_sha256: createHash("sha256")+ .update(header)+ .update(table)+ .digest("hex"),+ source_offset: selected.offset,+ byte_length: selected.size,+ cpu_type: selected.cpuType,+ cpu_subtype: selected.cpuSubtype,+ });};/**@@ -202,87 +481,398 @@ export const prepareHopperMachOImage = async (sourceSha256: string,image: HopperMachOImage,destination: string,- signal?: AbortSignal,+ options: HopperMachOImagePreparationOptions,): Promise<Result<string, HopperStartError | HopperCancelledError>> => {- if (signal?.aborted) return err(new HopperCancelledError());+ const copyDependencies = {+ resourceScope: options.resourceScope,+ fileSystem: options.fileSystem ?? defaultHopperMachOImageFileSystem,+ };+ const { signal, observer } = options;+ if (signal?.aborted) return err(new HopperCancelledError(signal.reason));+ if (image.method === "thin_verified_copy") {+ const prepared = await prepareThinHopperMachOImage(+ sourcePath,+ sourceSha256,+ image,+ destination,+ { signal, observer, ...copyDependencies },+ );+ return signal?.aborted && prepared.ok+ ? err(new HopperCancelledError(signal.reason))+ : prepared;+ }const tableEntrySize = image.method === "fat64_thin_slice" ? 32 : 20;+ const hash = createHash("sha256");+ const tableHash = createHash("sha256");+ const tableEnd = 8 + image.architecture_count * tableEntrySize;+ const thinHeader: Buffer[] = [];+ let copied = 0;+ const copiedResult = await copyHopperSource({+ sourcePath,+ destination,+ signal,+ observer,+ ...copyDependencies,+ selectBytes: (bytes, position) => {+ hash.update(bytes);+ if (position < tableEnd)+ tableHash.update(+ bytes.subarray(0, Math.min(bytes.length, tableEnd - position)),+ );+ const start = Math.max(0, image.source_offset - position);+ const end = Math.min(+ bytes.length,+ image.source_offset + image.byte_length - position,+ );+ if (end <= start) return undefined;+ if (copied < 12)+ thinHeader.push(+ bytes.subarray(start, Math.min(end, start + 12 - copied)),+ );+ copied += end - start;+ return bytes.subarray(start, end);+ },+ failureContext: `Cannot prepare the selected FAT image from ${sourcePath}`,+ });+ if (!copiedResult.ok) return copiedResult;+ const observed = hash.digest("hex");+ const header = Buffer.concat(thinHeader);+ const magic = header.length === 12 ? header.readUInt32BE(0) : 0;+ const little = magic === 0xcefaedfe || magic === 0xcffaedfe;+ const headerMatches =+ header.length === 12 &&+ [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&+ (little ? header.readUInt32LE(4) : header.readUInt32BE(4)) ===+ image.cpu_type &&+ (little ? header.readUInt32LE(8) : header.readUInt32BE(8)) ===+ image.cpu_subtype;+ if (+ tableHash.digest("hex") !== image.container_table_sha256 ||+ !headerMatches+ )+ return err(+ new HopperStartError({+ userMessage: `FAT source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,+ }),+ );+ if (observed !== sourceSha256 || copied !== image.byte_length)+ return err(+ new HopperStartError({+ userMessage: `FAT source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,+ }),+ );+ return signal?.aborted+ ? err(new HopperCancelledError(signal.reason))+ : ok(destination);+};++const prepareThinHopperMachOImage = async (+ sourcePath: string,+ sourceSha256: string,+ image: Extract<HopperMachOImage, { method: "thin_verified_copy" }>,+ destination: string,+ options: {+ readonly signal: AbortSignal | undefined;+ readonly observer: HopperMachOImageCopyObserver | undefined;+ readonly resourceScope: ArtifactResourceScope;+ readonly fileSystem: HopperMachOImageFileSystem;+ },+): Promise<Result<string, HopperStartError | HopperCancelledError>> => {+ const { signal, observer, resourceScope, fileSystem } = options;+ const hash = createHash("sha256");+ const prefix = Buffer.alloc(12);+ let prefixLength = 0;+ const copiedResult = await copyHopperSource({+ sourcePath,+ destination,+ signal,+ observer,+ resourceScope,+ fileSystem,+ selectBytes: (bytes) => {+ hash.update(bytes);+ const prefixBytes = Math.min(prefix.length - prefixLength, bytes.length);+ if (prefixBytes > 0) {+ bytes.copy(prefix, prefixLength, 0, prefixBytes);+ prefixLength += prefixBytes;+ }+ return bytes;+ },+ failureContext: `Cannot prepare the verified thin image from ${sourcePath}`,+ });+ if (!copiedResult.ok) return copiedResult;+ const copied = copiedResult.value;+ if (!Number.isSafeInteger(copied))+ return err(+ new HopperStartError({+ userMessage: `Thin Mach-O source ${sourcePath} exceeds exact copy coordinates.`,+ }),+ );+ const observed = hash.digest("hex");+ const magic = prefixLength === prefix.length ? prefix.readUInt32BE(0) : 0;+ const little = magic === 0xcefaedfe || magic === 0xcffaedfe;+ const headerMatches =+ prefixLength === prefix.length &&+ [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&+ (little ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4)) ===+ image.cpu_type &&+ (little ? prefix.readUInt32LE(8) : prefix.readUInt32BE(8)) ===+ image.cpu_subtype;+ if (+ observed !== sourceSha256 ||+ copied !== image.byte_length ||+ !headerMatches+ )+ return err(+ new HopperStartError({+ userMessage: `Thin Mach-O source ${sourcePath} no longer agrees with its admitted digest, size, or selected header. Open the stable source again.`,+ }),+ );+ return signal?.aborted+ ? err(new HopperCancelledError(signal.reason))+ : ok(destination);+};++type HopperImageHandle = OwnedFileHandle | undefined;+type HopperImageCloseFailure = {+ readonly resource: string;+ readonly cause: unknown;+};+type HopperImageCleanupAttempt = Extract<+ Awaited<ReturnType<ArtifactResourceScope["release"]>>,+ { readonly kind: "failed" }+>;++interface HopperImageCopyOperation {+ readonly copied: number;+ readonly operationFailure:+ | { readonly failed: false }+ | {+ readonly failed: true;+ readonly cause: unknown;+ };+ readonly cancelled:+ | { readonly cancelled: false }+ | {+ readonly cancelled: true;+ readonly reason: unknown;+ };+ readonly source: HopperImageHandle;+ readonly output: HopperImageHandle;+}++interface HopperImageCopyFinalization {+ readonly closeFailures: readonly HopperImageCloseFailure[];+ readonly retained: readonly HopperImageCleanupAttempt[];+}++/** Own source/output handles and copy finalization for both Mach-O layouts. */+const copyHopperSource = async (options: {+ readonly sourcePath: string;+ readonly destination: string;+ readonly signal: AbortSignal | undefined;+ readonly observer: HopperMachOImageCopyObserver | undefined;+ readonly resourceScope: ArtifactResourceScope;+ readonly fileSystem: HopperMachOImageFileSystem;+ readonly selectBytes: (chunk: Buffer, position: number) => Buffer | undefined;+ readonly failureContext: string;+}): Promise<Result<number, HopperStartError | HopperCancelledError>> => {+ if (options.signal?.aborted)+ return err(new HopperCancelledError(options.signal.reason));+ const operation = await performHopperImageCopy(options);+ const cancellationBeforeFinalization = operation.cancelled.cancelled+ ? operation.cancelled+ : options.signal?.aborted === true+ ? { cancelled: true as const, reason: options.signal.reason }+ : { cancelled: false as const };+ const finalization = await closeHopperImageHandles(operation, options);+ const cancelled =+ cancellationBeforeFinalization.cancelled ||+ (finalization.closeFailures.length === 0 &&+ options.signal?.aborted === true);+ const cancelReason = cancellationBeforeFinalization.cancelled+ ? cancellationBeforeFinalization.reason+ : options.signal?.reason;+ if (+ !operation.operationFailure.failed &&+ !cancelled &&+ finalization.closeFailures.length === 0+ )+ return ok(operation.copied);+ return hopperImageCopyFailure({+ operation,+ finalization,+ failureContext: options.failureContext,+ cancelled,+ cancelReason,+ });+};++const performHopperImageCopy = async (options: {+ readonly sourcePath: string;+ readonly destination: string;+ readonly signal: AbortSignal | undefined;+ readonly observer: HopperMachOImageCopyObserver | undefined;+ readonly fileSystem: HopperMachOImageFileSystem;+ readonly selectBytes: (chunk: Buffer, position: number) => Buffer | undefined;+}): Promise<HopperImageCopyOperation> => {+ let copied = 0;+ let source: HopperImageHandle;+ let output: HopperImageHandle;try {- const source = await open(sourcePath, "r");- try {- const output = await open(destination, "wx", 0o600);- try {- const hash = createHash("sha256");- const tableHash = createHash("sha256");- const tableEnd = 8 + image.architecture_count * tableEntrySize;- const thinHeader: Buffer[] = [];- let position = 0;- let copied = 0;- for await (const chunk of source.createReadStream({- autoClose: false,- })) {- if (signal?.aborted) return err(new HopperCancelledError());- const bytes = Buffer.from(chunk);- hash.update(bytes);- if (position < tableEnd)- tableHash.update(- bytes.subarray(0, Math.min(bytes.length, tableEnd - position)),- );- const start = Math.max(0, image.source_offset - position);- const end = Math.min(- bytes.length,- image.source_offset + image.byte_length - position,- );- if (end > start) {- if (copied < 12)- thinHeader.push(- bytes.subarray(start, Math.min(end, start + 12 - copied)),- );- await output.writeFile(bytes.subarray(start, end));- copied += end - start;- }- position += bytes.length;- }- const observed = hash.digest("hex");- const header = Buffer.concat(thinHeader);- const magic = header.length === 12 ? header.readUInt32BE(0) : 0;- const little = magic === 0xcefaedfe || magic === 0xcffaedfe;- const headerMatches =- header.length === 12 &&- [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&- (little ? header.readUInt32LE(4) : header.readUInt32BE(4)) ===- image.cpu_type &&- (little ? header.readUInt32LE(8) : header.readUInt32BE(8)) ===- image.cpu_subtype;- if (- tableHash.digest("hex") !== image.container_table_sha256 ||- !headerMatches- )- return err(- new HopperStartError({- userMessage: `FAT source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,- }),- );- if (observed !== sourceSha256 || copied !== image.byte_length)- return err(- new HopperStartError({- userMessage: `FAT source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,- }),- );- return ok(destination);- } finally {- await output.close();+ source = new OwnedFileHandle(+ await options.fileSystem.open(options.sourcePath, "r"),+ );+ output = new OwnedFileHandle(+ await options.fileSystem.open(options.destination, "wx", 0o600),+ );+ } catch (cause: unknown) {+ return {+ copied,+ operationFailure: { failed: true, cause },+ cancelled: { cancelled: false },+ source,+ output,+ };+ }++ try {+ let position = 0;+ for await (const bytes of readFileHandleChunks(source.handle)) {+ if (options.signal?.aborted)+ return {+ copied,+ operationFailure: { failed: false },+ cancelled: { cancelled: true, reason: options.signal.reason },+ source,+ output,+ };+ const selected = options.selectBytes(bytes, position);+ if (selected !== undefined && selected.length > 0) {+ await output.handle.writeFile(selected);+ copied += selected.length;+ await options.observer?.afterChunkWritten?.(copied);}- } finally {- await source.close();+ position += bytes.length;}+ return {+ copied,+ operationFailure: { failed: false },+ cancelled: { cancelled: false },+ source,+ output,+ };} catch (cause: unknown) {- return signal?.aborted- ? err(new HopperCancelledError())- : err(- new HopperStartError({- cause,- userMessage: `Cannot prepare the selected FAT image from ${sourcePath}: ${cause instanceof Error ? cause.message : String(cause)}`,- }),- );+ return {+ copied,+ operationFailure: { failed: true, cause },+ cancelled: { cancelled: false },+ source,+ output,+ };+ }+};++const closeHopperImageHandles = async (+ operation: HopperImageCopyOperation,+ options: {+ readonly sourcePath: string;+ readonly destination: string;+ readonly resourceScope: ArtifactResourceScope;+ },+): Promise<HopperImageCopyFinalization> => {+ const closeFailures: HopperImageCloseFailure[] = [];+ const retained: HopperImageCleanupAttempt[] = [];+ const close = async (+ owner: HopperImageHandle,+ resource: string,+ ): Promise<void> => {+ if (owner === undefined) return;+ try {+ await owner.close();+ } catch (cause: unknown) {+ closeFailures.push({ resource, cause });+ const attempt = await options.resourceScope.release({+ kind: "file-handle",+ resource,+ handle: owner,+ });+ if (attempt.kind === "failed") retained.push(attempt);+ }+ };+ await close(operation.output, `hopper-prepared-image:${options.destination}`);+ await close(operation.source, `hopper-image-source:${options.sourcePath}`);+ return { closeFailures, retained };+};++const hopperImageCopyFailure = (options: {+ readonly operation: HopperImageCopyOperation;+ readonly finalization: HopperImageCopyFinalization;+ readonly failureContext: string;+ readonly cancelled: boolean;+ readonly cancelReason: unknown;+}): Result<number, HopperStartError | HopperCancelledError> => {+ const { operation, finalization } = options;+ const cleanupErrors = finalization.retained.map((attempt) => {+ const cleanupError = new ProviderCleanupError(+ "hopper",+ [attempt.owner.resource],+ {+ reason:+ attempt.cause instanceof Error+ ? attempt.cause.message+ : String(attempt.cause),+ },+ { cause: attempt.cause },+ );+ attempt.lease.bindCleanupError(cleanupError);+ return cleanupError;+ });+ const cleanup =+ cleanupErrors.length === 0+ ? undefined+ : {+ reason: cleanupErrors.map((failure) => failure.message).join("; "),+ resources: [+ ...new Set(+ cleanupErrors.flatMap((failure) => failure.cleanupResources),+ ),+ ],+ };+ const primaryFailure = operation.operationFailure.failed+ ? operation.operationFailure.cause+ : finalization.closeFailures[0]?.cause;+ const resultError =+ options.cancelled && !operation.operationFailure.failed+ ? new HopperCancelledError(+ options.cancelReason,+ cleanup === undefined ? {} : { cleanup },+ )+ : new HopperStartError({+ ...(operation.operationFailure.failed ||+ finalization.closeFailures.length > 0+ ? { cause: primaryFailure }+ : {}),+ userMessage: `${options.failureContext}: ${primaryFailure instanceof Error ? primaryFailure.message : String(primaryFailure ?? "caller cancellation")}`,+ ...(cleanup === undefined ? {} : { cleanup }),+ });+ for (const closeFailure of finalization.closeFailures) {+ if (+ !operation.operationFailure.failed &&+ !options.cancelled &&+ closeFailure === finalization.closeFailures[0]+ )+ continue;+ resultError.retainSecondaryFailure(+ new HopperStartError({+ cause: closeFailure.cause,+ userMessage: `Could not confirm closure of ${closeFailure.resource}.`,+ }),+ );}+ for (const cleanupError of cleanupErrors)+ resultError.retainSecondaryFailure(cleanupError);+ if (cleanupErrors.length > 0)+ resultError.bindCleanupDependencies(cleanupErrors);+ return err(resultError);};diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.tsindex 610894440..c9c929947 100644--- a/src/hopper/HopperProvider.ts+++ b/src/hopper/HopperProvider.ts@@ -24,6 +24,14 @@ import type { JsonValue } from "../domain/jsonValue.js";import type { Logger } from "pino";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 {+ ArtifactResourceRetryFailure,+ ArtifactResourceScope,+} from "../artifacts/ArtifactResourceScope.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { HopperApplicationLauncher } from "./BridgeLauncher.js";import {hopperDeclinedArchitectureReason,@@ -44,6 +52,16 @@ import {/** Concrete analysis provider backed by REA's private Hopper bridge. */export class HopperProvider implements AnalysisProviderCandidate {private readonly environment: Readonly<NodeJS.ProcessEnv>;+ readonly #ownedResources = new ArtifactResourceScope();+ readonly #inspectionOwner: RetainedResourceScope = {+ retain: (owner, resource) =>+ this.#ownedResources.retain({+ kind: "lease",+ resource,+ lease: AnalysisCleanupLease.forCloseOwner(owner, resource),+ }),+ run: (operation) => this.#ownedResources.run(operation),+ };/*** Host platform, injected so availability and launch-mode decisions can be@@ -169,14 +187,37 @@ export class HopperProvider implements AnalysisProviderCandidate {target: BinaryTarget,options?: AnalysisProfileResolutionOptions,) {+ const resourceScope = options?.resourceScope ?? this.#inspectionOwner;return resolveHopperAnalysisProfile(target, {launcherPath: this.config.hopperLauncherPath,loaderArgsOverride: this.config.hopperLoaderArgs,provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope,...(options?.signal === undefined ? {} : { signal: options.signal }),});}+ hasPendingOwnedResources(): boolean {+ return this.#ownedResources.hasPending;+ }++ async closeOwnedResources() {+ try {+ await this.#ownedResources.close();+ return ok(null);+ } catch (cause: unknown) {+ const failure = new ProviderCleanupError(+ HOPPER_PROVIDER_IDENTITY.id,+ this.#ownedResources.cleanupResources,+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { cause, operation: "close_owned_resources" },+ );+ if (cause instanceof ArtifactResourceRetryFailure)+ new AnalysisCleanupLeaseGroup(failure, cause.cleanupLeases);+ return err(failure);+ }+ }+createClient(target: BinaryTarget,profile?: AnalysisProfileCommitment,@@ -287,7 +328,7 @@ export class HopperProvider implements AnalysisProviderCandidate {...(preparedImage === undefined? []: [- "REA loaded a verified thin Mach-O slice from the original FAT source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",+ "REA loaded a verified thin Mach-O image prepared from the original source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",]),...(CAPABILITIES.find((descriptor) => descriptor.operation === operation,diff --git a/tests/boundary/filesystem/directAnalysisPermissions.test.ts b/tests/boundary/filesystem/directAnalysisPermissions.test.tsindex e9e183828..20cf0a7b4 100644--- a/tests/boundary/filesystem/directAnalysisPermissions.test.ts+++ b/tests/boundary/filesystem/directAnalysisPermissions.test.ts@@ -4,6 +4,7 @@ import { join } from "node:path";import { afterEach, describe, expect, it, vi } from "vitest";import { withArtifactResourceScope } from "../../fixtures/artifactInventory.js";+import { createInspectionResources } from "../../fixtures/inspectionResources.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { writeAnalysisSnapshot } from "../../../src/application/binary/AnalysisSnapshotFiles.js";@@ -21,9 +22,13 @@ import {workflowAnalysisProfile,} from "../../../src/application/InvestigationProviders.js";import { HOPPER_PROVIDER_IDENTITY } from "../../../src/hopper/HopperProviderCapabilities.js";+import { resolveHopperAnalysisProfile } from "../../../src/hopper/HopperAnalysisProfile.js";+let inspectionResources = createInspectionResources();afterEach(async () => {+ await inspectionResources.close();+ inspectionResources = createInspectionResources();vi.unstubAllEnvs();});@@ -67,6 +72,7 @@ describe("direct analysis snapshot files", () => {launcherPath,loaderArgsOverride: [],provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope: inspectionResources.owner,});if (!resolved.ok || resolved.value.profile === null)throw new Error("fixture Hopper profile did not resolve");diff --git a/tests/boundary/providers/hopper/bridgeLauncher.test.ts b/tests/boundary/providers/hopper/bridgeLauncher.test.tsindex 85a561bfd..5d2611ecc 100644--- a/tests/boundary/providers/hopper/bridgeLauncher.test.ts+++ b/tests/boundary/providers/hopper/bridgeLauncher.test.ts@@ -1,6 +1,6 @@-import { randomUUID } from "node:crypto";+import { createHash, randomUUID } from "node:crypto";import { execFile } from "node:child_process";-import { access, chmod, rm, writeFile } from "node:fs/promises";+import { access, chmod, open, rm, writeFile } from "node:fs/promises";import { join } from "node:path";import { promisify } from "node:util";import { fileURLToPath } from "node:url";@@ -22,6 +22,8 @@ import { err, ok } from "../../../../src/domain/result.js";import { HopperReleaseError } from "../../../../src/application/HopperReleaseFeed.js";import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";import { ArtifactResourceScope } from "../../../../src/artifacts/ArtifactResourceScope.js";+import { AnalysisCleanupLease } from "../../../../src/artifacts/AnalysisCleanupLease.js";+import { ArtifactReaderFailure } from "../../../../src/artifacts/ArtifactReader.js";import { PrivateRuntimeRoot } from "../../../../src/process/PrivateRuntimeRoot.js";import { HopperClient } from "../../../../src/hopper/HopperClient.js";@@ -64,6 +66,140 @@ const options = (launcherPath: string): HopperApplicationLauncherOptions => ({demoHelperPath: "/rea/hopper-demo-x11.py",});+it("resolves mixed image and publisher cleanup only after each owner releases", async () => {+ const directory = await createTestTempDirectory("rea-hopper-mixed-cleanup-");+ const targetPath = join(directory, "target.macho");+ const source = Buffer.alloc(64);+ source.writeUInt32BE(0xfeedfacf, 0);+ source.writeUInt32BE(0x0100000c, 4);+ source.writeUInt32BE(0x80000002, 8);+ await writeFile(targetPath, source);++ let allowImageClose = false;+ let imageCloseAttempts = 0;+ const imageFileSystem = {+ async open(+ path: Parameters<typeof open>[0],+ flags: Parameters<typeof open>[1],+ mode?: Parameters<typeof open>[2],+ ) {+ const handle = await open(path, flags, mode);+ if (String(path) === targetPath && flags === "r") {+ const close = handle.close.bind(handle);+ handle.close = async () => {+ imageCloseAttempts += 1;+ if (!allowImageClose)+ throw new Error("Fixture image source close unavailable");+ await close();+ };+ }+ return handle;+ },+ };++ let allowPublisherClose = false;+ let publisherCloseAttempts = 0;+ const publisherOwner = {+ async close() {+ publisherCloseAttempts += 1;+ if (!allowPublisherClose)+ throw new Error("Fixture publisher close unavailable");+ },+ };+ const publisherLease = AnalysisCleanupLease.forCloseOwner(+ publisherOwner,+ "hopper-publisher-verification",+ );+ const retryPublisherCleanup = async () => {+ try {+ await publisherLease.release();+ } catch (cause: unknown) {+ const failure = new ArtifactReaderFailure(+ "unavailable",+ "Publisher verification cleanup remains incomplete",+ {+ cause,+ cleanup: {+ reason: cause instanceof Error ? cause.message : String(cause),+ resources: ["hopper-publisher-verification"],+ },+ cleanupLeases: [publisherLease],+ },+ );+ throw failure;+ }+ };+ const launcher = new HopperApplicationLauncher(+ {+ ...options("/missing/hopper"),+ targetPath,+ preparedImage: {+ image: {+ method: "thin_verified_copy",+ byte_length: source.length,+ cpu_type: 0x0100000c,+ cpu_subtype: 0x80000002,+ },+ sourceSha256: createHash("sha256").update(source).digest("hex"),+ },+ },+ {+ platform: "win32",+ imageFileSystem,+ retryPublisherCleanup,+ },+ );+ const session = {+ directory,+ socketPath: join(directory, "bridge.sock"),+ token: "fixture-token",+ runId: "fixture-run",+ };++ try {+ const launched = await launcher.launch(session);+ expect(launched).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });++ const first = await launcher.cleanup();+ expect(first).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ if (first.ok) throw new Error("Expected mixed cleanup to remain pending");+ const originalAggregate = first.error;+ expect(originalAggregate.cleanupResources).toEqual(+ expect.arrayContaining([+ expect.stringContaining("hopper-image-source:"),+ "hopper-publisher-verification",+ ]),+ );++ allowImageClose = true;+ const publisherOnly = await launcher.cleanup();+ expect(publisherOnly).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ expect(originalAggregate.cleanupIncomplete).toBe(true);+ const closedImageAttempts = imageCloseAttempts;+ expect(closedImageAttempts).toBeGreaterThan(1);++ allowPublisherClose = true;+ expect(await launcher.cleanup()).toEqual({ ok: true, value: null });+ expect(originalAggregate.cleanupIncomplete).toBe(false);+ expect(imageCloseAttempts).toBe(closedImageAttempts);+ expect(publisherCloseAttempts).toBe(3);+ } finally {+ allowImageClose = true;+ allowPublisherClose = true;+ await launcher.cleanup();+ await rm(directory, { recursive: true, force: true });+ }+});+it("retains cancelled verification cleanup through client shutdown and retries it", async () => {const directory = await createTestTempDirectory("rea-publisher-cancel-");const targetPath = join(directory, "target");diff --git a/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts b/tests/boundary/providers/hopper/hopperAnalysisProfile.test.tsindex 46b71deb7..af087e7b1 100644--- a/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts+++ b/tests/boundary/providers/hopper/hopperAnalysisProfile.test.ts@@ -4,6 +4,7 @@ import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";+import { createInspectionResources } from "../../../fixtures/inspectionResources.js";import type { BinaryTarget } from "../../../../src/domain/binaryTargetTypes.js";import {@@ -12,9 +13,12 @@ import {} from "../../../../src/hopper/HopperAnalysisProfile.js";import { HOPPER_PROVIDER_IDENTITY } from "../../../../src/hopper/HopperProviderCapabilities.js";+let inspectionResources = createInspectionResources();let directory: string | undefined;afterEach(async () => {+ await inspectionResources.close();+ inspectionResources = createInspectionResources();if (directory !== undefined)await rm(directory, { recursive: true, force: true });directory = undefined;@@ -70,6 +74,7 @@ describe("Hopper analysis profiles", () => {launcherPath: "/missing/hopper",loaderArgsOverride: [],provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope: inspectionResources.owner,},);expect(resolved).toEqual({@@ -99,6 +104,7 @@ describe("Hopper analysis profiles", () => {launcherPath,loaderArgsOverride: scenario.override,provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope: inspectionResources.owner,},);expect(resolved).toMatchObject({@@ -128,6 +134,7 @@ describe("Hopper analysis profiles", () => {launcherPath: launcher,loaderArgsOverride: [],provider: HOPPER_PROVIDER_IDENTITY,+ resourceScope: inspectionResources.owner,signal: controller.signal,});diff --git a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts b/tests/boundary/setup/linuxHopperPublisherVerification.test.tsindex 28d9791a9..ecb76d4af 100644--- a/tests/boundary/setup/linuxHopperPublisherVerification.test.ts+++ b/tests/boundary/setup/linuxHopperPublisherVerification.test.ts@@ -27,6 +27,7 @@ import {linuxHopperReleaseCacheDirectory,retryLinuxHopperPublisherCleanup,} from "../../../src/application/LinuxHopperPublisher.js";+import { ArtifactReaderFailure } from "../../../src/artifacts/ArtifactReader.js";import {HOPPER_LINUX_PRIMARY_FINGERPRINT,type LinuxHopperRelease,@@ -108,6 +109,21 @@ const fixture = async (family: "deb" | "arch" = "deb") => {};};+const verifyFixtureArchive = async (+ f: Awaited<ReturnType<typeof fixture>>,+ family: "deb" | "arch" = "deb",+) => {+ const result = await f.publisher.verifyArchive(+ family,+ f.release,+ f.archive,+ undefined,+ f.publicKey,+ );+ if (!result.ok) throw result.error;+ return result.value;+};+const admitFixturePublisher = (fingerprint: string,module: typeof signatures = signatures,@@ -173,16 +189,9 @@ describe("Linux signed package retention boundary", () => {});vi.stubGlobal("fetch", network);try {- const verified = await f.publisher.verifyArchive(- family,- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, family);expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });await f.publisher.close();// A new instance alone still shares process-local cryptographic proofs.@@ -240,16 +249,9 @@ linux.each([const f = await fixture();admitFixturePublisher(f.fingerprint);try {- const verified = await f.publisher.verifyArchive(- "deb",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "deb");const retained = await f.publisher.retainVerifiedArchive(- verified.value,+ verifiedArchive,f.archive,);if (!retained.ok) throw retained.error;@@ -300,7 +302,7 @@ linux.each([// An explicitly approved fresh package can repair this entry while// preserving the original evidence and keeping ordinary reads strict.expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });const backups = (await readdir(f.publisher.cacheRoot)).filter((name) =>name.startsWith(`${f.release.main_exe_hash}.backup-`),@@ -321,7 +323,7 @@ linux.each([ok: true,});expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });expect((await readdir(f.publisher.cacheRoot)).filter((name) =>@@ -345,16 +347,9 @@ linux.each([false, true])(| ReturnType<LinuxHopperPublisher["retainVerifiedArchive"]>| undefined;try {- const verified = await f.publisher.verifyArchive(- "deb",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "deb");expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });const staged = join(f.publisher.cacheRoot, "authenticated-fixture-stage");await cp(f.cache, staged, { recursive: true });@@ -399,7 +394,7 @@ linux.each([false, true])(},);retention = f.publisher.retainVerifiedArchive(- verified.value,+ verifiedArchive,f.archive,controller.signal,);@@ -450,16 +445,9 @@ linux("restores old evidence when replacement publication fails", async () => {const f = await fixture();admitFixturePublisher(f.fingerprint);try {- const verified = await f.publisher.verifyArchive(- "deb",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "deb");expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });const broken = "{interrupted cache metadata";await writeFile(join(f.cache, "release.json"), broken);@@ -479,7 +467,7 @@ linux("restores old evidence when replacement publication fails", async () => {syncBuiltinESMExports();try {const result = await f.publisher.retainVerifiedArchive(- verified.value,+ verifiedArchive,f.archive,);expect(result).toMatchObject({@@ -506,7 +494,7 @@ linux("restores old evidence when replacement publication fails", async () => {syncBuiltinESMExports();}expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });expect(await f.publisher.inspectLauncher(f.launcher)).toMatchObject({ok: true,@@ -522,16 +510,9 @@ linux(const f = await fixture();admitFixturePublisher(f.fingerprint);try {- const verified = await f.publisher.verifyArchive(- "deb",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "deb");expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toEqual({ ok: true, value: undefined });await writeFile(join(f.cache, "public-key.asc"), f.publicKey + "\n");const metadata = await readFile(join(f.cache, "release.json"));@@ -539,7 +520,7 @@ linux(.spyOn(nativeCommands, "execFileOutput").mockRejectedValue(new Error("Fixture native inspection unavailable"));expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toMatchObject({ok: false,error: { reason: "verification_unavailable" },@@ -621,16 +602,9 @@ linux(},);try {- const verified = await f.publisher.verifyArchive(- "deb",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "deb");expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toMatchObject({ ok: false, error: { reason: "cleanup_failed" } });const input = {cacheDirectory: f.publisher.cacheRoot,@@ -889,16 +863,9 @@ portableTar(async () => {const f = await fixture("arch");admitFixturePublisher(f.fingerprint);- const verified = await f.publisher.verifyArchive(- "arch",- f.release,- f.archive,- undefined,- f.publicKey,- );- if (!verified.ok) throw verified.error;+ const verifiedArchive = await verifyFixtureArchive(f, "arch");expect(- await f.publisher.retainVerifiedArchive(verified.value, f.archive),+ await f.publisher.retainVerifiedArchive(verifiedArchive, f.archive),).toMatchObject({ ok: true });let reachedMetadataClose!: () => void;@@ -964,6 +931,7 @@ linux(controller.abort();throw new Error("Fixture cleanup unavailable after cancellation");});+ let retryFailure: unknown;try {expect(await f.publisher.verifyArchive(@@ -977,10 +945,22 @@ linux(ok: false,error: { reason: "cleanup_failed" },});- await expect(retryLinuxHopperPublisherCleanup()).rejects.toMatchObject({+ try {+ await retryLinuxHopperPublisherCleanup();+ } catch (cause: unknown) {+ retryFailure = cause;+ }+ expect(retryFailure).toBeInstanceOf(ArtifactReaderFailure);+ expect(retryFailure).toMatchObject({cleanup: {resources: [expect.stringContaining("rea-hopper-publisher-")],},+ cleanupLeases: [expect.objectContaining({ released: false })],+ });+ cleanup.mockRestore();+ await retryLinuxHopperPublisherCleanup();+ expect(retryFailure).toMatchObject({+ cleanupLeases: [expect.objectContaining({ released: true })],});} finally {cleanup.mockRestore();