Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): join shared NativeAOT derivation and retain outcomes
morluto5120eb44127c
diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 4ba4278d4..f4d599eac 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -232,10 +232,12 @@ import type { WebPageInspection } from "./browserObservationSchemas.js";import type { WebExecution } from "./webExecution.js";import type { WebEventListeners } from "./webEventListeners.js";+import type { NativeAotSnapshotObservation } from "./native/nativeAotSnapshotObservation.js";import type { FileSnapshotPartialObservation } from "./fileSnapshotObservation.js";/** Provider-neutral evidence collected before a typed analysis failure. */export type AnalysisPartialObservation =+ | NativeAotSnapshotObservation| FileSnapshotPartialObservation| PartialProcessCaptureObservation| NativeCallPartialObservationdiff --git a/src/domain/native/nativeAotSnapshotObservation.test.ts b/src/domain/native/nativeAotSnapshotObservation.test.tsnew file mode 100644index 000000000..8212b011a--- /dev/null+++ b/src/domain/native/nativeAotSnapshotObservation.test.ts@@ -0,0 +1,33 @@+import { expect, it } from "vitest";+import { nativeAotSnapshotObservationSchema } from "./nativeAotSnapshotObservation.js";++const observation = {+ kind: "native-aot-snapshot",+ analysis_artifact_sha256: "a".repeat(64),+ image_base: "0x140000000",+ capture: { status: "captured", bytes: 2560 },+};++it("retains captured source coverage without raw bytes", () => {+ expect(nativeAotSnapshotObservationSchema.parse(observation)).toEqual(+ observation,+ );+ expect(+ nativeAotSnapshotObservationSchema.safeParse({+ ...observation,+ bytes: Buffer.alloc(1),+ }).success,+ ).toBe(false);+});++it.each([-1, 1.5, Number.MAX_SAFE_INTEGER + 1])(+ "refuses invalid source coverage %s",+ (bytes) => {+ expect(+ nativeAotSnapshotObservationSchema.safeParse({+ ...observation,+ capture: { status: "captured", bytes },+ }).success,+ ).toBe(false);+ },+);diff --git a/src/domain/native/nativeAotSnapshotObservation.ts b/src/domain/native/nativeAotSnapshotObservation.tsnew file mode 100644index 000000000..fbffb9a0b--- /dev/null+++ b/src/domain/native/nativeAotSnapshotObservation.ts@@ -0,0 +1,23 @@+import { z } from "zod";+import { nativeMetadataRecoverySummarySchema } from "./nativeMetadataRecovery.js";++const bytes = z.number().int().nonnegative().safe();++/** Captured source coverage and any completed derivation, without retaining raw bytes. */+export const nativeAotSnapshotObservationSchema = z.strictObject({+ kind: z.literal("native-aot-snapshot"),+ analysis_artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ image_base: z.string().regex(/^0x[0-9a-f]+$/u),+ capture: z.discriminatedUnion("status", [+ z.strictObject({ status: z.literal("captured"), bytes }),+ z.strictObject({+ status: z.literal("over-capacity"),+ source_bytes_at_least: bytes,+ maximum_bytes: bytes,+ }),+ ]),+ metadata_recovery: nativeMetadataRecoverySummarySchema.optional(),+});+export type NativeAotSnapshotObservation = z.infer<+ typeof nativeAotSnapshotObservationSchema+>;diff --git a/src/ghidra/GhidraNativeAotSnapshotOwner.ts b/src/ghidra/GhidraNativeAotSnapshotOwner.tsnew file mode 100644index 000000000..478c9fbd6--- /dev/null+++ b/src/ghidra/GhidraNativeAotSnapshotOwner.ts@@ -0,0 +1,358 @@+import type { AnalysisOperation } from "../application/AnalysisProvider.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import type { JsonValue } from "../domain/jsonValue.js";+import {+ NATIVE_AOT_MAX_REPORT_BYTES,+ NATIVE_AOT_MAX_SOURCE_BYTES,+ nativeAotSnapshotOverCapacity,+ parseNativeAotPe,+ type NativeAotPeResult,+} from "../domain/native/nativeAotPe.js";+import {+ nativeAotSnapshotObservationSchema,+ type NativeAotSnapshotObservation,+} from "../domain/native/nativeAotSnapshotObservation.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { err, ok, type Result } from "../domain/result.js";+import {+ SharedStartupAttempt,+ STARTUP_OWNER_CLOSED,+} from "../process/SharedStartupAttempt.js";+import type { GhidraClient, GhidraTargetSnapshot } from "./GhidraClient.js";+import { GhidraSessionError } from "./GhidraSessionError.js";++type Derivation = Result<NativeAotPeResult, GhidraSessionError>;++/** Own one captured PE derivation; each caller owns only its wait and projection. */+export class GhidraNativeAotSnapshotOwner {+ #base: string | undefined;+ #conflict: { imageBase: string; observations: JsonValue } | undefined;+ #closed = false;+ #cached: NativeAotPeResult | undefined;+ #attempt: SharedStartupAttempt<Derivation> | undefined;+ #failure: GhidraSessionError | undefined;+ #capture: NativeAotSnapshotObservation["capture"] | undefined;++ constructor(+ private readonly input: {+ readonly targetSha256: string;+ readonly readSnapshot: GhidraClient["readTargetSnapshot"] | undefined;+ readonly projectFailure: (+ operation: AnalysisOperation,+ failure: GhidraSessionError,+ ) => AnalysisError;+ },+ ) {}++ get cleanupFailure(): AnalysisError | undefined {+ const cleanup = this.#failure?.cleanupFailure;+ return cleanup?.cleanupIncomplete ? cleanup : undefined;+ }++ async derive(+ imageBase: string,+ operation: AnalysisOperation,+ callerSignal: AbortSignal | undefined,+ observations: JsonValue,+ ): Promise<Result<NativeAotPeResult, AnalysisError>> {+ if (callerSignal?.aborted)+ return err(+ new AnalysisCancelledError(operation, { cause: callerSignal.reason }),+ );+ if (this.#closed)+ return err(+ new AnalysisCancelledError(operation, { cause: STARTUP_OWNER_CLOSED }),+ );+ if (this.#conflict !== undefined)+ return err(this.#identityError(operation, imageBase, observations));+ let normalized: string;+ try {+ const base = BigInt(imageBase);+ if (base < 0n)+ throw new RangeError("Loaded image base must be nonnegative");+ normalized = `0x${base.toString(16)}`;+ } catch (cause: unknown) {+ return err(+ new ProviderAdapterError("ghidra", operation, {+ diagnostics: {+ reason:+ "Ghidra returned an invalid loaded image base for NativeAOT identity binding.",+ observed_image_base: imageBase,+ measured_observation: observations,+ },+ cause,+ }),+ );+ }+ if (this.#base !== undefined && this.#base !== normalized) {+ this.#conflict = { imageBase, observations };+ this.#cached = undefined;+ this.#attempt?.close();+ return err(this.#identityError(operation, imageBase, observations));+ }+ this.#base ??= normalized;+ if (this.cleanupFailure !== undefined && this.#failure !== undefined)+ return err(this.input.projectFailure(operation, this.#failure));+ if (this.#cached !== undefined) {+ const cached = this.#cached;+ await Promise.resolve();+ if (this.#conflict !== undefined)+ return err(this.#identityError(operation, imageBase, observations));+ return this.#closed || callerSignal?.aborted+ ? err(+ this.#cancelled(+ operation,+ callerSignal?.aborted+ ? callerSignal.reason+ : STARTUP_OWNER_CLOSED,+ cached,+ ),+ )+ : ok(cached);+ }+ const draining = this.#attempt;+ if (draining?.signal.aborted) {+ const waited = await draining.wait(callerSignal);+ if (+ waited.status !== "cancelled" &&+ !waited.value.ok &&+ (waited.value.error.kind !== "cancelled" ||+ waited.value.error.cleanupFailure?.cleanupIncomplete)+ )+ return err(+ this.#projectFailure(+ operation,+ waited.value.error,+ imageBase,+ observations,+ ),+ );+ if (waited.status === "cancelled")+ return err(+ new AnalysisCancelledError(operation, {+ cause: callerSignal?.reason,+ }),+ );+ if (callerSignal?.aborted)+ return err(+ waited.value.ok+ ? this.#cancelled(+ operation,+ callerSignal.reason,+ waited.value.value,+ )+ : new AnalysisCancelledError(operation, {+ cause: callerSignal.reason,+ partialObservation: waited.value.error.partialObservation,+ }),+ );+ return this.derive(imageBase, operation, callerSignal, observations);+ }+ const attempt = this.#attempt ?? this.#start(normalized);+ const waited = await attempt.wait(callerSignal);+ if (waited.status === "cancelled")+ return err(+ new AnalysisCancelledError(operation, { cause: callerSignal?.reason }),+ );+ const settled = waited.value;+ // A completed physical failure or retained cleanup outranks a later abort.+ if (!settled.ok) {+ return err(+ this.#projectFailure(operation, settled.error, imageBase, observations),+ );+ }+ if (this.#conflict !== undefined)+ return err(this.#identityError(operation, imageBase, observations));+ if (this.#closed || attempt.signal.aborted || callerSignal?.aborted)+ return err(+ this.#cancelled(+ operation,+ callerSignal?.aborted+ ? callerSignal.reason+ : this.#closed+ ? STARTUP_OWNER_CLOSED+ : attempt.signal.reason,+ settled.value,+ ),+ );+ return settled;+ }++ readTypeDetail(address: string) {+ return this.#closed || this.#conflict !== undefined+ ? undefined+ : this.#cached?.readTypeDetail(address, NATIVE_AOT_MAX_REPORT_BYTES);+ }++ #projectFailure(+ operation: AnalysisOperation,+ failure: GhidraSessionError,+ imageBase: string,+ observations: JsonValue,+ ): AnalysisError {+ if (failure.kind !== "cancelled" || this.#conflict === undefined)+ return this.input.projectFailure(operation, failure);+ return this.#identityError(operation, imageBase, observations, failure);+ }++ async close(): Promise<void> {+ this.#closed = true;+ this.#cached = undefined;+ const attempt = this.#attempt;+ attempt?.close();+ await attempt?.promise;+ }++ #start(imageBase: string): SharedStartupAttempt<Derivation> {+ this.#failure = undefined;+ this.#capture = undefined;+ const attempt = new SharedStartupAttempt((signal) =>+ this.#read(imageBase, signal),+ );+ this.#attempt = attempt;+ void attempt.promise.then((settled) => {+ if (this.#attempt !== attempt) return;+ this.#attempt = undefined;+ if (!settled.ok) this.#failure = settled.error;+ else if (+ !this.#closed &&+ this.#conflict === undefined &&+ !attempt.signal.aborted+ )+ this.#cached = settled.value;+ });+ return attempt;+ }++ async #read(imageBase: string, signal: AbortSignal): Promise<Derivation> {+ try {+ if (this.input.readSnapshot === undefined)+ return err(+ new GhidraSessionError(+ "protocol",+ "The Ghidra client does not expose its immutable target snapshot for NativeAOT metadata inspection.",+ ),+ );+ const snapshot = await this.input.readSnapshot(+ NATIVE_AOT_MAX_SOURCE_BYTES,+ signal,+ );+ if (!snapshot.ok) return snapshot;+ this.#capture = this.#captureFacts(snapshot.value);+ const partialObservation = this.#observation();+ if (signal.aborted)+ return err(+ new GhidraSessionError(+ "cancelled",+ "NativeAOT snapshot derivation stopped",+ {},+ {+ cause: signal.reason,+ cancellation: { reason: signal.reason },+ ...(partialObservation === undefined+ ? {}+ : { partialObservation }),+ },+ ),+ );+ const parsed =+ snapshot.value.kind === "over-capacity"+ ? {+ summary: nativeAotSnapshotOverCapacity(+ this.input.targetSha256,+ snapshot.value.sourceBytesAtLeast,+ NATIVE_AOT_MAX_REPORT_BYTES,+ ),+ readTypeDetail: () => undefined,+ }+ : parseNativeAotPe(+ snapshot.value.bytes,+ this.input.targetSha256,+ NATIVE_AOT_MAX_REPORT_BYTES,+ imageBase,+ );+ return ok(parsed);+ } catch (cause: unknown) {+ const partialObservation = this.#observation();+ return err(+ new GhidraSessionError(+ "protocol",+ "NativeAOT metadata could not be derived from the captured target snapshot.",+ {},+ {+ cause,+ ...(partialObservation === undefined ? {} : { partialObservation }),+ },+ ),+ );+ }+ }++ #captureFacts(+ snapshot: GhidraTargetSnapshot,+ ): NativeAotSnapshotObservation["capture"] {+ return snapshot.kind === "captured"+ ? { status: "captured", bytes: snapshot.bytes.length }+ : {+ status: "over-capacity",+ source_bytes_at_least: snapshot.sourceBytesAtLeast,+ maximum_bytes: snapshot.maximumBytes,+ };+ }++ #observation(+ result?: NativeAotPeResult,+ ): NativeAotSnapshotObservation | undefined {+ if (this.#capture === undefined || this.#base === undefined)+ return undefined;+ return nativeAotSnapshotObservationSchema.parse({+ kind: "native-aot-snapshot",+ analysis_artifact_sha256: this.input.targetSha256,+ image_base: this.#base,+ capture: this.#capture,+ ...(result === undefined ? {} : { metadata_recovery: result.summary }),+ });+ }++ #cancelled(+ operation: AnalysisOperation,+ reason: unknown,+ result: NativeAotPeResult,+ ): AnalysisError {+ return new AnalysisCancelledError(operation, {+ cause: reason,+ partialObservation: this.#observation(result),+ });+ }++ #identityError(+ operation: AnalysisOperation,+ imageBase: string,+ observations: JsonValue,+ source?: Pick<GhidraSessionError, "partialObservation" | "cleanupFailure">,+ ): AnalysisError {+ const primary = new ProviderAdapterError("ghidra", operation, {+ partialObservation: source?.partialObservation ?? this.#observation(),+ diagnostics: {+ reason:+ "The Ghidra session reported conflicting loaded image bases (a different loaded image base after binding); reopen the analysis session to establish a new identity.",+ artifact_sha256: this.input.targetSha256,+ bound_image_base: this.#base ?? null,+ observed_image_base: imageBase,+ measured_observation: observations,+ conflicting_image_base: this.#conflict?.imageBase ?? null,+ conflicting_observation: this.#conflict?.observations ?? null,+ },+ });+ const cleanup = source?.cleanupFailure ?? this.cleanupFailure;+ return cleanup?.cleanupIncomplete+ ? analysisErrorWithCleanupFailure(+ primary,+ cleanup,+ operation,+ ).bindCleanupDependencies([primary, cleanup])+ : primary;+ }+}diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.tsindex 4bd4d3ccd..79076c773 100644--- a/src/ghidra/GhidraProvider.behavior.test.ts+++ b/src/ghidra/GhidraProvider.behavior.test.ts@@ -1,3 +1,6 @@+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";+import { resolvedAnalysisError } from "../domain/analysisErrorBase.js";+import { createDeferred } from "../../tests/fixtures/binarySession.js";import { ProviderInspectionScope } from "../providers/ProviderInspectionScope.js";import { ok as javaProbeOk } from "../domain/result.js";import type { GhidraJavaObservation } from "./GhidraJavaProbe.js";@@ -1890,7 +1893,8 @@ it("shares one session snapshot across callers while isolating cancellation and});expect(snapshotReads).toBe(1);await client.close();- expect(snapshotSignal?.aborted).toBe(true);+ // The completed producer needs no stop; active-close joining is covered below.+ expect(snapshotSignal?.aborted).toBe(false);});it("retries a failed NativeAOT snapshot read without retaining a failed derivation", async () => {@@ -1944,40 +1948,134 @@ it("retries a failed NativeAOT snapshot read without retaining a failed derivatiawait client.close();});-it("rejects all waiters when the loaded image base changes during derivation", async () => {+it.each(["captured", "cancelled-with-facts"] as const)(+ "rejects all waiters when the loaded image base changes during derivation (%s)",+ async (outcome) => {+ const bytes = nativeAotPeFixture();+ const observation = fixtureDosLoadImage().observation;+ let calls = 0;+ let resolveSnapshot:+ | ((value: Result<GhidraTargetSnapshot, GhidraSessionError>) => void)+ | undefined;+ let markSnapshotStarted: (() => void) | undefined;+ const snapshotStarted = new Promise<void>((resolve) => {+ markSnapshotStarted = resolve;+ });+ const snapshot = new Promise<+ Result<GhidraTargetSnapshot, GhidraSessionError>+ >((resolve) => {+ resolveSnapshot = resolve;+ });+ const factory: GhidraProviderClientFactory = () => ({+ start: () => Promise.resolve(ok(sessionInfo())),+ callTool: () => {+ calls += 1;+ return Promise.resolve(+ ok(+ jsonValueSchema.parse({+ ...observation,+ image_base: calls === 1 ? "0x140000000" : "0x150000000",+ }),+ ),+ );+ },+ readTargetSnapshot: () => {+ markSnapshotStarted?.();+ return snapshot;+ },+ close: () => Promise.resolve(ok(null)),+ });+ const ghidra = provider(installationHost(), factory);+ const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };+ const profile = await ghidra.resolveAnalysisProfile(target);+ if (!profile.ok || profile.value.profile === null)+ throw new Error("Expected admitted PE profile");+ const client = ghidra.createClient(target, profile.value.profile);+ const originalBase = client.execute("inspect_native_load_image", {});+ await snapshotStarted;+ const changedBase = await client.execute("inspect_native_load_image", {});+ expect(changedBase).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ diagnostics: {+ observed_image_base: "0x150000000",+ measured_observation: { image_base: "0x150000000" },+ },+ },+ });+ resolveSnapshot?.(+ outcome === "captured"+ ? ok({ kind: "captured", bytes })+ : err(+ new GhidraSessionError(+ "cancelled",+ "Controlled identity stop",+ {},+ {+ cancellation: { reason: "identity conflict" },+ partialObservation: {+ kind: "file-snapshot-hash",+ path: "/controlled/snapshot",+ sha256: "a".repeat(64),+ bytes: 17,+ },+ },+ ),+ ),+ );+ const originalResult = await originalBase;+ expect(originalResult).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ diagnostics: {+ reason: expect.stringContaining("conflicting loaded image bases"),+ measured_observation: { image_base: "0x140000000" },+ conflicting_observation: { image_base: "0x150000000" },+ },+ },+ });+ if (outcome === "cancelled-with-facts") {+ expect(originalResult).toMatchObject({+ ok: false,+ error: {+ partialObservation: { kind: "file-snapshot-hash", bytes: 17 },+ },+ });+ }+ expect(calls).toBe(2);+ await client.close();+ },+);++const nativeAotWaiterClient = async () => {const bytes = nativeAotPeFixture();- const observation = fixtureDosLoadImage().observation;- let calls = 0;- let resolveSnapshot:- | ((value: Result<GhidraTargetSnapshot, GhidraSessionError>) => void)- | undefined;- let markSnapshotStarted: (() => void) | undefined;- const snapshotStarted = new Promise<void>((resolve) => {- markSnapshotStarted = resolve;- });- const snapshot = new Promise<- Result<GhidraTargetSnapshot, GhidraSessionError>- >((resolve) => {- resolveSnapshot = resolve;- });+ const observations = fixtureDosLoadImage().observation;+ observations.image_base = "0x140000000";+ const started = createDeferred<AbortSignal>();+ const snapshot =+ createDeferred<Result<GhidraTargetSnapshot, GhidraSessionError>>();+ const close = vi.fn(async () => ok(null));+ const readSnapshot = vi.fn(+ (_maximum: number | undefined, signal: AbortSignal | undefined) => {+ if (signal === undefined) throw new Error("Missing owned read signal");+ started.resolve(signal);+ return snapshot.promise;+ },+ );const factory: GhidraProviderClientFactory = () => ({- start: () => Promise.resolve(ok(sessionInfo())),- callTool: () => {- calls += 1;- return Promise.resolve(- ok(- jsonValueSchema.parse({- ...observation,- image_base: calls === 1 ? "0x140000000" : "0x150000000",- }),+ start: async () => ok(sessionInfo()),+ callTool: async (operation) =>+ ok(+ jsonValueSchema.parse(+ operation === "inspect_native_load_image"+ ? observations+ : unavailableNativeAotDatabaseType("0x140002280"),),- );- },- readTargetSnapshot: () => {- markSnapshotStarted?.();- return snapshot;- },- close: () => Promise.resolve(ok(null)),+ ),+ readTargetSnapshot: readSnapshot,+ close,});const ghidra = provider(installationHost(), factory);const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };@@ -1985,77 +2083,306 @@ it("rejects all waiters when the loaded image base changes during derivation", aif (!profile.ok || profile.value.profile === null)throw new Error("Expected admitted PE profile");const client = ghidra.createClient(target, profile.value.profile);- const originalBase = client.execute("inspect_native_load_image", {});- await snapshotStarted;- const changedBase = await client.execute("inspect_native_load_image", {});- expect(changedBase).toMatchObject({- ok: false,- error: {- _tag: "ProviderAdapterError",- diagnostics: {- observed_image_base: "0x150000000",- measured_observation: { image_base: "0x150000000" },- },- },+ onTestFinished(async () => {+ snapshot.resolve(ok({ kind: "captured", bytes }));+ await client.close();});- resolveSnapshot?.(ok({ kind: "captured", bytes }));- await expect(originalBase).resolves.toMatchObject({+ return { client, bytes, started, snapshot, close, readSnapshot };+};++it("joins the in-flight NativeAOT producer before closing its owning client", async () => {+ const fixture = await nativeAotWaiterClient();+ const pending = fixture.client.execute("inspect_native_load_image", {});+ const signal = await fixture.started.promise;+ let closed = false;+ const closing = fixture.client.close().then((result) => {+ closed = true;+ return result;+ });+ await new Promise<void>((resolve) => setImmediate(resolve));+ expect(signal.aborted).toBe(true);+ expect(closed).toBe(false);+ expect(fixture.close).not.toHaveBeenCalled();+ fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));+ await expect(pending).resolves.toMatchObject({ok: false,- error: {- _tag: "ProviderAdapterError",- diagnostics: {- reason: expect.stringContaining("conflicting loaded image bases"),- measured_observation: { image_base: "0x140000000" },- conflicting_observation: { image_base: "0x150000000" },- },- },+ error: { _tag: "AnalysisCancelledError" },});- expect(calls).toBe(2);- await client.close();+ expect((await closing).ok).toBe(true);});-it("cancels an in-flight NativeAOT waiter when its owning session closes", async () => {- const bytes = nativeAotPeFixture();- const observations = fixtureDosLoadImage().observation;- observations.image_base = "0x140000000";- let resolveSnapshot:- | ((value: Result<GhidraTargetSnapshot, GhidraSessionError>) => void)- | undefined;- let snapshotSignal: AbortSignal | undefined;- let markSnapshotStarted: (() => void) | undefined;- const snapshotStarted = new Promise<void>((resolve) => {- markSnapshotStarted = resolve;- });- const snapshot = new Promise<- Result<GhidraTargetSnapshot, GhidraSessionError>- >((resolve) => {- resolveSnapshot = resolve;+it("joins final NativeAOT waiter cancellation and retains exact producer cleanup", async () => {+ const fixture = await nativeAotWaiterClient();+ const caller = new AbortController();+ const reason = { caller: "final snapshot waiter" };+ let settled = false;+ const pending = fixture.client+ .execute("inspect_native_load_image", {}, { signal: caller.signal })+ .then((result) => {+ settled = true;+ return result;+ });+ const signal = await fixture.started.promise;+ const cleanup = new ProviderCleanupError(+ "ghidra",+ ["controlled snapshot descriptor"],+ { reason: "controlled close failure" },+ );+ const lease = new AnalysisCleanupLease(async () => {}, [+ "controlled snapshot descriptor",+ ]);+ lease.bindCleanupError(cleanup);+ onTestFinished(() => lease.release());+ caller.abort(reason);+ await new Promise<void>((resolve) => setImmediate(resolve));+ expect(signal.aborted).toBe(true);+ expect(signal.reason).toBe(reason);+ expect(settled).toBe(false);+ fixture.snapshot.resolve(+ err(+ new GhidraSessionError(+ "cancelled",+ "Controlled snapshot cancelled",+ {},+ { cancellation: { reason }, cause: reason },+ ).withCleanupFailure(cleanup),+ ),+ );+ const result = await pending;+ if (result.ok) throw new Error("Expected cancelled snapshot cleanup");+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(result.error.cleanupPrimary?.cause).toBe(reason);+ const refused = await fixture.client.execute("inspect_native_load_image", {});+ expect(refused.ok).toBe(false);+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);+ await lease.release();+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(resolvedAnalysisError(result.error).cause).toBe(reason);+});++it.each([null, "caller stopped", new Error("caller stopped")])(+ "preserves final NativeAOT cancellation reason and late capture (%s)",+ async (reason) => {+ const fixture = await nativeAotWaiterClient();+ const caller = new AbortController();+ const pending = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: caller.signal },+ );+ const signal = await fixture.started.promise;+ caller.abort(reason);+ await new Promise<void>((resolve) => setImmediate(resolve));+ expect(signal.aborted).toBe(true);+ expect(signal.reason).toBe(reason);+ fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));+ const cancelled = await pending;+ if (cancelled.ok) throw new Error("Expected final caller cancellation");+ expect(cancelled.error.cause).toBe(reason);+ expect(cancelled.error.partialObservation).toMatchObject({+ kind: "native-aot-snapshot",+ capture: { status: "captured", bytes: fixture.bytes.length },+ });+ const retried = await fixture.client.execute(+ "inspect_native_load_image",+ {},+ );+ expect(retried.ok).toBe(true);+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);+ await fixture.client.execute("inspect_native_load_image", {});+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);+ },+);++it.each(["caller", "owner"] as const)(+ "preserves NativeAOT physical failure and retained cleanup across %s cancellation",+ async (interruption) => {+ const fixture = await nativeAotWaiterClient();+ const caller = new AbortController();+ const pending = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: caller.signal },+ );+ await fixture.started.promise;+ const cleanup = new ProviderCleanupError(+ "ghidra",+ ["controlled snapshot descriptor"],+ { reason: "controlled close failure" },+ );+ const lease = new AnalysisCleanupLease(async () => {}, [+ "controlled snapshot descriptor",+ ]);+ lease.bindCleanupError(cleanup);+ onTestFinished(() => lease.release());+ const closing =+ interruption === "owner" ? fixture.client.close() : undefined;+ if (interruption === "caller") caller.abort("late caller");+ await new Promise<void>((resolve) => setImmediate(resolve));+ fixture.snapshot.resolve(+ err(+ new GhidraSessionError(+ "protocol",+ "Controlled independent physical failure",+ { physical_failure: "read rejected" },+ {+ partialObservation: {+ kind: "file-snapshot-hash",+ path: "/controlled/snapshot",+ sha256: "a".repeat(64),+ bytes: 17,+ },+ },+ ).withCleanupFailure(cleanup),+ ),+ );+ const result = await pending;+ if (result.ok) throw new Error("Expected retained physical failure");+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ partial_observation: { bytes: 17 },+ diagnostics: { primary_error: { code: "execution_failure" } },+ },+ });+ if (closing !== undefined) {+ const closed = await closing;+ expect(closed.ok).toBe(false);+ }+ await lease.release();+ expect(result.error.cleanupIncomplete).toBe(false);+ expect((await fixture.client.close()).ok).toBe(true);+ },+);++it("lets a new NativeAOT caller join a draining attempt before retrying", async () => {+ const fixture = await nativeAotWaiterClient();+ const caller = new AbortController();+ const first = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: caller.signal },+ );+ await fixture.started.promise;+ caller.abort("first caller");+ await new Promise<void>((resolve) => setImmediate(resolve));+ const second = fixture.client.execute("inspect_native_load_image", {});+ await new Promise<void>((resolve) => setImmediate(resolve));+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);+ fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));+ expect((await first).ok).toBe(false);+ expect((await second).ok).toBe(true);+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);+});++it("preserves a draining NativeAOT physical failure before later caller cancellation", async () => {+ const fixture = await nativeAotWaiterClient();+ const firstCaller = new AbortController();+ const first = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: firstCaller.signal },+ );+ await fixture.started.promise;+ firstCaller.abort("first caller");+ await new Promise<void>((resolve) => setImmediate(resolve));+ const secondCaller = new AbortController();+ const second = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: secondCaller.signal },+ );+ await new Promise<void>((resolve) => setImmediate(resolve));+ const cleanup = new ProviderCleanupError(+ "ghidra",+ ["controlled snapshot descriptor"],+ { reason: "controlled close failure" },+ );+ const lease = new AnalysisCleanupLease(async () => {}, [+ "controlled snapshot descriptor",+ ]);+ lease.bindCleanupError(cleanup);+ onTestFinished(() => lease.release());+ // The reader resumes first. Abort after its result settles the shared producer,+ // while the caller is still awaiting consumption of that completed result.+ void fixture.snapshot.promise.then(() =>+ queueMicrotask(() => secondCaller.abort("late second caller")),+ );+ fixture.snapshot.resolve(+ err(+ new GhidraSessionError(+ "protocol",+ "Controlled draining physical failure",+ ).withCleanupFailure(cleanup),+ ),+ );+ const result = await second;+ if (result.ok) throw new Error("Expected draining physical failure");+ expect(secondCaller.signal.aborted).toBe(true);+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "cleanup_incomplete",+ details: { diagnostics: { primary_error: { code: "execution_failure" } } },+ });+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);+ expect((await first).ok).toBe(false);+ await lease.release();+});++it("retains drained NativeAOT capture facts with the later caller's exact abort reason", async () => {+ const fixture = await nativeAotWaiterClient();+ const firstCaller = new AbortController();+ const first = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: firstCaller.signal },+ );+ await fixture.started.promise;+ firstCaller.abort("first caller");+ await new Promise<void>((resolve) => setImmediate(resolve));+ const secondCaller = new AbortController();+ const reason = { caller: "later draining waiter" };+ const second = fixture.client.execute(+ "inspect_native_load_image",+ {},+ { signal: secondCaller.signal },+ );+ await new Promise<void>((resolve) => setImmediate(resolve));+ void fixture.snapshot.promise.then(() =>+ queueMicrotask(() => secondCaller.abort(reason)),+ );+ fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));+ const result = await second;+ if (result.ok) throw new Error("Expected draining caller cancellation");+ expect(result.error.cause).toBe(reason);+ expect(result.error.partialObservation).toMatchObject({+ kind: "native-aot-snapshot",+ capture: { status: "captured", bytes: fixture.bytes.length },+ });+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);+ expect((await first).ok).toBe(false);+});++it("attributes shared NativeAOT producer failure to each requesting operation", async () => {+ const fixture = await nativeAotWaiterClient();+ const image = fixture.client.execute("inspect_native_load_image", {});+ await fixture.started.promise;+ const detail = fixture.client.execute("inspect_native_data_type", {+ address: "0x140002280",});- const factory: GhidraProviderClientFactory = () => ({- start: () => Promise.resolve(ok(sessionInfo())),- callTool: () => Promise.resolve(ok(jsonValueSchema.parse(observations))),- readTargetSnapshot: (_maximumBytes, signal) => {- snapshotSignal = signal;- markSnapshotStarted?.();- return snapshot;- },- close: () => Promise.resolve(ok(null)),+ await new Promise<void>((resolve) => setImmediate(resolve));+ fixture.snapshot.resolve(+ err(new GhidraSessionError("protocol", "Controlled shared failure")),+ );+ await expect(image).resolves.toMatchObject({+ ok: false,+ error: { operation: "inspect_native_load_image" },});- const ghidra = provider(installationHost(), factory);- const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };- const profile = await ghidra.resolveAnalysisProfile(target);- if (!profile.ok || profile.value.profile === null)- throw new Error("Expected admitted PE profile");- const client = ghidra.createClient(target, profile.value.profile);- const pending = client.execute("inspect_native_load_image", {});- await snapshotStarted;- await client.close();- expect(snapshotSignal?.aborted).toBe(true);- resolveSnapshot?.(ok({ kind: "captured", bytes }));- await expect(pending).resolves.toMatchObject({+ await expect(detail).resolves.toMatchObject({ok: false,- error: { _tag: "AnalysisCancelledError" },+ error: { operation: "inspect_native_data_type" },});+ expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);});describe("Ghidra NativeAOT snapshot budget", () => {diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex bab840bad..a8ce78314 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -79,14 +79,8 @@ import { ghidraPePdbLimitations } from "./GhidraPeProfile.js";import { unverifiedGhidraBuildLimitation } from "./GhidraReleasePolicy.js";import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";import { attestGhidraNativeLoadImage } from "./GhidraLoadImageAttest.js";-import {- NATIVE_AOT_MAX_REPORT_BYTES,- NATIVE_AOT_MAX_SOURCE_BYTES,- nativeAotSnapshotOverCapacity,- parseNativeAotPe,- type NativeAotPeResult,-} from "../domain/native/nativeAotPe.js";-import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";+import type { NativeAotPeResult } from "../domain/native/nativeAotPe.js";+import { GhidraNativeAotSnapshotOwner } from "./GhidraNativeAotSnapshotOwner.js";import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";import {GHIDRA_PROVIDER_IDENTITY,@@ -125,248 +119,6 @@ export type GhidraProviderClientFactory = (type GhidraProviderClientInstance = ReturnType<GhidraProviderClientFactory>;-type NativeAotSnapshotOwner = {- readonly derive: (- imageBase: string,- operation: AnalysisOperation,- callerSignal: AbortSignal | undefined,- observations: JsonValue,- ) => Promise<Result<NativeAotPeResult, AnalysisError>>;- readonly readTypeDetail: (- address: string,- ) => ReturnType<NativeAotPeResult["readTypeDetail"]>;- readonly close: () => void;-};--/** Own one session's captured PE snapshot and immutable NativeAOT derivation. */-const createNativeAotSnapshotOwner = (input: {- readonly client: GhidraProviderClientInstance;- readonly target: BinaryTarget;- readonly startupTimeoutMs: number;-}): NativeAotSnapshotOwner => {- const { client, target, startupTimeoutMs } = input;- const controller = new AbortController();- let identity: string | undefined;- let result: NativeAotPeResult | undefined;- let pending:- | {- readonly identity: string;- readonly promise: Promise<Result<NativeAotPeResult, AnalysisError>>;- }- | undefined;- let closed = false;- let identityConflict = false;- let identityConflictObservation:- | { readonly imageBase: string; readonly observations: JsonValue }- | undefined;- const identityError = (- operation: AnalysisOperation,- reason: string,- observedBase: string,- observations: JsonValue,- ): AnalysisError =>- new ProviderAdapterError("ghidra", operation, {- diagnostics: {- reason,- artifact_sha256: target.sha256,- bound_image_base:- identity === undefined- ? null- : `0x${identity.slice(target.sha256.length + 1)}`,- observed_image_base: observedBase,- measured_observation: observations,- conflicting_image_base: identityConflictObservation?.imageBase ?? null,- conflicting_observation:- identityConflictObservation?.observations ?? null,- },- });- const identityConflictFailure = (- operation: AnalysisOperation,- observedBase: string,- observations: JsonValue,- ): Result<NativeAotPeResult, AnalysisError> => {- return err(- identityError(- operation,- "The Ghidra session reported conflicting loaded image bases; reopen the analysis session to establish a new identity.",- observedBase,- observations,- ),- );- };- const derive = async (- imageBase: string,- operation: AnalysisOperation,- callerSignal: AbortSignal | undefined,- observations: JsonValue,- ): Promise<Result<NativeAotPeResult, AnalysisError>> => {- if (callerSignal?.aborted || closed)- return err(new AnalysisCancelledError(operation));- if (identityConflict)- return identityConflictFailure(operation, imageBase, observations);- if (controller.signal.aborted)- return err(new AnalysisCancelledError(operation));- let normalizedBase: string;- try {- normalizedBase = BigInt(imageBase).toString(16);- } catch (cause: unknown) {- return err(- new ProviderAdapterError("ghidra", operation, {- diagnostics: {- reason:- "Ghidra returned an invalid loaded image base for NativeAOT identity binding.",- artifact_sha256: target.sha256,- observed_image_base: imageBase,- measured_observation: observations,- },- cause,- }),- );- }- const key = `${target.sha256}:${normalizedBase}`;- if (identity !== undefined && identity !== key) {- identityConflict = true;- identityConflictObservation = { imageBase, observations };- result = undefined;- controller.abort();- return err(- identityError(- operation,- "The Ghidra session reported a different loaded image base after NativeAOT metadata was bound to its captured snapshot; reopen the analysis session to establish a new identity.",- imageBase,- observations,- ),- );- }- identity ??= key;- if (result !== undefined) {- const settled = await waitForAbortable(- Promise.resolve(ok(result)),- callerSignal,- );- if (closed) return err(new AnalysisCancelledError(operation));- if (identityConflict)- return identityConflictFailure(operation, imageBase, observations);- if (controller.signal.aborted)- return err(new AnalysisCancelledError(operation));- return settled === ABORTED- ? err(new AnalysisCancelledError(operation))- : settled;- }- if (pending !== undefined && pending.identity !== key)- return err(- identityError(- operation,- "A NativeAOT snapshot derivation is already bound to a different loaded image base.",- imageBase,- observations,- ),- );- if (pending === undefined) {- const promise: Promise<Result<NativeAotPeResult, AnalysisError>> =- (async () => {- try {- if (client.readTargetSnapshot === undefined)- return err(- new ProviderAdapterError("ghidra", operation, {- diagnostics: {- reason:- "The Ghidra client does not expose its immutable target snapshot for NativeAOT metadata inspection.",- },- }),- );- const snapshot = await client.readTargetSnapshot(- NATIVE_AOT_MAX_SOURCE_BYTES,- controller.signal,- );- if (!snapshot.ok)- return err(- projectSessionError(- operation,- snapshot.error,- startupTimeoutMs,- ),- );- if (closed) return err(new AnalysisCancelledError(operation));- if (identityConflict)- return identityConflictFailure(- operation,- imageBase,- observations,- );- if (controller.signal.aborted)- return err(new AnalysisCancelledError(operation));- const parsed =- snapshot.value.kind === "over-capacity"- ? {- summary: nativeAotSnapshotOverCapacity(- target.sha256,- snapshot.value.sourceBytesAtLeast,- NATIVE_AOT_MAX_REPORT_BYTES,- ),- readTypeDetail: () => undefined,- }- : parseNativeAotPe(- snapshot.value.bytes,- target.sha256,- NATIVE_AOT_MAX_REPORT_BYTES,- imageBase,- );- if (closed) return err(new AnalysisCancelledError(operation));- if (identityConflict)- return identityConflictFailure(- operation,- imageBase,- observations,- );- if (controller.signal.aborted)- return err(new AnalysisCancelledError(operation));- return ok(parsed);- } catch (cause: unknown) {- return err(- new ProviderAdapterError("ghidra", operation, {- diagnostics: {- reason:- cause instanceof Error- ? cause.message- : "NativeAOT metadata could not be derived from the captured target snapshot.",- },- cause,- }),- );- }- })();- const current = { identity: key, promise };- pending = current;- void promise.then((settled) => {- if (pending !== current) return;- pending = undefined;- if (settled.ok && !closed && !identityConflict) result = settled.value;- });- }- const settled = await waitForAbortable(pending.promise, callerSignal);- if (closed) return err(new AnalysisCancelledError(operation));- if (identityConflict)- return identityConflictFailure(operation, imageBase, observations);- if (controller.signal.aborted)- return err(new AnalysisCancelledError(operation));- return settled === ABORTED- ? err(new AnalysisCancelledError(operation))- : settled;- };- return {- derive,- readTypeDetail: (address) =>- result?.readTypeDetail(address, NATIVE_AOT_MAX_REPORT_BYTES),- close: () => {- closed = true;- controller.abort();- result = undefined;- pending = undefined;- },- };-};-/** Build one AnalysisClient for an admitted Ghidra target and profile. */export const createGhidraProviderClient = (input: {readonly config: AppConfig;@@ -732,10 +484,15 @@ export const createGhidraProviderClient = (input: {];const nativeAotOwner =target.format === "pe"- ? createNativeAotSnapshotOwner({- client,- target,- startupTimeoutMs: config.ghidraStartupTimeoutMs,+ ? new GhidraNativeAotSnapshotOwner({+ targetSha256: target.sha256,+ readSnapshot: client.readTargetSnapshot?.bind(client),+ projectFailure: (operation, failure) =>+ projectSessionError(+ operation,+ failure,+ config.ghidraStartupTimeoutMs,+ ),}): undefined;const projectExecution = (@@ -985,8 +742,18 @@ export const createGhidraProviderClient = (input: {: [{ provider: committedProfile.provider, observation }];},close: async () => {- nativeAotOwner?.close();- return client.close();+ await nativeAotOwner?.close();+ const closed = await client.close();+ const retained = nativeAotOwner?.cleanupFailure;+ if (retained === undefined) return closed;+ return closed.ok+ ? err(retained)+ : err(+ analysisErrorWithCleanupFailure(+ closed.error,+ retained,+ ).bindCleanupDependencies([closed.error, retained]),+ );},});};diff --git a/tests/boundary/mcp/ghidraFailureDiagnostics.test.ts b/tests/boundary/mcp/ghidraFailureDiagnostics.test.tsindex 7899b5f24..5d65a1772 100644--- a/tests/boundary/mcp/ghidraFailureDiagnostics.test.ts+++ b/tests/boundary/mcp/ghidraFailureDiagnostics.test.ts@@ -1,3 +1,4 @@+import { nativeAotSnapshotObservationSchema } from "../../../src/domain/native/nativeAotSnapshotObservation.js";import { writeFile } from "node:fs/promises";import { join } from "node:path";import { AnalysisCleanupLease } from "../../../src/artifacts/AnalysisCleanupLease.js";@@ -94,21 +95,36 @@ it("preserves queue failure diagnostics through the provider, CLI adapter and SD}}, 30_000);-it.each(["cancelled", "protocol"] as const)(- "retains completed snapshot facts and exact cleanup over provider/CLI/MCP after %s",- async (kind) => {+it.each(+ (["cancelled", "protocol"] as const).flatMap((kind) =>+ (["file", "native-aot"] as const).map((observation) => ({+ kind,+ observation,+ })),+ ),+)(+ "retains completed $observation snapshot facts and exact cleanup over provider/CLI/MCP after $kind",+ async ({ kind, observation }) => {const directory = await createTestTempDirectory("rea-ghidra-snapshot-projection-",);const path = join(directory, "Inert.exe");const bytes = nativeAotPeFixture();await writeFile(path, bytes);- const partialObservation = fileSnapshotPartialObservationSchema.parse({- kind: "file-snapshot-hash",- path,- sha256: nativeAotPeDigest(bytes),- bytes: bytes.length,- });+ const partialObservation =+ observation === "file"+ ? fileSnapshotPartialObservationSchema.parse({+ kind: "file-snapshot-hash",+ path,+ sha256: nativeAotPeDigest(bytes),+ bytes: bytes.length,+ })+ : nativeAotSnapshotObservationSchema.parse({+ kind: "native-aot-snapshot",+ analysis_artifact_sha256: nativeAotPeDigest(bytes),+ image_base: "0x140000000",+ capture: { status: "captured", bytes: bytes.length },+ });const cleanup = new ProviderCleanupError("ghidra", [path], {reason: "controlled snapshot descriptor remains",});