rea-agents 1.1.0 → 1.3.0

package/dist/application/LinuxHopper.js

@@ -1,14 +1,31 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
 import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { z } from "zod";
 const execFileAsync = promisify(execFile);
-const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
+const SUPPORTED_HOPPER_SHA256 = "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded";
+const SUPPORTED_RELEASES = {
+    deb: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
+        file_length: "35755772",
+        file_hash: "e4f79dff602648a8ff4a88b773875b6bfac0dc65",
+    },
+    rpm: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.rpm`,
+        file_length: "32264475",
+        file_hash: "b9a65f2f583a386d440d4401d9140aef3bf305de",
+    },
+    arch: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.pkg.tar.xz`,
+        file_length: "29405968",
+        file_hash: "92d780b61cab38eda95dc4112dee4fbeb0920f46",
+    },
+};
 /** Parse an os-release document without executing its shell syntax. */
 export const parseLinuxDistribution = (text) => {
     const fields = new Map();
@@ -57,15 +74,7 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         return { status: "failed", reason: "unsupported_host" };
     let temporary;
     try {
-        const metadataDownload = await host.download(RELEASES_URL, options);
-        if (!metadataDownload.ok)
-            return { status: "failed", reason: "release_metadata" };
-        const releases = parseReleases(metadataDownload.bytes);
-        if (releases === undefined)
-            return { status: "failed", reason: "release_metadata" };
-        const release = releases[releaseKey(distribution.packageFamily)];
-        if (!release.filename.startsWith(DOWNLOAD_PREFIX))
-            return { status: "failed", reason: "release_metadata" };
+        const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
         const archiveDownload = await host.download(release.filename, options);
         if (!archiveDownload.ok)
             return { status: "failed", reason: "download" };
@@ -77,8 +86,12 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         if (!(await host.installPackage(distribution.packageFamily, archive)))
             return { status: "failed", reason: "authorization_or_package_manager" };
         const launcherPath = "/opt/hopper/bin/Hopper";
-        if (!(await host.launcherReady(launcherPath)))
-            return { status: "failed", reason: "launcher_missing" };
+        const launcherStatus = await host.launcherStatus(launcherPath);
+        if (launcherStatus !== "ready")
+            return {
+                status: "failed",
+                reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
+            };
         return { status: "installed", launcherPath };
     }
     catch (cause) {
@@ -108,24 +121,40 @@ const systemLinuxHopperInstallHost = () => ({
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
     installPackage: installSystemPackage,
-    async launcherReady(path) {
+    async launcherStatus(path) {
         try {
             await access(path);
             const linked = await execFileAsync("ldd", [path]);
-            return linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`);
+            if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
+                return "runtime_dependencies";
+            return (await linuxHopperBinarySupported(path))
+                ? "ready"
+                : "unsupported_hopper_build";
         }
         catch {
-            return false;
+            return "missing";
         }
     },
     cleanup: (path) => rm(path, { recursive: true, force: true }),
 });
+/** Match the Linux Hopper build validated by the packaged demo-dialog adapter. */
+export const linuxHopperBinarySupported = async (path) => {
+    try {
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(path))
+            hash.update(chunk);
+        return hash.digest("hex") === SUPPORTED_HOPPER_SHA256;
+    }
+    catch {
+        return false;
+    }
+};
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive) => {
     try {
-        const command = linuxPackageManagerCommand(family, archive, process.getuid?.() === 0);
-        await execFileAsync(command.executable, command.args);
+        for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
+            await execFileAsync(command.executable, command.args);
         return true;
     }
     catch {
@@ -133,26 +162,32 @@ const installSystemPackage = async (family, archive) => {
     }
 };
 /** Select the native package manager and authorization boundary without shell evaluation. */
-export const linuxPackageManagerCommand = (family, archive, isRoot) => {
-    const command = family === "deb"
-        ? ["apt-get", "install", "-y", archive]
+export const linuxPackageManagerCommands = (family, archive, isRoot) => {
+    const runtimeDependencies = family === "deb"
+        ? ["xvfb", "xauth", "python3", "libx11-6", "libxtst6"]
         : family === "rpm"
-            ? ["dnf", "install", "-y", archive]
-            : ["pacman", "-U", "--noconfirm", archive];
-    const executable = isRoot ? command[0] : "pkexec";
-    if (executable === undefined)
-        throw new Error("package command is empty");
-    return { executable, args: isRoot ? command.slice(1) : command };
-};
-const parseReleases = (bytes) => {
-    try {
-        const parsed = JSON.parse(new TextDecoder().decode(bytes));
-        const result = releasesSchema.safeParse(parsed);
-        return result.success ? result.data : undefined;
-    }
-    catch {
-        return undefined;
-    }
+            ? [
+                "xorg-x11-server-Xvfb",
+                "xorg-x11-xauth",
+                "python3",
+                "libX11",
+                "libXtst",
+            ]
+            : ["xorg-server-xvfb", "xorg-xauth", "python", "libx11", "libxtst"];
+    const commands = family === "deb"
+        ? [["apt-get", "install", "-y", archive, ...runtimeDependencies]]
+        : family === "rpm"
+            ? [["dnf", "install", "-y", archive, ...runtimeDependencies]]
+            : [
+                ["pacman", "-S", "--needed", "--noconfirm", ...runtimeDependencies],
+                ["pacman", "-U", "--noconfirm", archive],
+            ];
+    return commands.map((command) => {
+        const executable = isRoot ? command[0] : "pkexec";
+        if (executable === undefined)
+            throw new Error("package command is empty");
+        return { executable, args: isRoot ? command.slice(1) : command };
+    });
 };
 const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
     bytes.byteLength <= MAX_PACKAGE_BYTES &&
@@ -172,15 +207,4 @@ const packageFamilyFor = (id, idLike) => {
 };
 const versionAtLeast = (version, minimum) => version !== undefined &&
     Number.parseInt(version.split(".")[0] ?? "0", 10) >= minimum;
-const releaseKey = (family) => family === "deb" ? "Ubuntu / Mint" : family === "rpm" ? "Fedora" : "Arch";
 const isAbortCause = (cause) => cause instanceof Error && cause.name === "AbortError";
-const releaseSchema = z.object({
-    filename: z.string().url(),
-    file_length: z.string().regex(/^\d+$/u),
-    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
-});
-const releasesSchema = z.object({
-    "Ubuntu / Mint": releaseSchema,
-    Fedora: releaseSchema,
-    Arch: releaseSchema,
-});

package/dist/application/ProcessCaptureAuthority.js

@@ -0,0 +1,25 @@
+import { realpath } from "node:fs/promises";
+import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
+const isWithin = (candidate, root) => candidate === root ||
+    candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
+export const assertRealPathAuthority = async (scenario, policy) => {
+    const executable = await realpath(scenario.executable);
+    const executableRoots = await Promise.all(policy.executableRoots.map((root) => realpath(root)));
+    if (!executableRoots.some((root) => isWithin(executable, root)))
+        throw new ProcessCaptureError("resolved executable is outside approved roots");
+    const workingDirectory = await realpath(scenario.working_directory);
+    const workingRoots = await Promise.all(policy.workingRoots.map((root) => realpath(root)));
+    if (!workingRoots.some((root) => isWithin(workingDirectory, root)))
+        throw new ProcessCaptureError("resolved working directory is outside approved roots");
+    for (const root of scenario.filesystem_roots) {
+        const resolvedRoot = await realpath(root);
+        if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))
+            throw new ProcessCaptureError("resolved filesystem root is outside approved roots");
+    }
+};
+/** Expected refusal or runtime failure from the process capture adapter. */
+export const assertNotCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw processCaptureCancelled();
+};
+/** Runtime availability of the native PTY adapter on this host. */

package/dist/application/ProcessCaptureCapability.js

@@ -0,0 +1,23 @@
+import { tmpdir } from "node:os";
+import { spawn } from "node-pty";
+/** Probe the actual native PTY seam instead of inferring support from the OS name. */
+export const probeProcessCaptureCapability = async () => {
+    try {
+        const terminal = spawn(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {
+            cwd: tmpdir(),
+            env: { HOME: tmpdir(), TERM: "xterm-256color" },
+            cols: 80,
+            rows: 24,
+            name: "xterm-256color",
+        });
+        await new Promise((resolveExit) => terminal.onExit(() => resolveExit()));
+        return { available: true, backend: "node-pty" };
+    }
+    catch {
+        return {
+            available: false,
+            backend: "node-pty",
+            reason: "the native PTY backend could not start a probe process",
+        };
+    }
+};

package/dist/application/ProcessCaptureError.js

@@ -0,0 +1,17 @@
+import { AnalysisError } from "../domain/errors.js";
+/** Typed application failure produced by controlled process capture. */
+export class ProcessCaptureError extends AnalysisError {
+    _tag = "ProcessCaptureError";
+    userMessage;
+    userCategory;
+    constructor(message, options) {
+        super(message, options);
+        this.userMessage = options?.userMessage;
+        this.userCategory = options?.userCategory;
+    }
+}
+/** Caller-visible cancellation without exposing capture implementation state. */
+export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
+    userCategory: "cancelled",
+    userMessage: "Process capture was cancelled. Start it again when ready.",
+});

package/dist/application/ProcessCaptureLifecycle.js

@@ -0,0 +1,287 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { authorizeProcessScenario, digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { snapshotRoots } from "./FilesystemSnapshot.js";
+import { cleanupOwnedProcessGroup, observeOwnedProcessGroup, } from "./ProcessOwnership.js";
+import { classifyFilesystemEffects, ProcessCheckpoints, } from "./ProcessCheckpoints.js";
+import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { assertNotCancelled, assertRealPathAuthority, } from "./ProcessCaptureAuthority.js";
+import { normalizeProcessSamples, normalizeProcessText, redactProtocolEvents, } from "./ProcessNormalization.js";
+import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
+import { TerminalRenderer } from "./TerminalRenderer.js";
+export const buildCaptureResult = (options) => ({
+    schema_version: 4,
+    manifest: options.manifest,
+    normalization: options.scenario.normalization,
+    frames: options.frames,
+    rendered_frames: [...options.renderedFrames]
+        .sort((left, right) => left.at_ms - right.at_ms || left.sequence - right.sequence)
+        .map((frame, sequence) => ({ ...frame, sequence })),
+    interaction_events: options.interactions,
+    exit: {
+        code: options.exit.reason === "exited" && options.exit.exitCode >= 0
+            ? options.exit.exitCode
+            : null,
+        signal: options.exit.signal ?? null,
+        reason: options.exit.reason,
+    },
+    settlement: options.settlement,
+    process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
+    filesystem_checkpoints: options.checkpoints,
+    shim_events: options.shimEvents,
+    protocol_events: redactProtocolEvents(options.replay.events, options.scenario),
+    files_before: options.before.files,
+    files_after: options.after.files,
+    filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
+    truncated: options.truncated,
+    limitations: [
+        "Process trees are sampled and may omit short-lived descendants.",
+        ...(options.samplingPartial
+            ? ["Process-tree sampling ended with an incomplete observation."]
+            : []),
+        "Filesystem observations are before/after snapshots, not syscall traces.",
+        "The harness does not enforce external network isolation.",
+    ],
+    residual_unknowns: [
+        {
+            scope: "process",
+            reason: "Process trees are sampled and may omit short-lived descendants.",
+        },
+        {
+            scope: "network",
+            reason: "External network isolation is not enforced by this adapter.",
+        },
+    ],
+    cleanup: {
+        owned_process_group: "verified",
+        temporary_root: "removed",
+    },
+});
+const hashFile = async (path) => {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+};
+export const createRunManifest = async (scenario, startedAt, completedAt) => {
+    const executableSha256 = await hashFile(scenario.executable);
+    const scenarioCommitment = processScenarioCommitment(scenario, executableSha256);
+    const comparisonContract = processComparisonContract(scenario);
+    return {
+        rea_version: PRODUCT_IDENTITY.packageVersion,
+        provider_version: PROCESS_PROVIDER.version,
+        platform: process.platform,
+        architecture: process.arch,
+        pty_backend: "node-pty",
+        started_at: startedAt.toISOString(),
+        completed_at: completedAt.toISOString(),
+        scenario: scenarioCommitment,
+        comparison_contract: comparisonContract,
+        shim_plan: scenario.command_shims,
+        replay_plan: scenario.replay,
+        full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
+        comparison_contract_sha256: digestProcessCommitment(comparisonContract),
+        executable_sha256: executableSha256,
+        normalization_sha256: digestProcessCommitment(scenario.normalization),
+        shim_plan_sha256: digestProcessCommitment(scenario.command_shims),
+        replay_plan_sha256: digestProcessCommitment(scenario.replay),
+    };
+};
+export const observeSettlement = async (runId, processGroupIds, settleMs) => {
+    if (process.platform === "win32")
+        return { state: "unverifiable", elapsed_ms: 0 };
+    const started = Date.now();
+    let consecutiveEmpty = 0;
+    let deadlineReached = false;
+    while (!deadlineReached) {
+        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({
+            runId,
+            leaderPid: processGroupId,
+            processGroupId,
+        })));
+        if (observations.some(({ state }) => state === "unverifiable"))
+            return { state: "unverifiable", elapsed_ms: Date.now() - started };
+        if (observations.every(({ state }) => state === "empty")) {
+            consecutiveEmpty += 1;
+            if (consecutiveEmpty >= 2)
+                return { state: "quiesced", elapsed_ms: Date.now() - started };
+        }
+        else
+            consecutiveEmpty = 0;
+        deadlineReached = Date.now() - started >= settleMs;
+        if (deadlineReached)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
+};
+export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, }) => new Promise((resolveExit) => {
+    // The kill caused by a deadline is observed later as an ordinary PTY exit.
+    // Keep the initiating lifecycle reason so comparisons distinguish a target
+    // exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
+    let reason = "exited";
+    terminal.onExit((exit) => {
+        for (const [eventIndex, event] of scenario.events.entries()) {
+            if (dispatchedEventIndexes.has(eventIndex))
+                continue;
+            interactions.push({
+                sequence: interactions.length,
+                scheduled_at_ms: event.at_ms,
+                dispatched_at_ms: Math.max(0, Date.now() - started),
+                type: event.type,
+                data: event.type === "input"
+                    ? "<not-dispatched>"
+                    : event.type === "resize"
+                        ? `${String(event.columns)}x${String(event.rows)}`
+                        : event.signal,
+                outcome: "target_exited",
+            });
+        }
+        for (const timer of timers) {
+            clearTimeout(timer);
+            clearInterval(timer);
+        }
+        timers.clear();
+        resolveExit({ ...exit, reason });
+    });
+    const timeout = setInterval(() => {
+        if (signal?.aborted === true) {
+            reason = "cancelled";
+            terminal.kill("SIGKILL");
+        }
+        else if (Date.now() - started >= scenario.timeout_ms) {
+            reason = "timeout";
+            terminal.kill("SIGKILL");
+        }
+        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
+            reason = "idle_timeout";
+            terminal.kill("SIGKILL");
+        }
+    }, 20);
+    timers.add(timeout);
+});
+export const releaseProcessResources = async (options) => {
+    for (const timer of options.timers)
+        clearTimeout(timer);
+    let failure;
+    try {
+        await options.replay?.close();
+    }
+    catch {
+        failure = "loopback replay cleanup failed";
+    }
+    try {
+        await options.shimReplay?.close();
+    }
+    catch {
+        failure ??= "command shim replay cleanup failed";
+    }
+    try {
+        await options.renderer?.dispose();
+    }
+    catch {
+        failure ??= "terminal renderer cleanup failed";
+    }
+    try {
+        await options.checkpoints?.dispose();
+    }
+    catch {
+        failure ??= "filesystem checkpoint cleanup failed";
+    }
+    if (options.terminal !== undefined && process.platform !== "win32") {
+        const processGroupIds = new Set([
+            options.terminal.pid,
+            ...options.sampledProcessGroupIds,
+        ]);
+        for (const processGroupId of processGroupIds) {
+            const cleaned = await cleanupOwnedProcessGroup({
+                runId: options.runId,
+                leaderPid: processGroupId,
+                processGroupId,
+            });
+            if (!cleaned.cleaned)
+                failure ??= cleaned.reason;
+        }
+    }
+    try {
+        await rm(options.temporaryRoot, { recursive: true, force: true });
+    }
+    catch {
+        failure ??= "temporary process root cleanup failed";
+    }
+    return failure;
+};
+export const captureTerminalFrames = (options) => {
+    let outputBytes = 0;
+    let truncated = false;
+    options.terminal.onData((data) => {
+        options.onFirstOutput();
+        options.onOutput();
+        const bytes = Buffer.byteLength(data);
+        if (options.frames.length >= options.scenario.limits.frames ||
+            outputBytes + bytes > options.scenario.limits.output_bytes) {
+            truncated = true;
+            return;
+        }
+        outputBytes += bytes;
+        const atMs = Math.floor((Date.now() - options.started) /
+            options.scenario.normalization.time_bucket_ms) * options.scenario.normalization.time_bucket_ms;
+        const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
+        options.frames.push({
+            sequence: options.frames.length,
+            at_ms: atMs,
+            data: normalized,
+        });
+        options.renderer.write(data, atMs);
+        options.checkpoints.observeTerminal(normalized);
+    });
+    return () => truncated;
+};
+export const resolveProcessResult = (capture, executionFailure, cleanupFailure) => {
+    if (executionFailure instanceof ProcessCaptureError)
+        throw executionFailure;
+    if (executionFailure !== undefined)
+        throw new ProcessCaptureError("process capture failed", {
+            cause: executionFailure,
+        });
+    if (cleanupFailure !== undefined)
+        throw new ProcessCaptureError(cleanupFailure);
+    if (capture === undefined)
+        throw new ProcessCaptureError("process capture produced no result");
+    return capture;
+};
+export const prepareProcessCapture = async (scenario, policy, signal) => {
+    const decision = authorizeProcessScenario(scenario, policy);
+    if (!decision.allowed)
+        throw new ProcessCaptureError(decision.reason, {
+            userCategory: "permission_required",
+            userMessage: processPolicyMessage(decision.reason),
+        });
+    await assertRealPathAuthority(scenario, policy);
+    assertNotCancelled(signal);
+    const before = await snapshotRoots(scenario, signal);
+    const temporaryRoot = await mkdtemp(join(tmpdir(), "rea-process-"));
+    const runId = randomUUID();
+    const home = join(temporaryRoot, "home");
+    await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
+    return { temporaryRoot, runId, home, before };
+};
+const processPolicyMessage = (reason) => {
+    if (reason === "process capture is disabled")
+        return "Process capture is disabled. Set `REA_PROCESS_CAPTURE_ENABLED=true`, configure approved roots, then restart REA.";
+    if (reason === "host network access is not approved by operator policy")
+        return "This capture requests host network access, but policy does not allow it. Use replayed network access or ask the operator to enable external network capture.";
+    if (reason === "executable is outside approved roots")
+        return "The executable is outside the approved capture directories. Choose an approved executable or add its directory to `REA_PROCESS_EXECUTABLE_ROOTS_JSON`.";
+    if (reason === "working directory is outside approved roots")
+        return "The working directory is outside the approved capture directories. Choose an approved directory or add it to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "filesystem root is outside approved roots")
+        return "A requested filesystem root is outside the approved capture directories. Remove it or add its directory to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "scenario requests an environment variable not allowed by policy")
+        return "The capture requests an environment variable that policy does not allow. Remove it or add its name to `REA_PROCESS_ALLOWED_ENV_JSON`.";
+    return reason;
+};

package/dist/application/ProcessCheckpoints.js

@@ -0,0 +1,129 @@
+import { snapshotRoots } from "./FilesystemSnapshot.js";
+/** Classify path-stable filesystem effects between two bounded states. */
+export const classifyFilesystemEffects = (before, after) => {
+    const beforeByPath = new Map(before.map((file) => [file.path, file]));
+    const afterByPath = new Map(after.map((file) => [file.path, file]));
+    return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
+        .sort()
+        .map((path) => {
+        const beforeFile = beforeByPath.get(path) ?? null;
+        const afterFile = afterByPath.get(path) ?? null;
+        const status = beforeFile === null
+            ? "created"
+            : afterFile === null
+                ? "deleted"
+                : JSON.stringify(beforeFile) === JSON.stringify(afterFile)
+                    ? "unchanged"
+                    : "modified";
+        return { path, status, before: beforeFile, after: afterFile };
+    });
+};
+/** Coordinates named lifecycle filesystem observations without overlapping scans. */
+export class ProcessCheckpoints {
+    scenario;
+    started;
+    signal;
+    #captures = [];
+    #captured = new Set();
+    #terminalCounts = new Map();
+    #terminalTails = new Map();
+    #timers = new Set();
+    #pending = Promise.resolve();
+    constructor(scenario, started, before, signal) {
+        this.scenario = scenario;
+        this.started = started;
+        this.signal = signal;
+        this.#captures.push({
+            name: "before",
+            at_ms: 0,
+            files: before.files,
+            effects: [],
+            truncated: before.truncated,
+        });
+        this.#captured.add("before");
+        for (const checkpoint of scenario.checkpoints) {
+            if (checkpoint.trigger.type !== "time")
+                continue;
+            const timer = setTimeout(() => this.capture(checkpoint.name), checkpoint.trigger.at_ms);
+            this.#timers.add(timer);
+        }
+    }
+    /** Observe normalized terminal text and fire matching literal checkpoints once. */
+    observeTerminal(data) {
+        for (const checkpoint of this.scenario.checkpoints) {
+            const trigger = checkpoint.trigger;
+            if (trigger.type !== "terminal_literal" ||
+                this.#captured.has(checkpoint.name))
+                continue;
+            const combined = `${this.#terminalTails.get(checkpoint.name) ?? ""}${data}`;
+            const count = (this.#terminalCounts.get(checkpoint.name) ?? 0) +
+                countOccurrences(combined, trigger.value);
+            this.#terminalCounts.set(checkpoint.name, count);
+            this.#terminalTails.set(checkpoint.name, trigger.value.length === 1
+                ? ""
+                : combined.slice(-(trigger.value.length - 1)));
+            if (count >= trigger.occurrence)
+                this.capture(checkpoint.name);
+        }
+    }
+    /** Capture every checkpoint assigned to the specified lifecycle trigger. */
+    trigger(type) {
+        for (const checkpoint of this.scenario.checkpoints)
+            if (checkpoint.trigger.type === type)
+                this.capture(checkpoint.name);
+    }
+    /** Queue one idempotent named snapshot. */
+    capture(name) {
+        if (this.#captured.has(name))
+            return;
+        this.#captured.add(name);
+        // Serialize scans even when time, terminal, and lifecycle triggers fire
+        // together. Each effect set is intentionally relative to the immediately
+        // preceding checkpoint, which preserves transient create/delete behavior.
+        this.#pending = this.#pending.then(async () => {
+            const snapshot = await snapshotRoots(this.scenario, this.signal);
+            const previous = this.#captures.at(-1)?.files ?? [];
+            this.#captures.push({
+                name,
+                at_ms: Math.max(0, Date.now() - this.started),
+                files: snapshot.files,
+                effects: classifyFilesystemEffects(previous, snapshot.files),
+                truncated: snapshot.truncated,
+            });
+        });
+    }
+    /** Finish pending snapshots and return them in observation order. */
+    async finish(after) {
+        for (const timer of this.#timers)
+            clearTimeout(timer);
+        await this.#pending;
+        const previous = this.#captures.at(-1)?.files ?? [];
+        this.#captures.push({
+            name: "after_settlement",
+            at_ms: Math.max(0, Date.now() - this.started),
+            files: after.files,
+            effects: classifyFilesystemEffects(previous, after.files),
+            truncated: after.truncated,
+        });
+        return this.#captures;
+    }
+    /** Cancel scheduled captures and await any snapshot already in progress. */
+    async dispose() {
+        for (const timer of this.#timers)
+            clearTimeout(timer);
+        this.#timers.clear();
+        await this.#pending;
+    }
+}
+const countOccurrences = (text, value) => {
+    let count = 0;
+    let offset = 0;
+    while (offset <= text.length - value.length) {
+        const found = text.indexOf(value, offset);
+        if (found < 0)
+            break;
+        count += 1;
+        offset = found + value.length;
+    }
+    return count;
+};