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): prepare ownership before Java probe deadline
morluto376eeca77082
diff --git a/docs/installation.md b/docs/installation.mdindex 330a6b81c..0b7319e0d 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -1125,6 +1125,10 @@ compiler remains distinguishable from a compiler that exited with an error.The helper compile deadline defaults to 120,000 ms; set`REA_SWIFTC_COMPILE_TIMEOUT_MS` to an integer between 1 and 2,147,483,647 whena busy host needs longer.+On macOS, the Java prerequisite probe waits for this independently bounded+preparation before starting its five-second command deadline. Caller cancellation+still interrupts preparation, and failed helper cleanup remains owned for retry.+Linux process-table preparation remains inside the command deadline.Other rejection values retain their primitive value or an explicit type.Shutdown warnings include the failurekind, message, and diagnostics, while process and temporary-project cleanupdiff --git a/src/ghidra/GhidraJavaProbe.ts b/src/ghidra/GhidraJavaProbe.tsindex 63c2b124b..e843fa636 100644--- a/src/ghidra/GhidraJavaProbe.ts+++ b/src/ghidra/GhidraJavaProbe.ts@@ -12,6 +12,7 @@ import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRimport {OwnedCommandFailure,runOwnedCommand,+ prepareOwnedCommand,} from "../process/OwnedCommand.js";import type { ProviderProcessSnapshot } from "../process/ProviderProcess.js";import { boundedUtf8Text } from "../process/boundedUtf8Text.js";@@ -150,6 +151,7 @@ const observeGhidraJava = async (| Result<GhidraJavaObservation, GhidraJavaProbeFailure>| undefined;try {+ await prepareOwnedCommand(options.signal);await runOwnedCommand({command,diff --git a/src/process/OwnedCommand.ts b/src/process/OwnedCommand.tsindex 6247ce26f..5c4a31e54 100644--- a/src/process/OwnedCommand.ts+++ b/src/process/OwnedCommand.ts@@ -1,3 +1,7 @@+import {+ prepareProcessOwnershipInspection,+ systemProcessOwnershipHost,+} from "./ProcessOwnershipObservation.js";import { DarwinProcessOwnershipInspectionError } from "./DarwinProcessRunTokenReader.js";import type { Readable, Writable } from "node:stream";import { pipeline } from "node:stream/promises";@@ -93,6 +97,64 @@ interface OwnedCommandLimits {readonly stdout?: Writable;}+/** Keep independently bounded macOS helper compilation outside a short command deadline.+ * Other platforms still prepare inside runOwnedCommand: Linux ps has no separate deadline.+ */+export const prepareOwnedCommand = async (+ signal?: AbortSignal,+): Promise<void> => {+ if (systemProcessOwnershipHost.platform !== "darwin") return;+ try {+ signal?.throwIfAborted();+ await prepareProcessOwnershipInspection(signal);+ } catch (cause: unknown) {+ throwCommandPreparationFailure(+ cause,+ signal,+ signal?.aborted === true ? "cancelled" : undefined,+ );+ }+};++/** Both preparation stages preserve physical failures, opaque cancellation and exact owners. */+function throwCommandPreparationFailure(+ cause: unknown,+ signal: AbortSignal | undefined,+ interruption: "cancelled" | "timeout" | undefined,+): never {+ // A caller's raw abort reason remains opaque even if it is a typed error.+ const preparationFailure =+ cause instanceof DarwinProcessOwnershipInspectionError &&+ !(signal?.aborted === true && cause === signal.reason)+ ? cause+ : undefined;+ // Preparation owns its physical outcome and any retained helper resources.+ if (+ preparationFailure !== undefined &&+ preparationFailure.cancellation === undefined+ )+ throw preparationFailure;+ if (interruption !== undefined)+ throw new OwnedCommandFailure(+ interruption,+ interruption === "cancelled"+ ? "Command cancelled during ownership preparation."+ : "Command deadline elapsed during ownership preparation.",+ null,+ null,+ {+ cause,+ ...(interruption === "cancelled"+ ? {+ cancellation: { reason: signal?.reason },+ }+ : {}),+ ...(preparationFailure === undefined ? {} : { preparationFailure }),+ },+ );+ throw cause;+}+/** Execute a single owned process with independent cleanup and bounded diagnostic retention. */export const runOwnedCommand = async (spawn: OwnedProviderProcessSpawnOptions,@@ -154,38 +216,7 @@ const collectOwnedCommand = async (signal,});} catch (cause: unknown) {- // A caller's raw abort reason remains opaque even if it is a typed error.- const preparationFailure =- cause instanceof DarwinProcessOwnershipInspectionError &&- !(signal.aborted && cause === signal.reason)- ? cause- : undefined;- // Preparation owns its physical outcome and any retained helper resources.- if (- preparationFailure !== undefined &&- preparationFailure.cancellation === undefined- )- throw preparationFailure;- const interruption = deadline.interruption;- if (interruption !== undefined)- throw new OwnedCommandFailure(- interruption,- interruption === "cancelled"- ? "Command cancelled during ownership preparation."- : "Command deadline elapsed during ownership preparation.",- null,- null,- {- cause,- ...(interruption === "cancelled"- ? {- cancellation: { reason: signal.reason },- }- : {}),- ...(preparationFailure === undefined ? {} : { preparationFailure }),- },- );- throw cause;+ throwCommandPreparationFailure(cause, signal, deadline.interruption);}let exceeded = false;let processFailure: string | undefined;diff --git a/src/process/OwnedCommandPreparation.test.ts b/src/process/OwnedCommandPreparation.test.tsnew file mode 100644index 000000000..9c1006b73--- /dev/null+++ b/src/process/OwnedCommandPreparation.test.ts@@ -0,0 +1,186 @@+import { afterEach, expect, it, vi } from "vitest";+import { createDeferred } from "../../tests/fixtures/binarySession.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { DarwinProcessOwnershipInspectionError } from "./DarwinProcessRunTokenReader.js";+import {+ OwnedCommandFailure,+ prepareOwnedCommand,+ runOwnedCommand,+} from "./OwnedCommand.js";+import {+ prepareProcessOwnershipInspection,+ systemProcessOwnershipHost,+} from "./ProcessOwnershipObservation.js";++const platform = Object.getOwnPropertyDescriptor(+ systemProcessOwnershipHost,+ "platform",+)!;+afterEach(() => {+ vi.restoreAllMocks();+ Object.defineProperty(systemProcessOwnershipHost, "platform", platform);+ vi.useRealTimers();+});+const hostPlatform = (value: NodeJS.Platform) =>+ Object.defineProperty(systemProcessOwnershipHost, "platform", {+ value,+ configurable: true,+ });++it("gives bounded macOS preparation the caller signal and no command deadline", async () => {+ hostPlatform("darwin");+ vi.useFakeTimers();+ const prepared = createDeferred<void>();+ const controller = new AbortController();+ const prepare = vi+ .spyOn(systemProcessOwnershipHost, "prepare")+ .mockImplementation(async (signal) => {+ expect(signal).toBe(controller.signal);+ await prepared.promise;+ });+ let completed = false;+ const pending = prepareOwnedCommand(controller.signal).then(() => {+ completed = true;+ });+ await vi.advanceTimersByTimeAsync(10_000);+ expect(completed).toBe(false);+ expect(controller.signal.aborted).toBe(false);+ prepared.resolve();+ await pending;+ expect(prepare).toHaveBeenCalledOnce();+});++it.each(["linux", "win32"] as const)(+ "leaves %s preparation inside the command deadline",+ async (value) => {+ hostPlatform(value);+ const prepare = vi.spyOn(systemProcessOwnershipHost, "prepare");+ await prepareOwnedCommand();+ expect(prepare).not.toHaveBeenCalled();+ },+);++it("keeps an observed compiler failure primary when cancellation is also observed", async () => {+ hostPlatform("darwin");+ const failure = new DarwinProcessOwnershipInspectionError(+ "physical compiler failure",+ );+ const controller = new AbortController();+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async () => {+ controller.abort({ caller: "after compiler failure" });+ throw failure;+ },+ );+ await expect(prepareOwnedCommand(controller.signal)).rejects.toBe(failure);+});++it.each(["before", "during"] as const)(+ "does not reinterpret a typed opaque caller reason as a helper failure: %s",+ async (phase) => {+ hostPlatform("darwin");+ const reason = new DarwinProcessOwnershipInspectionError(+ "caller-owned reason",+ );+ const controller = new AbortController();+ const prepare = vi+ .spyOn(systemProcessOwnershipHost, "prepare")+ .mockImplementation(async () => {+ controller.abort(reason);+ throw reason;+ });+ if (phase === "before") controller.abort(reason);+ let observed: unknown;+ try {+ await prepareOwnedCommand(controller.signal);+ } catch (error) {+ observed = error;+ }+ expect(observed).toBeInstanceOf(OwnedCommandFailure);+ if (!(observed instanceof OwnedCommandFailure)) throw observed;+ expect(observed.reason).toBe("cancelled");+ expect(observed.cancellation?.reason).toBe(reason);+ expect(observed.preparationFailure).toBeUndefined();+ expect(prepare).toHaveBeenCalledTimes(phase === "before" ? 0 : 1);+ },+);++it("preserves exact cancelled preparation cleanup capabilities", async () => {+ hostPlatform("darwin");+ const reason = { caller: "during helper final cleanup" };+ const controller = new AbortController();+ const cleanup = new ProviderCleanupError(+ "process-ownership",+ ["authored-owned-helper"],+ {},+ );+ const owner = {+ close: vi.fn(async () => {+ cleanup.resolveCleanup();+ }),+ };+ const failure = new DarwinProcessOwnershipInspectionError(+ "cancelled helper",+ { cancellation: { reason }, cleanupFailure: cleanup, cleanupOwner: owner },+ );+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async () => {+ controller.abort(reason);+ throw failure;+ },+ );+ let observed: unknown;+ try {+ await prepareOwnedCommand(controller.signal);+ } catch (error) {+ observed = error;+ }+ if (!(observed instanceof OwnedCommandFailure)) throw observed;+ expect(observed.cancellation?.reason).toBe(reason);+ expect(observed.preparationFailure).toBe(failure);+ if (observed.preparationFailure === undefined)+ throw new Error("Expected retained preparation failure");+ expect(observed.preparationFailure.cleanupOwner).toBe(owner);+ expect(observed.preparationFailure.cleanupFailure).toBe(cleanup);+ await observed.preparationFailure.cleanupOwner!.close();+ expect(cleanup.cleanupIncomplete).toBe(false);+});++it("bounds simulated Linux preparation by the command deadline before launch", async () => {+ hostPlatform("linux");+ vi.useFakeTimers();+ const preparing = vi+ .spyOn(systemProcessOwnershipHost, "prepare")+ .mockImplementation(async (signal) => {+ await new Promise<void>((_resolve, reject) =>+ signal?.addEventListener("abort", () => reject(signal.reason), {+ once: true,+ }),+ );+ });+ await prepareOwnedCommand();+ expect(preparing).not.toHaveBeenCalled();+ let enteredLaunch = false;+ const pending = runOwnedCommand(+ {+ command: "never-launched",+ arguments: [],+ runId: "authored-linux-prepare",+ },+ { timeoutMs: 50, diagnosticBytes: 1024 },+ {+ launcher: async (input) => {+ await prepareProcessOwnershipInspection(input.signal);+ enteredLaunch = true;+ throw new Error("Preparation should time out before launch");+ },+ },+ );+ const expected = expect(pending).rejects.toMatchObject({+ reason: "timeout",+ message: "Command deadline elapsed during ownership preparation.",+ });+ await vi.advanceTimersByTimeAsync(51);+ await expected;+ expect(enteredLaunch).toBe(false);+});diff --git a/tests/boundary/process/ghidraJavaProbePreparation.test.ts b/tests/boundary/process/ghidraJavaProbePreparation.test.tsnew file mode 100644index 000000000..d64d35971--- /dev/null+++ b/tests/boundary/process/ghidraJavaProbePreparation.test.ts@@ -0,0 +1,244 @@+import { AnalysisError } from "../../../src/domain/analysisErrorBase.js";+import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";+import { access, mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { setTimeout as delay } from "node:timers/promises";+import { afterEach, beforeAll, expect, it, vi } from "vitest";++import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../../../src/domain/providerAdapterError.js";+import { probeGhidraJava } from "../../../src/ghidra/GhidraJavaProbe.js";+import { DarwinProcessOwnershipInspectionError } from "../../../src/process/DarwinProcessRunTokenReader.js";+import {+ prepareProcessOwnershipInspection,+ systemProcessOwnershipHost,+} from "../../../src/process/ProcessOwnershipObservation.js";+import { createInspectionResources } from "../../fixtures/inspectionResources.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++// Long enough for an ordinary owned launch, short enough to keep the cold case quick.+const PROBE_TIMEOUT_MS = 2_000;++let inspectionResources = createInspectionResources();+afterEach(async () => {+ vi.restoreAllMocks();+ await inspectionResources.close();+ inspectionResources = createInspectionResources();+});++// Prepare the real inspector once; each case models its own first-time preparation.+beforeAll(() => prepareProcessOwnershipInspection());++/** Java-shaped Node command that records whether it was launched; not a JVM. */+const writeJava = async () => {+ const home = await createTestTempDirectory("rea-java-preparation-");+ const launched = join(home, "launched");+ const command = join(home, "bin", "java");+ await mkdir(join(home, "bin"));+ await writeFile(+ command,+ `#!${process.execPath}\nrequire("node:fs").writeFileSync(${JSON.stringify(launched)}, "");\nprocess.stderr.write(${JSON.stringify(` java.version = 21.0.11\n java.home = ${home}\n sun.arch.data.model = 64\n`)});\n`,+ { mode: 0o700 },+ );+ return { command, launched };+};++const probe = (command: string, signal?: AbortSignal) =>+ probeGhidraJava(+ command,+ {},+ {+ resourceOwner: inspectionResources.owner,+ timeoutMs: PROBE_TIMEOUT_MS,+ ...(signal === undefined ? {} : { signal }),+ },+ );++it.runIf(process.platform === "darwin")(+ "spends a cold macOS ownership preparation outside the Java probe deadline",+ async () => {+ const java = await writeJava();+ const prepare = systemProcessOwnershipHost.prepare;+ let cold = true;+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async (signal) => {+ // A cold Swift SDK cache makes the first preparation outlast the probe.+ if (cold) {+ await delay(PROBE_TIMEOUT_MS + 1_000, undefined, { signal });+ cold = false;+ }+ await prepare?.(signal);+ },+ );++ const result = await probe(java.command);++ expect(result).toMatchObject({+ ok: true,+ value: { version: "21.0.11", major: 21 },+ });+ await expect(access(java.launched)).resolves.toBeUndefined();+ },+);++it.runIf(process.platform === "linux")(+ "keeps Linux ownership preparation inside the Java probe deadline",+ async () => {+ const java = await writeJava();+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ // A stalled `ps` check has no time limit of its own.+ async (signal) => {+ await delay(60_000, undefined, { signal });+ },+ );++ const result = await probe(java.command);++ expect(result).toMatchObject({+ ok: false,+ error: {+ processErrorCode: "ETIMEDOUT",+ detail: expect.stringContaining(+ "Command deadline elapsed during ownership preparation.",+ ),+ },+ });+ await expect(access(java.launched)).rejects.toThrow();+ },+);++it.skipIf(process.platform === "win32")(+ "reports cancellation during ownership preparation without launching Java",+ async () => {+ const java = await writeJava();+ const controller = new AbortController();+ let entered = (): void => undefined;+ const preparing = new Promise<void>((resolve) => {+ entered = resolve;+ });+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async (signal) => {+ entered();+ await delay(60_000, undefined, { signal });+ },+ );++ const outcome = probe(java.command, controller.signal);+ await preparing;+ controller.abort();+ const result = await outcome;++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected a cancelled Java probe");+ expect(result.error).toBeInstanceOf(AnalysisCancelledError);+ await expect(access(java.launched)).rejects.toThrow();+ },+);++it.skipIf(process.platform === "win32")(+ "reports a failed ownership preparation as its own stage without launching Java",+ async () => {+ const java = await writeJava();+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockRejectedValue(+ new DarwinProcessOwnershipInspectionError("helper compilation failed", {+ compilerOutcome: {+ outcome: "exited",+ code: 1,+ signal: null,+ stderr: "error: failed to build module 'Swift'",+ stderrTruncated: false,+ outputTruncated: false,+ killed: false,+ },+ }),+ );++ const result = await probe(java.command);++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected a failed Java probe");+ expect(result.error).toBeInstanceOf(ProviderAdapterError);+ expect(result.error).toMatchObject({+ diagnostics: {+ stage: "ownership_preparation",+ compiler_outcome: { outcome: "exited", code: 1 },+ },+ });+ await expect(access(java.launched)).rejects.toThrow();+ },+);++it.runIf(process.platform === "darwin")(+ "retains preparation cleanup through cancellation and clears only the confirmed helper owner",+ async () => {+ const java = await writeJava();+ const controller = new AbortController();+ const reason = new ProviderCleanupError(+ "caller",+ ["caller-owned-resource"],+ {},+ );+ const cleanup = new ProviderCleanupError(+ "process-ownership",+ ["controlled-helper-root"],+ {},+ );+ let denied = true;+ const close = vi.fn(async () => {+ if (denied) throw cleanup;+ cleanup.resolveCleanup();+ });+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async () => {+ controller.abort(reason);+ throw new DarwinProcessOwnershipInspectionError(+ "cancelled helper with retained cleanup",+ {+ cancellation: { reason },+ cleanupFailure: cleanup,+ cleanupOwner: { close },+ },+ );+ },+ );+ try {+ const result = await probe(java.command, controller.signal);+ if (result.ok || !(result.error instanceof AnalysisError))+ throw new Error("Expected an owned cleanup failure");+ expect(result.error.cleanupResources).toEqual(["controlled-helper-root"]);+ expect(result.error.cleanupPrimary?.cause).toBe(reason);+ await expect(inspectionResources.close()).rejects.toThrow();+ denied = false;+ await inspectionResources.close();+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(projectAnalysisError(result.error).code).toBe("cancelled");+ expect(result.error.cleanupPrimary?.cause).toBe(reason);+ expect(reason.cleanupIncomplete).toBe(true);+ expect(close).toHaveBeenCalledTimes(2);+ await expect(access(java.launched)).rejects.toThrow();+ } finally {+ denied = false;+ await inspectionResources.close();+ }+ },+);++it.runIf(process.platform === "darwin")(+ "refuses launch when cancellation arrives at the completed preparation handoff",+ async () => {+ const java = await writeJava();+ const controller = new AbortController();+ const reason = { caller: "after ownership preparation" };+ vi.spyOn(systemProcessOwnershipHost, "prepare").mockImplementation(+ async () => {+ controller.abort(reason);+ },+ );+ const result = await probe(java.command, controller.signal);+ if (result.ok || !(result.error instanceof AnalysisCancelledError))+ throw new Error("Expected cancelled handoff");+ expect(result.error.cause).toBe(reason);+ await expect(access(java.launched)).rejects.toThrow();+ },+);