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
@@ -8,6 +8,7 @@ import type { AnalysisClient } from "../../../src/application/AnalysisProvider.j
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { ARTIFACT_COMPARISON_EXAMPLE } from "../../../src/contracts/artifactComparisonExample.js";
import { PROCESS_CAPTURE_REFERENCE } from "../../../src/contracts/investigationExamples.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js";
import { createEvidence } from "../../../src/domain/evidence.js";
import { createArtifactInspection } from "../../../src/domain/artifactInspection.js";
import { artifactInventoryResultSchema } from "../../../src/domain/artifactGraph.js";
@@ -57,6 +58,36 @@ describe("guided prompt completion from live analysis", () => {
});
describe("guided prompt completion from investigation records", () => {
it("completes process captures imported in the original v3 format", async () => {
const session = createTestBinarySession(() => client([]));
const {
selected_executable_sha256: _selectedDigest,
executable_identity: _identity,
executable_sha256,
...legacyManifest
} = EMPTY_PROCESS_CAPTURE_EXAMPLE.manifest;
const legacyCapture = {
...EMPTY_PROCESS_CAPTURE_EXAMPLE,
manifest: { ...legacyManifest, executable_sha256 },
};
const evidence = createEvidence(undefined, fixtureProvider, {
operation: "capture_process_scenario",
parameters: {},
result: legacyCapture,
confidence: "observed",
authority: "controlled-replay",
environment: fixtureEnvironment,
});
expect(session.recordEvidence(evidence).ok).toBe(true);
const completion = createPromptCompletionSource(session, session);
expect(
await completion.complete("capture", evidence.evidence_id.slice(0, 8)),
).toEqual([evidence.evidence_id]);
await session.close();
});
it("projects only validated typed identifiers from the evidence ledger", async () => {
const session = createTestBinarySession(() => client([]));
const invalidCapture = createEvidence(undefined, fixtureProvider, {
+222 -3
View File
@@ -1,14 +1,24 @@
import { describe, expect, it } from "vitest";
import { z } from "zod";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { McpServer } from "@modelcontextprotocol/server";
import type { ToolContract } from "../../../src/contracts/toolContracts.js";
import { ok } from "../../../src/domain/result.js";
import { err } from "../../../src/domain/result.js";
import { ProcessCaptureError } from "../../../src/process/capture/ProcessCaptureError.js";
import { resolveProcessResult } from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import {
toolContract,
type ToolContract,
} from "../../../src/contracts/toolContracts.js";
import { err, ok } from "../../../src/domain/result.js";
import { HopperProcessError } from "../../../src/domain/hopperErrors.js";
import type { IncompleteProcessCaptureObservations } from "../../../src/domain/process/processCapture.js";
import { processScenarioSchema } from "../../../src/domain/process/processScenario.js";
import { toCallToolResult } from "../../../src/server/toolResult.js";
import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";
import { emptyProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
import type { JsonValue } from "../../../src/domain/jsonValue.js";
import { evidenceResultOf } from "../../../src/contracts/toolOutputSchemas.js";
import { toolRegistrationOptions } from "../../../src/server/toolRegistrationOptions.js";
const contract: ToolContract = {
name: "provider_neutral_fixture",
@@ -36,6 +46,215 @@ const contract: ToolContract = {
examples: [{ title: "Example fixture request", input: {} }],
};
describe("completed partial process capture MCP projection", () => {
it("preserves partial capture details over the MCP SDK transport", async () => {
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",
},
terminal_renderer: { state: "cleaned" as const, reason: null },
temporary_root: { state: "cleaned" as const, reason: null },
};
const capture = {
...emptyProcessCapture(),
frames: [{ sequence: 0, at_ms: 0, data: "observed output" }],
event_journal: [],
};
let failure: ProcessCaptureError | undefined;
try {
resolveProcessResult(capture, executionFailure, cleanup);
} catch (cause: unknown) {
if (!(cause instanceof ProcessCaptureError)) throw cause;
failure = cause;
}
expect(failure).toBeDefined();
if (failure === undefined)
throw new Error("expected cleanup-incomplete result");
const captureContract = toolContract("capture_process_scenario");
const server = new McpServer({
name: "process-partial-error",
version: "1",
});
server.registerTool(
captureContract.name,
toolRegistrationOptions(captureContract),
async () => toCallToolResult(err(failure), captureContract),
);
const client = new Client({
name: "process-partial-error-client",
version: "1",
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
try {
await server.connect(serverTransport);
await client.connect(clientTransport);
const result = await client.callTool({
name: captureContract.name,
arguments: captureContract.examples[0]?.input ?? {},
});
expect(result.isError).toBe(true);
expect(result.structuredContent).toMatchObject({
error: {
code: "cleanup_incomplete",
details: {
cleanup_report: cleanup,
execution_failure: "capture ended after a fixture error",
partial_observation: {
capture: {
frames: [{ data: "observed output" }],
settlement: { cleanup_outcome: "failed" },
},
execution_failure: "capture ended after a fixture error",
},
},
},
});
const textContent = result.content.find((block) => block.type === "text");
expect(textContent?.type === "text" ? textContent.text : undefined).toBe(
JSON.stringify(result.structuredContent),
);
} finally {
await Promise.all([client.close(), server.close()]);
}
});
});
describe("incomplete partial process observations MCP projection", () => {
it("preserves normalized raw observations over the MCP SDK transport", async () => {
const captureContract = toolContract("capture_process_scenario");
const example = captureContract.examples[0];
if (example === undefined)
throw new Error("missing process scenario example");
const scenario = processScenarioSchema.parse({
...example.input,
normalization: { pids: false },
});
const rootPid = 45678;
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 },
};
const observations: IncompleteProcessCaptureObservations = {
target_pid: { state: "available", value: rootPid },
frames: {
state: "available",
value: [{ sequence: 0, at_ms: 0, data: "partial output" }],
},
rendered_frames: {
state: "unavailable",
reason: "fixture renderer observation unavailable",
},
interaction_events: { state: "available", value: [] },
exit: {
state: "unavailable",
reason: "fixture terminal exit unavailable",
},
settlement: {
state: "unavailable",
reason: "fixture process settlement unavailable",
},
process_samples: {
state: "available",
value: [
{
at_ms: 1,
pid: rootPid,
parent_pid: 1,
command: `fixture ${String(rootPid)}`,
process_group_id: rootPid,
session_id: rootPid,
},
],
},
filesystem_snapshots: {
before: { state: "available", value: { files: [], truncated: false } },
after: {
state: "unavailable",
reason: "fixture final snapshot unavailable",
},
},
event_journal: { state: "available", value: [] },
manifest: {
state: "unavailable",
reason: "fixture capture manifest unavailable",
},
};
let failure: ProcessCaptureError | undefined;
try {
resolveProcessResult(
undefined,
new Error("capture failed before completion"),
cleanup,
observations,
{ scenario, rootPid },
);
} catch (cause: unknown) {
if (!(cause instanceof ProcessCaptureError)) throw cause;
failure = cause;
}
if (failure === undefined)
throw new Error("expected cleanup-incomplete result");
const server = new McpServer({
name: "process-partial-observations",
version: "1",
});
server.registerTool(
captureContract.name,
toolRegistrationOptions(captureContract),
async () => toCallToolResult(err(failure), captureContract),
);
const client = new Client({
name: "process-partial-observations-client",
version: "1",
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
try {
await server.connect(serverTransport);
await client.connect(clientTransport);
const result = await client.callTool({
name: captureContract.name,
arguments: example.input,
});
expect(result.isError).toBe(true);
expect(result.structuredContent).toMatchObject({
error: {
details: {
partial_observation: {
observations: {
target_pid: { state: "available", value: rootPid },
frames: {
state: "available",
value: [{ data: "partial output" }],
},
process_samples: {
state: "available",
value: [{ pid: rootPid }],
},
},
},
},
},
});
} finally {
await Promise.all([client.close(), server.close()]);
}
});
});
describe("tool result projection", () => {
it("exposes an actionable adapter code to MCP callers", () => {
const result = toCallToolResult(err(new HopperProcessError(76)), contract);
+18 -2
View File
@@ -1,7 +1,11 @@
import { expect, it } from "vitest";
import { createProcessCaptureEvidence } from "../../../src/application/process/ProcessEvidence.js";
import { createRunManifest } from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import {
createRunManifest,
observeLaunchedExecutable,
observeSelectedExecutable,
} from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import { emptyUnverifiedProcessCapture } from "../../../src/domain/process/processCapture.fixture.js";
import {
compareProcessCaptures,
@@ -61,8 +65,20 @@ const captureEvidenceForEnvironmentSecret = async (value: string) => {
environment: { API_TOKEN: value },
events: [{ type: "input", at_ms: 0, data: value }],
});
const selectedExecutable = await observeSelectedExecutable(
scenario.executable,
);
const executableIdentity = observeLaunchedExecutable(
scenario.executable,
selectedExecutable,
);
const manifest = await createRunManifest(
scenario,
new Date(0),
new Date(1),
executableIdentity,
);
const base = emptyUnverifiedProcessCapture();
const manifest = await createRunManifest(scenario, new Date(0), new Date(1));
const scenarioManifest = {
...manifest,
normalization_sha256: digestProcessCommitment(scenario.normalization),
@@ -0,0 +1,724 @@
import { execFile, spawn, type ChildProcess } from "node:child_process";
import {
access,
chmod,
mkdtemp,
readFile,
rm,
symlink,
writeFile,
} from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { _electron as electron } from "playwright-core";
import { expect, it, vi } from "vitest";
import {
createSystemProcessOwnershipHost,
systemProcessOwnershipHost,
} from "../../../src/process/ProcessOwnershipObservation.js";
import { createDarwinProcessRunTokenReader } from "../../../src/process/DarwinProcessRunTokenReader.js";
import { execFileOutput } from "../../../src/process/ExecFileOutput.js";
import { normalizeCaptureFailure } from "../../../src/process/capture/ProcessHarness.js";
import { PlaywrightElectronActiveProvider } from "../../../src/browser/PlaywrightElectronActiveProvider.js";
import { electronActiveObservationInputSchema } from "../../../src/domain/javascript/electronActiveObservation.js";
const execFileAsync = promisify(execFile);
const onDarwin = process.platform === "darwin";
const writeBlockingCompiler = async (directory: string) => {
const executable = join(directory, "fake-xcrun");
const statePath = join(directory, "compile-state.json");
const releasePath = join(directory, "release-compiler");
const source = `#!/usr/bin/env node
const fs = require("node:fs");
const path = require("node:path");
const statePath = ${JSON.stringify(statePath)};
const releasePath = ${JSON.stringify(releasePath)};
const state = fs.existsSync(statePath)
? JSON.parse(fs.readFileSync(statePath, "utf8"))
: { calls: 0 };
state.calls += 1;
const moduleIndex = process.argv.indexOf("-module-cache-path");
state.root = path.dirname(process.argv[moduleIndex + 1]);
const outputIndex = process.argv.indexOf("-o");
state.output = process.argv[outputIndex + 1];
state.releasePath = releasePath;
fs.writeFileSync(statePath, JSON.stringify(state));
if (state.calls === 1) {
const timer = setInterval(() => {
if (!fs.existsSync(releasePath)) return;
clearInterval(timer);
fs.writeFileSync(state.output, "compiled");
}, 10);
} else {
fs.writeFileSync(state.output, "compiled");
}
`;
await writeFile(executable, source);
await chmod(executable, 0o755);
return { executable, statePath, releasePath };
};
const writeBlockingIdentityCompiler = async (directory: string) => {
const executable = join(directory, "fake-identity-xcrun");
const statePath = join(directory, "identity-helper-state.json");
const helperSource = `#!/usr/bin/env node
const fs = require("node:fs");
fs.writeFileSync(${JSON.stringify(statePath)}, JSON.stringify({
root: __dirname,
}));
setInterval(() => {}, 1000);
`;
const compilerSource = `#!/usr/bin/env node
const fs = require("node:fs");
const outputIndex = process.argv.indexOf("-o");
const output = process.argv[outputIndex + 1];
fs.writeFileSync(output, ${JSON.stringify(helperSource)});
fs.chmodSync(output, 0o755);
`;
await writeFile(executable, compilerSource);
await chmod(executable, 0o755);
return { executable, statePath };
};
const waitForCompileState = async (statePath: string) => {
const deadline = Date.now() + 5_000;
while (Date.now() < deadline) {
try {
const parsed: unknown = JSON.parse(await readFile(statePath, "utf8"));
if (
typeof parsed === "object" &&
parsed !== null &&
"calls" in parsed &&
typeof parsed.calls === "number" &&
"root" in parsed &&
typeof parsed.root === "string" &&
"output" in parsed &&
typeof parsed.output === "string" &&
"releasePath" in parsed &&
typeof parsed.releasePath === "string"
)
return {
calls: parsed.calls,
root: parsed.root,
output: parsed.output,
releasePath: parsed.releasePath,
};
} catch {
await new Promise((resolve) => setTimeout(resolve, 10));
}
}
throw new Error("fake compiler did not start");
};
const waitForIdentityHelper = async (statePath: string) => {
const deadline = Date.now() + 5_000;
while (Date.now() < deadline) {
try {
const parsed: unknown = JSON.parse(await readFile(statePath, "utf8"));
if (
typeof parsed === "object" &&
parsed !== null &&
"root" in parsed &&
typeof parsed.root === "string"
)
return { root: parsed.root };
} catch {
await new Promise((resolve) => setTimeout(resolve, 10));
}
}
throw new Error("fake identity helper did not start");
};
type ElectronCaptureResult = Awaited<
ReturnType<PlaywrightElectronActiveProvider["capture"]>
>;
type ElectronCaptureOutcome =
| { readonly state: "result"; readonly value: ElectronCaptureResult }
| { readonly state: "rejected"; readonly cause: unknown };
it("reports an actionable missing Swift compiler without installing it", async () => {
const reader = createDarwinProcessRunTokenReader({
xcrun: join(tmpdir(), "rea-no-such-xcrun"),
});
try {
await expect(
reader.read([
{
pid: 1,
parentPid: 0,
processGroupId: 1,
state: "S",
command: "fixture",
},
]),
).rejects.toThrow(/requires the Apple Swift compiler via xcrun/u);
} finally {
await reader.close();
}
});
it.skipIf(process.platform === "win32")(
"rethrows compile cancellation, removes its temporary root, and permits retry",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-process-token-abort-test-"),
);
const fakeCompiler = await writeBlockingCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const controller = new AbortController();
const compilation = reader.prepare(controller.signal).then(
() => ({ state: "fulfilled" as const }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
try {
const firstAttempt = await waitForCompileState(fakeCompiler.statePath);
controller.abort();
const outcome = await compilation;
expect(outcome.state).toBe("rejected");
if (outcome.state !== "rejected")
throw new Error(
"aborted native reader compilation unexpectedly succeeded",
);
expect(outcome.cause).toMatchObject({ name: "AbortError" });
expect(
normalizeCaptureFailure(outcome.cause, controller.signal),
).toMatchObject({ reason: "cancelled", userCategory: "cancelled" });
await expect(access(firstAttempt.root)).rejects.toThrow();
await reader.prepare();
const retry = await waitForCompileState(fakeCompiler.statePath);
expect(retry).toMatchObject({ calls: 2 });
await expect(access(retry.output)).resolves.toBeUndefined();
await reader.close();
await expect(access(retry.root)).rejects.toThrow();
} finally {
if (!controller.signal.aborted) controller.abort();
await compilation;
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32").each(["first", "second"] as const)(
"keeps shared compilation alive when the %s waiter cancels",
async (cancelledWaiter) => {
const directory = await mkdtemp(
join(tmpdir(), "rea-process-token-shared-compile-test-"),
);
const fakeCompiler = await writeBlockingCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const firstController = new AbortController();
const secondController = new AbortController();
const firstWaiter = reader.prepare(firstController.signal).then(
(value) => ({ state: "fulfilled" as const, value }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
const secondWaiterPromise = (async () => {
const state = await waitForCompileState(fakeCompiler.statePath);
const secondWaiter = reader.prepare(secondController.signal).then(
(value) => ({ state: "fulfilled" as const, value }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
const cancelled =
cancelledWaiter === "first" ? firstWaiter : secondWaiter;
const surviving =
cancelledWaiter === "first" ? secondWaiter : firstWaiter;
(cancelledWaiter === "first"
? firstController
: secondController
).abort();
const firstOutcome = await cancelled;
expect(firstOutcome.state).toBe("rejected");
if (firstOutcome.state !== "rejected")
throw new Error("cancelled compilation waiter unexpectedly succeeded");
expect(firstOutcome.cause).toMatchObject({ name: "AbortError" });
await expect(access(state.root)).resolves.toBeUndefined();
await writeFile(fakeCompiler.releasePath, "release");
return { state, outcome: await surviving };
})();
try {
const { state, outcome } = await secondWaiterPromise;
expect(state.calls).toBe(1);
expect(outcome.state).toBe("fulfilled");
if (outcome.state !== "fulfilled") throw outcome.cause;
expect(outcome.value).toBe(state.output);
await reader.close();
await expect(access(state.root)).rejects.toThrow();
} finally {
if (!firstController.signal.aborted) firstController.abort();
if (!secondController.signal.aborted) secondController.abort();
await Promise.allSettled([firstWaiter, secondWaiterPromise]);
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
"retains a failed compilation cleanup for a later close retry",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-process-token-cleanup-retry-test-"),
);
const fakeCompiler = await writeBlockingCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const controller = new AbortController();
const preparation = reader.prepare(controller.signal).then(
() => ({ state: "fulfilled" as const }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
let compilationRoot: string | undefined;
try {
const state = await waitForCompileState(fakeCompiler.statePath);
compilationRoot = state.root;
await writeFile(
join(state.root, "retained.txt"),
"cleanup must remain tracked",
);
await chmod(state.root, 0o000);
controller.abort();
expect((await preparation).state).toBe("rejected");
await expect(reader.close()).rejects.toThrow();
await chmod(state.root, 0o700);
await reader.close();
await expect(access(state.root)).rejects.toThrow();
} finally {
if (!controller.signal.aborted) controller.abort();
await preparation;
if (compilationRoot !== undefined)
await chmod(compilationRoot, 0o700).catch(() => undefined);
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32")(
"aborts and cleans an active compilation when the reader closes",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-process-token-close-compile-test-"),
);
const fakeCompiler = await writeBlockingCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const preparation = reader.prepare().then(
() => ({ state: "fulfilled" as const }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
try {
const state = await waitForCompileState(fakeCompiler.statePath);
await reader.close();
const outcome = await preparation;
expect(outcome.state).toBe("rejected");
if (outcome.state !== "rejected")
throw new Error("closed reader compilation unexpectedly succeeded");
expect(outcome.cause).toMatchObject({ name: "AbortError" });
await expect(access(state.root)).rejects.toThrow();
await expect(reader.prepare()).rejects.toThrow(/reader is closed/u);
await expect(reader.close()).resolves.toBeUndefined();
} finally {
await Promise.allSettled([preparation]);
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32")(
"maps cancellation during native preparation before Electron path resolution",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-electron-token-abort-test-"),
);
const fakeCompiler = await writeBlockingCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const prepareSpy = vi
.spyOn(systemProcessOwnershipHost, "prepare")
.mockImplementation(async (signal) => {
await reader.prepare(signal);
});
const launchSpy = vi.spyOn(electron, "launch");
const controller = new AbortController();
let captureOutcome: Promise<ElectronCaptureOutcome> | undefined;
try {
const input = electronActiveObservationInputSchema.parse({
executable_path: "/missing/electron",
application_path: "/missing/application.js",
});
captureOutcome = new PlaywrightElectronActiveProvider()
.capture(input, { signal: controller.signal })
.then(
(value) => ({ state: "result" as const, value }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
const compileState = await waitForCompileState(fakeCompiler.statePath);
controller.abort();
const outcome = await captureOutcome;
expect(outcome.state).toBe("result");
if (outcome.state !== "result") throw outcome.cause;
expect(outcome.value).toMatchObject({
ok: false,
error: { reason: "cancelled", userCategory: "cancelled" },
});
expect(launchSpy).not.toHaveBeenCalled();
await expect(access(compileState.root)).rejects.toThrow();
} finally {
if (!controller.signal.aborted) controller.abort();
if (captureOutcome !== undefined) await captureOutcome;
prepareSpy.mockRestore();
launchSpy.mockRestore();
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32")(
"preserves cancellation through system-host baseline identity inspection",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-process-baseline-abort-test-"),
);
const fakeCompiler = await writeBlockingIdentityCompiler(directory);
const host = createSystemProcessOwnershipHost("darwin", process.env, {
darwinXcrun: fakeCompiler.executable,
});
const controller = new AbortController();
let helperRoot: string | undefined;
const baseline =
host.captureBaseline?.(controller.signal).then(
() => ({ state: "fulfilled" as const }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
) ?? Promise.resolve({ state: "missing" as const });
try {
if (host.captureBaseline === undefined)
throw new Error("Darwin host did not expose process baselines");
const helper = await waitForIdentityHelper(fakeCompiler.statePath);
helperRoot = helper.root;
controller.abort();
const outcome = await baseline;
expect(outcome.state).toBe("rejected");
if (outcome.state !== "rejected")
throw new Error("aborted identity inspection unexpectedly succeeded");
expect(outcome.cause).toMatchObject({ name: "AbortError" });
expect(
normalizeCaptureFailure(outcome.cause, controller.signal),
).toMatchObject({ reason: "cancelled", userCategory: "cancelled" });
await expect(access(helper.root)).resolves.toBeUndefined();
} finally {
if (!controller.signal.aborted) controller.abort();
await baseline;
await host.close?.();
if (helperRoot !== undefined)
await expect(access(helperRoot)).rejects.toThrow();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(process.platform === "win32")(
"passes Electron cancellation into capture-local baseline inspection",
async () => {
const directory = await mkdtemp(
join(tmpdir(), "rea-electron-baseline-abort-test-"),
);
const fakeCompiler = await writeBlockingIdentityCompiler(directory);
const reader = createDarwinProcessRunTokenReader({
xcrun: fakeCompiler.executable,
});
const prepareSpy = vi
.spyOn(systemProcessOwnershipHost, "prepare")
.mockResolvedValue();
const baselineSpy = vi
.spyOn(systemProcessOwnershipHost, "captureBaseline")
.mockImplementation(async (signal) => {
await reader.identities(
[
{
pid: process.pid,
parentPid: process.ppid,
processGroupId: process.pid,
state: "S",
command: process.execPath,
},
],
signal,
);
return [];
});
const launchSpy = vi.spyOn(electron, "launch");
const controller = new AbortController();
let captureOutcome: Promise<ElectronCaptureOutcome> | undefined;
try {
const input = electronActiveObservationInputSchema.parse({
executable_path: process.execPath,
application_path: fileURLToPath(import.meta.url),
application_root: process.cwd(),
});
captureOutcome = new PlaywrightElectronActiveProvider()
.capture(input, { signal: controller.signal })
.then(
(value) => ({ state: "result" as const, value }),
(cause: unknown) => ({ state: "rejected" as const, cause }),
);
const helper = await waitForIdentityHelper(fakeCompiler.statePath);
controller.abort();
const outcome = await captureOutcome;
expect(outcome.state).toBe("result");
if (outcome.state !== "result") throw outcome.cause;
expect(outcome.value).toMatchObject({
ok: false,
error: { reason: "cancelled", userCategory: "cancelled" },
});
expect(launchSpy).not.toHaveBeenCalled();
await expect(access(helper.root)).resolves.toBeUndefined();
} finally {
if (!controller.signal.aborted) controller.abort();
if (captureOutcome !== undefined) await captureOutcome;
prepareSpy.mockRestore();
baselineSpy.mockRestore();
launchSpy.mockRestore();
await reader.close();
await rm(directory, { recursive: true, force: true });
}
},
);
it.skipIf(!onDarwin)(
"parses exact NUL-delimited token records and rejects truncated argv",
async () => {
const root = await mkdtemp(
join(tmpdir(), "rea-process-token-parser-test-"),
);
const executable = join(root, "parser-test");
const core = fileURLToPath(
new URL(
"../../../bridge/process/ProcessRunTokenReader.swift",
import.meta.url,
),
);
const fixture = fileURLToPath(
new URL(
"../../fixtures/processRunTokenParserProbe.swift",
import.meta.url,
),
);
try {
await execFileOutput(
"/usr/bin/xcrun",
[
"swiftc",
"-module-cache-path",
join(root, "modules"),
core,
fixture,
"-o",
executable,
],
{ timeout: 60_000 },
);
const { stdout } = await execFileAsync(executable, [], {
encoding: "utf8",
timeout: 10_000,
});
expect(JSON.parse(stdout)).toEqual({
argvDecoyIgnored: true,
alternatePaddingRead: true,
appleVectorTokenFailsClosed: true,
clearedAppleVectorTokenFailsClosed: true,
callerPfzBeforeTokenRead: true,
emptyLaterArgumentRead: true,
emptyEnvironmentFailsClosed: true,
emptyArgv0Read: true,
emptyEnvironmentRecordsBeforeTokenFailClosed: true,
duplicateTokenFailsClosed: true,
finalAssignmentArgumentRead: true,
missingAppleBoundaryFailsClosed: true,
nonAsciiPathRead: true,
realTokenRead: true,
reservedArgumentIgnored: true,
truncatedArgvFailsClosed: true,
zeroArgumentsRead: true,
});
} finally {
await rm(root, { recursive: true, force: true });
}
},
);
it.skipIf(!onDarwin)(
"retries a growing process table after ENOMEM and preserves other sysctl errors",
async () => {
const root = await mkdtemp(
join(tmpdir(), "rea-process-snapshot-retry-test-"),
);
const executable = join(root, "snapshot-probe");
const core = fileURLToPath(
new URL(
"../../../bridge/process/ProcessRunTokenReader.swift",
import.meta.url,
),
);
const fixture = fileURLToPath(
new URL(
"../../fixtures/processRunTokenSnapshotProbe.swift",
import.meta.url,
),
);
try {
await execFileOutput(
"/usr/bin/xcrun",
[
"swiftc",
"-module-cache-path",
join(root, "modules"),
core,
fixture,
"-o",
executable,
],
{ timeout: 60_000 },
);
const { stdout } = await execFileAsync(executable, [], {
encoding: "utf8",
timeout: 10_000,
});
expect(JSON.parse(stdout)).toEqual({
preservedOtherErrno: true,
retriedAfterFreshSize: true,
});
} finally {
await rm(root, { recursive: true, force: true });
}
},
);
it.skipIf(!onDarwin)(
"reads only the exact ownership key from live process environments",
async () => {
const host = createSystemProcessOwnershipHost("darwin");
const decoy = await startNodeChild({
DECOY: "words REA_PROCESS_RUN_ID=synthetic-decoy",
});
const owned = await startNodeChild({
REA_PROCESS_RUN_ID: "synthetic-owned",
});
try {
const processes = await host.listProcesses();
const entries = [decoy, owned].map(({ pid }) => {
const entry = processes.find((process) => process.pid === pid);
if (entry === undefined)
throw new Error("test child is absent from process table");
return entry;
});
const observations = await host.runTokens?.(entries);
const identities = await host.processIdentities?.(entries);
expect(observations?.get(decoy.pid)).toEqual({
state: "readable",
runId: undefined,
});
expect(observations?.get(owned.pid)).toEqual({
state: "readable",
runId: "synthetic-owned",
});
expect(identities?.get(decoy.pid)?.state).toBe("readable");
expect(identities?.get(owned.pid)?.state).toBe("readable");
} finally {
await stopNodeChild(decoy.child);
await stopNodeChild(owned.child);
await host.close?.();
}
},
);
it.skipIf(!onDarwin)(
"reads owned tokens with empty later arguments across executable path padding",
async () => {
const root = await mkdtemp(join(tmpdir(), "rea-process-token-padding-"));
const host = createSystemProcessOwnershipHost("darwin");
const children: Awaited<ReturnType<typeof startNodeChild>>[] = [];
try {
const executables = [join(root, "n"), join(root, "node")];
for (const executable of executables)
await symlink(process.execPath, executable);
for (let index = 0; index < executables.length; index += 1) {
const executable = executables[index];
if (executable === undefined)
throw new Error("test executable is missing");
children.push(
await startNodeChild(
{ REA_PROCESS_RUN_ID: `synthetic-padding-${String(index)}` },
executable,
["-e", "setInterval(() => {}, 1_000)", "", "FOO=bar"],
index === 0 ? "" : undefined,
),
);
}
const processes = await host.listProcesses();
const entries = children.map(({ pid }) => {
const entry = processes.find((process) => process.pid === pid);
if (entry === undefined)
throw new Error("owned test child is absent from process table");
return entry;
});
const observations = await host.runTokens?.(entries);
expect(children.map(({ pid }) => observations?.get(pid))).toEqual([
{ state: "readable", runId: "synthetic-padding-0" },
{ state: "readable", runId: "synthetic-padding-1" },
]);
} finally {
for (const { child } of children) await stopNodeChild(child);
await host.close?.();
await rm(root, { recursive: true, force: true });
}
},
);
const startNodeChild = async (
environment: NodeJS.ProcessEnv,
command = process.execPath,
arguments_: readonly string[] = ["-e", "setInterval(() => {}, 1_000)"],
argv0?: string,
) => {
const child = spawn(command, [...arguments_], {
env: environment,
stdio: "ignore",
...(argv0 === undefined ? {} : { argv0 }),
});
if (child.pid === undefined)
throw new Error("test child did not receive a PID");
await new Promise<void>((resolve, reject) => {
child.once("spawn", resolve);
child.once("error", reject);
});
return { child, pid: child.pid };
};
const stopNodeChild = async (child: ChildProcess) => {
if (child.exitCode !== null || child.signalCode !== null) return;
const exited = new Promise<void>((resolve) =>
child.once("exit", () => resolve()),
);
child.kill("SIGKILL");
await exited;
};
@@ -52,6 +52,31 @@ describe("process capture capability diagnostics", () => {
).toContain("spawn EACCES");
});
it("prepares Darwin ownership inspection before probing or admitting a PTY", async () => {
let loaded = false;
const capability = await probeProcessCaptureCapability({
platform: "darwin",
prepareOwnershipInspector: async () => {
throw new Error(
"macOS process ownership inspection requires the Apple Swift compiler via xcrun",
);
},
loadPty: async () => {
loaded = true;
return await import("@lydell/node-pty");
},
});
expect(loaded).toBe(false);
expect(capability).toEqual({
available: false,
backend: "node-pty",
reason: expect.stringContaining(
"requires the Apple Swift compiler via xcrun",
),
});
});
it("keeps the ownership limitation separate from native PTY support", () => {
expect(processCaptureOwnershipUnavailableReason("win32")).toContain(
"Windows PTY process capture",
@@ -1,5 +1,6 @@
import { createHash } from "node:crypto";
import { execFile } from "node:child_process";
import { rm, symlink, writeFile } from "node:fs/promises";
import { access, readFile, rm, symlink, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
@@ -9,7 +10,16 @@ import { itWithCaptureCapability } from "./processCaptureCapability.js";
import { captureProcessScenario } from "../../../src/process/capture/ProcessHarness.js";
import { snapshotRoots } from "../../../src/process/capture/FilesystemSnapshot.js";
import { parseProcessScenario } from "../../../src/domain/process/processCapture.js";
import { ProcessCaptureError } from "../../../src/process/capture/ProcessCaptureError.js";
import {
type ProcessCaptureCleanupHost,
observeLaunchedExecutable,
observeSelectedExecutable,
} from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import {
parseProcessScenario,
type ProcessCapture,
} from "../../../src/domain/process/processCapture.js";
const processFixture = fileURLToPath(
new URL("../../fixtures/processFidelity.mjs", import.meta.url),
@@ -19,6 +29,357 @@ const snapshotCancellationFixture = fileURLToPath(
);
const execFileAsync = promisify(execFile);
type CaptureRun = Awaited<ReturnType<typeof captureProcessScenario>>;
type PartialCapture = Extract<
NonNullable<ProcessCaptureError["partialObservation"]>,
{ readonly capture: unknown }
>["capture"];
const captureObservations = (
result: CaptureRun,
): {
readonly capture: ProcessCapture | PartialCapture;
readonly cleanupIncomplete: boolean;
} => {
if (result.ok) return { capture: result.value, cleanupIncomplete: false };
if (!(result.error instanceof ProcessCaptureError)) throw result.error;
const report = result.error.cleanupReport;
const partial = result.error.partialObservation;
expect(result.error.reason).toBe("cleanup_incomplete");
expect(report?.owned_process_group.state).toBe("unverified");
const [summary, breakdown] = (report?.owned_process_group.reason ?? "").split(
": ",
);
expect(summary).toMatch(
/^process ownership token could not be read for [1-9][0-9]* live process\(es\)$/u,
);
const categories = breakdown?.split(", ") ?? [];
expect(categories.length).toBeGreaterThan(0);
const expectedCategory =
process.platform === "linux"
? /^environment_errno_(?:EACCES|EPERM)=[1-9][0-9]*$/u
: /^environment_unavailable=[1-9][0-9]*$/u;
for (const category of categories) expect(category).toMatch(expectedCategory);
expect(report?.terminal_renderer.state).toBe("cleaned");
expect(report?.temporary_root.state).toBe("cleaned");
if (partial === undefined || !("capture" in partial))
throw new Error(
"cleanup-incomplete capture omitted completed observations",
);
const capture = partial.capture;
expect(capture.settlement.cleanup_outcome).toBe("failed");
return { capture, cleanupIncomplete: true };
};
const processState = async (pid: number): Promise<string | undefined> => {
try {
const { stdout } = await execFileAsync("ps", [
"-o",
"stat=",
"-p",
String(pid),
]);
return stdout.trim() || undefined;
} catch (cause: unknown) {
if (
cause instanceof Error &&
"code" in cause &&
cause.code === 1 &&
"stdout" in cause &&
cause.stdout === ""
)
return undefined;
throw cause;
}
};
const waitForProcessExit = async (pid: number): Promise<void> => {
const deadline = Date.now() + 2_000;
while (Date.now() < deadline) {
const state = await processState(pid);
if (state === undefined || state.startsWith("Z")) return;
await new Promise((resolve) => setTimeout(resolve, 20));
}
throw new Error(`Process ${String(pid)} did not exit within the test bound`);
};
const readDetachedFixturePids = async (marker: string): Promise<number[]> => {
let contents: string;
try {
contents = await readFile(marker, "utf8");
} catch (cause: unknown) {
if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
return [];
throw cause;
}
const parsed: unknown = JSON.parse(contents);
if (typeof parsed !== "object" || parsed === null) return [];
const candidatePids = [
"ownedPid" in parsed ? parsed.ownedPid : undefined,
"unownedPid" in parsed ? parsed.unownedPid : undefined,
];
return candidatePids.flatMap((pid) =>
typeof pid === "number" && Number.isSafeInteger(pid) && pid > 1
? [pid]
: [],
);
};
const terminateFixtureProcess = async (pid: number): Promise<void> => {
try {
process.kill(pid, "SIGKILL");
} catch (cause: unknown) {
if (!(cause instanceof Error && "code" in cause && cause.code === "ESRCH"))
throw cause;
}
await waitForProcessExit(pid);
};
itWithCaptureCapability(
"cleans detached run-token children omitted by sampling and preserves an unowned neighbor",
async () => {
const root = await createTestTempDirectory("rea-detached-cleanup-");
const pidMarker = join(root, "children.json");
let ownedPid: number | undefined;
let unownedPid: number | undefined;
try {
const result = await captureProcessScenario(
parseProcessScenario({
executable: process.execPath,
arguments: [processFixture, "detached-cleanup", pidMarker],
working_directory: root,
settle_ms: 0,
timeout_ms: 5_000,
idle_timeout_ms: 5_000,
limits: { processes: 1 },
}),
);
const { capture, cleanupIncomplete } = captureObservations(result);
const parsed: unknown = JSON.parse(await readFile(pidMarker, "utf8"));
if (
typeof parsed !== "object" ||
parsed === null ||
!("ownedPid" in parsed) ||
typeof parsed.ownedPid !== "number" ||
!("unownedPid" in parsed) ||
typeof parsed.unownedPid !== "number"
)
throw new TypeError("detached-child fixture wrote invalid PIDs");
// Register fixture children before assertions so teardown can clean them
// even when a later expectation fails.
ownedPid = parsed.ownedPid;
unownedPid = parsed.unownedPid;
expect(capture.process_samples.some(({ pid }) => pid === ownedPid)).toBe(
false,
);
if (cleanupIncomplete)
expect(capture.settlement.cleanup_outcome).toBe("failed");
else
expect(result.ok && result.value.cleanup.owned_process_group).toBe(
"verified",
);
await waitForProcessExit(ownedPid);
const unownedState = await processState(unownedPid);
expect(unownedState).toBeDefined();
expect(unownedState?.startsWith("Z")).toBe(false);
} finally {
try {
let fixturePids: number[] = [];
let teardownFailure: unknown;
try {
fixturePids = await readDetachedFixturePids(pidMarker);
} catch (cause: unknown) {
teardownFailure = cause;
}
for (const pid of new Set([
...fixturePids,
...(ownedPid === undefined ? [] : [ownedPid]),
...(unownedPid === undefined ? [] : [unownedPid]),
])) {
try {
await terminateFixtureProcess(pid);
} catch (cause: unknown) {
teardownFailure ??= cause;
}
}
if (teardownFailure !== undefined) throw teardownFailure;
} finally {
await rm(root, { recursive: true, force: true });
}
}
},
10_000,
);
itWithCaptureCapability(
"retains collected observations when completion and cleanup both fail",
async () => {
let snapshotCalls = 0;
const captureSnapshot: typeof snapshotRoots = async () => {
snapshotCalls += 1;
if (snapshotCalls === 1) return { files: [], truncated: false };
throw new Error("fixture final snapshot failure");
};
const cleanupHost: ProcessCaptureCleanupHost = {
platform: process.platform,
cleanupProcessGroup: async () => ({
cleaned: false,
reason: "fixture cleanup could not be verified",
}),
verifyTokenOwnedProcesses: async () => ({
cleaned: false,
reason: "fixture cleanup could not be verified",
}),
removeTemporaryRoot: async (path) =>
rm(path, { recursive: true, force: true }),
};
const result = await captureProcessScenario(
parseProcessScenario({
executable: process.execPath,
arguments: [processFixture, "partial"],
working_directory: dirname(processFixture),
settle_ms: 0,
timeout_ms: 5_000,
idle_timeout_ms: 5_000,
}),
undefined,
process.platform,
process.env,
captureSnapshot,
cleanupHost,
);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("expected cleanup-incomplete failure");
if (!(result.error instanceof ProcessCaptureError)) throw result.error;
const partial = result.error.partialObservation;
expect(result.error.reason).toBe("cleanup_incomplete");
expect(result.error.executionFailure).toBe(
"fixture final snapshot failure",
);
expect(partial).toBeDefined();
if (partial === undefined || !("observations" in partial))
throw new Error("expected incomplete process observations");
const observations = partial.observations;
expect(observations.frames.state).toBe("available");
if (observations.frames.state !== "available")
throw new Error("expected terminal output observations");
expect(
observations.frames.value.map(({ data }) => data).join(""),
).toContain("partial-frame");
expect(observations.rendered_frames.state).toBe("available");
if (observations.rendered_frames.state !== "available")
throw new Error("expected rendered terminal observations");
expect(observations.rendered_frames.value.length).toBeGreaterThan(0);
expect(observations.interaction_events.state).toBe("available");
expect(observations.exit).toMatchObject({
state: "available",
value: { reason: "exited" },
});
expect(observations.settlement.state).toBe("available");
expect(observations.process_samples.state).toBe("available");
expect(observations.target_pid).toEqual({ state: "available", value: 1 });
expect(observations.filesystem_snapshots.before.state).toBe("available");
if (observations.filesystem_snapshots.before.state !== "available")
throw new Error("expected initial filesystem snapshot");
expect(observations.filesystem_snapshots.before.value.truncated).toBe(
false,
);
expect(observations.filesystem_snapshots.after).toEqual({
state: "unavailable",
reason:
"Final filesystem snapshot failed: fixture final snapshot failure",
});
expect(observations.event_journal.state).toBe("available");
if (observations.event_journal.state !== "available")
throw new Error("expected capture event journal");
expect(
observations.event_journal.value.some(
({ collection }) => collection === "lifecycle",
),
).toBe(true);
expect(observations.manifest.state).toBe("unavailable");
expect(snapshotCalls).toBe(2);
},
10_000,
);
itWithCaptureCapability(
"keeps selected executable evidence separate when the path identity changes before validation",
async () => {
const root = await createTestTempDirectory("rea-executable-replaced-");
const executable = join(root, "selected-executable");
await symlink(process.execPath, executable);
try {
const selected = await observeSelectedExecutable(executable);
expect(selected.sha256).toMatch(/^[a-f0-9]{64}$/u);
await rm(executable);
await symlink("/bin/sh", executable);
expect(observeLaunchedExecutable(executable, selected)).toEqual({
selectedSha256: selected.sha256,
sha256: null,
state: "unknown",
reason: "Executable path metadata changed between sampling and spawn.",
});
} finally {
await rm(root, { recursive: true, force: true });
}
},
);
itWithCaptureCapability(
"keeps the prelaunch executable sample when the selected path is replaced during capture",
async () => {
const root = await createTestTempDirectory("rea-executable-identity-");
const executable = join(root, "selected-executable");
const readyMarker = join(root, "child-ready");
await symlink(process.execPath, executable);
const launchedDigest = createHash("sha256")
.update(await readFile(process.execPath))
.digest("hex");
try {
const capturePromise = captureProcessScenario(
parseProcessScenario({
executable,
arguments: [processFixture, "ready-hang", readyMarker],
working_directory: root,
timeout_ms: 1_500,
idle_timeout_ms: 5_000,
}),
);
const deadline = Date.now() + 2_000;
let ready = false;
while (!ready && Date.now() < deadline) {
try {
await access(readyMarker);
ready = true;
} catch {
await new Promise((resolve) => setTimeout(resolve, 10));
}
}
expect(ready).toBe(true);
await rm(executable);
await symlink("/bin/sh", executable);
const result = await capturePromise;
const { capture } = captureObservations(result);
expect(capture.manifest).toMatchObject({
selected_executable_sha256: launchedDigest,
executable_sha256: launchedDigest,
executable_identity: {
state: "path_metadata_unchanged",
reason: null,
},
});
expect(capture.exit.reason).toBe("timeout");
expect(capture.limitations).toContain(
"The executable digest is a prelaunch file sample; matching path metadata immediately after spawn does not prove an atomic operating-system image binding.",
);
} finally {
await rm(root, { recursive: true, force: true });
}
},
10_000,
);
itWithCaptureCapability(
"records external symlink metadata without following the target",
async () => {
@@ -32,16 +393,15 @@ itWithCaptureCapability(
filesystem_observation_paths: [root],
}),
);
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
const escaped = result.value.files_after.find((file) =>
const { capture } = captureObservations(result);
const escaped = capture.files_after.find((file) =>
file.path.endsWith(":escape"),
);
expect(escaped?.symlink_target).toBe("/etc/passwd");
expect(result.value.truncated).toBe(false);
expect(JSON.stringify(result.value.files_after)).not.toContain(root);
expect(capture.truncated).toBe(false);
expect(JSON.stringify(capture.files_after)).not.toContain(root);
expect(
result.value.files_after.some((file) => file.path.includes("passwd")),
capture.files_after.some((file) => file.path.includes("passwd")),
).toBe(false);
} finally {
await rm(root, { recursive: true, force: true });
@@ -61,13 +421,13 @@ itWithCaptureCapability(
idle_timeout_ms: 5_000,
}),
);
expect(timedOut.ok).toBe(true);
if (!timedOut.ok) throw timedOut.error;
expect(timedOut.value.exit.reason).toBe("timeout");
expect(timedOut.value.cleanup).toEqual({
owned_process_group: "verified",
temporary_root: "removed",
});
const timedOutCapture = captureObservations(timedOut);
expect(timedOutCapture.capture.exit.reason).toBe("timeout");
if (!timedOutCapture.cleanupIncomplete && timedOut.ok)
expect(timedOut.value.cleanup).toEqual({
owned_process_group: "verified",
temporary_root: "removed",
});
const controller = new AbortController();
setTimeout(() => controller.abort(), 50);
@@ -212,17 +572,16 @@ itWithCaptureCapability(
idle_timeout_ms: 10_000,
}),
);
if (!result.ok) throw result.error;
expect(result.ok).toBe(true);
const output = result.value.frames.map(({ data }) => data).join("");
const { capture } = captureObservations(result);
const output = capture.frames.map(({ data }) => data).join("");
expect(output).toContain("prompt>");
expect(output).toContain("input:answer unicode:雪");
expect(output).toContain("resize:100x40");
expect(result.value.interaction_events).toMatchObject([
expect(capture.interaction_events).toMatchObject([
{ type: "resize", outcome: "dispatched", scheduled_at_ms: 0 },
{ type: "input", outcome: "dispatched", scheduled_at_ms: 0 },
]);
const resized = result.value.rendered_frames.find(
const resized = capture.rendered_frames.find(
({ columns, rows, lines }) =>
columns === 100 &&
rows === 40 &&
@@ -230,7 +589,7 @@ itWithCaptureCapability(
);
expect(resized).toBeDefined();
expect(resized?.lines.join("\n")).toContain("input:answer unicode:雪");
expect(result.value.exit.code).toBe(0);
expect(capture.exit.code).toBe(0);
},
);
@@ -247,12 +606,11 @@ itWithCaptureCapability(
idle_timeout_ms: 2_000,
}),
);
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
expect(result.value.interaction_events).toMatchObject([
const { capture } = captureObservations(result);
expect(capture.interaction_events).toMatchObject([
{ type: "signal", data: "SIGTERM", outcome: "dispatched" },
]);
expect(result.value.exit).toMatchObject({ signal: 15, reason: "exited" });
expect(capture.exit).toMatchObject({ signal: 15, reason: "exited" });
},
);
@@ -272,24 +630,22 @@ itWithCaptureCapability(
idle_timeout_ms: 20_000,
}),
);
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
expect(result.value.frames.map(({ data }) => data).join("")).toContain(
const { capture } = captureObservations(result);
expect(capture.frames.map(({ data }) => data).join("")).toContain(
"input:answer",
);
expect(result.value.interaction_events).toMatchObject([
expect(capture.interaction_events).toMatchObject([
{ type: "resize", scheduled_at_ms: 25, outcome: "dispatched" },
{ type: "input", scheduled_at_ms: 50, outcome: "dispatched" },
]);
expect(
result.value.interaction_events.every(
capture.interaction_events.every(
({ scheduled_at_ms, dispatched_at_ms }) =>
dispatched_at_ms >= scheduled_at_ms,
),
).toBe(true);
expect(
result.value.frames.find(({ data }) => data.includes("input:answer"))
?.at_ms,
capture.frames.find(({ data }) => data.includes("input:answer"))?.at_ms,
).toBeGreaterThanOrEqual(50);
},
);
@@ -306,13 +662,12 @@ itWithCaptureCapability(
idle_timeout_ms: 20_000,
}),
);
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
expect(result.value.exit).toMatchObject({ code: 0, reason: "exited" });
expect(result.value.frames.map(({ data }) => data).join("")).toContain(
const { capture } = captureObservations(result);
expect(capture.exit).toMatchObject({ code: 0, reason: "exited" });
expect(capture.frames.map(({ data }) => data).join("")).toContain(
"tree-ready",
);
const commands = result.value.process_samples.map(({ command }) => command);
const commands = capture.process_samples.map(({ command }) => command);
expect(commands.some((command) => command.includes("tree-child"))).toBe(
true,
);
@@ -322,7 +677,7 @@ itWithCaptureCapability(
expect(
commands.some((command) => command.includes("tree-grandchild")),
).toBe(true);
expect(JSON.stringify(result.value.process_samples)).toContain(
expect(JSON.stringify(capture.process_samples)).toContain(
dirname(processFixture),
);
const { stdout } = await execFileAsync("ps", ["-axo", "command="]);
@@ -3,6 +3,8 @@ import { expect, it } from "vitest";
import { parseProcessScenario } from "../../../src/domain/process/processScenario.js";
import {
createRunManifest,
observeLaunchedExecutable,
observeSelectedExecutable,
observeSettlement,
} from "../../../src/process/capture/ProcessCaptureLifecycle.js";
@@ -16,10 +18,14 @@ it("uses one selected host identity for manifest and settlement", async () => {
platform: "win32" as const,
architecture: "arm64" as const,
};
const selectedExecutable = await observeSelectedExecutable(
scenario.executable,
);
const manifest = await createRunManifest(
scenario,
new Date(0),
new Date(1),
observeLaunchedExecutable(scenario.executable, selectedExecutable),
selectedHost,
);
const settlement = await observeSettlement(
@@ -0,0 +1,62 @@
import { expect, it, vi } from "vitest";
import { snapshotRoots } from "../../../src/process/capture/FilesystemSnapshot.js";
import { prepareProcessCapture } from "../../../src/process/capture/ProcessCaptureLifecycle.js";
import { parseProcessScenario } from "../../../src/domain/process/processCapture.js";
it("prepares ownership inspection before snapshotting or allocating a target run", async () => {
const failure = new Error("native process identity inspection unavailable");
const createTemporaryRoot = vi.fn(async () => "/unused");
const cleanup = vi.fn(async () => undefined);
const prepareOwnershipInspector = vi.fn(async () => {
throw failure;
});
const captureSnapshot: typeof snapshotRoots = async () => {
throw new Error("snapshot must not run after failed ownership preflight");
};
await expect(
prepareProcessCapture(
parseProcessScenario({
executable: "/bin/true",
working_directory: "/tmp",
}),
undefined,
captureSnapshot,
{ prepareOwnershipInspector, createTemporaryRoot, cleanup },
),
).rejects.toBe(failure);
expect(prepareOwnershipInspector).toHaveBeenCalledOnce();
expect(createTemporaryRoot).not.toHaveBeenCalled();
expect(cleanup).not.toHaveBeenCalled();
});
it("cleans the temporary root when cancellation arrives during identity capture", async () => {
const controller = new AbortController();
const temporaryRoot = "/temporary-capture-root";
const cleanup = vi.fn(async () => undefined);
const host = {
createTemporaryRoot: vi.fn(async () => temporaryRoot),
captureOwnershipBaseline: vi.fn(async (signal?: AbortSignal) => {
expect(signal).toBe(controller.signal);
controller.abort();
return [];
}),
cleanup,
};
await expect(
prepareProcessCapture(
parseProcessScenario({
executable: "/bin/true",
working_directory: "/tmp",
}),
controller.signal,
async () => ({ files: [], truncated: false }),
host,
),
).rejects.toThrow(/cancelled/u);
expect(host.captureOwnershipBaseline).toHaveBeenCalledWith(controller.signal);
expect(cleanup).toHaveBeenCalledWith(temporaryRoot);
});
+50 -1
View File
@@ -8,7 +8,10 @@ import { PendingOperations } from "../../../src/process/PendingOperations.js";
import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";
import { ProviderStartupDeadline } from "../../../src/process/ProviderDeadline.js";
import { cleanupOwnedProcessGroup } from "../../../src/process/ProcessOwnership.js";
import { observeOwnedProcessLineage } from "../../../src/process/ProcessOwnershipObservation.js";
import {
observeOwnedProcessLineage,
systemProcessOwnershipHost,
} from "../../../src/process/ProcessOwnershipObservation.js";
import {
ProviderProcessSupervisor,
spawnOwnedProviderProcess,
@@ -371,6 +374,52 @@ describe("provider process host injection", () => {
});
});
describe("provider startup cancellation", () => {
it("rejects an already cancelled launch before preparing or spawning", async () => {
const controller = new AbortController();
const cancellation = new Error("provider launch already cancelled");
controller.abort(cancellation);
await expect(
spawnOwnedProviderProcess({
command: `${tmpdir()}/rea-provider-must-not-spawn-after-cancel`,
arguments: [],
runId: "provider-process-pre-aborted-run",
signal: controller.signal,
}),
).rejects.toBe(cancellation);
});
it.skipIf(process.platform !== "darwin")(
"forwards cancellation through native ownership preparation before spawning",
async () => {
const controller = new AbortController();
const cancellation = new Error("cancelled during native preparation");
const prepare = vi.spyOn(systemProcessOwnershipHost, "prepare");
prepare.mockImplementation(async (signal) => {
expect(signal).toBe(controller.signal);
await new Promise<void>((resolve) => {
signal?.addEventListener("abort", () => resolve(), { once: true });
});
});
try {
const starting = spawnOwnedProviderProcess({
command: `${tmpdir()}/rea-provider-must-not-spawn-after-cancel`,
arguments: [],
runId: "provider-process-cancelled-preparation-run",
signal: controller.signal,
});
controller.abort(cancellation);
await expect(starting).rejects.toBe(cancellation);
expect(prepare).toHaveBeenCalledOnce();
} finally {
prepare.mockRestore();
}
},
);
});
describe("provider process spawning primitives", () => {
it("spawns an owned process group with exact identity coordinates", async () => {
const runId = "provider-process-run";
+27
View File
@@ -1,4 +1,5 @@
import { spawn } from "node:child_process";
import { writeFile } from "node:fs/promises";
const mode = process.argv[2];
@@ -63,6 +64,32 @@ if (mode === "interactive") {
process.exit(23);
} else if (mode === "hang") {
setInterval(() => undefined, 1_000);
} else if (mode === "ready-hang") {
await writeFile(process.argv[3], "ready");
process.stdout.write("ready\n");
setInterval(() => undefined, 1_000);
} else if (mode === "detached-cleanup") {
const owned = spawn(process.execPath, [process.argv[1], "detached-child"], {
detached: true,
stdio: "ignore",
});
const unowned = spawn(process.execPath, [process.argv[1], "detached-child"], {
detached: true,
env: { ...process.env, REA_PROCESS_RUN_ID: "unowned-neighbor" },
stdio: "ignore",
});
if (owned.pid === undefined || unowned.pid === undefined)
throw new Error("detached fixture children did not receive PIDs");
owned.unref();
unowned.unref();
await writeFile(
process.argv[3],
JSON.stringify({ ownedPid: owned.pid, unownedPid: unowned.pid }),
);
await new Promise((resolve) => setTimeout(resolve, 100));
process.stdout.write("detached-ready\n");
} else if (mode === "detached-child") {
setInterval(() => undefined, 1_000);
} else {
process.stderr.write("unknown fixture mode\n");
process.exit(2);
+176
View File
@@ -0,0 +1,176 @@
import Foundation
func fixture(
arguments: [String],
environment: [String],
pointerSize: Int = 8,
executablePath: String = "/fixture/executable",
appleRecords: [String] = ["pfz=synthetic"],
zeroedPfz: Bool = false
) -> [UInt8] {
var bytes = withUnsafeBytes(of: Int32(arguments.count).littleEndian, Array.init)
let pathBytes = Array(executablePath.utf8)
bytes.append(contentsOf: pathBytes + [0])
let prefixLength = Array("executable_path=".utf8).count
let padding = (pointerSize - ((prefixLength + pathBytes.count + 1) % pointerSize)) % pointerSize
bytes.append(contentsOf: repeatElement(UInt8(0), count: padding))
for argument in arguments { bytes.append(contentsOf: Array(argument.utf8) + [0]) }
for entry in environment { bytes.append(contentsOf: Array(entry.utf8) + [0]) }
if zeroedPfz {
bytes.append(contentsOf: repeatElement(UInt8(0), count: Array("pfz=synthetic".utf8).count + 1))
}
for record in appleRecords { bytes.append(contentsOf: Array(record.utf8) + [0]) }
return bytes
}
@main
struct ProcessRunTokenParserProbe {
static func main() throws {
let argvDecoy = try token(in: fixture(
arguments: ["/fixture/executable", "REA_PROCESS_RUN_ID=argv-decoy", "trailing"],
environment: ["DECOY=words REA_PROCESS_RUN_ID=synthetic-decoy"]
))
let realToken = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["DECOY=words REA_PROCESS_RUN_ID=synthetic-decoy", "REA_PROCESS_RUN_ID=owned-token"]
))
let emptyLaterArgument = try token(in: fixture(
arguments: ["/fixture/executable", "", "after-empty"],
environment: ["REA_PROCESS_RUN_ID=empty-argument-token"],
pointerSize: 8
))
let alternatePadding = try token(in: fixture(
arguments: ["/fixture/executable", "argument"],
environment: ["REA_PROCESS_RUN_ID=alternate-padding-token"],
pointerSize: 4
), pointerSize: 4)
let emptyArgv0Read = try token(in: fixture(
arguments: ["", "", "after-empty"],
environment: ["REA_PROCESS_RUN_ID=empty-argv0-token"],
pointerSize: 8
))
let finalAssignmentArgumentRead = try token(in: fixture(
arguments: ["/fixture/executable", "FOO=bar"],
environment: ["REA_PROCESS_RUN_ID=final-assignment-token"]
))
let reservedArgumentIgnored = try token(in: fixture(
arguments: ["/fixture/executable", "REA_PROCESS_RUN_ID=argv-decoy"],
environment: ["DECOY=words REA_PROCESS_RUN_ID=synthetic-decoy"]
))
let nonAsciiPathRead = try token(in: fixture(
arguments: ["/fixture/é", "FOO=bar"],
environment: ["REA_PROCESS_RUN_ID=utf8-path-token"],
pointerSize: 8,
executablePath: "/fixture/é"
))
let appleVectorTokenFailsClosed: Bool
do {
_ = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["pfz=user-value", "PATH=/usr/bin"],
appleRecords: ["pfz=synthetic", "REA_PROCESS_RUN_ID=apple-decoy"]
))
appleVectorTokenFailsClosed = false
} catch RunTokenReadError.ambiguousEnvironmentBoundary {
appleVectorTokenFailsClosed = true
}
let clearedAppleVectorTokenFailsClosed: Bool
do {
_ = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["REA_PROCESS_RUN_ID=cleared-pfz-owned-token"],
appleRecords: ["REA_PROCESS_RUN_ID=apple-decoy"],
zeroedPfz: true
))
clearedAppleVectorTokenFailsClosed = false
} catch RunTokenReadError.ambiguousEnvironmentBoundary {
clearedAppleVectorTokenFailsClosed = true
}
let callerPfzBeforeTokenRead = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["pfz=caller-value", "REA_PROCESS_RUN_ID=cleared-pfz-owned-token"],
zeroedPfz: true
))
let emptyEnvironmentRecordsBeforeTokenFailClosed: Bool
do {
_ = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["DECOY=value", "", "", "REA_PROCESS_RUN_ID=synthetic-decoy"],
appleRecords: [],
zeroedPfz: true
))
emptyEnvironmentRecordsBeforeTokenFailClosed = false
} catch RunTokenReadError.ambiguousEnvironmentBoundary {
emptyEnvironmentRecordsBeforeTokenFailClosed = true
}
let zeroArgumentsRead = try token(in: fixture(
arguments: [],
environment: ["REA_PROCESS_RUN_ID=zero-argc-token"],
pointerSize: 4
), pointerSize: 4)
var truncatedArgv = withUnsafeBytes(of: Int32(2).littleEndian, Array.init)
let truncatedPath = Array("/fixture/executable".utf8)
truncatedArgv.append(contentsOf: truncatedPath + [0])
let truncatedPadding = (8 - ((Array("executable_path=".utf8).count + truncatedPath.count + 1) % 8)) % 8
truncatedArgv.append(contentsOf: repeatElement(UInt8(0), count: truncatedPadding))
truncatedArgv.append(contentsOf: Array("/fixture/executable".utf8) + [0])
truncatedArgv.append(contentsOf: Array("REA_PROCESS_RUN_ID=synthetic-decoy".utf8))
let truncatedArgvFailsClosed: Bool
do {
_ = try token(in: truncatedArgv)
truncatedArgvFailsClosed = false
} catch {
truncatedArgvFailsClosed = true
}
let duplicateTokenFailsClosed: Bool
do {
_ = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["REA_PROCESS_RUN_ID=first", "REA_PROCESS_RUN_ID=second"]
))
duplicateTokenFailsClosed = false
} catch RunTokenReadError.duplicateToken {
duplicateTokenFailsClosed = true
}
let emptyEnvironmentFailsClosed: Bool
do {
_ = try token(in: fixture(arguments: ["/fixture/executable"], environment: []))
emptyEnvironmentFailsClosed = false
} catch RunTokenReadError.environmentUnavailable {
emptyEnvironmentFailsClosed = true
}
let missingAppleBoundaryFailsClosed: Bool
do {
_ = try token(in: fixture(
arguments: ["/fixture/executable"],
environment: ["REA_PROCESS_RUN_ID=synthetic-decoy"],
appleRecords: []
))
missingAppleBoundaryFailsClosed = false
} catch RunTokenReadError.appleVectorUnavailable {
missingAppleBoundaryFailsClosed = true
}
let result: [String: Any] = [
"argvDecoyIgnored": argvDecoy == nil,
"realTokenRead": realToken == "owned-token",
"emptyLaterArgumentRead": emptyLaterArgument == "empty-argument-token",
"alternatePaddingRead": alternatePadding == "alternate-padding-token",
"truncatedArgvFailsClosed": truncatedArgvFailsClosed,
"duplicateTokenFailsClosed": duplicateTokenFailsClosed,
"emptyEnvironmentFailsClosed": emptyEnvironmentFailsClosed,
"missingAppleBoundaryFailsClosed": missingAppleBoundaryFailsClosed,
"emptyArgv0Read": emptyArgv0Read == "empty-argv0-token",
"finalAssignmentArgumentRead": finalAssignmentArgumentRead == "final-assignment-token",
"reservedArgumentIgnored": reservedArgumentIgnored == nil,
"nonAsciiPathRead": nonAsciiPathRead == "utf8-path-token",
"appleVectorTokenFailsClosed": appleVectorTokenFailsClosed,
"clearedAppleVectorTokenFailsClosed": clearedAppleVectorTokenFailsClosed,
"callerPfzBeforeTokenRead": callerPfzBeforeTokenRead == "cleared-pfz-owned-token",
"emptyEnvironmentRecordsBeforeTokenFailClosed": emptyEnvironmentRecordsBeforeTokenFailClosed,
"zeroArgumentsRead": zeroArgumentsRead == "zero-argc-token",
]
let output = try JSONSerialization.data(withJSONObject: result, options: [.sortedKeys])
FileHandle.standardOutput.write(output)
}
}
+40
View File
@@ -0,0 +1,40 @@
import Darwin
import Foundation
@main
struct ProcessRunTokenSnapshotProbe {
static func main() throws {
var sizeQueries = 0
var readAttempts = 0
let retried = readProcessSnapshot { _, output, size in
guard output != nil else {
sizeQueries += 1
size = MemoryLayout<kinfo_proc>.stride
return 0
}
readAttempts += 1
if readAttempts == 1 {
errno = ENOMEM
return -1
}
size = 0
return 0
}
let otherError = readProcessSnapshot { _, output, size in
if output == nil {
size = MemoryLayout<kinfo_proc>.stride
return 0
}
errno = EACCES
return -1
}
let output: [String: Any] = [
"retriedAfterFreshSize": retried.failure == nil && sizeQueries == 2 && readAttempts == 2,
"preservedOtherErrno": otherError.failure == "process_table_failed_\(EACCES)"
]
let data = try JSONSerialization.data(withJSONObject: output, options: [.sortedKeys])
FileHandle.standardOutput.write(data)
}
}