rea-agents 6.3.0 → 6.5.0

package/dist/process/capture/ProcessCaptureLifecycle.js

@@ -3,21 +3,22 @@ import { constants, statSync } from "node:fs";
 import { open, mkdtemp, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
+import { setImmediate, setTimeout as delay } from "node:timers/promises";
 import { digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../../domain/process/processScenario.js";
 import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
 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";
+import { normalizeProcessElapsedTime, normalizeProcessSamples, } from "./ProcessNormalization.js";
 import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
 import { hasCaptureTruncation, } from "../../domain/process/processCaptureCoverage.js";
 import { scheduleProcessInterval } from "./ProcessTimer.js";
+import { monotonicProcessCaptureClock } from "./ProcessCaptureClock.js";
 import { partialProcessCaptureObservationSchema } from "../../domain/process/processCapture.js";
 /** Seed explicit observation availability before capture completion begins. */
 export const createProcessCaptureObservationBuffer = (options) => ({
@@ -35,6 +36,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.",
@@ -75,16 +84,20 @@ const normalizePartialProcessObservations = (observations, context) => {
 };
 /** Wait for trailing PTY callbacks before the capture becomes immutable. */
 export const settleProcessCaptureJournal = async (journal, quietMs = 25, maxWaitMs = 500) => {
-    const deadline = Date.now() + maxWaitMs;
+    const deadline = monotonicProcessCaptureClock() + maxWaitMs;
     let observed = journal.length;
-    let lastChangeAt = Date.now();
-    while (Date.now() < deadline) {
+    let lastChangeAt = monotonicProcessCaptureClock();
+    while (monotonicProcessCaptureClock() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 4));
+        // A stalled event loop can leave timer and poll callbacks that were already
+        // due queued behind this wake-up. Drain them before judging silence so a
+        // trailing observation is not dropped by an early settle.
+        await setImmediate();
         if (journal.length !== observed) {
             observed = journal.length;
-            lastChangeAt = Date.now();
+            lastChangeAt = monotonicProcessCaptureClock();
         }
-        else if (Date.now() - lastChangeAt >= quietMs)
+        else if (monotonicProcessCaptureClock() - lastChangeAt >= quietMs)
             return;
     }
 };
@@ -109,6 +122,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),
@@ -121,6 +137,12 @@ export const buildCaptureResult = (options) => {
         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.",
+            ...(Date.parse(options.manifest.completed_at) <
+                Date.parse(options.manifest.started_at)
+                ? [
+                    "Wall-clock completion time precedes start time; elapsed capture timing is recorded separately and remains monotonic.",
+                ]
+                : []),
             "Process trees are sampled and may omit short-lived descendants.",
             ...(options.samplingPartial
                 ? ["Process-tree sampling ended with an incomplete observation."]
@@ -173,13 +195,17 @@ const captureCoverageUnknowns = (details) => {
     if (details.raw_terminal.observed_frames > details.raw_terminal.retained_frames)
         unknowns.push({
             scope: "terminal",
-            reason: "Raw PTY chunks exceeded output_bytes and were omitted; rendered states also lack those inputs. See truncation_details.raw_terminal.",
+            reason: (details.normalized_terminal?.omitted_frames ?? 0) > 0
+                ? "Raw PTY chunks were omitted because original input exceeded output_bytes or an ordered normalization stage exceeded its remaining bound; final normalized sizes for the latter omissions are unknown. Rendered states also lack those inputs. See raw_terminal and normalized_terminal retention details, including the normalized omission count."
+                : "Raw PTY chunks exceeded output_bytes and were omitted; rendered states also lack those inputs. See truncation_details.raw_terminal.",
         });
     if (details.rendered_terminal.observed_frames >
         details.rendered_terminal.retained_frames)
         unknowns.push({
             scope: "terminal",
-            reason: "Cumulative rendered state and visible-line bytes exceeded output_bytes; whole rendered frames were omitted. Raw PTY coverage is reported separately. See truncation_details.rendered_terminal.",
+            reason: (details.rendered_terminal.unknown_size_frames ?? 0) > 0
+                ? "Rendered frames were omitted because a normalization stage exceeded the remaining output_bytes budget; final rendered byte totals are unknown for those frames. See truncation_details.rendered_terminal."
+                : "Cumulative rendered state and visible-line bytes exceeded output_bytes; whole rendered frames were omitted. Raw PTY coverage is reported separately. See truncation_details.rendered_terminal.",
         });
     for (const [name, coverage] of [
         ["before", details.filesystem_before],
@@ -349,46 +375,192 @@ 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 };
     }
-    const started = Date.now();
+    const started = monotonicProcessCaptureClock();
     let consecutiveEmpty = 0;
+    let sawLive = false;
     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 };
+            return {
+                state: "unverifiable",
+                elapsed_ms: monotonicProcessCaptureClock() - started,
+            };
         }
-        if (observations.every(({ state }) => state === "empty")) {
+        if ([...observations.values()].every(({ state }) => state === "empty")) {
             consecutiveEmpty += 1;
             if (consecutiveEmpty >= 2) {
                 recordEvent("lifecycle", 1);
-                return { state: "quiesced", elapsed_ms: Date.now() - started };
+                return {
+                    state: "quiesced",
+                    elapsed_ms: monotonicProcessCaptureClock() - started,
+                };
             }
         }
-        else
+        else {
             consecutiveEmpty = 0;
-        deadlineReached = Date.now() - started >= settleMs;
+            sawLive = true;
+        }
+        deadlineReached = monotonicProcessCaptureClock() - started >= settleMs;
         if (deadlineReached)
             break;
         await delay(50, undefined, { signal });
     }
     recordEvent("lifecycle", 1);
-    return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
+    // A lone empty observation proves neither liveness nor quiescence; only an
+    // observed live member justifies alive_at_deadline.
+    return sawLive
+        ? {
+            state: "alive_at_deadline",
+            elapsed_ms: monotonicProcessCaptureClock() - started,
+        }
+        : {
+            state: "unverifiable",
+            elapsed_ms: monotonicProcessCaptureClock() - started,
+        };
+};
+/** 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;
 };
-export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, recordEvent, }) => new Promise((resolveExit) => {
+/**
+ * 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.max(0, monotonicProcessCaptureClock() - 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 = monotonicProcessCaptureClock();
+        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.max(0, monotonicProcessCaptureClock() - finalizationStartedAt);
         recordEvent("lifecycle", 0);
         for (const [eventIndex, event] of scenario.events.entries()) {
             if (dispatchedEventIndexes.has(eventIndex))
@@ -397,7 +569,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
             interactions.push({
                 sequence,
                 scheduled_at_ms: event.at_ms,
-                dispatched_at_ms: Math.max(0, Date.now() - started),
+                dispatched_at_ms: Math.max(0, monotonicProcessCaptureClock() - started),
                 type: event.type,
                 data: event.type === "input"
                     ? "<not-dispatched>"
@@ -412,20 +584,61 @@ 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 (monotonicProcessCaptureClock() - finalizationStartedAt >=
+                scenario.finalization_ms)
+                forceKill();
         }
-        else if (Date.now() - started >= scenario.timeout_ms) {
+        else if (monotonicProcessCaptureClock() - started >=
+            scenario.timeout_ms) {
             reason = "timeout";
-            terminal.kill("SIGKILL");
+            terminateAtDeadline();
         }
-        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
+        else if (monotonicProcessCaptureClock() - lastOutput() >=
+            scenario.idle_timeout_ms) {
             reason = "idle_timeout";
-            terminal.kill("SIGKILL");
+            terminateAtDeadline();
         }
     }, 20);
     timers.add(timeout);
@@ -439,10 +652,10 @@ const processCaptureCleanupHost = {
 const PROCESS_CLEANUP_VERIFICATION_GRACE_MS = 1_000;
 const PROCESS_CLEANUP_VERIFICATION_INTERVAL_MS = 25;
 const verifyTokenOwnedProcessesUntilSettled = async (verify) => {
-    const deadline = Date.now() + PROCESS_CLEANUP_VERIFICATION_GRACE_MS;
+    const deadline = monotonicProcessCaptureClock() + PROCESS_CLEANUP_VERIFICATION_GRACE_MS;
     let result = await verify();
     while (!result.cleaned) {
-        const remaining = deadline - Date.now();
+        const remaining = deadline - monotonicProcessCaptureClock();
         if (remaining <= 0)
             return result;
         await new Promise((resolve) => setTimeout(resolve, Math.min(PROCESS_CLEANUP_VERIFICATION_INTERVAL_MS, remaining)));
@@ -494,60 +707,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
@@ -557,36 +880,51 @@ export const cleanupReportFailure = (report) => {
             .join("; ");
 };
 export const captureTerminalFrames = (options) => {
-    let outputBytes = 0;
+    let rawBytes = 0;
+    let normalizedBytes = 0;
     let observedBytes = 0;
     let observedFrames = 0;
+    let normalizedOmittedFrames = 0;
     options.terminal.onData((data) => {
         options.onOutput();
         const bytes = Buffer.byteLength(data);
         observedBytes += bytes;
         observedFrames += 1;
-        if (outputBytes + bytes > options.scenario.limits.output_bytes) {
+        const budget = options.scenario.limits.output_bytes;
+        if (bytes > budget - rawBytes) {
             return;
         }
-        outputBytes += bytes;
-        const atMs = normalizeProcessElapsedTime(Date.now() - options.started, options.scenario.normalization.time_bucket_ms);
-        const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
+        const normalized = options.normalizeText(data, budget - normalizedBytes);
+        if (normalized.state === "over_budget") {
+            normalizedOmittedFrames += 1;
+            return;
+        }
+        rawBytes += bytes;
+        normalizedBytes += normalized.utf8Bytes;
+        const atMs = normalizeProcessElapsedTime(monotonicProcessCaptureClock() - options.started, options.scenario.normalization.time_bucket_ms);
         const sequence = options.frames.length;
         options.frames.push({
             sequence,
             at_ms: atMs,
-            data: normalized,
-            ...(normalized === data ? {} : { raw_data: data }),
+            data: normalized.value,
+            ...(normalized.value === data ? {} : { raw_data: data }),
         });
         options.renderer.write(data, atMs);
         options.recordEvent("frames", sequence);
     });
     return () => ({
-        budget_bytes: options.scenario.limits.output_bytes,
-        observed_bytes: observedBytes,
-        retained_bytes: outputBytes,
-        observed_frames: observedFrames,
-        retained_frames: options.frames.length,
+        raw_terminal: {
+            budget_bytes: options.scenario.limits.output_bytes,
+            observed_bytes: observedBytes,
+            retained_bytes: rawBytes,
+            observed_frames: observedFrames,
+            retained_frames: options.frames.length,
+        },
+        normalized_terminal: {
+            budget_bytes: options.scenario.limits.output_bytes,
+            retained_bytes: normalizedBytes,
+            omitted_frames: normalizedOmittedFrames,
+        },
     });
 };
 export const resolveProcessResult = (capture, executionFailure, cleanup, observations, partialContext) => {
@@ -715,7 +1053,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);
@@ -729,20 +1067,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;
     }