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(native): retain LLDB cleanup ownership through client close
morluto7ad353fa8b3f
diff --git a/src/domain/providerCleanupError.ts b/src/domain/providerCleanupError.tsindex 8e582caa8..4503b583e 100644--- a/src/domain/providerCleanupError.ts+++ b/src/domain/providerCleanupError.ts@@ -1,5 +1,6 @@import type { JsonValue } from "./jsonValue.js";import { ProviderAdapterError } from "./providerAdapterError.js";+import type { AnalysisPartialObservation } from "./analysisErrorBase.js";/** Provider resources could not be proven closed after bounded cleanup. */export class ProviderCleanupError extends ProviderAdapterError {@@ -13,10 +14,21 @@ export class ProviderCleanupError extends ProviderAdapterError {resources: readonly string[],diagnostics: Readonly<Record<string, JsonValue>>,/** Identify the operation owning these resources; binary callers retain their default. */- options?: ErrorOptions & { readonly operation?: string },+ options?: ErrorOptions & {+ readonly operation?: string;+ readonly partialObservation?: AnalysisPartialObservation;+ },) {- const { operation = "close_binary", ...errorOptions } = options ?? {};- super(providerId, operation, { ...errorOptions, diagnostics });+ const {+ operation = "close_binary",+ partialObservation,+ ...errorOptions+ } = options ?? {};+ super(providerId, operation, {+ ...errorOptions,+ ...(partialObservation === undefined ? {} : { partialObservation }),+ diagnostics,+ });this.cleanupResources = [...resources];}}diff --git a/src/native/LldbCallTracer.ts b/src/native/LldbCallTracer.tsindex c0ea59c8b..9fa5813b8 100644--- a/src/native/LldbCallTracer.ts+++ b/src/native/LldbCallTracer.ts@@ -12,10 +12,9 @@ import {AnalysisTimeoutError,} from "../domain/analysisErrorCore.js";import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";-import type {- AnalysisCleanupObservation,- AnalysisError,-} from "../domain/analysisErrorBase.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";+import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";import type { NativeCallPartialObservation } from "../domain/native/nativeCallPartialObservation.js";import {nativeCallEventSchema,@@ -23,6 +22,7 @@ import {type NativeCallObservationInput,} from "../domain/native/nativeCallObservation.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";import { safeParseJson } from "../domain/safeJson.js";import {@@ -32,7 +32,6 @@ import {import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";import {observeProcessStartIdentity,- prepareProcessOwnershipInspection,signalProcessWithStartIdentity,} from "../process/ProcessOwnershipObservation.js";import type { ProcessIdentityObservation } from "../process/ProcessOwnership.js";@@ -158,6 +157,8 @@ export interface NativeCallTracer {},signal?: AbortSignal,): Promise<Result<NativeCallTrace, AnalysisError>>;+ /** Retry cleanup retained after a trace could not verify process exit. */+ close(): Promise<Result<null, AnalysisError>>;}/** Remediation for a target LLDB may not debug. */@@ -167,6 +168,8 @@ const ATTACH_REMEDIATION =/** Production tracer: `lldb --batch` running the REA LLDB bridge. */export class LldbCallTracer implements NativeCallTracer {private readonly environment: NodeJS.ProcessEnv;+ #tail: Promise<void> = Promise.resolve();+ #pendingCleanup: RetainedLldbResources | undefined;constructor(environment: Readonly<NodeJS.ProcessEnv>,private readonly launch: typeof runLldb = runLldb,@@ -183,6 +186,15 @@ export class LldbCallTracer implements NativeCallTracer {request: Parameters<NativeCallTracer["trace"]>[0],signal?: AbortSignal,): Promise<Result<NativeCallTrace, AnalysisError>> {+ return this.#serialize(() => this.#trace(request, signal));+ }++ async #trace(+ request: Parameters<NativeCallTracer["trace"]>[0],+ signal?: AbortSignal,+ ): Promise<Result<NativeCallTrace, AnalysisError>> {+ const pendingCleanup = await this.#retryPendingCleanup();+ if (pendingCleanup !== undefined) return err(pendingCleanup);const lldb = await this.resolveTool("lldb", signal);if (!lldb.ok)return err(@@ -196,30 +208,155 @@ export class LldbCallTracer implements NativeCallTracer {),);const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });+ const paths = lldbRuntimePaths(root.path);+ let result: Result<NativeCallTrace, AnalysisError>;+ try {+ result = await this.#run(lldb.value, root, request, signal);+ } catch (cause: unknown) {+ const partialObservation = await partialNativeObservation({+ request,+ pidPath: paths.pid,+ stdoutPath: paths.stdoutCapture,+ stderrPath: paths.stderrCapture,+ observationPath: paths.observations,+ version: null,+ reason: "tracer-failure",+ });+ const retained = this.#pendingCleanup;+ const resources =+ retained === undefined ? [] : await lldbCleanupResources(retained);+ result = err(+ new ProviderAdapterError(PROVIDER, OPERATION, {+ cause,+ diagnostics: {+ reason: cause instanceof Error ? cause.message : String(cause),+ },+ partialObservation,+ ...(retained === undefined+ ? {}+ : {+ cleanup: {+ reason: "LLDB trace failed while owned resources remain",+ resources,+ },+ }),+ }),+ );+ }+ if (this.#pendingCleanup?.root === root) return result;try {- return await this.#run(lldb.value, root.path, request, signal);- } finally {await root.close();+ } catch (cause: unknown) {+ this.#pendingCleanup = {+ root,+ supervisor: undefined,+ pidPath: paths.pid,+ targetIdentity: undefined,+ processStopped: true,+ targetStopped: true,+ };+ const partialObservation = result.ok+ ? partialObservationFromTrace(request, result.value)+ : result.error.partialObservation;+ return err(+ new ProviderCleanupError(+ PROVIDER,+ [root.path],+ {+ reason: cause instanceof Error ? cause.message : String(cause),+ ...(result.ok+ ? {}+ : {+ execution_failure: projectAnalysisError(result.error).code,+ primary_failure: result.error.message,+ }),+ },+ {+ operation: OPERATION,+ cause: result.ok+ ? cause+ : new AggregateError(+ [result.error, cause],+ "LLDB trace and runtime cleanup both failed",+ ),+ ...(partialObservation === undefined ? {} : { partialObservation }),+ },+ ),+ );+ }+ return result;+ }++ /** Retry retained LLDB cleanup without abandoning its process or runtime owner. */+ async close(): Promise<Result<null, AnalysisError>> {+ return this.#serialize(() => this.#close());+ }++ async #close(): Promise<Result<null, AnalysisError>> {+ const failure = await this.#retryPendingCleanup();+ return failure === undefined ? ok(null) : err(failure);+ }++ #serialize<T>(operation: () => Promise<T>): Promise<T> {+ const call = this.#tail.then(operation, operation);+ this.#tail = call.then(+ () => undefined,+ () => undefined,+ );+ return call;+ }++ async #retryPendingCleanup(): Promise<ProviderCleanupError | undefined> {+ const owner = this.#pendingCleanup;+ if (owner === undefined) return undefined;+ let firstFailure: string | undefined;+ if (!owner.processStopped) {+ const stopped = await owner.supervisor?.stop();+ if (stopped?.status === "incomplete") firstFailure = stopped.reason;+ else {+ owner.supervisor?.dispose();+ owner.processStopped = true;+ }}+ if (firstFailure === undefined && !owner.targetStopped) {+ const targetTermination = await ensureTerminated(+ owner.pidPath,+ owner.targetIdentity,+ true,+ );+ if (targetTermination !== "terminated")+ firstFailure = targetTerminationReason(targetTermination);+ else owner.targetStopped = true;+ }+ if (firstFailure === undefined) {+ try {+ await owner.root.close();+ this.#pendingCleanup = undefined;+ return undefined;+ } catch (cause: unknown) {+ firstFailure = cause instanceof Error ? cause.message : String(cause);+ }+ }+ const resources = await lldbCleanupResources(owner);+ return new ProviderCleanupError(+ PROVIDER,+ resources,+ {+ reason: firstFailure ?? "LLDB cleanup remains incomplete",+ resources,+ },+ { operation: OPERATION },+ );}async #run(lldb: ResolvedTool,- directory: string,+ root: PrivateRuntimeRoot,request: Parameters<NativeCallTracer["trace"]>[0],signal?: AbortSignal,): Promise<Result<NativeCallTrace, AnalysisError>> {- const paths = {- config: join(directory, "config.json"),- result: join(directory, "result.json"),- pid: join(directory, "pid"),- identityAck: join(directory, "identity.ack"),- stdout: join(directory, "stdout"),- stderr: join(directory, "stderr"),- stdoutCapture: join(directory, "stdout.capture"),- stderrCapture: join(directory, "stderr.capture"),- observations: join(directory, "observations.jsonl"),- };+ const directory = root.path;+ const paths = lldbRuntimePaths(directory);const { input } = request;await writeFile(paths.config,@@ -251,7 +388,6 @@ export class LldbCallTracer implements NativeCallTracer {}),{ mode: 0o600 },);- await prepareProcessOwnershipInspection(signal);const exited = await this.launch(lldb.path,[@@ -271,15 +407,22 @@ export class LldbCallTracer implements NativeCallTracer {...(signal === undefined ? {} : { signal }),},);+ const retained: RetainedLldbResources = {+ root,+ supervisor: exited.cleanupOwner,+ pidPath: paths.pid,+ targetIdentity: exited.targetIdentity,+ processStopped: exited.cleanupOwner === undefined,+ targetStopped: !exited.targetLaunched,+ };+ this.#pendingCleanup = retained;const output =exited.kind === "exited"? await readTracerOutput(paths.result): undefined;- let targetTermination = await ensureTerminated(- paths.pid,- exited.targetIdentity,- true,- );+ let targetTermination: TargetTermination = exited.targetLaunched+ ? await ensureTerminated(paths.pid, exited.targetIdentity, true)+ : "terminated";// These two bridge outcomes are emitted before a target process exists.// Other missing-PID cases, including a missing result, remain unknown.if (@@ -288,6 +431,9 @@ export class LldbCallTracer implements NativeCallTracer {(await readTargetPid(paths.pid)) === undefined)targetTermination = "terminated";+ retained.targetStopped = targetTermination === "terminated";+ if (retained.processStopped && retained.targetStopped)+ this.#pendingCleanup = undefined;const terminated = targetTermination === "terminated";const cleanupDetails = [exited.cleanupFailure,@@ -298,16 +444,7 @@ export class LldbCallTracer implements NativeCallTracer {? undefined: {reason: cleanupDetails.join("; "),- resources: [- ...(exited.cleanupFailure === undefined- ? []- : ["lldb-process-group"]),- ...(terminated- ? []- : [- `native-target:${String((await readTargetPid(paths.pid)) ?? "unknown")}`,- ]),- ],+ resources: await lldbCleanupResources(retained),};const partialReason =exited.kind === "cancelled"@@ -357,20 +494,38 @@ export class LldbCallTracer implements NativeCallTracer {);if (exited.cleanupFailure !== undefined)return err(- new ProviderAdapterError(PROVIDER, OPERATION, {- cleanup: lifecycleCleanup ?? {- reason: exited.cleanupFailure,- resources: ["lldb-process-group"],- },- diagnostics: {+ new ProviderCleanupError(+ PROVIDER,+ await lldbCleanupResources(retained),+ {reason: "LLDB process-group cleanup could not be verified",cleanup_failure: exited.cleanupFailure,...(lifecycleCleanup === undefined? {}: { target_cleanup: lifecycleCleanup }),},- partialObservation: await getPartialObservation(),- }),+ {+ operation: OPERATION,+ partialObservation: await getPartialObservation(),+ },+ ),+ );+ if (!terminated)+ return err(+ new ProviderCleanupError(+ PROVIDER,+ await lldbCleanupResources(retained),+ {+ reason: "LLDB target process termination could not be verified",+ ...(lifecycleCleanup === undefined+ ? {}+ : { target_cleanup: lifecycleCleanup }),+ },+ {+ operation: OPERATION,+ partialObservation: await getPartialObservation(),+ },+ ),);if (output === undefined)return err(@@ -532,6 +687,43 @@ const partialNativeObservation = async (options: {});};+const partialObservationFromTrace = (+ request: Parameters<NativeCallTracer["trace"]>[0],+ trace: NativeCallTrace,+): NativeCallPartialObservation =>+ projectLldbPartialObservation({+ target: {+ path: request.executable,+ sha256: request.expectedSha256,+ architecture: request.architecture,+ arguments: request.input.arguments,+ environment: request.input.environment,+ working_directory: request.input.working_directory ?? null,+ },+ pid: trace.run.pid,+ stdout: trace.stdout,+ stderr: trace.stderr,+ version: trace.run.version,+ journal: {+ events: trace.run.events,+ otherStops: trace.run.other_stops,+ limitations: [],+ },+ reason: "cleanup-failure",+ });++const lldbRuntimePaths = (directory: string) => ({+ config: join(directory, "config.json"),+ result: join(directory, "result.json"),+ pid: join(directory, "pid"),+ identityAck: join(directory, "identity.ack"),+ stdout: join(directory, "stdout"),+ stderr: join(directory, "stderr"),+ stdoutCapture: join(directory, "stdout.capture"),+ stderrCapture: join(directory, "stderr.capture"),+ observations: join(directory, "observations.jsonl"),+});+const readTracerOutput = async (path: string,): Promise<z.infer<typeof tracerOutputSchema> | undefined> => {@@ -588,24 +780,43 @@ const capturedOutput = async (}};-type LldbExit =+interface RetainedLldbResources {+ readonly root: PrivateRuntimeRoot;+ readonly supervisor: ProviderProcessSupervisor | undefined;+ readonly pidPath: string;+ readonly targetIdentity: string | undefined;+ processStopped: boolean;+ targetStopped: boolean;+}++type LldbOutcome =| {readonly kind: "exited";readonly exitCode: number | null;readonly output: string;- readonly targetIdentity: string | undefined;- readonly cleanupFailure: string | undefined;}- | {- readonly kind: "cancelled";- readonly targetIdentity: string | undefined;- readonly cleanupFailure: string | undefined;- }- | {- readonly kind: "timeout";- readonly targetIdentity: string | undefined;- readonly cleanupFailure: string | undefined;- };+ | { readonly kind: "cancelled" }+ | { readonly kind: "timeout" };++type LldbExit = LldbOutcome & {+ /** False proves LLDB never started and could not have created a target. */+ readonly targetLaunched: boolean;+ readonly targetIdentity: string | undefined;+ readonly cleanupFailure: string | undefined;+ readonly cleanupOwner?: ProviderProcessSupervisor;+};++const lldbCleanupResources = async (+ owner: RetainedLldbResources,+): Promise<string[]> => [+ ...(owner.processStopped ? [] : ["lldb-process-group"]),+ ...(owner.targetStopped+ ? []+ : [+ `native-target:${String((await readTargetPid(owner.pidPath)) ?? "unknown")}`,+ ]),+ owner.root.path,+];/** Supervise LLDB as an owned process group while observing its target PID identity. */const runLldb = async (@@ -622,6 +833,7 @@ const runLldb = async (if (options.signal?.aborted === true)return {kind: "cancelled",+ targetLaunched: false,targetIdentity: undefined,cleanupFailure: undefined,};@@ -631,6 +843,23 @@ const runLldb = async ();let targetIdentity: string | undefined;let supervisor: ProviderProcessSupervisor | undefined;+ let retained = false;+ const finish = async (outcome: LldbOutcome): Promise<LldbExit> => {+ const stopped = await supervisor?.stop();+ retained = stopped?.status === "incomplete";+ return {+ ...(deadline.interruption === undefined+ ? outcome+ : { kind: deadline.interruption }),+ targetLaunched: supervisor !== undefined,+ targetIdentity,+ cleanupFailure:+ stopped?.status === "incomplete" ? stopped.reason : undefined,+ ...(retained && supervisor !== undefined+ ? { cleanupOwner: supervisor }+ : {}),+ };+ };try {const launched = await spawnOwnedProviderProcess({command: executable,@@ -668,52 +897,36 @@ const runLldb = async (identityAckWritten = true;}const interruption = deadline.interruption;- if (interruption !== undefined) {- const stopped = await supervisor.stop();- const cleanupFailure =- stopped.status === "incomplete" ? stopped.reason : undefined;- return interruption === "cancelled"- ? { kind: "cancelled", targetIdentity, cleanupFailure }- : { kind: "timeout", targetIdentity, cleanupFailure };- }+ if (interruption !== undefined)+ return await finish({ kind: interruption });await waitForAbortableDelay(20, deadline.signal);}const snapshot = supervisor.snapshot();- const stopped = await supervisor.stop();- const cleanupFailure =- stopped.status === "incomplete" ? stopped.reason : undefined;const interruption = deadline.interruption;- if (interruption === "cancelled")- return { kind: "cancelled", targetIdentity, cleanupFailure };- if (interruption === "timeout")- return { kind: "timeout", targetIdentity, cleanupFailure };- return {- kind: "exited",- exitCode: snapshot.exitCode ?? null,- output: `${snapshot.stdout.text}${snapshot.stderr.text}`.slice(- -DIAGNOSTIC_BYTES,- ),- targetIdentity,- cleanupFailure,- };+ return await finish(+ interruption === undefined+ ? {+ kind: "exited",+ exitCode: snapshot.exitCode ?? null,+ output: `${snapshot.stdout.text}${snapshot.stderr.text}`.slice(+ -DIAGNOSTIC_BYTES,+ ),+ }+ : { kind: interruption },+ );} catch (cause: unknown) {const interruption = deadline.interruption;- const stopped = await supervisor?.stop();- const cleanupFailure =- stopped?.status === "incomplete" ? stopped.reason : undefined;- return interruption === "timeout"- ? { kind: "timeout", targetIdentity, cleanupFailure }- : interruption === "cancelled"- ? { kind: "cancelled", targetIdentity, cleanupFailure }- : {+ return await finish(+ interruption === undefined+ ? {kind: "exited",exitCode: null,output: cause instanceof Error ? cause.message : String(cause),- targetIdentity,- cleanupFailure,- };+ }+ : { kind: interruption },+ );} finally {- supervisor?.dispose();+ if (!retained) supervisor?.dispose();deadline.dispose();}};@@ -724,8 +937,10 @@ const runLldb = async (*/const readTargetPid = async (pidPath: string): Promise<number | undefined> => {try {- const pid = Number.parseInt(await readFile(pidPath, "utf8"), 10);- return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;+ const contents = (await readFile(pidPath, "utf8")).trim();+ if (!/^[1-9]\d*$/u.test(contents)) return undefined;+ const pid = Number(contents);+ return Number.isSafeInteger(pid) ? pid : undefined;} catch {return undefined;}diff --git a/src/native/NativeCallObservation.test.ts b/src/native/NativeCallObservation.test.tsindex fcff10565..15b9b2604 100644--- a/src/native/NativeCallObservation.test.ts+++ b/src/native/NativeCallObservation.test.ts@@ -7,7 +7,7 @@ import { describe, expect, it } from "vitest";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";import type { AnalysisError } from "../domain/analysisErrorBase.js";import type { JsonValue } from "../domain/jsonValue.js";-import { err, type Result } from "../domain/result.js";+import { ok, type Result } from "../domain/result.js";import type { NativeCallTrace, NativeCallTracer } from "./LldbCallTracer.js";import { observeNativeCalls } from "./NativeCallObservation.js";import { nativeMachoTarget } from "../../tests/fixtures/nativeCommands.js";@@ -20,6 +20,10 @@ class NeverStartedTracer implements NativeCallTracer {this.calls += 1;throw new Error("tracer must not run after hash cancellation");}++ close(): Promise<Result<null, AnalysisError>> {+ return Promise.resolve(ok(null));+ }}describe("native call target digest cancellation", () => {diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.tsindex 0d25f969c..12c94814f 100644--- a/src/native/NativeMacOSProvider.ts+++ b/src/native/NativeMacOSProvider.ts@@ -82,6 +82,7 @@ import {export class NativeMacOSProvider implements AnalysisProvider {readonly #capabilities: readonly CapabilityDescriptor[];readonly #environment: NodeJS.ProcessEnv;+ readonly #tracerFactory: () => NativeCallTracer;constructor(environment: Readonly<NodeJS.ProcessEnv>,@@ -89,9 +90,11 @@ export class NativeMacOSProvider implements AnalysisProvider {environment,),platform: NodeJS.Platform = process.platform,- private readonly tracer: NativeCallTracer = new LldbCallTracer(environment),+ tracerFactory?: () => NativeCallTracer,) {this.#environment = snapshotEnvironment(environment, platform);+ this.#tracerFactory =+ tracerFactory ?? (() => new LldbCallTracer(this.#environment));this.#capabilities = nativeMacOSCapabilities(platform);}@@ -107,7 +110,7 @@ export class NativeMacOSProvider implements AnalysisProvider {return new NativeMacOSClient(target,this.runner,- this.tracer,+ this.#tracerFactory(),this.#environment,);}@@ -246,7 +249,7 @@ class NativeMacOSClient implements AnalysisClient {}close(): Promise<Result<null, AnalysisError>> {- return Promise.resolve(ok(null));+ return this.tracer.close();}#dispatch(diff --git a/src/native/NativeMacOSProviderInput.test.ts b/src/native/NativeMacOSProviderInput.test.tsindex df4131e69..a795bf76c 100644--- a/src/native/NativeMacOSProviderInput.test.ts+++ b/src/native/NativeMacOSProviderInput.test.ts@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";import { NativeMacOSProvider } from "./NativeMacOSProvider.js";import type { JsonValue } from "../domain/jsonValue.js";+import { ok } from "../domain/result.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import {NativeFixtureRunner,@@ -57,4 +58,33 @@ describe("native dispatch metadata input boundary", () => {});}});++ it("closes only the native call tracer owned by that client", async () => {+ const closes = [0, 0];+ let next = 0;+ const provider = new NativeMacOSProvider(+ {},+ new NativeFixtureRunner(),+ "darwin",+ () => {+ const index = next++;+ return {+ trace: async () => {+ throw new Error("trace is unused in this lifecycle test");+ },+ close: async () => {+ closes[index] = (closes[index] ?? 0) + 1;+ return ok(null);+ },+ };+ },+ );+ const first = provider.createClient(nativeMachoTarget("/first"));+ const second = provider.createClient(nativeMachoTarget("/second"));++ expect((await first.close()).ok).toBe(true);+ expect(closes).toEqual([1, 0]);+ expect((await second.close()).ok).toBe(true);+ expect(closes).toEqual([1, 1]);+ });});diff --git a/tests/boundary/mcp/nativeCallObservationMcp.test.ts b/tests/boundary/mcp/nativeCallObservationMcp.test.tsindex cecd3b2f4..52c26c282 100644--- a/tests/boundary/mcp/nativeCallObservationMcp.test.ts+++ b/tests/boundary/mcp/nativeCallObservationMcp.test.ts@@ -81,6 +81,7 @@ const tracer: NativeCallTracer & { calls: number } = {}),);},+ close: () => Promise.resolve(ok(null)),};it("routes observe_native_calls through MCP with schema-checked input and output", async () => {@@ -88,7 +89,12 @@ it("routes observe_native_calls through MCP with schema-checked input and outputconst path = join(directory, "Tool");await writeFile(path, machoHeader());const session = createTestBinarySession(- new NativeMacOSProvider({}, new NativeFixtureRunner(), "darwin", tracer),+ new NativeMacOSProvider(+ {},+ new NativeFixtureRunner(),+ "darwin",+ () => tracer,+ ),);const server = createServer({ kind: "session", session });const client = new Client({ name: "native-calls-mcp-test", version: "1" });@@ -138,6 +144,62 @@ it("routes observe_native_calls through MCP with schema-checked input and output}});+const partialObservationFor = (options: {+ readonly path: string;+ readonly sha256: string;+ readonly arguments: string[];+ readonly environment: Record<string, string>;+ readonly workingDirectory: string;+ readonly reason: "cancelled" | "cleanup-failure";+}) =>+ nativeCallPartialObservationSchema.parse({+ kind: "native-call-observation",+ target: {+ path: options.path,+ sha256: options.sha256,+ architecture: "arm64",+ arguments: options.arguments,+ environment: options.environment,+ working_directory: options.workingDirectory,+ },+ process: {+ pid: 4242,+ stdout: {+ text: "partial target output",+ bytes: 21,+ truncated: true,+ complete: false,+ },+ stderr: {+ text: "debugger diagnostic",+ bytes: 19,+ truncated: false,+ complete: false,+ },+ other_stops: ["signal SIGSTOP"],+ },+ debugger: { version: "lldb-fixture" },+ events: [+ {+ sequence: 0,+ elapsed_ms: 4,+ thread_id: 3,+ breakpoint_index: 0,+ load_address: "0x1000",+ file_address: "0x1000",+ module: "Tool",+ module_path: options.path,+ symbol: "open",+ receiver_class: null,+ selector: null,+ registers: [{ name: "x0", value: "0x2" }],+ backtrace: [],+ },+ ],+ coverage: { status: "partial", reason: options.reason },+ limitations: ["Observation ended before the requested window completed."],+ });+it.each([["cancelled", "cancelled", undefined],[@@ -161,57 +223,16 @@ it.each([const launchArguments = ["--fixture", "selected argument"];const launchEnvironment = { REA_NATIVE_FIXTURE: "selected value" };const workingDirectory = directory;- const partialObservation = nativeCallPartialObservationSchema.parse({- kind: "native-call-observation",- target: {- path,- sha256,- architecture: "arm64",- arguments: launchArguments,- environment: launchEnvironment,- working_directory: workingDirectory,- },- process: {- pid: 4242,- stdout: {- text: "partial target output",- bytes: 21,- truncated: true,- complete: false,- },- stderr: {- text: "debugger diagnostic",- bytes: 19,- truncated: false,- complete: false,- },- other_stops: ["signal SIGSTOP"],- },- debugger: { version: "lldb-fixture" },- events: [- {- sequence: 0,- elapsed_ms: 4,- thread_id: 3,- breakpoint_index: 0,- load_address: "0x1000",- file_address: "0x1000",- module: "Tool",- module_path: path,- symbol: "open",- receiver_class: null,- selector: null,- registers: [{ name: "x0", value: "0x2" }],- backtrace: [],- },- ],- coverage: {- status: "partial",- reason: cleanup === undefined ? "cancelled" : "cleanup-failure",- },- limitations: ["Observation ended before the requested window completed."],+ const partialObservation = partialObservationFor({+ path,+ sha256,+ arguments: launchArguments,+ environment: launchEnvironment,+ workingDirectory,+ reason: cleanup === undefined ? "cancelled" : "cleanup-failure",});const tracer: NativeCallTracer = {+ close: () => Promise.resolve(ok(null)),trace: () =>Promise.resolve(err(@@ -231,7 +252,12 @@ it.each([),};const session = createTestBinarySession(- new NativeMacOSProvider({}, new NativeFixtureRunner(), "darwin", tracer),+ new NativeMacOSProvider(+ {},+ new NativeFixtureRunner(),+ "darwin",+ () => tracer,+ ),);const server = createServer({ kind: "session", session });const client = new Client({diff --git a/tests/boundary/providers/native/LldbCallTracer.cleanup.test.ts b/tests/boundary/providers/native/LldbCallTracer.cleanup.test.tsnew file mode 100644index 000000000..b3e365d5c--- /dev/null+++ b/tests/boundary/providers/native/LldbCallTracer.cleanup.test.ts@@ -0,0 +1,250 @@+import { randomUUID } from "node:crypto";+import { spawn } from "node:child_process";+import { once } from "node:events";+import { access, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { expect, it } from "vitest";++import { AnalysisCancelledError } from "../../../../src/domain/analysisErrorCore.js";+import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js";+import { ok } from "../../../../src/domain/result.js";+import { cleanupOwnedProcessGroup } from "../../../../src/process/ProcessOwnership.js";+import { observeProcessStartIdentity } from "../../../../src/process/ProcessOwnershipObservation.js";+import {+ ProviderProcessSupervisor,+ spawnOwnedProviderProcess,+} from "../../../../src/process/ProviderProcess.js";+import type { NativeCallTracer } from "../../../../src/native/LldbCallTracer.js";+import { LldbCallTracer } from "../../../../src/native/LldbCallTracer.js";+import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js";+import {+ NativeFixtureRunner,+ nativeMachoTarget,+} from "../../../fixtures/nativeCommands.js";++const request: Parameters<NativeCallTracer["trace"]>[0] = {+ executable: "/fixture/target",+ architecture: "arm64",+ expectedSha256: "0".repeat(64),+ input: {+ breakpoints: [{ kind: "function", name: "main" }],+ arguments: [],+ environment: {},+ duration_ms: 100,+ max_events: 1,+ argument_registers: 0,+ backtrace_frames: 0,+ },+};+const tool = { path: process.execPath, sha256: "0".repeat(64) };++const createTracer = (+ launch?: ConstructorParameters<typeof LldbCallTracer>[1],+): LldbCallTracer =>+ new LldbCallTracer(process.env, launch, async () => ok(tool));++const createClient = (tracer: NativeCallTracer) =>+ new NativeMacOSProvider(+ {},+ new NativeFixtureRunner(),+ "darwin",+ () => tracer,+ ).createClient(nativeMachoTarget(request.executable));++const runtimeRoot = (error: ProviderCleanupError): string => {+ const root = error.cleanupResources.find((resource) =>+ resource.startsWith(`${tmpdir()}/rea-lldb-`),+ );+ if (root === undefined) throw new Error("Expected retained runtime root");+ return root;+};++const liveChild = async () => {+ const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {+ stdio: "ignore",+ });+ await once(child, "spawn");+ if (child.pid === undefined) throw new Error("Fixture process had no PID");+ return { child, pid: child.pid };+};++const stopChild = async (child: ReturnType<typeof spawn>) => {+ if (child.exitCode === null && child.signalCode === null) {+ const exited = once(child, "exit");+ child.kill("SIGKILL");+ await exited;+ }+};++it.skipIf(process.platform === "win32")(+ "retains a real LLDB process owner and runtime until a later cleanup retry succeeds",+ async () => {+ let cleanupFailures = 2;+ let ownedPid: number | undefined;+ const tracer = createTracer(async (_exe, _args, options) => {+ const target = spawn(process.execPath, ["-e", "process.exit(0)"], {+ stdio: "ignore",+ });+ await once(target, "exit");+ if (target.pid === undefined)+ throw new Error("Fixture target had no PID");+ await writeFile(options.pidPath, String(target.pid));+ const launched = await spawnOwnedProviderProcess({+ command: process.execPath,+ arguments: ["-e", "setInterval(() => {}, 1000)"],+ runId: randomUUID(),+ hostEnvironment: options.environment,+ });+ ownedPid = launched.process.pid;+ const supervisor = new ProviderProcessSupervisor({+ ...launched,+ ownsProcessLifetime: true,+ cleanup: async () => {+ if (cleanupFailures-- > 0)+ return {+ cleaned: false,+ reason: "fixture transient cleanup failure",+ };+ return cleanupOwnedProcessGroup(launched.ownership);+ },+ });+ const stopped = await supervisor.stop();+ return {+ kind: "exited" as const,+ targetLaunched: true,+ exitCode: null,+ output: "",+ targetIdentity: undefined,+ cleanupFailure:+ stopped.status === "incomplete" ? stopped.reason : undefined,+ ...(stopped.status === "incomplete"+ ? { cleanupOwner: supervisor }+ : {}),+ };+ });+ const client = createClient(tracer);++ try {+ const trace = await tracer.trace(request);+ expect(trace.ok).toBe(false);+ if (trace.ok) throw new Error("Expected incomplete cleanup");+ expect(trace.error).toBeInstanceOf(ProviderCleanupError);+ if (!(trace.error instanceof ProviderCleanupError)) return;+ expect(trace.error.cleanupResources).toContain("lldb-process-group");+ expect(trace.error.partialObservation).toBeDefined();+ const root = runtimeRoot(trace.error);+ await expect(access(root)).resolves.toBeUndefined();+ if (ownedPid === undefined) throw new Error("Expected owned process PID");+ const pid = ownedPid;+ expect(() => process.kill(pid, 0)).not.toThrow();+ expect((await client.close()).ok).toBe(false);+ expect(() => process.kill(pid, 0)).not.toThrow();+ await expect(access(root)).resolves.toBeUndefined();+ expect((await client.close()).ok).toBe(true);+ expect(() => process.kill(pid, 0)).toThrow();+ await expect(access(root)).rejects.toThrow();+ } finally {+ await client.close();+ }+ },+);++it.skipIf(process.platform === "win32")(+ "does not retain a target when cancellation proves LLDB never launched",+ async () => {+ const controller = new AbortController();+ const cancelledTracer = new LldbCallTracer(+ process.env,+ undefined,+ async () => {+ controller.abort();+ return ok(tool);+ },+ );+ const result = await cancelledTracer.trace(request, controller.signal);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected cancelled trace");+ expect(result.error).toBeInstanceOf(AnalysisCancelledError);+ expect((await cancelledTracer.close()).ok).toBe(true);+ },+);++it.skipIf(process.platform === "win32")(+ "retains an unidentified debuggee and runtime until exit can be confirmed",+ async () => {+ const { child, pid } = await liveChild();+ const tracer = createTracer(async (_exe, _args, options) => {+ await writeFile(options.pidPath, String(pid));+ return {+ kind: "exited",+ targetLaunched: true,+ exitCode: 0,+ output: "",+ targetIdentity: undefined,+ cleanupFailure: undefined,+ };+ });+ const client = createClient(tracer);++ try {+ const trace = await tracer.trace(request);+ expect(trace.ok).toBe(false);+ if (trace.ok) throw new Error("Expected unverified target cleanup");+ expect(trace.error).toBeInstanceOf(ProviderCleanupError);+ if (!(trace.error instanceof ProviderCleanupError)) return;+ expect(trace.error.cleanupResources).toContain(`native-target:${pid}`);+ const root = runtimeRoot(trace.error);+ await expect(access(root)).resolves.toBeUndefined();+ expect(() => process.kill(pid, 0)).not.toThrow();+ expect((await client.close()).ok).toBe(false);+ expect(() => process.kill(pid, 0)).not.toThrow();+ await expect(access(root)).resolves.toBeUndefined();+ await stopChild(child);+ expect((await client.close()).ok).toBe(true);+ await expect(access(root)).rejects.toThrow();+ } finally {+ await stopChild(child);+ await client.close();+ }+ },+);++it.skipIf(process.platform === "win32")(+ "rejects malformed PID authority and retries after the target exits",+ async () => {+ const { child, pid } = await liveChild();+ const identity = await observeProcessStartIdentity(pid);+ if (identity?.state !== "readable")+ throw new Error("Host could not read fixture process identity");+ const tracer = createTracer(async (_exe, _args, options) => {+ await writeFile(options.pidPath, `${pid}junk`);+ return {+ kind: "exited",+ targetLaunched: true,+ exitCode: 0,+ output: "",+ targetIdentity: identity.identity,+ cleanupFailure: undefined,+ };+ });+ const client = createClient(tracer);++ try {+ const trace = await tracer.trace(request);+ expect(trace.ok).toBe(false);+ if (trace.ok) throw new Error("Expected malformed PID cleanup failure");+ expect(trace.error).toBeInstanceOf(ProviderCleanupError);+ if (!(trace.error instanceof ProviderCleanupError)) return;+ expect(trace.error.cleanupResources).toContain("native-target:unknown");+ expect(() => process.kill(pid, 0)).not.toThrow();+ const root = runtimeRoot(trace.error);+ await stopChild(child);+ await writeFile(join(root, "pid"), String(pid));+ expect((await client.close()).ok).toBe(true);+ } finally {+ await stopChild(child);+ await client.close();+ }+ },+);diff --git a/tests/boundary/providers/native/lldbCallTracerFailures.test.ts b/tests/boundary/providers/native/lldbCallTracerFailures.test.tsindex 6f10e6b20..a8d65dedb 100644--- a/tests/boundary/providers/native/lldbCallTracerFailures.test.ts+++ b/tests/boundary/providers/native/lldbCallTracerFailures.test.ts@@ -12,6 +12,12 @@ import type { NativeCallTracer } from "../../../../src/native/LldbCallTracer.js"import { LldbCallTracer } from "../../../../src/native/LldbCallTracer.js";import { err, ok } from "../../../../src/domain/result.js";import { NativeCommandFailure } from "../../../../src/native/CommandRunner.js";+import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js";+import { createDeferred } from "../../../fixtures/binarySession.js";+import {+ NativeFixtureRunner,+ nativeMachoTarget,+} from "../../../fixtures/nativeCommands.js";const EVENT = {sequence: 0,@@ -83,11 +89,13 @@ const fixtureTracer = (return outcome === "cancelled"? {kind: "cancelled",+ targetLaunched: false,targetIdentity: undefined,cleanupFailure: undefined,}: {kind: "exited",+ targetLaunched: false,exitCode: 1,output: "bridge reported target integrity failure",targetIdentity: undefined,@@ -108,6 +116,56 @@ const fixtureTracer = (};describe("LLDB failure retention through the production tracer", () => {+ it("waits for an active trace before client close removes its runtime root", async () => {+ const launchGate = createDeferred<void>();+ const launchStarted = createDeferred<void>();+ const tracer = new LldbCallTracer(+ {},+ async (_executable, arguments_) => {+ const { config } = await configFromArguments(arguments_);+ await writeFile(+ config.observation_path,+ `${JSON.stringify({ kind: "event", event: EVENT })}\n`,+ );+ await writeFile(config.stdout_capture_path, "captured prefix");+ launchStarted.resolve();+ await launchGate.promise;+ return {+ kind: "exited",+ targetLaunched: false,+ exitCode: 0,+ output: "",+ targetIdentity: undefined,+ cleanupFailure: undefined,+ };+ },+ async () => ok(fakeTool),+ );+ const client = new NativeMacOSProvider(+ {},+ new NativeFixtureRunner(),+ "darwin",+ () => tracer,+ ).createClient(nativeMachoTarget(request.executable));+ const tracePromise = tracer.trace(request);+ await launchStarted.promise;+ let closeFinished = false;+ const closePromise = client.close().then((result) => {+ closeFinished = true;+ return result;+ });+ await Promise.resolve();+ expect(closeFinished).toBe(false);+ launchGate.resolve();+ const [trace, close] = await Promise.all([tracePromise, closePromise]);+ expect(close.ok).toBe(true);+ if (trace.ok) throw new Error("expected missing LLDB result");+ expect(trace.error.partialObservation).toMatchObject({+ events: [EVENT],+ process: { stdout: { text: "captured prefix", complete: false } },+ });+ });+it("names the missing LLDB requirement instead of asking for another target", async () => {const tracer = new LldbCallTracer({},diff --git a/tests/boundary/providers/native/nativeCallObservation.test.ts b/tests/boundary/providers/native/nativeCallObservation.test.tsindex 0ae599748..c915da0d9 100644--- a/tests/boundary/providers/native/nativeCallObservation.test.ts+++ b/tests/boundary/providers/native/nativeCallObservation.test.ts@@ -108,6 +108,10 @@ class FixtureTracer implements NativeCallTracer {this.requests.push(request);return Promise.resolve(this.outcome);}++ close() {+ return Promise.resolve(ok(null));+ }}const BREAKPOINTS = [@@ -131,7 +135,7 @@ const observe = async (target?: Awaited<ReturnType<typeof fixtureTarget>>,signal?: AbortSignal,) =>- new NativeMacOSProvider({}, new NativeFixtureRunner(), "darwin", tracer)+ new NativeMacOSProvider({}, new NativeFixtureRunner(), "darwin", () => tracer).createClient(target ?? (await fixtureTarget())).execute("observe_native_calls",@@ -421,7 +425,7 @@ describe("observe_native_calls failures", () => {{},new NativeFixtureRunner(),"darwin",- tracer,+ () => tracer,).createClient({path: target.path,