From 95dfbae68e31a01901deab358db572c472866bcf Mon Sep 17 00:00:00 2001 From: Clark <301422770+clark970417-eng@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:17:41 +0800 Subject: [PATCH] fix(process): record PTY session-leader SIGHUP limitation in Evidence --- .../capture/ProcessCaptureLifecycle.ts | 5 ++ .../capture/ProcessCaptureObservation.test.ts | 46 ++++++++++++++ .../boundary/process/ProcessEvidence.test.ts | 60 +++++++++++++++++++ 3 files changed, 111 insertions(+) diff --git a/src/process/capture/ProcessCaptureLifecycle.ts b/src/process/capture/ProcessCaptureLifecycle.ts index d4f7956115..7cc7703880 100644 --- a/src/process/capture/ProcessCaptureLifecycle.ts +++ b/src/process/capture/ProcessCaptureLifecycle.ts @@ -392,6 +392,11 @@ export const buildCaptureResult = ( ] : []), "Process trees are sampled and may omit short-lived descendants.", + ...(options.manifest.platform !== "win32" + ? [ + "The target runs as the capture PTY session leader; still-running children in its foreground process group receive terminal SIGHUP when it exits unless they leave the group or ignore SIGHUP.", + ] + : []), ...(options.samplingPartial ? ["Process-tree sampling ended with an incomplete observation."] : []), diff --git a/src/process/capture/ProcessCaptureObservation.test.ts b/src/process/capture/ProcessCaptureObservation.test.ts index 43aa49000a..d413dd00ac 100644 --- a/src/process/capture/ProcessCaptureObservation.test.ts +++ b/src/process/capture/ProcessCaptureObservation.test.ts @@ -329,3 +329,49 @@ it.each(["symlink_not_followed", "observer_owned"] as const)( expect(result.truncated).toBe(false); }, ); + +it("records the PTY session-leader SIGHUP limitation on POSIX captures only", () => { + const capture = emptyCapture(); + const buildForPlatform = (platform: string) => + buildCaptureResult({ + frames: [], + exit: { exitCode: 0, reason: "exited" }, + samples: [], + before: { + files: [], + truncated: false, + completeRoots: [], + coverage: emptyFilesystemCoverage(), + }, + after: { + files: [], + truncated: false, + completeRoots: [], + coverage: emptyFilesystemCoverage(), + }, + truncationDetails: truncationDetails([], [], []), + scenario: processScenarioSchema.parse(base), + rootPid: 1, + samplingPartial: false, + renderedFrames: [], + interactions: [], + checkpoints: capture.filesystem_checkpoints, + settlement: { + state: capture.settlement.state, + elapsed_ms: capture.settlement.elapsed_ms, + }, + manifest: { ...capture.manifest, platform }, + eventJournal: [], + }); + + for (const posixPlatform of ["linux", "darwin"]) { + expect(buildForPlatform(posixPlatform).limitations).toContain( + "The target runs as the capture PTY session leader; still-running children in its foreground process group receive terminal SIGHUP when it exits unless they leave the group or ignore SIGHUP.", + ); + } + expect( + buildForPlatform("win32").limitations.some((line) => + line.includes("SIGHUP"), + ), + ).toBe(false); +}); diff --git a/tests/boundary/process/ProcessEvidence.test.ts b/tests/boundary/process/ProcessEvidence.test.ts index 6923af9dc0..3db71a4bee 100644 --- a/tests/boundary/process/ProcessEvidence.test.ts +++ b/tests/boundary/process/ProcessEvidence.test.ts @@ -5,6 +5,7 @@ import { createProcessScenarioPlanEvidence, } from "../../../src/application/process/ProcessEvidence.js"; import { + buildCaptureResult, createRunManifest, observeLaunchedExecutable, observeSelectedExecutable, @@ -173,3 +174,62 @@ it("preserves selected local environment and input values", async () => { terminal: "changed", }); }); + +it("projects the PTY session-leader SIGHUP limitation onto process capture Evidence", () => { + const scenario = processScenarioSchema.parse({ + executable: "/bin/echo", + working_directory: "/tmp", + }); + const base = emptyUnverifiedProcessCapture(); + const executableSha256 = "0".repeat(64); + const scenarioProjection = processScenarioCommitment( + scenario, + executableSha256, + ); + const comparisonContract = processComparisonContract(scenario); + const manifest = { + ...base.manifest, + platform: "darwin", + scenario: scenarioProjection, + comparison_contract: comparisonContract, + full_scenario_sha256: digestProcessCommitment(scenarioProjection), + comparison_contract_sha256: digestProcessCommitment(comparisonContract), + executable_sha256: executableSha256, + normalization_sha256: digestProcessCommitment(scenario.normalization), + }; + const emptySnapshot = { + files: [], + truncated: false, + completeRoots: [], + coverage: base.truncation_details.filesystem_before, + }; + const pending = buildCaptureResult({ + frames: [], + exit: { exitCode: 0, reason: "exited" }, + samples: [], + before: emptySnapshot, + after: emptySnapshot, + truncationDetails: base.truncation_details, + scenario, + rootPid: 1, + samplingPartial: false, + renderedFrames: [], + interactions: [], + checkpoints: base.filesystem_checkpoints, + settlement: { + state: base.settlement.state, + elapsed_ms: base.settlement.elapsed_ms, + }, + manifest, + eventJournal: [], + }); + const capture = parseProcessCapture({ + ...pending, + settlement: base.settlement, + cleanup: base.cleanup, + }); + const evidence = createProcessCaptureEvidence(scenario, capture); + expect(evidence.limitations).toContain( + "The target runs as the capture PTY session leader; still-running children in its foreground process group receive terminal SIGHUP when it exits unless they leave the group or ignore SIGHUP.", + ); +});