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(process): record no normal exit code for signal-terminated targets (#6486)
Muhammad Hamza4cfc61147b3f
diff --git a/docs/process-capture.md b/docs/process-capture.mdindex 7e7fd48ca..92a830358 100644--- a/docs/process-capture.md+++ b/docs/process-capture.md@@ -335,6 +335,10 @@ validation is recorded as `unverified` with its reason. Cancellation before anydeadline keeps the existing terminal kill. Descendants are not signalled duringfinalization; owned-process cleanup handles them afterwards.+For an `exited` capture, `exit.code` is the target's normal exit code. It is+`null` when the target ended on a signal, such as one sent by a scenario+`signal` event, and the observed signal stays in `exit.signal`.+`exit.reason` keeps the initiating deadline (`timeout` or `idle_timeout`).`exit.code` is `null` for every deadline exit; the code of an exit observedduring finalization is `exit.finalization.exit_code`, and the observed signaldiff --git a/src/process/capture/ProcessCaptureLifecycle.ts b/src/process/capture/ProcessCaptureLifecycle.tsindex a2b8e64a8..22134e960 100644--- a/src/process/capture/ProcessCaptureLifecycle.ts+++ b/src/process/capture/ProcessCaptureLifecycle.ts@@ -124,6 +124,33 @@ export type TerminalExitResult =readonly finalization: ProcessCaptureFinalization;};+/**+ * The target's normal exit code. A signal-terminated process has none, so a+ * nonzero signal yields null even when the PTY reports a numeric code.+ */+const normalExitCode = (exit: {+ readonly exitCode: number;+ readonly signal?: number;+}): number | null =>+ exit.exitCode >= 0 && (exit.signal ?? 0) === 0 ? exit.exitCode : null;++/** Project an observed exit; only an `exited` reason carries a normal code. */+export const captureExitObservation = <+ Reason extends TerminalExitResult["reason"],+>(exit: {+ readonly exitCode: number;+ readonly signal?: number;+ readonly reason: Reason;+ readonly finalization?: ProcessCaptureFinalization;+}) => ({+ code: exit.reason === "exited" ? normalExitCode(exit) : null,+ signal: exit.signal ?? null,+ reason: exit.reason,+ ...(exit.finalization === undefined+ ? {}+ : { finalization: exit.finalization }),+});+interface CaptureResultOptions {readonly frames: readonly TerminalFrame[];readonly exit: {@@ -330,17 +357,7 @@ export const buildCaptureResult = (frames: options.frames,rendered_frames: options.renderedFrames,interaction_events: options.interactions,- exit: {- code:- options.exit.reason === "exited" && options.exit.exitCode >= 0- ? options.exit.exitCode- : null,- signal: options.exit.signal ?? null,- reason: options.exit.reason,- ...(options.exit.finalization === undefined- ? {}- : { finalization: options.exit.finalization }),- },+ exit: captureExitObservation(options.exit),settlement: options.settlement,process_samples: normalizeProcessSamples(options.samples,@@ -985,9 +1002,7 @@ export const awaitTerminalExit = async ({: {finalization: snapshot(finalizationElapsedMs,- exit.exitCode >= 0 && (exit.signal ?? 0) === 0- ? exit.exitCode- : null,+ normalExitCode(exit),),}),});diff --git a/src/process/capture/ProcessHarness.ts b/src/process/capture/ProcessHarness.tsindex 1580a1cb7..67e47eaea 100644--- a/src/process/capture/ProcessHarness.ts+++ b/src/process/capture/ProcessHarness.ts@@ -53,6 +53,7 @@ import {type ProcessCaptureResourceCleanupOptions,ProcessCaptureResourceScope,type TerminalCaptureRetention,+ captureExitObservation,} from "./ProcessCaptureLifecycle.js";import {assertNotCancelled,@@ -801,15 +802,7 @@ const runProcessScenario = async (};observations.exit = {state: "available",- value: {- code:- exit.reason === "exited" && exit.exitCode >= 0 ? exit.exitCode : null,- signal: exit.signal ?? null,- reason: exit.reason,- ...(exit.finalization === undefined- ? {}- : { finalization: exit.finalization }),- },+ value: captureExitObservation(exit),};capture = await completeCapture({scenario,diff --git a/tests/acceptance/process/processSignalExit.test.ts b/tests/acceptance/process/processSignalExit.test.tsnew file mode 100644index 000000000..8a4b24c2c--- /dev/null+++ b/tests/acceptance/process/processSignalExit.test.ts@@ -0,0 +1,94 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect } from "vitest";++import { toolContract } from "../../../src/contracts/toolContracts.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { parseProcessCapture } from "../../../src/domain/process/processCaptureParsing.js";+import { runCliJson } from "../../fixtures/cliJsonProcess.js";+import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { itWithCaptureCapability as captureTest } from "../../boundary/process/processCaptureCapability.js";++const hang = ["-e", "setTimeout(() => {}, 5000)"];++captureTest(+ "records no normal exit code for a target a scenario signal terminated",+ async () => {+ const root = await createTestTempDirectory("rea-process-signal-exit-");+ for (const [name, additions, expected] of [+ [+ "SIGKILL",+ { events: [{ type: "signal", at_ms: 200, signal: "SIGKILL" }] },+ { code: null, signal: 9, reason: "exited" },+ ],+ [+ "SIGTERM",+ { events: [{ type: "signal", at_ms: 200, signal: "SIGTERM" }] },+ { code: null, signal: 15, reason: "exited" },+ ],+ [+ "exit 3",+ { arguments: ["-e", "process.exit(3)"] },+ { code: 3, signal: 0, reason: "exited" },+ ],+ [+ "exit 0",+ { arguments: ["-e", "process.exit(0)"] },+ { code: 0, signal: 0, reason: "exited" },+ ],+ ["deadline", { timeout_ms: 300 }, { code: null, reason: "timeout" }],+ ] as const) {+ const scenarioPath = join(root, `${name.replace(" ", "-")}.json`);+ await writeFile(+ scenarioPath,+ JSON.stringify({+ executable: process.execPath,+ arguments: hang,+ timeout_ms: 5_000,+ settle_ms: 300,+ ...additions,+ }),+ );+ const document = await runCliJson([+ "capture-process",+ scenarioPath,+ "--format",+ "json",+ ]);+ const capture = parseProcessCapture(+ parseEvidence(document).normalized_result,+ );+ expect(capture.exit, name).toMatchObject(expected);+ }+ },+ 60_000,+);++captureTest(+ "records no normal exit code for a signal-terminated target through MCP",+ async () => {+ const { call } = await connectLocalToolsMcp();+ const response = await call("capture_process_scenario", {+ executable: process.execPath,+ arguments: hang,+ timeout_ms: 5_000,+ settle_ms: 300,+ events: [{ type: "signal", at_ms: 200, signal: "SIGKILL" }],+ });+ expect(response.isError).not.toBe(true);+ const capture = parseProcessCapture(+ parseEvidence(+ toolContract("capture_process_scenario").outputSchema.parse(+ response.structuredContent,+ ),+ ).normalized_result,+ );+ expect(capture.exit).toMatchObject({+ code: null,+ signal: 9,+ reason: "exited",+ });+ },+ 30_000,+);diff --git a/tests/boundary/process/processCaptureLifecycle.test.ts b/tests/boundary/process/processCaptureLifecycle.test.tsindex efad455e8..68694d876 100644--- a/tests/boundary/process/processCaptureLifecycle.test.ts+++ b/tests/boundary/process/processCaptureLifecycle.test.ts@@ -1179,7 +1179,11 @@ itWithCaptureCapability(expect(capture.interaction_events).toMatchObject([{ type: "signal", data: "SIGTERM", outcome: "dispatched" },]);- expect(capture.exit).toMatchObject({ signal: 15, reason: "exited" });+ expect(capture.exit).toMatchObject({+ code: null,+ signal: 15,+ reason: "exited",+ });},);