fix(process): preserve partial evidence and verify detached cleanup (#1011)

* test(ci): allow transport delivery in source identity regression

* fix(process): preserve partial evidence and verify detached cleanup

* fix(process): scope Linux token sweeps by stable process identity

* fix(process): retain environment permission failure codes

* fix(process): wait for signaled processes before verifying cleanup

* fix(process): verify sampled detached groups during cleanup

* fix(electron): preserve prelaunch identities through cleanup

* fix(process): retry growing Darwin process table snapshots

* fix(process): retain compatibility with saved v3 capture evidence

* fix(process): migrate saved v3 captures during reconstruction verification

* fix(process): preserve cancellation during Darwin helper compilation

* fix(process): propagate cancellation through ownership baselines

* perf(javascript): cache canonical export comparison sort keys

* fix(process): cancel provider ownership preparation before spawn

* fix(process): isolate native compiler waiter cancellation
This commit is contained in:
morluto
2026-10-08 04:46:46 +08:00
committed by GitHub
parent 63ba7424c0
commit 63cf28fd8f
51 changed files with 5506 additions and 316 deletions
@@ -1,4 +1,5 @@
import { tmpdir } from "node:os";
import { prepareProcessOwnershipInspection } from "../ProcessOwnershipObservation.js";
export type ProcessCaptureCapability =
| { readonly available: true; readonly backend: "node-pty" }
@@ -20,6 +21,7 @@ export const processCaptureOwnershipUnavailableReason = (
export interface ProcessCaptureProbeOptions {
readonly platform?: NodeJS.Platform;
readonly loadPty?: () => Promise<typeof import("@lydell/node-pty")>;
readonly prepareOwnershipInspector?: () => Promise<void>;
}
/** Probe the native PTY seam and explain loader failures at their source. */
@@ -56,6 +58,22 @@ export const probeProcessCaptureCapability = async (
backend: "node-pty",
reason: ownershipReason,
};
if (platform === "darwin") {
try {
await (
options.prepareOwnershipInspector ?? prepareProcessOwnershipInspection
)();
} catch (cause: unknown) {
return {
available: false,
backend: "node-pty",
reason:
cause instanceof Error
? cause.message
: "macOS process ownership inspection could not be prepared",
};
}
}
try {
const { spawn } = await (
options.loadPty ?? (() => import("@lydell/node-pty"))
@@ -1,10 +1,17 @@
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import type {
PartialProcessCaptureObservation,
ProcessCaptureCleanupReport,
} from "../../domain/process/processCapture.js";
interface ProcessCaptureErrorOptions extends ErrorOptions {
readonly userMessage?: string;
readonly userCategory?: "cancelled";
readonly reason?: "capture_failed" | "cleanup_incomplete" | "cancelled";
readonly cleanupResources?: readonly string[];
readonly executionFailure?: string;
readonly partialObservation?: PartialProcessCaptureObservation;
readonly cleanupReport?: ProcessCaptureCleanupReport;
}
/** Typed application failure produced by controlled process capture. */
@@ -16,6 +23,11 @@ export class ProcessCaptureError extends AnalysisError {
readonly reason: NonNullable<ProcessCaptureErrorOptions["reason"]>;
override readonly cleanupIncomplete: boolean;
override readonly cleanupResources: readonly string[];
override readonly executionFailure: string | undefined;
override readonly partialObservation:
| PartialProcessCaptureObservation
| undefined;
override readonly cleanupReport: ProcessCaptureCleanupReport | undefined;
constructor(message: string, options?: ProcessCaptureErrorOptions) {
super(message, options);
@@ -26,9 +38,22 @@ export class ProcessCaptureError extends AnalysisError {
(options?.userCategory === "cancelled" ? "cancelled" : "capture_failed");
this.cleanupIncomplete = this.reason === "cleanup_incomplete";
this.cleanupResources = options?.cleanupResources ?? [];
this.executionFailure = options?.executionFailure;
this.partialObservation = options?.partialObservation;
this.cleanupReport = options?.cleanupReport;
}
}
/** Return one non-recursive, domain-neutral summary of an execution failure. */
export const describeProcessCaptureExecutionFailure = (
failure: unknown,
): string | undefined => {
if (failure instanceof Error) return failure.message || failure.name;
if (typeof failure === "string") return failure;
if (failure === undefined) return undefined;
return "Process capture failed with a non-error rejection.";
};
/** Caller-visible cancellation without exposing capture implementation state. */
export const processCaptureCancelled = (): ProcessCaptureError =>
new ProcessCaptureError("process capture was cancelled", {
+503 -35
View File
@@ -1,6 +1,6 @@
import { createHash, randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
import { mkdtemp, rm } from "node:fs/promises";
import { constants, statSync, type BigIntStats } from "node:fs";
import { open, mkdtemp, rm, stat } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { IPty } from "@lydell/node-pty";
@@ -12,6 +12,11 @@ import type {
UnverifiedProcessCapture,
ProcessSample,
ProcessSettlement,
ProcessCaptureCleanupReport,
PartialProcessCaptureObservation,
IncompleteProcessCaptureObservations,
PartialFilesystemSnapshot,
PartialProcessObservationField,
ProcessScenario,
ProcessCaptureEventJournalEntry,
RecordProcessCaptureEvent,
@@ -19,6 +24,8 @@ import type {
} from "../../domain/process/processCapture.js";
import {
digestProcessCommitment,
parseProcessCapture,
partialProcessCaptureObservationSchema,
processComparisonContract,
processScenarioCommitment,
} from "../../domain/process/processCapture.js";
@@ -26,9 +33,21 @@ import { PRODUCT_IDENTITY } from "../../identity.js";
import type { SnapshotResult } from "./FilesystemSnapshot.js";
import { snapshotRoots } from "./FilesystemSnapshot.js";
import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
import { cleanupOwnedProcessGroup } from "../ProcessOwnership.js";
import { observeOwnedProcessGroup } from "../ProcessOwnershipObservation.js";
import { ProcessCaptureError } from "./ProcessCaptureError.js";
import {
cleanupOwnedProcessGroup,
verifyNoTokenOwnedProcesses,
type ProcessCleanupResult,
type ProcessOwnershipBaseline,
} from "../ProcessOwnership.js";
import {
observeOwnedProcessGroup,
prepareProcessOwnershipInspection,
systemProcessOwnershipHost,
} from "../ProcessOwnershipObservation.js";
import {
describeProcessCaptureExecutionFailure,
ProcessCaptureError,
} from "./ProcessCaptureError.js";
import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
import {
normalizeProcessElapsedTime,
@@ -92,6 +111,107 @@ export type PendingProcessCapture = Omit<
readonly settlement: ObservedProcessSettlement;
};
/** Mutable collection of facts available if completion stops before a capture exists. */
export interface ProcessCaptureObservationBuffer {
target_pid: PartialProcessObservationField<number>;
frames: PartialProcessObservationField<readonly TerminalFrame[]>;
rendered_frames: PartialProcessObservationField<
UnverifiedProcessCapture["rendered_frames"]
>;
interaction_events: PartialProcessObservationField<
UnverifiedProcessCapture["interaction_events"]
>;
exit: IncompleteProcessCaptureObservations["exit"];
settlement: IncompleteProcessCaptureObservations["settlement"];
process_samples: PartialProcessObservationField<readonly ProcessSample[]>;
filesystem_snapshots: {
before: PartialProcessObservationField<PartialFilesystemSnapshot>;
after: PartialProcessObservationField<PartialFilesystemSnapshot>;
};
event_journal: PartialProcessObservationField<
readonly ProcessCaptureEventJournalEntry[]
>;
manifest: IncompleteProcessCaptureObservations["manifest"];
}
/** Seed explicit observation availability before capture completion begins. */
export const createProcessCaptureObservationBuffer = (options: {
readonly frames: readonly TerminalFrame[];
readonly interactions: readonly InteractionEvent[];
readonly samples: readonly ProcessSample[];
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
readonly before: SnapshotResult;
}): ProcessCaptureObservationBuffer => ({
target_pid: {
state: "unavailable",
reason: "No PTY process was spawned before the run failed.",
},
frames: { state: "available", value: options.frames },
rendered_frames: {
state: "unavailable",
reason:
"Rendered terminal frames were not collected before capture completion finished.",
},
interaction_events: { state: "available", value: options.interactions },
exit: {
state: "unavailable",
reason: "Terminal exit was not observed before the run failed.",
},
settlement: {
state: "unavailable",
reason:
"Process settlement was not observed before capture completion finished.",
},
process_samples: { state: "available", value: options.samples },
filesystem_snapshots: {
before: {
state: "available",
value: {
files: options.before.files,
truncated: options.before.truncated,
},
},
after: {
state: "unavailable",
reason:
"Final filesystem snapshot was not collected before capture completion finished.",
},
},
event_journal: { state: "available", value: options.eventJournal },
manifest: {
state: "unavailable",
reason:
"Capture manifest was not produced before capture completion finished.",
},
});
const normalizePartialProcessObservations = (
observations: IncompleteProcessCaptureObservations,
context: { readonly scenario: ProcessScenario; readonly rootPid?: number },
): IncompleteProcessCaptureObservations => {
const targetPid = observations.target_pid;
const target_pid =
targetPid.state === "available" && context.rootPid !== undefined
? {
state: "available" as const,
value: context.scenario.normalization.pids ? 1 : context.rootPid,
}
: targetPid;
const samples = observations.process_samples;
const process_samples =
samples.state === "available" && context.rootPid !== undefined
? {
state: "available" as const,
value: normalizeProcessSamples(
samples.value,
context.scenario,
context.rootPid,
),
}
: samples;
return { ...observations, target_pid, process_samples };
};
/** Wait for trailing PTY callbacks before the capture becomes immutable. */
export const settleProcessCaptureJournal = async (
journal: readonly ProcessCaptureEventJournalEntry[],
@@ -152,6 +272,7 @@ export const buildCaptureResult = (
),
truncated: options.truncated,
limitations: [
"The executable digest is a prelaunch file sample; matching path metadata immediately after spawn does not prove an atomic operating-system image binding.",
"Process trees are sampled and may omit short-lived descendants.",
...(options.samplingPartial
? ["Process-tree sampling ended with an incomplete observation."]
@@ -167,6 +288,11 @@ export const buildCaptureResult = (
reason:
"Process trees are sampled and may omit short-lived descendants.",
},
{
scope: "process",
reason:
"The executable digest is a prelaunch file sample; operating-system image binding is not atomically observed.",
},
{
scope: "environment",
reason: "Inherited host environment variables are not recorded.",
@@ -190,16 +316,163 @@ export const buildCaptureResult = (
};
};
const hashFile = async (path: string): Promise<string> => {
const hash = createHash("sha256");
for await (const chunk of createReadStream(path)) hash.update(chunk);
return hash.digest("hex");
interface ExecutableFileIdentity {
readonly dev: bigint;
readonly ino: bigint;
readonly mode: bigint;
readonly size: bigint;
readonly mtimeNs: bigint;
readonly ctimeNs: bigint;
}
export interface SelectedExecutableObservation {
readonly sha256: string | null;
readonly identity: ExecutableFileIdentity | null;
readonly reason: string | null;
}
export interface LaunchedExecutableObservation {
readonly selectedSha256: string | null;
readonly sha256: string | null;
readonly state: "path_metadata_unchanged" | "unknown";
readonly reason: string | null;
}
const identityFromStats = (stats: BigIntStats): ExecutableFileIdentity => ({
dev: stats.dev,
ino: stats.ino,
mode: stats.mode,
size: stats.size,
mtimeNs: stats.mtimeNs,
ctimeNs: stats.ctimeNs,
});
const sameExecutableIdentity = (
left: ExecutableFileIdentity,
right: ExecutableFileIdentity,
): boolean =>
left.dev === right.dev &&
left.ino === right.ino &&
left.mode === right.mode &&
left.size === right.size &&
left.mtimeNs === right.mtimeNs &&
left.ctimeNs === right.ctimeNs;
const filesystemFailure = (cause: unknown): string | undefined => {
if (!(cause instanceof Error) || !("code" in cause) || !("syscall" in cause))
return undefined;
return `Executable file observation failed: ${cause.message}`;
};
/** Sample the caller-selected executable contents and stable file identity before launch. */
export const observeSelectedExecutable = async (
path: string,
signal?: AbortSignal,
): Promise<SelectedExecutableObservation> => {
assertNotCancelled(signal);
let handle: Awaited<ReturnType<typeof open>> | undefined;
try {
handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
const openedStats = await handle.stat({ bigint: true });
if (!openedStats.isFile())
return {
sha256: null,
identity: null,
reason: "Selected executable is not a regular file.",
};
const openedIdentity = identityFromStats(openedStats);
const selectedPathIdentity = identityFromStats(
await stat(path, { bigint: true }),
);
if (!sameExecutableIdentity(openedIdentity, selectedPathIdentity))
return {
sha256: null,
identity: null,
reason: "Selected executable path changed while it was being opened.",
};
const hash = createHash("sha256");
for await (const chunk of handle.createReadStream({
autoClose: false,
signal,
})) {
assertNotCancelled(signal);
hash.update(chunk);
}
assertNotCancelled(signal);
const finalIdentity = identityFromStats(
await handle.stat({ bigint: true }),
);
if (!sameExecutableIdentity(openedIdentity, finalIdentity))
return {
sha256: null,
identity: null,
reason: "Selected executable changed while its contents were sampled.",
};
return {
sha256: hash.digest("hex"),
identity: openedIdentity,
reason: null,
};
} catch (cause: unknown) {
assertNotCancelled(signal);
const reason = filesystemFailure(cause);
if (reason !== undefined) return { sha256: null, identity: null, reason };
throw cause;
} finally {
await handle?.close();
}
};
/** Compare the selected file metadata with the path immediately after PTY spawn. */
export const observeLaunchedExecutable = (
path: string,
selected: SelectedExecutableObservation,
): LaunchedExecutableObservation => {
if (selected.identity === null || selected.sha256 === null)
return {
selectedSha256: selected.sha256,
sha256: null,
state: "unknown",
reason: selected.reason ?? "Selected executable identity is unavailable.",
};
try {
const currentStats = statSync(path, { bigint: true });
const currentIdentity = identityFromStats(currentStats);
if (
currentStats.isFile() &&
sameExecutableIdentity(selected.identity, currentIdentity)
)
return {
selectedSha256: selected.sha256,
sha256: selected.sha256,
state: "path_metadata_unchanged",
reason: null,
};
return {
selectedSha256: selected.sha256,
sha256: null,
state: "unknown",
reason: "Executable path metadata changed between sampling and spawn.",
};
} catch (cause: unknown) {
const reason = filesystemFailure(cause);
if (reason !== undefined)
return {
selectedSha256: selected.sha256,
sha256: null,
state: "unknown",
reason,
};
throw cause;
}
};
export const createRunManifest = async (
scenario: ProcessScenario,
startedAt: Date,
completedAt: Date,
executable: LaunchedExecutableObservation,
host: {
readonly platform: NodeJS.Platform;
readonly architecture: NodeJS.Architecture;
@@ -208,10 +481,9 @@ export const createRunManifest = async (
architecture: process.arch,
},
): Promise<UnverifiedProcessCapture["manifest"]> => {
const executableSha256 = await hashFile(scenario.executable);
const scenarioCommitment = processScenarioCommitment(
scenario,
executableSha256,
executable.selectedSha256 ?? undefined,
);
const comparisonContract = processComparisonContract(scenario);
return {
@@ -226,7 +498,12 @@ export const createRunManifest = async (
comparison_contract: comparisonContract,
full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
comparison_contract_sha256: digestProcessCommitment(comparisonContract),
executable_sha256: executableSha256,
selected_executable_sha256: executable.selectedSha256,
executable_sha256: executable.sha256,
executable_identity: {
state: executable.state,
reason: executable.reason,
},
normalization_sha256: digestProcessCommitment(scenario.normalization),
};
};
@@ -339,50 +616,142 @@ export const awaitTerminalExit = async ({
export interface ProcessCaptureCleanupHost {
readonly platform: NodeJS.Platform;
readonly cleanupProcessGroup: typeof cleanupOwnedProcessGroup;
readonly verifyTokenOwnedProcesses: typeof verifyNoTokenOwnedProcesses;
readonly removeTemporaryRoot: (path: string) => Promise<void>;
}
const processCaptureCleanupHost: ProcessCaptureCleanupHost = {
platform: process.platform,
cleanupProcessGroup: cleanupOwnedProcessGroup,
verifyTokenOwnedProcesses: verifyNoTokenOwnedProcesses,
removeTemporaryRoot: (path) => rm(path, { recursive: true, force: true }),
};
const PROCESS_CLEANUP_VERIFICATION_GRACE_MS = 1_000;
const PROCESS_CLEANUP_VERIFICATION_INTERVAL_MS = 25;
const verifyTokenOwnedProcessesUntilSettled = async (
verify: () => Promise<ProcessCleanupResult>,
): Promise<ProcessCleanupResult> => {
const deadline = Date.now() + PROCESS_CLEANUP_VERIFICATION_GRACE_MS;
let result = await verify();
while (!result.cleaned) {
const remaining = deadline - Date.now();
if (remaining <= 0) return result;
await new Promise<void>((resolve) =>
setTimeout(
resolve,
Math.min(PROCESS_CLEANUP_VERIFICATION_INTERVAL_MS, remaining),
),
);
result = await verify();
}
return result;
};
export const releaseProcessResources = async (options: {
readonly timers: ReadonlySet<ProcessTimer>;
readonly terminal: IPty | undefined;
readonly terminal: Pick<IPty, "pid"> | undefined;
readonly renderer: TerminalRenderer | undefined;
readonly runId: string;
readonly temporaryRoot: string;
readonly capturedProcessGroupIds: readonly number[];
readonly captureBaseline?: ProcessOwnershipBaseline;
readonly sampledProcessGroupIds?: readonly number[];
readonly host?: ProcessCaptureCleanupHost;
}): Promise<string | undefined> => {
}): Promise<ProcessCaptureCleanupReport> => {
const host = options.host ?? processCaptureCleanupHost;
for (const timer of options.timers) timer.cancel();
let failure: string | undefined;
let terminalRenderer: ProcessCaptureCleanupReport["terminal_renderer"] = {
state: options.renderer === undefined ? "not_required" : "cleaned",
reason: null,
};
try {
await options.renderer?.dispose();
} catch (cause: unknown) {
void cause;
failure ??= "terminal renderer cleanup failed";
terminalRenderer = {
state: "failed",
reason:
cause instanceof Error
? cause.message || cause.name || "renderer dispose failed"
: "renderer dispose failed",
};
}
if (options.terminal !== undefined && host.platform !== "win32") {
for (const processGroupId of new Set(options.capturedProcessGroupIds)) {
let ownedProcessGroup: ProcessCaptureCleanupReport["owned_process_group"] = {
state: options.terminal === undefined ? "not_required" : "cleaned",
reason: null,
};
if (options.terminal !== undefined) {
if (host.platform === "win32") {
ownedProcessGroup = {
state: "unverified",
reason:
"owned process cleanup is unverifiable on Windows without process-job authority",
};
} else {
const cleaned = await host.cleanupProcessGroup({
runId: options.runId,
leaderPid: processGroupId,
processGroupId,
leaderPid: options.terminal.pid,
processGroupId: options.terminal.pid,
sweepTokenOwnedProcesses: true,
...(options.sampledProcessGroupIds === undefined
? {}
: { sampledProcessGroupIds: options.sampledProcessGroupIds }),
...(options.captureBaseline === undefined
? {}
: { captureBaseline: options.captureBaseline }),
});
if (!cleaned.cleaned) failure ??= cleaned.reason;
if (!cleaned.cleaned) {
ownedProcessGroup = { state: "unverified", reason: cleaned.reason };
} else {
const verified = await verifyTokenOwnedProcessesUntilSettled(() =>
host.verifyTokenOwnedProcesses(
options.runId,
undefined,
options.captureBaseline,
),
);
if (!verified.cleaned)
ownedProcessGroup = { state: "unverified", reason: verified.reason };
}
}
}
let temporaryRoot: ProcessCaptureCleanupReport["temporary_root"] = {
state: "cleaned",
reason: null,
};
try {
await host.removeTemporaryRoot(options.temporaryRoot);
} catch (cause: unknown) {
void cause;
failure ??= "temporary process root cleanup failed";
temporaryRoot = {
state: "failed",
reason:
cause instanceof Error
? cause.message || cause.name || "temporary root removal failed"
: "temporary root removal failed",
};
}
return failure;
return {
owned_process_group: ownedProcessGroup,
terminal_renderer: terminalRenderer,
temporary_root: temporaryRoot,
};
};
export const cleanupReportFailure = (
report: ProcessCaptureCleanupReport,
): string | undefined => {
const failures = Object.entries(report).filter(
([, outcome]) =>
outcome.state === "failed" || outcome.state === "unverified",
);
return failures.length === 0
? undefined
: failures
.map(
([resource, outcome]) =>
`${resource}: ${outcome.reason ?? outcome.state}`,
)
.join("; ");
};
export const captureTerminalFrames = (options: {
@@ -428,22 +797,106 @@ export const captureTerminalFrames = (options: {
};
export const resolveProcessResult = (
capture: ProcessCapture | undefined,
capture: PendingProcessCapture | ProcessCapture | undefined,
executionFailure: unknown,
cleanupFailure: string | undefined,
cleanup: ProcessCaptureCleanupReport,
observations?: IncompleteProcessCaptureObservations,
partialContext?: {
readonly scenario: ProcessScenario;
readonly rootPid?: number;
},
): ProcessCapture => {
const cleanupFailure = cleanupReportFailure(cleanup);
if (cleanupFailure !== undefined) {
const cleanupResources = Object.entries(cleanup)
.filter(
([, outcome]) =>
outcome.state === "failed" || outcome.state === "unverified",
)
.map(([resource]) => resource);
const executionFailureReason =
describeProcessCaptureExecutionFailure(executionFailure);
let partialObservation: PartialProcessCaptureObservation | undefined;
if (capture !== undefined || observations !== undefined) {
const normalizedObservations =
observations === undefined || partialContext === undefined
? observations
: normalizePartialProcessObservations(observations, partialContext);
const partialPayload =
capture === undefined
? { observations: normalizedObservations }
: { capture };
const pendingCapture =
capture === undefined
? undefined
: {
...capture,
settlement: {
...capture.settlement,
cleanup_outcome: "failed" as const,
},
};
const partialResult = partialProcessCaptureObservationSchema.safeParse({
...partialPayload,
...(pendingCapture === undefined
? {}
: {
capture: Object.fromEntries(
Object.entries(pendingCapture).filter(
([key]) => key !== "cleanup",
),
),
}),
cleanup,
execution_failure: executionFailureReason ?? null,
});
if (partialResult.success) partialObservation = partialResult.data;
}
throw new ProcessCaptureError(cleanupFailure, {
cause: executionFailure,
reason: "cleanup_incomplete",
cleanupResources,
...(executionFailureReason === undefined
? {}
: { executionFailure: executionFailureReason }),
...(partialObservation === undefined ? {} : { partialObservation }),
cleanupReport: cleanup,
});
}
if (executionFailure instanceof ProcessCaptureError) throw executionFailure;
if (executionFailure !== undefined)
if (executionFailure !== undefined) {
const executionFailureReason =
describeProcessCaptureExecutionFailure(executionFailure);
throw new ProcessCaptureError("process capture failed", {
cause: executionFailure,
...(executionFailureReason === undefined
? {}
: { executionFailure: executionFailureReason }),
});
if (cleanupFailure !== undefined)
throw new ProcessCaptureError(cleanupFailure, {
reason: "cleanup_incomplete",
});
}
if (capture === undefined)
throw new ProcessCaptureError("process capture produced no result");
return capture;
if ("cleanup" in capture) return capture;
const settlement: UnverifiedProcessCapture["settlement"] =
capture.settlement.state === "quiesced"
? { ...capture.settlement, cleanup_outcome: "not_required" }
: { ...capture.settlement, cleanup_outcome: "cleaned" };
try {
return parseProcessCapture({
...capture,
settlement,
cleanup: {
owned_process_group: "verified",
temporary_root: "removed",
},
});
} catch (cause: unknown) {
throw new ProcessCaptureError(
`process capture validation failed${cause instanceof Error ? `: ${cause.message}` : ""}`,
{ cause },
);
}
};
export const prepareProcessCapture = async (
@@ -454,14 +907,21 @@ export const prepareProcessCapture = async (
): Promise<{
readonly temporaryRoot: string;
readonly runId: string;
readonly ownershipBaseline: ProcessOwnershipBaseline;
readonly before: SnapshotResult;
}> => {
assertNotCancelled(signal);
await host.prepareOwnershipInspector?.(signal);
assertNotCancelled(signal);
const before = await captureSnapshot(scenario, signal);
const temporaryRoot = await host.createTemporaryRoot();
try {
assertNotCancelled(signal);
const runId = randomUUID();
return { temporaryRoot, runId, before };
const ownershipBaseline =
(await host.captureOwnershipBaseline?.(signal)) ?? [];
assertNotCancelled(signal);
return { temporaryRoot, runId, ownershipBaseline, before };
} catch (cause: unknown) {
await host.cleanup(temporaryRoot);
throw cause;
@@ -470,11 +930,19 @@ export const prepareProcessCapture = async (
/** Filesystem seam for allocating and cleaning a capture's temporary root. */
export interface ProcessPreparationHost {
prepareOwnershipInspector?(signal?: AbortSignal): Promise<void>;
/** Capture the process baseline with the caller's startup cancellation. */
captureOwnershipBaseline?(
signal?: AbortSignal,
): Promise<ProcessOwnershipBaseline>;
createTemporaryRoot(): Promise<string>;
cleanup(path: string): Promise<void>;
}
const systemProcessPreparationHost: ProcessPreparationHost = {
prepareOwnershipInspector: prepareProcessOwnershipInspection,
captureOwnershipBaseline: (signal) =>
systemProcessOwnershipHost.captureBaseline?.(signal) ?? Promise.resolve([]),
createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
cleanup: (path) => rm(path, { recursive: true, force: true }),
};
+293 -3
View File
@@ -1,11 +1,27 @@
import { expect, it } from "vitest";
import { expect, it, vi } from "vitest";
import { processScenarioSchema } from "../../domain/process/processScenario.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { captureProcessScenario } from "./ProcessHarness.js";
import {
captureProcessScenario,
normalizeCaptureFailure,
ProcessCaptureError,
} from "./ProcessHarness.js";
import { settleProcessCaptureJournal } from "./ProcessCaptureLifecycle.js";
import { processCaptureSchema } from "../../domain/process/processCapture.js";
import {
parseProcessCapture,
partialProcessCaptureObservationSchema,
processCaptureSchema,
} from "../../domain/process/processCapture.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../domain/process/processCapture.fixture.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { emptyProcessCapture } from "../../domain/process/processCapture.fixture.js";
import { analysisErrorProjectionSchema } from "../../contracts/errorSchemas.js";
import {
releaseProcessResources,
resolveProcessResult,
type ProcessCaptureCleanupHost,
} from "./ProcessCaptureLifecycle.js";
import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";
it("rejects legacy replay output instead of silently discarding it", () => {
expect(
@@ -16,6 +32,21 @@ it("rejects legacy replay output instead of silently discarding it", () => {
).toBe(false);
});
it("preserves the actionable Darwin ownership compiler prerequisite", () => {
const normalized = normalizeCaptureFailure(
new DarwinProcessOwnershipInspectionError(
"macOS process ownership inspection requires the Apple Swift compiler via xcrun",
),
undefined,
);
expect(normalized).toBeInstanceOf(ProcessCaptureError);
expect(normalized).toMatchObject({
message:
"macOS process ownership inspection requires the Apple Swift compiler via xcrun",
});
});
it("waits for terminal observations delivered after the exit callback", async () => {
const journal: Array<{
capture_order: number;
@@ -41,6 +72,265 @@ it("waits for terminal observations delivered after the exit callback", async ()
expect(journal[1]).toMatchObject({ collection: "frames", index: 1 });
});
it("keeps empty cleanup exception messages actionable in the report", async () => {
const host: ProcessCaptureCleanupHost = {
platform: process.platform,
cleanupProcessGroup: async () => ({
cleaned: false,
reason: "unused process cleanup",
}),
verifyTokenOwnedProcesses: async () => ({
cleaned: false,
reason: "unused process cleanup",
}),
removeTemporaryRoot: async () => {
throw new Error("");
},
};
const report = await releaseProcessResources({
timers: new Set(),
terminal: undefined,
renderer: undefined,
runId: "fixture-run",
temporaryRoot: "/fixture/root",
host,
});
expect(report.temporary_root).toEqual({ state: "failed", reason: "Error" });
});
it("waits for token-owned processes to exit after one cleanup signal", async () => {
vi.useFakeTimers();
try {
let verificationCalls = 0;
const exitsAt = Date.now() + 50;
let cleanupCalls = 0;
const host: ProcessCaptureCleanupHost = {
platform: "linux",
cleanupProcessGroup: async () => {
cleanupCalls += 1;
return { cleaned: true, signaled: true };
},
verifyTokenOwnedProcesses: async () => {
verificationCalls += 1;
return Date.now() < exitsAt
? { cleaned: false, reason: "owned process is exiting" }
: { cleaned: true, signaled: false };
},
removeTemporaryRoot: async () => undefined,
};
const result = releaseProcessResources({
timers: new Set(),
terminal: { pid: 321 },
renderer: undefined,
runId: "fixture-run",
temporaryRoot: "/fixture/root",
host,
});
await vi.runAllTimersAsync();
const report = await result;
expect(report.owned_process_group).toEqual({
state: "cleaned",
reason: null,
});
expect(cleanupCalls).toBe(1);
expect(verificationCalls).toBeGreaterThan(1);
} finally {
vi.useRealTimers();
}
});
it("retains the last ownership failure when the verification grace expires", async () => {
vi.useFakeTimers();
try {
let verificationCalls = 0;
let cleanupCalls = 0;
const host: ProcessCaptureCleanupHost = {
platform: "linux",
cleanupProcessGroup: async () => {
cleanupCalls += 1;
return { cleaned: true, signaled: true };
},
verifyTokenOwnedProcesses: async () => {
verificationCalls += 1;
return {
cleaned: false,
reason:
verificationCalls === 1
? "owned process has not exited yet"
: "owned process remained after identity recheck",
};
},
removeTemporaryRoot: async () => undefined,
};
const result = releaseProcessResources({
timers: new Set(),
terminal: { pid: 322 },
renderer: undefined,
runId: "fixture-run",
temporaryRoot: "/fixture/root",
host,
});
await vi.runAllTimersAsync();
const report = await result;
expect(report.owned_process_group).toEqual({
state: "unverified",
reason: "owned process remained after identity recheck",
});
expect(cleanupCalls).toBe(1);
expect(verificationCalls).toBeGreaterThan(1);
} finally {
vi.useRealTimers();
}
});
it("passes sampled detached groups into cleanup even when their token is unknown", async () => {
let sampledGroups: readonly number[] | undefined;
const host: ProcessCaptureCleanupHost = {
platform: "linux",
cleanupProcessGroup: async (ownership) => {
sampledGroups = ownership.sampledProcessGroupIds;
return {
cleaned: false,
reason: "sampled group has no verifiable run token",
};
},
verifyTokenOwnedProcesses: async () => ({
cleaned: true,
signaled: false,
}),
removeTemporaryRoot: async () => undefined,
};
const report = await releaseProcessResources({
timers: new Set(),
terminal: { pid: 321 },
renderer: undefined,
runId: "fixture-run",
temporaryRoot: "/fixture/root",
sampledProcessGroupIds: [654],
host,
});
expect(sampledGroups).toEqual([654]);
expect(report.owned_process_group).toEqual({
state: "unverified",
reason: "sampled group has no verifiable run token",
});
});
it("retains observations and both causes when process cleanup is unverifiable", () => {
const verified = emptyProcessCapture();
const capture = parseProcessCapture({
...verified,
frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
process_samples: [
{
at_ms: 1,
pid: 654,
parent_pid: 321,
command: "sanitized-detached-child",
process_group_id: 654,
session_id: 654,
},
],
event_journal: [],
});
const executionFailure = new Error("capture ended after a fixture error");
const cleanup = {
owned_process_group: {
state: "unverified" as const,
reason:
"process ownership token could not be read for 1 live process(es): environment_unavailable=1",
},
terminal_renderer: { state: "cleaned" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
let error: ProcessCaptureError | undefined;
try {
resolveProcessResult(capture, executionFailure, cleanup);
} catch (cause: unknown) {
if (!(cause instanceof ProcessCaptureError)) throw cause;
error = cause;
}
expect(error).toBeDefined();
if (error === undefined) throw new Error("expected cleanup-incomplete error");
const projection = projectAnalysisError(error);
const parsedProjection = analysisErrorProjectionSchema.parse(projection);
expect(parsedProjection).toMatchObject({
code: "cleanup_incomplete",
details: {
cleanup_report: cleanup,
execution_failure: "capture ended after a fixture error",
partial_observation: {
capture: {
frames: [{ data: "observed output" }],
process_samples: [{ pid: 654, process_group_id: 654 }],
settlement: { cleanup_outcome: "failed" },
},
execution_failure: "capture ended after a fixture error",
},
},
});
expect(error.cause).toBe(executionFailure);
const partialObservation = error.partialObservation;
expect(partialObservation).toBeDefined();
if (partialObservation === undefined)
throw new Error("expected validated partial observation");
expect(
partialProcessCaptureObservationSchema.safeParse({
...partialObservation,
cleanup: {
owned_process_group: { state: "cleaned", reason: null },
terminal_renderer: { state: "cleaned", reason: null },
temporary_root: { state: "cleaned", reason: null },
},
}).success,
).toBe(false);
if (!("capture" in partialObservation))
throw new Error("expected completed partial capture observations");
const partialCapture = partialObservation.capture;
expect(() => parseProcessCapture(partialCapture)).toThrow();
});
it("projects execution and cleanup failures when capture never completed", () => {
const executionFailure = new Error("terminal startup failed");
const cleanup = {
owned_process_group: {
state: "unverified" as const,
reason: "process ownership token could not be read",
},
terminal_renderer: { state: "cleaned" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
let error: ProcessCaptureError | undefined;
try {
resolveProcessResult(undefined, executionFailure, cleanup);
} catch (cause: unknown) {
if (!(cause instanceof ProcessCaptureError)) throw cause;
error = cause;
}
expect(error).toBeDefined();
if (error === undefined) throw new Error("expected cleanup-incomplete error");
expect(error.partialObservation).toBeUndefined();
expect(error.cause).toBe(executionFailure);
expect(projectAnalysisError(error)).toMatchObject({
code: "cleanup_incomplete",
details: {
cleanup_report: cleanup,
execution_failure: "terminal startup failed",
},
});
});
it("fails closed on Windows before resolving or launching scenario paths", async () => {
const scenario = processScenarioSchema.parse({
executable: "Z:/missing/should-never-be-resolved.exe",
+251 -41
View File
@@ -14,6 +14,7 @@ import { err, ok, type Result } from "../../domain/result.js";
import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
import { type AnalysisError } from "../../domain/analysisErrorBase.js";
import {
describeProcessCaptureExecutionFailure,
ProcessCaptureError,
processCaptureCancelled,
} from "./ProcessCaptureError.js";
@@ -27,13 +28,19 @@ import { selectCapturedProcessGroupIds } from "../ProcessOwnershipProcessTree.js
import {
awaitTerminalExit,
buildCaptureResult,
cleanupReportFailure,
captureTerminalFrames,
createProcessCaptureObservationBuffer,
createRunManifest,
observeLaunchedExecutable,
observeSelectedExecutable,
observeSettlement,
prepareProcessCapture,
releaseProcessResources,
resolveProcessResult,
settleProcessCaptureJournal,
type ProcessCaptureCleanupHost,
type ProcessCaptureObservationBuffer,
type PendingProcessCapture,
} from "./ProcessCaptureLifecycle.js";
import {
@@ -47,6 +54,8 @@ import {
import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
import type { ProcessOwnershipBaseline } from "../ProcessOwnership.js";
import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";
export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
interface StartedCaptureRuntime {
@@ -54,6 +63,7 @@ interface StartedCaptureRuntime {
readonly terminal: IPty;
readonly started: number;
readonly startedAt: Date;
readonly executableIdentity: ReturnType<typeof observeLaunchedExecutable>;
readonly lastOutput: () => number;
readonly framesTruncated: () => boolean;
readonly stopSampler: () => Promise<{ readonly partial: boolean }>;
@@ -65,19 +75,58 @@ const cleanupFailedStartup = async (options: {
readonly terminal: IPty | undefined;
readonly renderer: TerminalRenderer | undefined;
readonly runId: string;
readonly captureBaseline: ProcessOwnershipBaseline;
readonly scenario: ProcessScenario;
readonly cleanupHost?: ProcessCaptureCleanupHost;
readonly observations?: ProcessCaptureObservationBuffer;
readonly temporaryRoot: string;
}): Promise<never> => {
const sampledProcessGroupIds =
options.terminal !== undefined &&
options.observations?.process_samples.state === "available"
? selectCapturedProcessGroupIds(
options.terminal.pid,
options.observations.process_samples.value,
).filter((groupId) => groupId !== options.terminal?.pid)
: undefined;
options.terminal?.kill("SIGKILL");
if (options.observations !== undefined && options.renderer !== undefined) {
try {
options.observations.rendered_frames = {
state: "available",
value: await options.renderer.frames(),
};
} catch (cause: unknown) {
options.observations.rendered_frames = {
state: "unavailable",
reason: `Rendered terminal frame collection failed: ${cause instanceof Error ? cause.message : "unknown failure"}`,
};
}
}
const cleanupFailure = await releaseProcessResources({
...options,
capturedProcessGroupIds:
options.terminal === undefined ? [] : [options.terminal.pid],
timers: options.timers,
terminal: options.terminal,
renderer: options.renderer,
runId: options.runId,
captureBaseline: options.captureBaseline,
...(sampledProcessGroupIds === undefined ? {} : { sampledProcessGroupIds }),
temporaryRoot: options.temporaryRoot,
...(options.cleanupHost === undefined ? {} : { host: options.cleanupHost }),
});
if (cleanupFailure !== undefined)
throw new ProcessCaptureError(cleanupFailure, {
cause: options.cause,
reason: "cleanup_incomplete",
});
if (cleanupReportFailure(cleanupFailure) !== undefined) {
resolveProcessResult(
undefined,
options.cause,
cleanupFailure,
options.observations,
{
scenario: options.scenario,
...(options.terminal === undefined
? {}
: { rootPid: options.terminal.pid }),
},
);
}
throw options.cause;
};
@@ -102,6 +151,10 @@ interface StartCaptureRuntimeOptions {
readonly hostEnvironment: Readonly<Record<string, string | undefined>>;
readonly temporaryRoot: string;
readonly runId: string;
readonly ownershipBaseline: ProcessOwnershipBaseline;
readonly cleanupHost?: ProcessCaptureCleanupHost;
readonly observationBuffer: ProcessCaptureObservationBuffer;
readonly onSpawn: (pid: number) => void;
readonly frames: TerminalFrame[];
readonly samples: ProcessSample[];
readonly interactions: InteractionEvent[];
@@ -119,6 +172,10 @@ const startCaptureRuntime = async (
let terminal: IPty | undefined;
try {
const { spawn } = await import("@lydell/node-pty");
const selectedExecutable = await observeSelectedExecutable(
scenario.executable,
options.signal,
);
const startedAt = new Date();
const started = Date.now();
let lastOutput = started;
@@ -135,6 +192,15 @@ const startCaptureRuntime = async (
rows: scenario.terminal.rows,
name: "xterm-256color",
});
options.onSpawn(terminal.pid);
options.observationBuffer.target_pid = {
state: "available",
value: scenario.normalization.pids ? 1 : terminal.pid,
};
const executableIdentity = observeLaunchedExecutable(
scenario.executable,
selectedExecutable,
);
const framesTruncated = captureTerminalFrames({
...options,
terminal,
@@ -161,6 +227,7 @@ const startCaptureRuntime = async (
terminal,
started,
startedAt,
executableIdentity,
lastOutput: () => lastOutput,
framesTruncated,
stopSampler,
@@ -172,6 +239,12 @@ const startCaptureRuntime = async (
terminal,
renderer,
runId: options.runId,
captureBaseline: options.ownershipBaseline,
scenario,
...(options.cleanupHost === undefined
? {}
: { cleanupHost: options.cleanupHost }),
observations: options.observationBuffer,
temporaryRoot: options.temporaryRoot,
});
}
@@ -181,27 +254,36 @@ const finishProcessRun = async (options: {
readonly runtime: StartedCaptureRuntime | undefined;
readonly timers: Set<ProcessTimer>;
readonly runId: string;
readonly captureBaseline: ProcessOwnershipBaseline;
readonly cleanupHost?: ProcessCaptureCleanupHost;
readonly temporaryRoot: string;
readonly scenario: ProcessScenario;
readonly samples: readonly ProcessSample[];
readonly stopSampler: () => Promise<{ readonly partial: boolean }>;
readonly capture: PendingProcessCapture | undefined;
readonly executionFailure: unknown;
readonly observations?: ProcessCaptureObservationBuffer;
readonly rootPid?: number;
}): Promise<ProcessCapture> => {
await options.stopSampler();
const cleanupFailure = await releaseProcessResources({
const sampledProcessGroupIds =
options.runtime === undefined
? undefined
: selectCapturedProcessGroupIds(
options.runtime.terminal.pid,
options.samples,
).filter((groupId) => groupId !== options.runtime?.terminal.pid);
const cleanup = await releaseProcessResources({
timers: options.timers,
terminal: options.runtime?.terminal,
renderer: options.runtime?.renderer,
runId: options.runId,
captureBaseline: options.captureBaseline,
...(sampledProcessGroupIds === undefined ? {} : { sampledProcessGroupIds }),
temporaryRoot: options.temporaryRoot,
capturedProcessGroupIds:
options.runtime === undefined
? []
: selectCapturedProcessGroupIds(
options.runtime.terminal.pid,
options.samples,
),
...(options.cleanupHost === undefined ? {} : { host: options.cleanupHost }),
});
const cleanupFailure = cleanupReportFailure(cleanup);
let { capture, executionFailure } = options;
let verifiedCapture: ProcessCapture | undefined;
if (capture !== undefined && cleanupFailure === undefined) {
@@ -226,18 +308,28 @@ const finishProcessRun = async (options: {
);
}
}
const rootPid = options.runtime?.terminal.pid ?? options.rootPid;
const partialContext =
rootPid === undefined
? { scenario: options.scenario }
: { scenario: options.scenario, rootPid };
return resolveProcessResult(
verifiedCapture,
cleanupFailure === undefined ? verifiedCapture : capture,
executionFailure,
cleanupFailure,
cleanup,
options.observations,
partialContext,
);
};
const normalizeCaptureFailure = (
/** Preserve typed process-inspection preflight failures at the capture boundary. */
export const normalizeCaptureFailure = (
cause: unknown,
signal: AbortSignal | undefined,
): unknown => {
if (cause instanceof ProcessCaptureError) return cause;
if (cause instanceof DarwinProcessOwnershipInspectionError)
return new ProcessCaptureError(cause.message, { cause });
if (
signal?.aborted === true &&
(cause === signal.reason ||
@@ -262,24 +354,72 @@ const completeCapture = async (options: {
readonly captureSnapshot: typeof snapshotRoots;
readonly initiallyTruncated: boolean;
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
readonly observationBuffer: ProcessCaptureObservationBuffer;
readonly recordEvent: RecordProcessCaptureEvent;
}): Promise<PendingProcessCapture> => {
const unavailableReason = (stage: string, cause: unknown): string =>
`${stage} failed: ${cause instanceof Error ? cause.message : "unknown failure"}`;
const { runtime, scenario } = options;
const { reason } = options.exit;
if (reason === "cancelled") throw processCaptureCancelled();
const settlement = await observeSettlement(
options.runId,
selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples),
scenario.settle_ms,
options.recordEvent,
options.hostPlatform,
);
let settlement: Awaited<ReturnType<typeof observeSettlement>>;
try {
settlement = await observeSettlement(
options.runId,
selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples),
scenario.settle_ms,
options.recordEvent,
options.hostPlatform,
);
} catch (cause: unknown) {
options.observationBuffer.settlement = {
state: "unavailable",
reason: unavailableReason("Process settlement observation", cause),
};
throw cause;
}
options.observationBuffer.settlement = {
state: "available",
value: settlement,
};
const samplingPartial = (await runtime.stopSampler()).partial;
await settleProcessCaptureJournal(options.eventJournal);
assertNotCancelled(options.signal);
const after = await options.captureSnapshot(scenario, options.signal);
let after: Awaited<ReturnType<typeof snapshotRoots>>;
try {
after = await options.captureSnapshot(scenario, options.signal);
} catch (cause: unknown) {
options.observationBuffer.filesystem_snapshots = {
...options.observationBuffer.filesystem_snapshots,
after: {
state: "unavailable",
reason: unavailableReason("Final filesystem snapshot", cause),
},
};
throw cause;
}
options.observationBuffer.filesystem_snapshots = {
...options.observationBuffer.filesystem_snapshots,
after: {
state: "available",
value: { files: after.files, truncated: after.truncated },
},
};
options.recordEvent("filesystem_checkpoints", 1);
const renderedFrames = await runtime.renderer.frames();
let renderedFrames: Awaited<ReturnType<TerminalRenderer["frames"]>>;
try {
renderedFrames = await runtime.renderer.frames();
} catch (cause: unknown) {
options.observationBuffer.rendered_frames = {
state: "unavailable",
reason: unavailableReason("Rendered terminal frame collection", cause),
};
throw cause;
}
options.observationBuffer.rendered_frames = {
state: "available",
value: renderedFrames,
};
const checkpoints: UnverifiedProcessCapture["filesystem_checkpoints"] = [
{
name: "before",
@@ -296,12 +436,23 @@ const completeCapture = async (options: {
truncated: after.truncated,
},
];
const manifest = await createRunManifest(
scenario,
runtime.startedAt,
new Date(),
{ platform: options.hostPlatform, architecture: process.arch },
);
let manifest: Awaited<ReturnType<typeof createRunManifest>>;
try {
manifest = await createRunManifest(
scenario,
runtime.startedAt,
new Date(),
runtime.executableIdentity,
{ platform: options.hostPlatform, architecture: process.arch },
);
} catch (cause: unknown) {
options.observationBuffer.manifest = {
state: "unavailable",
reason: unavailableReason("Capture manifest creation", cause),
};
throw cause;
}
options.observationBuffer.manifest = { state: "available", value: manifest };
const truncated =
options.initiallyTruncated ||
after.truncated ||
@@ -335,23 +486,29 @@ const runProcessScenario = async (
hostEnvironment: Readonly<Record<string, string | undefined>> = process.env,
hostPlatform: NodeJS.Platform = process.platform,
captureSnapshot: typeof snapshotRoots = snapshotRoots,
cleanupHost?: ProcessCaptureCleanupHost,
): Promise<ProcessCapture> => {
const { temporaryRoot, runId, before } = await prepareProcessCapture(
scenario,
signal,
captureSnapshot,
);
const { temporaryRoot, runId, ownershipBaseline, before } =
await prepareProcessCapture(scenario, signal, captureSnapshot);
const frames: TerminalFrame[] = [];
const samples: ProcessSample[] = [];
const interactions: InteractionEvent[] = [];
const journal = createProcessCaptureJournal();
const { entries: eventJournal, recordEvent } = journal;
recordEvent("filesystem_checkpoints", 0);
const observations = createProcessCaptureObservationBuffer({
frames,
interactions,
samples,
eventJournal,
before,
});
let runtime: StartedCaptureRuntime | undefined;
let actualRootPid: number | undefined;
const timers = new Set<ProcessTimer>();
let capture: PendingProcessCapture | undefined;
let executionFailure: unknown;
let stopSampler = async () => ({ partial: false });
const interactions: InteractionEvent[] = [];
const dispatchedEventIndexes = new Set<number>();
try {
@@ -360,6 +517,12 @@ const runProcessScenario = async (
hostEnvironment,
temporaryRoot,
runId,
ownershipBaseline,
...(cleanupHost === undefined ? {} : { cleanupHost }),
observationBuffer: observations,
onSpawn: (pid) => {
actualRootPid = pid;
},
frames,
samples,
interactions,
@@ -380,6 +543,15 @@ const runProcessScenario = async (
dispatchedEventIndexes,
recordEvent,
});
observations.exit = {
state: "available",
value: {
code:
exit.reason === "exited" && exit.exitCode >= 0 ? exit.exitCode : null,
signal: exit.signal ?? null,
reason: exit.reason,
},
};
capture = await completeCapture({
scenario,
hostPlatform,
@@ -393,6 +565,7 @@ const runProcessScenario = async (
exit,
initiallyTruncated: before.truncated,
eventJournal,
observationBuffer: observations,
recordEvent,
captureSnapshot,
...(signal === undefined ? {} : { signal }),
@@ -400,16 +573,44 @@ const runProcessScenario = async (
} catch (cause: unknown) {
runtime?.terminal.kill("SIGKILL");
executionFailure = normalizeCaptureFailure(cause, signal);
if (
runtime !== undefined &&
observations.rendered_frames.state === "unavailable" &&
observations.rendered_frames.reason.startsWith(
"Rendered terminal frames were not collected",
)
) {
try {
observations.rendered_frames = {
state: "available",
value: await runtime.renderer.frames(),
};
} catch (renderCause: unknown) {
const renderFailure =
renderCause instanceof Error
? renderCause.message
: "unknown failure";
observations.rendered_frames = {
state: "unavailable",
reason: `Rendered terminal frame collection failed: ${renderFailure}`,
};
}
}
}
return finishProcessRun({
runtime,
timers,
runId,
captureBaseline: ownershipBaseline,
...(cleanupHost === undefined ? {} : { cleanupHost }),
temporaryRoot,
scenario,
samples,
stopSampler,
capture,
executionFailure,
observations,
...(actualRootPid === undefined ? {} : { rootPid: actualRootPid }),
});
};
@@ -420,6 +621,7 @@ export const captureProcessScenario = async (
platform: NodeJS.Platform = process.platform,
environment: Readonly<Record<string, string | undefined>> = process.env,
captureSnapshot: typeof snapshotRoots = snapshotRoots,
cleanupHost?: ProcessCaptureCleanupHost,
): Promise<Result<ProcessCapture, ProcessCaptureError | AnalysisError>> => {
const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
if (ownershipReason !== undefined)
@@ -444,14 +646,22 @@ export const captureProcessScenario = async (
environment,
platform,
captureSnapshot,
cleanupHost,
),
);
} catch (cause: unknown) {
const failure = normalizeCaptureFailure(cause, signal);
const executionFailureReason =
describeProcessCaptureExecutionFailure(cause);
return err(
failure instanceof ProcessCaptureError
? failure
: new ProcessCaptureError("process capture failed", { cause }),
: new ProcessCaptureError("process capture failed", {
cause,
...(executionFailureReason === undefined
? {}
: { executionFailure: executionFailureReason }),
}),
);
}
};