Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(ghidra): prepare ownership before Java probe deadline

morluto376eeca77082
diff --git a/docs/installation.md b/docs/installation.md
index 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 when
a 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 failure
kind, message, and diagnostics, while process and temporary-project cleanup
diff --git a/src/ghidra/GhidraJavaProbe.ts b/src/ghidra/GhidraJavaProbe.ts
index 63c2b124b..e843fa636 100644
--- a/src/ghidra/GhidraJavaProbe.ts
+++ b/src/ghidra/GhidraJavaProbe.ts
@@ -12,6 +12,7 @@ import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessR
import {
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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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();
+ },
+);