rea-agents 6.2.0 → 6.4.0

package/dist/process/capture/ProcessCaptureLifecycle.js

@@ -10,7 +10,7 @@ import { PRODUCT_IDENTITY } from "../../identity.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { cleanupOwnedProcessGroup, verifyNoTokenOwnedProcesses, } from "../ProcessOwnership.js";
-import { observeOwnedProcessGroup, prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "../ProcessOwnershipObservation.js";
+import { observeOwnedProcessGroups, prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "../ProcessOwnershipObservation.js";
 import { describeProcessCaptureExecutionFailure, normalizeCaptureFailure, ProcessCaptureError, } from "./ProcessCaptureError.js";
 import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
 import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } from "./ProcessNormalization.js";
@@ -35,6 +35,14 @@ export const createProcessCaptureObservationBuffer = (options) => ({
         state: "unavailable",
         reason: "Terminal exit was not observed before the run failed.",
     },
+    ...(options.finalizationEnabled === true
+        ? {
+            finalization: {
+                state: "unavailable",
+                reason: "Finalization was not observed before capture completion finished.",
+            },
+        }
+        : {}),
     settlement: {
         state: "unavailable",
         reason: "Process settlement was not observed before capture completion finished.",
@@ -43,10 +51,7 @@ export const createProcessCaptureObservationBuffer = (options) => ({
     filesystem_snapshots: {
         before: {
             state: "available",
-            value: {
-                files: options.before.files,
-                truncated: options.before.truncated,
-            },
+            value: options.before,
         },
         after: {
             state: "unavailable",
@@ -97,8 +102,9 @@ export const buildCaptureResult = (options) => {
     const filesystemObservationUnknown = "No filesystem observation paths were selected; filesystem effects remain unknown.";
     const hasFilesystemObservations = options.scenario.filesystem_observation_paths.length > 0;
     const filesystemEffects = classifyFilesystemEffects(options.before, options.after);
-    const hasUnknownFilesystemEffects = filesystemEffects.some(({ status }) => status === "unknown");
-    const incompleteFilesystemUnknown = "Path absence in incomplete enumeration or below an unfollowed symbolic link remains unknown.";
+    const filesystemUnknowns = [
+        ...new Set(filesystemEffects.flatMap((effect) => effect.status === "unknown" ? [effect.reason] : [])),
+    ];
     return {
         manifest: options.manifest,
         normalization: options.scenario.normalization,
@@ -111,6 +117,9 @@ export const buildCaptureResult = (options) => {
                 : null,
             signal: options.exit.signal ?? null,
             reason: options.exit.reason,
+            ...(options.exit.finalization === undefined
+                ? {}
+                : { finalization: options.exit.finalization }),
         },
         settlement: options.settlement,
         process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
@@ -119,12 +128,8 @@ export const buildCaptureResult = (options) => {
         files_before: options.before.files,
         files_after: options.after.files,
         filesystem_effects: filesystemEffects,
-        truncated: options.truncationDetails === undefined
-            ? options.truncated
-            : hasCaptureTruncation(options.truncationDetails),
-        ...(options.truncationDetails === undefined
-            ? {}
-            : { truncation_details: options.truncationDetails }),
+        truncated: hasCaptureTruncation(options.truncationDetails),
+        truncation_details: options.truncationDetails,
         limitations: [
             "The executable digest is a prelaunch file sample; matching path metadata immediately after spawn does not prove an atomic operating-system image binding.",
             "Process trees are sampled and may omit short-lived descendants.",
@@ -134,10 +139,8 @@ export const buildCaptureResult = (options) => {
             "Filesystem observations are before/after snapshots, not syscall traces.",
             "Inherited host environment variables are not recorded and may affect results.",
             ...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
-            ...(hasUnknownFilesystemEffects ? [incompleteFilesystemUnknown] : []),
-            ...(options.truncationDetails === undefined
-                ? []
-                : captureCoverageUnknowns(options.truncationDetails).map(({ reason }) => reason)),
+            ...filesystemUnknowns,
+            ...captureCoverageUnknowns(options.truncationDetails).map(({ reason }) => reason),
             ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
         ],
         residual_unknowns: [
@@ -165,20 +168,14 @@ export const buildCaptureResult = (options) => {
                     },
                 ]
                 : []),
-            ...(hasUnknownFilesystemEffects
-                ? [
-                    {
-                        scope: "filesystem",
-                        reason: incompleteFilesystemUnknown,
-                    },
-                ]
-                : []),
+            ...filesystemUnknowns.map((reason) => ({
+                scope: "filesystem",
+                reason,
+            })),
             ...(hasSensitiveScriptedInput
                 ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
                 : []),
-            ...(options.truncationDetails === undefined
-                ? []
-                : captureCoverageUnknowns(options.truncationDetails).filter(({ scope }) => scope !== "terminal")),
+            ...captureCoverageUnknowns(options.truncationDetails).filter(({ scope }) => scope !== "terminal"),
         ],
     };
 };
@@ -363,8 +360,9 @@ export const createRunManifest = async (scenario, startedAt, completedAt, execut
         normalization_sha256: digestProcessCommitment(scenario.normalization),
     };
 };
-export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform, signal) => {
+export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform, signal, onLiveProgress) => {
     assertNotCancelled(signal);
+    onLiveProgress?.();
     if (platform === "win32") {
         recordEvent("lifecycle", 1);
         return { state: "unverifiable", elapsed_ms: 0 };
@@ -373,14 +371,15 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
     let consecutiveEmpty = 0;
     let deadlineReached = false;
     while (!deadlineReached) {
+        onLiveProgress?.();
         assertNotCancelled(signal);
-        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({ runId, leaderPid: processGroupId, processGroupId }, undefined, signal)));
+        const observations = await observeOwnedProcessGroups(runId, processGroupIds, undefined, signal);
         assertNotCancelled(signal);
-        if (observations.some(({ state }) => state === "unverifiable")) {
+        if ([...observations.values()].some(({ state }) => state === "unverifiable")) {
             recordEvent("lifecycle", 1);
             return { state: "unverifiable", elapsed_ms: Date.now() - started };
         }
-        if (observations.every(({ state }) => state === "empty")) {
+        if ([...observations.values()].every(({ state }) => state === "empty")) {
             consecutiveEmpty += 1;
             if (consecutiveEmpty >= 2) {
                 recordEvent("lifecycle", 1);
@@ -397,12 +396,137 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
     recordEvent("lifecycle", 1);
     return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
 };
-export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, recordEvent, }) => new Promise((resolveExit) => {
+/** Name why an attempt is unverified; a blank message never reaches the capture schema. */
+export const describeUnverifiedCause = (cause, fallback) => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return message.trim() === "" ? fallback : message;
+};
+/**
+ * Wait for the captured terminal to exit and report how it ended.
+ *
+ * A timeout or idle deadline kills the root at once when `finalization_ms` is
+ * 0. With a positive interval it sends SIGTERM through `signalTarget`, keeps
+ * observing, and sends SIGKILL once if the interval ends first; cancellation
+ * during the interval sends that SIGKILL at once. Every attempt is recorded
+ * with its delivery result before the delivery is awaited, and each wait is
+ * bounded by the cleanup verification grace. If the SIGKILL cannot be
+ * delivered the wait ends with `unobserved: true` and no invented exit, so the
+ * caller can keep its observations and release the run through cleanup.
+ */
+export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, signalTarget, recordFinalization, timers, interactions, dispatchedEventIndexes, recordEvent, onLiveProgress, }) => 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";
+    onLiveProgress?.();
+    // A deadline with a finalization interval sends SIGTERM first and keeps
+    // observing; SIGKILL follows only when the interval elapses or the request
+    // is cancelled. Both go through the identity-checked signaller.
+    // The interval is measured on the monotonic clock so a wall-clock change
+    // cannot shorten it or produce a negative elapsed time.
+    let finalizationStartedAt;
+    let escalationSent = false;
+    let settled = false;
+    let exitObserved = false;
+    const finalizationSignals = [];
+    const pendingDeliveries = [];
+    const snapshot = (elapsed, exitCode = null) => ({
+        requested_ms: scenario.finalization_ms,
+        elapsed_ms: elapsed,
+        exit_code: exitCode,
+        signals: finalizationSignals.map((attempt) => ({ ...attempt })),
+    });
+    const unobservedExit = () => {
+        if (settled || exitObserved || finalizationStartedAt === undefined)
+            return;
+        settled = true;
+        for (const timer of timers)
+            timer.cancel();
+        timers.clear();
+        resolveExit({
+            unobserved: true,
+            reason: reason === "exited" ? "timeout" : reason,
+            finalization: snapshot(null),
+        });
+    };
+    // An attempt is recorded before its delivery is awaited, so a hung or
+    // failed delivery still leaves the attempt in the observations.
+    const attempt = (finalizationSignal) => {
+        if (finalizationStartedAt === undefined)
+            return;
+        const record = {
+            signal: finalizationSignal,
+            sent_at_ms: Math.round(performance.now() - finalizationStartedAt),
+            delivery: "unverified",
+            reason: "delivery had not settled when the record was published",
+        };
+        finalizationSignals.push(record);
+        recordFinalization(snapshot(null));
+        const deliveryBound = new AbortController();
+        // The wait is bounded by the cleanup verification grace: a delivery that
+        // never settles is recorded as unverified instead of holding the capture.
+        pendingDeliveries.push(Promise.race([
+            signalTarget(finalizationSignal),
+            delay(PROCESS_CLEANUP_VERIFICATION_GRACE_MS, {
+                delivery: "unverified",
+                reason: `delivery did not settle within ${String(PROCESS_CLEANUP_VERIFICATION_GRACE_MS)} ms`,
+            }, {
+                ref: false,
+                signal: deliveryBound.signal,
+            }).catch(() => ({
+                delivery: "unverified",
+                reason: "delivery wait was interrupted",
+            })),
+        ])
+            .finally(() => {
+            deliveryBound.abort();
+        })
+            .then(({ delivery, reason: deliveryReason }) => {
+            record.delivery = delivery;
+            if (deliveryReason !== undefined)
+                record.reason = deliveryReason;
+            else
+                delete record.reason;
+        }, (cause) => {
+            record.delivery = "unverified";
+            record.reason = describeUnverifiedCause(cause, "signal delivery failed without a message");
+        })
+            .then(() => {
+            recordFinalization(snapshot(null));
+            // A kill that cannot reach the root leaves no exit to wait for.
+            if (finalizationSignal === "SIGKILL" &&
+                record.delivery !== "signaled" &&
+                record.delivery !== "gone")
+                unobservedExit();
+        }));
+    };
+    const forceKill = () => {
+        if (finalizationStartedAt !== undefined) {
+            if (escalationSent)
+                return;
+            escalationSent = true;
+            attempt("SIGKILL");
+            return;
+        }
+        terminal.kill("SIGKILL");
+    };
+    const terminateAtDeadline = () => {
+        if (scenario.finalization_ms === 0) {
+            terminal.kill("SIGKILL");
+            return;
+        }
+        finalizationStartedAt = performance.now();
+        attempt("SIGTERM");
+    };
     terminal.onExit((exit) => {
+        if (settled)
+            return;
+        exitObserved = true;
+        // Measures when the exit was observed, not when the operating system
+        // ended the process; the PTY layer can deliver the notification late.
+        const finalizationElapsedMs = finalizationStartedAt === undefined
+            ? undefined
+            : Math.round(performance.now() - finalizationStartedAt);
         recordEvent("lifecycle", 0);
         for (const [eventIndex, event] of scenario.events.entries()) {
             if (dispatchedEventIndexes.has(eventIndex))
@@ -426,20 +550,59 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
             timer.cancel();
         }
         timers.clear();
-        resolveExit({ ...exit, reason });
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolveExit({
+                ...exit,
+                reason,
+                ...(finalizationElapsedMs === undefined
+                    ? {}
+                    : {
+                        finalization: snapshot(finalizationElapsedMs, exit.exitCode >= 0 && (exit.signal ?? 0) === 0
+                            ? exit.exitCode
+                            : null),
+                    }),
+            });
+        };
+        if (pendingDeliveries.length === 0) {
+            finish();
+            return;
+        }
+        // A delivery that never settles must not hold back an observed exit;
+        // its attempt stays recorded as unverified.
+        const grace = new AbortController();
+        void Promise.race([
+            Promise.allSettled(pendingDeliveries),
+            delay(PROCESS_CLEANUP_VERIFICATION_GRACE_MS, undefined, {
+                ref: false,
+                signal: grace.signal,
+            }).catch(() => undefined),
+        ])
+            .finally(() => {
+            grace.abort();
+        })
+            .then(finish);
     });
     const timeout = scheduleProcessInterval(() => {
+        onLiveProgress?.();
         if (signal?.aborted === true) {
             reason = "cancelled";
-            terminal.kill("SIGKILL");
+            forceKill();
+        }
+        else if (finalizationStartedAt !== undefined) {
+            if (performance.now() - finalizationStartedAt >=
+                scenario.finalization_ms)
+                forceKill();
         }
         else if (Date.now() - started >= scenario.timeout_ms) {
             reason = "timeout";
-            terminal.kill("SIGKILL");
+            terminateAtDeadline();
         }
         else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
             reason = "idle_timeout";
-            terminal.kill("SIGKILL");
+            terminateAtDeadline();
         }
     }, 20);
     timers.add(timeout);
@@ -508,60 +671,170 @@ const releaseCapturedProcessGroup = async (ownership, host) => {
             ],
         };
 };
-export const releaseProcessResources = async (options) => {
-    const host = options.host ?? processCaptureCleanupHost;
-    for (const timer of options.timers)
-        timer.cancel();
-    let terminalRenderer = {
-        state: options.renderer === undefined ? "not_required" : "cleaned",
-        reason: null,
-    };
-    try {
-        await options.renderer?.dispose();
+/** One capture's exact resource owner, with completion tracked per resource. */
+class ProcessCaptureResourceOwner {
+    options;
+    #host;
+    #terminalRenderer;
+    #ownedProcessGroup;
+    #temporaryRoot;
+    constructor(options) {
+        this.options = options;
+        this.#host = options.host ?? processCaptureCleanupHost;
+        if (options.renderer === undefined)
+            this.#terminalRenderer = { state: "not_required", reason: null };
+        if (options.terminal === undefined)
+            this.#ownedProcessGroup = { state: "not_required", reason: null };
     }
-    catch (cause) {
-        terminalRenderer = {
-            state: "failed",
-            reason: cause instanceof Error
-                ? cause.message || cause.name || "renderer dispose failed"
-                : "renderer dispose failed",
+    async close() {
+        for (const timer of this.options.timers)
+            timer.cancel();
+        await this.#releaseRenderer();
+        await this.#releaseOwnedProcessGroup();
+        await this.#releaseTemporaryRoot();
+        return {
+            owned_process_group: this.#ownedProcessGroup ?? {
+                state: "unverified",
+                reason: "owned process cleanup was not attempted",
+            },
+            terminal_renderer: this.#terminalRenderer ?? {
+                state: "unverified",
+                reason: "terminal renderer cleanup was not attempted",
+            },
+            temporary_root: this.#temporaryRoot ?? {
+                state: "unverified",
+                reason: "temporary root cleanup was not attempted",
+            },
         };
     }
-    const ownedProcessGroup = options.terminal === undefined
-        ? { state: "not_required", reason: null }
-        : await releaseCapturedProcessGroup({
-            runId: options.runId,
-            leaderPid: options.terminal.pid,
-            processGroupId: options.terminal.pid,
+    async #releaseRenderer() {
+        if (this.options.renderer === undefined ||
+            this.#terminalRenderer?.state === "cleaned" ||
+            this.#terminalRenderer?.state === "not_required")
+            return;
+        try {
+            await this.options.renderer.dispose();
+            this.#terminalRenderer = { state: "cleaned", reason: null };
+        }
+        catch (cause) {
+            this.#terminalRenderer = {
+                state: "failed",
+                reason: cleanupFailureMessage(cause, "renderer dispose failed"),
+            };
+        }
+    }
+    async #releaseOwnedProcessGroup() {
+        if (this.options.terminal === undefined ||
+            this.#ownedProcessGroup?.state === "cleaned" ||
+            this.#ownedProcessGroup?.state === "not_required")
+            return;
+        this.#ownedProcessGroup = await releaseCapturedProcessGroup({
+            runId: this.options.runId,
+            leaderPid: this.options.terminal.pid,
+            processGroupId: this.options.terminal.pid,
             sweepTokenOwnedProcesses: true,
-            ...(options.sampledProcessGroupIds === undefined
+            ...(this.options.sampledProcessGroupIds === undefined
                 ? {}
-                : { sampledProcessGroupIds: options.sampledProcessGroupIds }),
-            ...(options.captureBaseline === undefined
+                : { sampledProcessGroupIds: this.options.sampledProcessGroupIds }),
+            ...(this.options.captureBaseline === undefined
                 ? {}
-                : { captureBaseline: options.captureBaseline }),
-        }, host);
-    let temporaryRoot = {
-        state: "cleaned",
-        reason: null,
-    };
-    try {
-        await host.removeTemporaryRoot(options.temporaryRoot);
+                : { captureBaseline: this.options.captureBaseline }),
+        }, this.#host);
     }
-    catch (cause) {
-        temporaryRoot = {
-            state: "failed",
-            reason: cause instanceof Error
-                ? cause.message || cause.name || "temporary root removal failed"
-                : "temporary root removal failed",
-        };
+    async #releaseTemporaryRoot() {
+        if (this.#temporaryRoot?.state === "cleaned")
+            return;
+        const owned = this.#ownedProcessGroup;
+        if (owned?.state === "failed" || owned?.state === "unverified") {
+            this.#temporaryRoot = {
+                state: "unverified",
+                reason: `temporary root retained because owned process cleanup is ${owned.state}: ${owned.reason ?? "ownership could not be verified"}`,
+            };
+            return;
+        }
+        try {
+            await this.#host.removeTemporaryRoot(this.options.temporaryRoot);
+            this.#temporaryRoot = { state: "cleaned", reason: null };
+        }
+        catch (cause) {
+            this.#temporaryRoot = {
+                state: "failed",
+                reason: cleanupFailureMessage(cause, "temporary root removal failed"),
+            };
+        }
     }
-    return {
-        owned_process_group: ownedProcessGroup,
-        terminal_renderer: terminalRenderer,
-        temporary_root: temporaryRoot,
-    };
-};
+}
+const cleanupFailureMessage = (cause, fallback) => cause instanceof Error ? cause.message || cause.name || fallback : fallback;
+/** Release one capture's resources, retaining the exact owner for scoped retry. */
+export const releaseProcessResources = async (options) => new ProcessCaptureResourceOwner(options).close();
+/** Run-local owner collection for resources whose first cleanup did not finish. */
+export class ProcessCaptureResourceScope {
+    #pending = new Set();
+    #active = new Set();
+    #draining;
+    #closed = false;
+    /** Admit one capture before it starts acquiring resources. */
+    async run(operation) {
+        while (true) {
+            while (this.#draining !== undefined)
+                await this.#draining;
+            if (this.#closed)
+                throw new ProcessCaptureError("process capture lifecycle is closing; start a new server session before capturing again");
+            if (this.#pending.size === 0)
+                break;
+            await this.retryCleanup();
+        }
+        const running = Promise.resolve().then(operation);
+        this.#active.add(running);
+        try {
+            return await running;
+        }
+        finally {
+            this.#active.delete(running);
+        }
+    }
+    async release(options) {
+        const owner = new ProcessCaptureResourceOwner(options);
+        const report = await owner.close();
+        if (cleanupReportFailure(report) !== undefined) {
+            this.#pending.add(owner);
+        }
+        return report;
+    }
+    /** Drain active captures, then retry their retained resources without closing admission. */
+    retryCleanup() {
+        if (this.#draining !== undefined)
+            return this.#draining;
+        this.#draining = this.#drainAndRetry().finally(() => {
+            this.#draining = undefined;
+        });
+        return this.#draining;
+    }
+    /** Stop admitting new captures, drain active runs, and retry all retained owners. */
+    close() {
+        this.#closed = true;
+        return this.retryCleanup();
+    }
+    async #drainAndRetry() {
+        while (this.#active.size > 0)
+            await Promise.allSettled(this.#active);
+        const failures = [];
+        for (const owner of this.#pending) {
+            try {
+                const report = await owner.close();
+                if (cleanupReportFailure(report) === undefined)
+                    this.#pending.delete(owner);
+                else
+                    failures.push(cleanupReportFailure(report) ?? "cleanup incomplete");
+            }
+            catch (cause) {
+                failures.push(cause instanceof Error ? cause.message || cause.name : String(cause));
+            }
+        }
+        if (failures.length > 0)
+            throw new AggregateError(failures, `Process capture cleanup remains incomplete: ${failures.join("; ")}`);
+    }
+}
 export const cleanupReportFailure = (report) => {
     const failures = Object.entries(report).filter(([, outcome]) => outcome.state === "failed" || outcome.state === "unverified");
     return failures.length === 0
@@ -729,7 +1002,7 @@ export const resolveProcessResult = (capture, executionFailure, cleanup, observa
         throw new ProcessCaptureError(`process capture validation failed${cause instanceof Error ? `: ${cause.message}` : ""}`, { cause });
     }
 };
-export const prepareProcessCapture = async (scenario, signal, captureSnapshot = snapshotRoots, host = systemProcessPreparationHost) => {
+export const prepareProcessCapture = async (scenario, signal, captureSnapshot = snapshotRoots, host = systemProcessPreparationHost, resourceScope) => {
     assertNotCancelled(signal);
     await host.prepareOwnershipInspector?.(signal);
     assertNotCancelled(signal);
@@ -743,20 +1016,24 @@ export const prepareProcessCapture = async (scenario, signal, captureSnapshot =
         return { temporaryRoot, runId, ownershipBaseline, before };
     }
     catch (cause) {
-        const cleanup = await releaseProcessResources({
+        const cleanupOptions = {
             timers: new Set(),
             terminal: undefined,
             renderer: undefined,
             runId,
             temporaryRoot,
             host: { ...processCaptureCleanupHost, removeTemporaryRoot: host.cleanup },
-        });
+        };
+        const cleanup = resourceScope === undefined
+            ? await releaseProcessResources(cleanupOptions)
+            : await resourceScope.release(cleanupOptions);
         resolveProcessResult(undefined, normalizeCaptureFailure(cause, signal), cleanup, createProcessCaptureObservationBuffer({
             frames: [],
             interactions: [],
             samples: [],
             eventJournal: [],
             before,
+            finalizationEnabled: scenario.finalization_ms > 0,
         }), { scenario });
         throw cause;
     }

package/dist/process/capture/ProcessCaptureProgress.js

@@ -0,0 +1,62 @@
+const formatProgressMessage = (elapsedMs, counts, disposition, cleanup) => {
+    const status = `elapsed_ms=${String(elapsedMs)} frames=${String(counts.frames)} samples=${String(counts.samples)} interactions=${String(counts.interactions)}`;
+    const dispositionText = disposition === undefined ? "" : ` disposition=${disposition}`;
+    const cleanupText = cleanup === undefined
+        ? ""
+        : ` owned_process_group=${cleanup.owned_process_group.state} terminal_renderer=${cleanup.terminal_renderer.state} temporary_root=${cleanup.temporary_root.state}`;
+    return `${status}${dispositionText}${cleanupText}`;
+};
+/** Serialize observed capture status through one rate-limited reporter. */
+export const createProcessCaptureProgressTracker = (progress, now = Date.now) => {
+    const started = now();
+    let completed = 0;
+    let live = true;
+    let next;
+    let pending;
+    const flush = async () => {
+        try {
+            while (next !== undefined) {
+                const update = next;
+                next = undefined;
+                try {
+                    await progress?.report(update);
+                }
+                catch {
+                    // Progress delivery is observational; capture and cleanup still finish.
+                    continue;
+                }
+            }
+        }
+        finally {
+            pending = undefined;
+        }
+    };
+    return {
+        closeLive() {
+            live = false;
+            if (next?.terminal !== true)
+                next = undefined;
+        },
+        report(update) {
+            if (progress === undefined)
+                return Promise.resolve();
+            if (update.terminal !== true && !live)
+                return Promise.resolve();
+            const units = update.counts.frames +
+                update.counts.samples +
+                update.counts.interactions;
+            if (units > completed)
+                completed = units;
+            // A slow observer needs the latest observation, not a queue of old states.
+            next = {
+                phase: update.phase,
+                completed,
+                total: null,
+                message: formatProgressMessage(Math.max(0, now() - started), update.counts, update.disposition, update.cleanup),
+                ...(update.terminal === true ? { terminal: true } : {}),
+            };
+            pending ??= Promise.resolve().then(flush);
+            return pending;
+        },
+    };
+};