rea-agents 6.4.0 → 6.5.0

package/dist/process/capture/ProcessCaptureLifecycle.js

@@ -3,7 +3,7 @@ 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";
@@ -13,11 +13,12 @@ import { cleanupOwnedProcessGroup, verifyNoTokenOwnedProcesses, } from "../Proce
 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) => ({
@@ -83,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;
     }
 };
@@ -132,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."]
@@ -184,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],
@@ -367,8 +382,9 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
         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?.();
@@ -377,24 +393,42 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
         assertNotCancelled(signal);
         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.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) => {
@@ -456,7 +490,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
             return;
         const record = {
             signal: finalizationSignal,
-            sent_at_ms: Math.round(performance.now() - finalizationStartedAt),
+            sent_at_ms: Math.max(0, monotonicProcessCaptureClock() - finalizationStartedAt),
             delivery: "unverified",
             reason: "delivery had not settled when the record was published",
         };
@@ -515,7 +549,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
             terminal.kill("SIGKILL");
             return;
         }
-        finalizationStartedAt = performance.now();
+        finalizationStartedAt = monotonicProcessCaptureClock();
         attempt("SIGTERM");
     };
     terminal.onExit((exit) => {
@@ -526,7 +560,7 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
         // ended the process; the PTY layer can deliver the notification late.
         const finalizationElapsedMs = finalizationStartedAt === undefined
             ? undefined
-            : Math.round(performance.now() - finalizationStartedAt);
+            : Math.max(0, monotonicProcessCaptureClock() - finalizationStartedAt);
         recordEvent("lifecycle", 0);
         for (const [eventIndex, event] of scenario.events.entries()) {
             if (dispatchedEventIndexes.has(eventIndex))
@@ -535,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>"
@@ -592,15 +626,17 @@ export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutpu
             forceKill();
         }
         else if (finalizationStartedAt !== undefined) {
-            if (performance.now() - finalizationStartedAt >=
+            if (monotonicProcessCaptureClock() - finalizationStartedAt >=
                 scenario.finalization_ms)
                 forceKill();
         }
-        else if (Date.now() - started >= scenario.timeout_ms) {
+        else if (monotonicProcessCaptureClock() - started >=
+            scenario.timeout_ms) {
             reason = "timeout";
             terminateAtDeadline();
         }
-        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
+        else if (monotonicProcessCaptureClock() - lastOutput() >=
+            scenario.idle_timeout_ms) {
             reason = "idle_timeout";
             terminateAtDeadline();
         }
@@ -616,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)));
@@ -844,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) => {

package/dist/process/capture/ProcessCaptureProgress.js

@@ -1,3 +1,4 @@
+import { monotonicProcessCaptureClock } from "./ProcessCaptureClock.js";
 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}`;
@@ -7,7 +8,7 @@ const formatProgressMessage = (elapsedMs, counts, disposition, cleanup) => {
     return `${status}${dispositionText}${cleanupText}`;
 };
 /** Serialize observed capture status through one rate-limited reporter. */
-export const createProcessCaptureProgressTracker = (progress, now = Date.now) => {
+export const createProcessCaptureProgressTracker = (progress, now = monotonicProcessCaptureClock) => {
     const started = now();
     let completed = 0;
     let live = true;

package/dist/process/capture/ProcessHarness.js

@@ -1,12 +1,12 @@
 import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
-import {} from "../../domain/analysisErrorBase.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
 import { describeProcessCaptureExecutionFailure, ProcessCaptureError, normalizeCaptureFailure, processCaptureCancelled, } from "./ProcessCaptureError.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
-import { normalizeProcessText } from "./ProcessNormalization.js";
+import { createBoundedProcessTextNormalizer, } from "./ProcessNormalization.js";
 import { selectCapturedProcessGroupIds } from "../ProcessOwnershipProcessTree.js";
 import { awaitTerminalExit, buildCaptureResult, cleanupReportFailure, captureTerminalFrames, createProcessCaptureObservationBuffer, createRunManifest, observeLaunchedExecutable, observeSelectedExecutable, observeSettlement, prepareProcessCapture, releaseProcessResources, resolveProcessResult, settleProcessCaptureJournal, describeUnverifiedCause, ProcessCaptureResourceScope, } from "./ProcessCaptureLifecycle.js";
 import { assertNotCancelled, resolveProcessScenarioRuntimePaths, } from "./ProcessScenarioRuntimeValidation.js";
@@ -16,6 +16,7 @@ import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
 import { createProcessCaptureProgressTracker, } from "./ProcessCaptureProgress.js";
 import { observeProcessStartIdentity, signalProcessWithStartIdentity, } from "../ProcessOwnershipObservation.js";
+import { monotonicProcessCaptureClock } from "./ProcessCaptureClock.js";
 /** Bind the captured root's initial identity to its run token before retaining it. */
 export const retainRootSignaller = (pid, finalizationMs, runId, host = {
     observe: (rootPid) => observeProcessStartIdentity(rootPid, undefined, runId),
@@ -102,12 +103,12 @@ const cleanupFailedStartup = async (options) => {
     }
     throw options.cause;
 };
-const createTerminalRenderer = (scenario, temporaryRoot, terminalPid, recordEvent) => new TerminalRenderer({
+const createTerminalRenderer = (scenario, normalizeText, recordEvent) => new TerminalRenderer({
     columns: scenario.terminal.columns,
     rows: scenario.terminal.rows,
     scrollback: scenario.terminal.scrollback,
     maxBytes: scenario.limits.output_bytes,
-    normalize: (value) => normalizeProcessText(value, scenario, temporaryRoot, terminalPid()),
+    normalize: normalizeText,
     recordEvent,
 });
 const startCaptureRuntime = async (options) => {
@@ -118,9 +119,10 @@ const startCaptureRuntime = async (options) => {
         const { spawn } = await import("@lydell/node-pty");
         const selectedExecutable = await observeSelectedExecutable(scenario.executable, options.signal);
         const startedAt = new Date();
-        const started = Date.now();
+        const started = monotonicProcessCaptureClock();
         let lastOutput = started;
-        renderer = createTerminalRenderer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1, options.recordEvent);
+        const normalizeText = createBoundedProcessTextNormalizer(scenario, options.temporaryRoot, () => terminal?.pid ?? -1);
+        renderer = createTerminalRenderer(scenario, normalizeText, options.recordEvent);
         terminal = spawn(scenario.executable, [...scenario.arguments], {
             cwd: scenario.working_directory,
             env: makeProcessCaptureEnvironment(options),
@@ -134,12 +136,13 @@ const startCaptureRuntime = async (options) => {
             value: scenario.normalization.pids ? 1 : terminal.pid,
         };
         const executableIdentity = observeLaunchedExecutable(scenario.executable, selectedExecutable);
-        const rawTerminalRetention = captureTerminalFrames({
+        const terminalRetention = captureTerminalFrames({
             ...options,
             terminal,
             started,
-            onOutput: () => (lastOutput = Date.now()),
+            onOutput: () => (lastOutput = monotonicProcessCaptureClock()),
             renderer,
+            normalizeText,
         });
         scheduleScenarioInteractions({
             ...options,
@@ -162,7 +165,7 @@ const startCaptureRuntime = async (options) => {
             startedAt,
             executableIdentity,
             lastOutput: () => lastOutput,
-            rawTerminalRetention,
+            terminalRetention,
             stopSampler,
             signalRoot: retainRootSignaller(terminal.pid, scenario.finalization_ms, options.runId, options.finalizationHost),
         };
@@ -271,7 +274,7 @@ const completeCapture = async (options) => {
     assertNotCancelled(options.signal);
     let after;
     try {
-        after = await options.captureSnapshot(scenario, options.signal);
+        after = await options.captureSnapshot(scenario, options.signal, options.before);
     }
     catch (cause) {
         options.observationBuffer.filesystem_snapshots = {
@@ -316,7 +319,7 @@ const completeCapture = async (options) => {
         },
         {
             name: "after_settlement",
-            at_ms: Math.max(0, Date.now() - runtime.started),
+            at_ms: Math.max(0, monotonicProcessCaptureClock() - runtime.started),
             files: after.files,
             effects: classifyFilesystemEffects(options.before, after),
             truncated: after.truncated,
@@ -341,7 +344,7 @@ const completeCapture = async (options) => {
         before: options.before,
         after,
         truncationDetails: {
-            raw_terminal: runtime.rawTerminalRetention(),
+            ...runtime.terminalRetention(),
             rendered_terminal: runtime.renderer.retention(),
             filesystem_before: options.before.coverage,
             filesystem_after: after.coverage,
@@ -570,7 +573,7 @@ export const captureProcessScenario = async (scenario, signal, platform = proces
         catch (cause) {
             const failure = normalizeCaptureFailure(cause, signal);
             const executionFailureReason = describeProcessCaptureExecutionFailure(cause);
-            return err(failure instanceof ProcessCaptureError
+            return err(failure instanceof AnalysisError
                 ? failure
                 : new ProcessCaptureError("process capture failed", {
                     cause,
@@ -587,7 +590,7 @@ export const captureProcessScenario = async (scenario, signal, platform = proces
         catch (cause) {
             const failure = normalizeCaptureFailure(cause, signal);
             const executionFailure = describeProcessCaptureExecutionFailure(cause);
-            return err(failure instanceof ProcessCaptureError
+            return err(failure instanceof AnalysisError
                 ? failure
                 : new ProcessCaptureError("process capture lifecycle failed", {
                     cause,