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:
@@ -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", {
|
||||
|
||||
@@ -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 }),
|
||||
};
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 }),
|
||||
}),
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user