rea-agents 6.1.0 → 6.2.0

package/dist/process/capture/ProcessCaptureLifecycle.js

@@ -3,18 +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 { digestProcessCommitment, parseProcessCapture, partialProcessCaptureObservationSchema, processComparisonContract, processScenarioCommitment, } from "../../domain/process/processCapture.js";
+import { 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 { describeProcessCaptureExecutionFailure, ProcessCaptureError, } from "./ProcessCaptureError.js";
+import { describeProcessCaptureExecutionFailure, normalizeCaptureFailure, ProcessCaptureError, } from "./ProcessCaptureError.js";
 import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
 import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } 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 { partialProcessCaptureObservationSchema } from "../../domain/process/processCapture.js";
 /** Seed explicit observation availability before capture completion begins. */
 export const createProcessCaptureObservationBuffer = (options) => ({
     target_pid: {
@@ -92,6 +96,9 @@ export const buildCaptureResult = (options) => {
     const sensitiveInputUnknown = "Sensitive scripted input values are redacted from process capture Evidence.";
     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.";
     return {
         manifest: options.manifest,
         normalization: options.scenario.normalization,
@@ -111,8 +118,13 @@ export const buildCaptureResult = (options) => {
         event_journal: options.eventJournal,
         files_before: options.before.files,
         files_after: options.after.files,
-        filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
-        truncated: options.truncated,
+        filesystem_effects: filesystemEffects,
+        truncated: options.truncationDetails === undefined
+            ? options.truncated
+            : hasCaptureTruncation(options.truncationDetails),
+        ...(options.truncationDetails === undefined
+            ? {}
+            : { 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.",
@@ -122,6 +134,10 @@ 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)),
             ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
         ],
         residual_unknowns: [
@@ -149,12 +165,58 @@ export const buildCaptureResult = (options) => {
                     },
                 ]
                 : []),
+            ...(hasUnknownFilesystemEffects
+                ? [
+                    {
+                        scope: "filesystem",
+                        reason: incompleteFilesystemUnknown,
+                    },
+                ]
+                : []),
             ...(hasSensitiveScriptedInput
                 ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
                 : []),
+            ...(options.truncationDetails === undefined
+                ? []
+                : captureCoverageUnknowns(options.truncationDetails).filter(({ scope }) => scope !== "terminal")),
         ],
     };
 };
+const captureCoverageUnknowns = (details) => {
+    const unknowns = [];
+    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.",
+        });
+    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.",
+        });
+    for (const [name, coverage] of [
+        ["before", details.filesystem_before],
+        ["after_settlement", details.filesystem_after],
+    ]) {
+        if (coverage.enumeration_truncated)
+            unknowns.push({
+                scope: "filesystem",
+                reason: `Filesystem ${name} path enumeration was incomplete: ${coverage.enumeration_reasons.join(", ")}. See truncation_details.`,
+            });
+        if (coverage.hash_omissions.length > 0)
+            unknowns.push({
+                scope: "filesystem",
+                reason: `Filesystem ${name} omitted ${String(coverage.hash_omissions.length)} whole-file digests; per-path reasons and remaining file_bytes budget are in truncation_details.`,
+            });
+    }
+    if (details.process.sampling_partial)
+        unknowns.push({
+            scope: "process",
+            reason: "Process sampling stopped with incomplete observations; sample_limit is reported in truncation_details.process.",
+        });
+    return unknowns;
+};
 const identityFromStats = (stats) => ({
     dev: stats.dev,
     ino: stats.ino,
@@ -301,7 +363,8 @@ 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) => {
+export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform, signal) => {
+    assertNotCancelled(signal);
     if (platform === "win32") {
         recordEvent("lifecycle", 1);
         return { state: "unverifiable", elapsed_ms: 0 };
@@ -310,11 +373,9 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
     let consecutiveEmpty = 0;
     let deadlineReached = false;
     while (!deadlineReached) {
-        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({
-            runId,
-            leaderPid: processGroupId,
-            processGroupId,
-        })));
+        assertNotCancelled(signal);
+        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({ runId, leaderPid: processGroupId, processGroupId }, undefined, signal)));
+        assertNotCancelled(signal);
         if (observations.some(({ state }) => state === "unverifiable")) {
             recordEvent("lifecycle", 1);
             return { state: "unverifiable", elapsed_ms: Date.now() - started };
@@ -331,7 +392,7 @@ export const observeSettlement = async (runId, processGroupIds, settleMs, record
         deadlineReached = Date.now() - started >= settleMs;
         if (deadlineReached)
             break;
-        await new Promise((resolve) => setTimeout(resolve, 50));
+        await delay(50, undefined, { signal });
     }
     recordEvent("lifecycle", 1);
     return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
@@ -403,6 +464,50 @@ const verifyTokenOwnedProcessesUntilSettled = async (verify) => {
     }
     return result;
 };
+const releaseCapturedProcessGroup = async (ownership, host) => {
+    if (host.platform === "win32")
+        return {
+            state: "unverified",
+            reason: "owned process cleanup is unverifiable on Windows without process-job authority",
+        };
+    let outcome = {
+        state: "cleaned",
+        reason: null,
+    };
+    const unverified = [];
+    try {
+        const cleaned = await host.cleanupProcessGroup(ownership);
+        unverified.push(...(cleaned.unverified ?? []));
+        if (!cleaned.cleaned) {
+            outcome = { state: "unverified", reason: cleaned.reason };
+        }
+        else {
+            const verified = await verifyTokenOwnedProcessesUntilSettled(() => host.verifyTokenOwnedProcesses(ownership.runId, undefined, ownership.captureBaseline, ownership));
+            unverified.push(...(verified.unverified ?? []));
+            if (!verified.cleaned)
+                outcome = { state: "unverified", reason: verified.reason };
+        }
+    }
+    catch (cause) {
+        outcome = {
+            state: "failed",
+            reason: cause instanceof Error
+                ? cause.message || cause.name || "owned process cleanup failed"
+                : "owned process cleanup failed",
+        };
+    }
+    return unverified.length === 0
+        ? outcome
+        : {
+            ...outcome,
+            unverified_processes: [
+                ...new Map(unverified.map(({ pid, diagnostic }) => [
+                    `${String(pid)}:${diagnostic}`,
+                    { pid, reason: diagnostic },
+                ])).values(),
+            ],
+        };
+};
 export const releaseProcessResources = async (options) => {
     const host = options.host ?? processCaptureCleanupHost;
     for (const timer of options.timers)
@@ -422,60 +527,20 @@ export const releaseProcessResources = async (options) => {
                 : "renderer dispose failed",
         };
     }
-    let ownedProcessGroup = {
-        state: options.terminal === undefined ? "not_required" : "cleaned",
-        reason: null,
-    };
-    if (options.terminal !== undefined) {
-        if (host.platform === "win32") {
-            ownedProcessGroup = {
-                state: "unverified",
-                reason: "owned process cleanup is unverifiable on Windows without process-job authority",
-            };
-        }
-        else {
-            const terminalPid = options.terminal.pid;
-            const relation = {
-                leaderPid: terminalPid,
-                processGroupId: terminalPid,
-                ...(options.sampledProcessGroupIds === undefined
-                    ? {}
-                    : { sampledProcessGroupIds: options.sampledProcessGroupIds }),
-            };
-            const cleaned = await host.cleanupProcessGroup({
-                runId: options.runId,
-                leaderPid: terminalPid,
-                processGroupId: terminalPid,
-                sweepTokenOwnedProcesses: true,
-                ...(options.sampledProcessGroupIds === undefined
-                    ? {}
-                    : { sampledProcessGroupIds: options.sampledProcessGroupIds }),
-                ...(options.captureBaseline === undefined
-                    ? {}
-                    : { captureBaseline: options.captureBaseline }),
-            });
-            const unverified = [...(cleaned.unverified ?? [])];
-            if (!cleaned.cleaned) {
-                ownedProcessGroup = { state: "unverified", reason: cleaned.reason };
-            }
-            else {
-                const verified = await verifyTokenOwnedProcessesUntilSettled(() => host.verifyTokenOwnedProcesses(options.runId, undefined, options.captureBaseline, relation));
-                unverified.push(...(verified.unverified ?? []));
-                if (!verified.cleaned)
-                    ownedProcessGroup = { state: "unverified", reason: verified.reason };
-            }
-            if (unverified.length > 0)
-                ownedProcessGroup = {
-                    ...ownedProcessGroup,
-                    unverified_processes: [
-                        ...new Map(unverified.map(({ pid, diagnostic }) => [
-                            `${String(pid)}:${diagnostic}`,
-                            { pid, reason: diagnostic },
-                        ])).values(),
-                    ],
-                };
-        }
-    }
+    const ownedProcessGroup = options.terminal === undefined
+        ? { state: "not_required", reason: null }
+        : await releaseCapturedProcessGroup({
+            runId: options.runId,
+            leaderPid: options.terminal.pid,
+            processGroupId: options.terminal.pid,
+            sweepTokenOwnedProcesses: true,
+            ...(options.sampledProcessGroupIds === undefined
+                ? {}
+                : { sampledProcessGroupIds: options.sampledProcessGroupIds }),
+            ...(options.captureBaseline === undefined
+                ? {}
+                : { captureBaseline: options.captureBaseline }),
+        }, host);
     let temporaryRoot = {
         state: "cleaned",
         reason: null,
@@ -507,12 +572,14 @@ export const cleanupReportFailure = (report) => {
 };
 export const captureTerminalFrames = (options) => {
     let outputBytes = 0;
-    let truncated = false;
+    let observedBytes = 0;
+    let observedFrames = 0;
     options.terminal.onData((data) => {
         options.onOutput();
         const bytes = Buffer.byteLength(data);
+        observedBytes += bytes;
+        observedFrames += 1;
         if (outputBytes + bytes > options.scenario.limits.output_bytes) {
-            truncated = true;
             return;
         }
         outputBytes += bytes;
@@ -523,11 +590,18 @@ export const captureTerminalFrames = (options) => {
             sequence,
             at_ms: atMs,
             data: normalized,
+            ...(normalized === data ? {} : { raw_data: data }),
         });
         options.renderer.write(data, atMs);
         options.recordEvent("frames", sequence);
     });
-    return () => truncated;
+    return () => ({
+        budget_bytes: options.scenario.limits.output_bytes,
+        observed_bytes: observedBytes,
+        retained_bytes: outputBytes,
+        observed_frames: observedFrames,
+        retained_frames: options.frames.length,
+    });
 };
 export const resolveProcessResult = (capture, executionFailure, cleanup, observations, partialContext) => {
     const cleanupFailure = cleanupReportFailure(cleanup);
@@ -660,16 +734,30 @@ export const prepareProcessCapture = async (scenario, signal, captureSnapshot =
     await host.prepareOwnershipInspector?.(signal);
     assertNotCancelled(signal);
     const before = await captureSnapshot(scenario, signal);
+    const runId = randomUUID();
     const temporaryRoot = await host.createTemporaryRoot();
     try {
         assertNotCancelled(signal);
-        const runId = randomUUID();
         const ownershipBaseline = (await host.captureOwnershipBaseline?.(signal)) ?? [];
         assertNotCancelled(signal);
         return { temporaryRoot, runId, ownershipBaseline, before };
     }
     catch (cause) {
-        await host.cleanup(temporaryRoot);
+        const cleanup = await releaseProcessResources({
+            timers: new Set(),
+            terminal: undefined,
+            renderer: undefined,
+            runId,
+            temporaryRoot,
+            host: { ...processCaptureCleanupHost, removeTemporaryRoot: host.cleanup },
+        });
+        resolveProcessResult(undefined, normalizeCaptureFailure(cause, signal), cleanup, createProcessCaptureObservationBuffer({
+            frames: [],
+            interactions: [],
+            samples: [],
+            eventJournal: [],
+            before,
+        }), { scenario });
         throw cause;
     }
 };

package/dist/process/capture/ProcessFilesystemEffects.js

@@ -1,12 +1,42 @@
-/** Classify path-stable filesystem effects between two bounded states. */
+import { sep } from "node:path";
+const unobservedAbsenceReason = (path, phase, completeRoots, filesByPath) => {
+    const alias = path.slice(0, path.indexOf(":"));
+    if (!completeRoots.has(alias))
+        return `The ${phase} snapshot did not exhaust path enumeration under ${alias}; absence remains unknown.`;
+    const rootPath = `${alias}:.`;
+    if (path !== rootPath && filesByPath.get(rootPath)?.type === "symlink")
+        return `The ${phase} snapshot did not follow the symbolic link at ${rootPath}; descendant absence remains unknown.`;
+    for (let index = path.lastIndexOf(sep); index > 0; index = path.lastIndexOf(sep, index - 1)) {
+        const parent = path.slice(0, index);
+        if (filesByPath.get(parent)?.type === "symlink")
+            return `The ${phase} snapshot did not follow the symbolic link at ${parent}; descendant absence remains unknown.`;
+    }
+    return undefined;
+};
+/** Classify effects only when a snapshot establishes the missing path's absence. */
 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]));
+    const beforeByPath = new Map(before.files.map((file) => [file.path, file]));
+    const afterByPath = new Map(after.files.map((file) => [file.path, file]));
+    const beforeCompleteRoots = new Set(before.completeRoots);
+    const afterCompleteRoots = new Set(after.completeRoots);
     return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
         .sort()
         .map((path) => {
         const beforeFile = beforeByPath.get(path) ?? null;
         const afterFile = afterByPath.get(path) ?? null;
+        const reason = beforeFile === null
+            ? unobservedAbsenceReason(path, "before", beforeCompleteRoots, beforeByPath)
+            : afterFile === null
+                ? unobservedAbsenceReason(path, "after", afterCompleteRoots, afterByPath)
+                : undefined;
+        if (reason !== undefined)
+            return {
+                path,
+                status: "unknown",
+                before: beforeFile,
+                after: afterFile,
+                reason,
+            };
         if (beforeFile === null) {
             if (afterFile === null)
                 throw new TypeError(`Filesystem effect ${path} has no file state`);

package/dist/process/capture/ProcessHarness.js

@@ -1,9 +1,8 @@
-import { parseProcessCapture } from "../../domain/process/processCapture.js";
+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 { describeProcessCaptureExecutionFailure, ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
-export { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { describeProcessCaptureExecutionFailure, ProcessCaptureError, normalizeCaptureFailure, processCaptureCancelled, } from "./ProcessCaptureError.js";
 import { startProcessSampler } from "./ProcessSampling.js";
 import { snapshotRoots } from "./FilesystemSnapshot.js";
 import { TerminalRenderer } from "./TerminalRenderer.js";
@@ -15,14 +14,11 @@ import { createProcessCaptureJournal, scheduleScenarioInteractions, } from "./Pr
 import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
 import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
 import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
-import { DarwinProcessOwnershipInspectionError } from "../DarwinProcessRunTokenReader.js";
-export { probeProcessCaptureCapability } from "./ProcessCaptureCapability.js";
 const cleanupFailedStartup = async (options) => {
     const sampledProcessGroupIds = options.terminal !== undefined &&
         options.observations?.process_samples.state === "available"
         ? selectCapturedProcessGroupIds(options.terminal.pid, options.observations.process_samples.value).filter((groupId) => groupId !== options.terminal?.pid)
         : undefined;
-    options.terminal?.kill("SIGKILL");
     if (options.observations !== undefined && options.renderer !== undefined) {
         try {
             options.observations.rendered_frames = {
@@ -89,7 +85,7 @@ const startCaptureRuntime = async (options) => {
             value: scenario.normalization.pids ? 1 : terminal.pid,
         };
         const executableIdentity = observeLaunchedExecutable(scenario.executable, selectedExecutable);
-        const framesTruncated = captureTerminalFrames({
+        const rawTerminalRetention = captureTerminalFrames({
             ...options,
             terminal,
             started,
@@ -117,7 +113,7 @@ const startCaptureRuntime = async (options) => {
             startedAt,
             executableIdentity,
             lastOutput: () => lastOutput,
-            framesTruncated,
+            rawTerminalRetention,
             stopSampler,
         };
     }
@@ -181,18 +177,6 @@ const finishProcessRun = async (options) => {
         : { scenario: options.scenario, rootPid };
     return resolveProcessResult(cleanupFailure === undefined ? verifiedCapture : capture, executionFailure, cleanup, options.observations, partialContext);
 };
-/** Preserve typed process-inspection preflight failures at the capture boundary. */
-export const normalizeCaptureFailure = (cause, signal) => {
-    if (cause instanceof ProcessCaptureError)
-        return cause;
-    if (cause instanceof DarwinProcessOwnershipInspectionError)
-        return new ProcessCaptureError(cause.message, { cause });
-    if (signal?.aborted === true &&
-        (cause === signal.reason ||
-            (cause instanceof Error && cause.name === "AbortError")))
-        return processCaptureCancelled();
-    return cause;
-};
 const completeCapture = async (options) => {
     const unavailableReason = (stage, cause) => `${stage} failed: ${cause instanceof Error ? cause.message : "unknown failure"}`;
     const { runtime, scenario } = options;
@@ -201,7 +185,7 @@ const completeCapture = async (options) => {
         throw processCaptureCancelled();
     let settlement;
     try {
-        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform);
+        settlement = await observeSettlement(options.runId, selectCapturedProcessGroupIds(runtime.terminal.pid, options.samples), scenario.settle_ms, options.recordEvent, options.hostPlatform, options.signal);
     }
     catch (cause) {
         options.observationBuffer.settlement = {
@@ -214,7 +198,8 @@ const completeCapture = async (options) => {
         state: "available",
         value: settlement,
     };
-    const samplingPartial = (await runtime.stopSampler()).partial;
+    const sampling = await runtime.stopSampler();
+    const samplingPartial = sampling.partial;
     await settleProcessCaptureJournal(options.eventJournal);
     assertNotCancelled(options.signal);
     let after;
@@ -266,7 +251,7 @@ const completeCapture = async (options) => {
             name: "after_settlement",
             at_ms: Math.max(0, Date.now() - runtime.started),
             files: after.files,
-            effects: classifyFilesystemEffects(options.before.files, after.files),
+            effects: classifyFilesystemEffects(options.before, after),
             truncated: after.truncated,
         },
     ];
@@ -284,7 +269,8 @@ const completeCapture = async (options) => {
     options.observationBuffer.manifest = { state: "available", value: manifest };
     const truncated = options.initiallyTruncated ||
         after.truncated ||
-        runtime.framesTruncated() ||
+        runtime.rawTerminalRetention().observed_frames >
+            runtime.rawTerminalRetention().retained_frames ||
         checkpoints.some(({ truncated: partial }) => partial) ||
         samplingPartial ||
         runtime.renderer.truncated();
@@ -295,6 +281,17 @@ const completeCapture = async (options) => {
         before: options.before,
         after,
         truncated,
+        ...(options.before.coverage === undefined || after.coverage === undefined
+            ? {}
+            : {
+                truncationDetails: {
+                    raw_terminal: runtime.rawTerminalRetention(),
+                    rendered_terminal: runtime.renderer.retention(),
+                    filesystem_before: options.before.coverage,
+                    filesystem_after: after.coverage,
+                    process: sampling.coverage,
+                },
+            }),
         scenario,
         rootPid: runtime.terminal.pid,
         samplingPartial,
@@ -389,7 +386,6 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
         });
     }
     catch (cause) {
-        runtime?.terminal.kill("SIGKILL");
         executionFailure = normalizeCaptureFailure(cause, signal);
         if (runtime !== undefined &&
             observations.rendered_frames.state === "unavailable" &&

package/dist/process/capture/ProcessNormalization.js

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 /** Bucket one elapsed process-capture timestamp under scenario normalization. */
 export const normalizeProcessElapsedTime = (elapsedMs, timeBucketMs) => Math.floor(elapsedMs / timeBucketMs) * timeBucketMs;
 /** Normalize one terminal/protocol payload under explicitly selected scenario rules. */
@@ -10,14 +11,31 @@ export const normalizeProcessText = (value, scenario, temporaryRoot, pid) => {
         for (const [index, root] of scenario.filesystem_observation_paths.entries())
             normalized = normalized.replaceAll(root, `<filesystem-root-${String(index)}>`);
     }
+    if (scenario.normalization.ports)
+        normalized = normalizePortTokens(normalized);
     if (scenario.normalization.pids)
         normalized = normalizePidTokens(normalized, [pid]);
-    if (scenario.normalization.ports)
-        normalized = normalized.replaceAll(/(?<=[:=])\d{2,5}\b/g, "<port>");
     for (const pattern of scenario.normalization.patterns)
         normalized = normalized.replaceAll(pattern.pattern, pattern.replacement);
     return normalized;
 };
+// A port may end a sentence, but a period followed by a letter, digit, or
+// underscore in any script continues a decimal, version, or host name and is
+// not a port boundary.
+// PTY chunks are normalized independently, so a period that ends the chunk
+// stays unnormalized: its continuation may arrive in the next chunk.
+const normalizePortTokens = (value) => {
+    const endpointNormalized = value.replaceAll(/(\b[a-z][a-z0-9+.-]*:\/\/[^\s/?#"'<>]+|\blocalhost|\b(?:\d{1,3}\.){3}\d{1,3}|\[[\da-f:.%]+\]):(\d{1,5})(?![\p{L}\p{N}_@:]|\.(?:[\p{L}\p{N}_]|$))/giu, (match, endpoint, port) => {
+        if (Number(port) > 65_535)
+            return match;
+        const isEndpoint = endpoint.includes("://")
+            ? URL.canParse(`${endpoint}:${port}`)
+            : endpoint.toLowerCase() === "localhost" ||
+                isIP(endpoint.replace(/^\[|\]$/gu, "")) !== 0;
+        return isEndpoint ? `${endpoint}:<port>` : match;
+    });
+    return endpointNormalized.replaceAll(/(\b(?:port|tcp_port|udp_port|listen)\b["']?\s*[:=]\s*)(\d{1,5})(?![\p{L}\p{N}_]|\.(?:[\p{L}\p{N}_]|$))/giu, (match, prefix, port) => Number(port) <= 65_535 ? `${prefix}<port>` : match);
+};
 /** Project sampled observations under the caller-selected normalization rules. */
 export const normalizeProcessSamples = (samples, scenario, rootPid) => {
     const identifiers = [

package/dist/process/capture/ProcessSampling.js

@@ -328,6 +328,9 @@ export const startProcessSampler = (options) => {
     let stopped = false;
     let abortCurrent;
     let partial = false;
+    let limitReached = false;
+    let samplingFailures = 0;
+    let firstSamplingFailure = null;
     let rootInitialized = false;
     const sample = () => {
         if (stopped || pending !== undefined)
@@ -363,6 +366,7 @@ export const startProcessSampler = (options) => {
                     continue;
                 if (samples.length >= limit) {
                     partial = true;
+                    limitReached = true;
                     continue;
                 }
                 lastObservations.set(value.pid, observation);
@@ -372,8 +376,16 @@ export const startProcessSampler = (options) => {
             }
         })
             .catch((cause) => {
-            if (!(cause instanceof Error && cause.name === "AbortError"))
+            if (!(cause instanceof Error && cause.name === "AbortError")) {
                 partial = true;
+                samplingFailures += 1;
+                firstSamplingFailure ??=
+                    cause instanceof Error
+                        ? `${cause.name}: ${cause.message}`
+                        : typeof cause === "string"
+                            ? cause
+                            : `Unexpected sampling rejection (${typeof cause})`;
+            }
         })
             .then(() => {
             abortCurrent = undefined;
@@ -387,6 +399,17 @@ export const startProcessSampler = (options) => {
         clearInterval(timer);
         abortCurrent?.();
         await pending;
-        return { partial };
+        return {
+            partial,
+            coverage: {
+                sample_limit: limit,
+                sampling_partial: partial,
+                retained_samples: samples.length,
+                sample_limit_reached: limitReached,
+                sampling_failures: samplingFailures,
+                first_sampling_failure: firstSamplingFailure,
+                coverage: "sampled",
+            },
+        };
     };
 };

package/dist/process/capture/TerminalRenderer.js

@@ -19,6 +19,8 @@ export class TerminalRenderer {
     #frames = [];
     #pending = Promise.resolve();
     #capturedBytes = 0;
+    #observedBytes = 0;
+    #observedFrames = 0;
     #truncated = false;
     constructor(options) {
         this.options = options;
@@ -55,6 +57,16 @@ export class TerminalRenderer {
     truncated() {
         return this.#truncated;
     }
+    /** Budget accounting after awaiting queued writes with frames(). */
+    retention() {
+        return {
+            budget_bytes: this.options.maxBytes,
+            observed_bytes: this.#observedBytes,
+            retained_bytes: this.#capturedBytes,
+            observed_frames: this.#observedFrames,
+            retained_frames: this.#frames.length,
+        };
+    }
     /** Release addon and terminal resources after all writes settle. */
     async dispose() {
         await this.#pending;
@@ -71,6 +83,8 @@ export class TerminalRenderer {
         const serializedState = this.options.normalize(this.#serializeAddon.serialize());
         const bytes = Buffer.byteLength(serializedState) +
             lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
+        this.#observedBytes += bytes;
+        this.#observedFrames += 1;
         if (this.#capturedBytes + bytes > this.options.maxBytes) {
             this.#truncated = true;
             return;

package/dist/process/snapshotEnvironment.js

@@ -0,0 +1,14 @@
+/** Snapshot caller-selected variables using Node child-process key semantics. */
+export const snapshotEnvironment = (environment, platform = process.platform) => {
+    if (platform !== "win32")
+        return Object.freeze({ ...environment });
+    const snapshot = {};
+    // Node sorts keys lexicographically and forwards the first case-insensitive
+    // match on Windows. Canonical keys also make subsequent lookups deterministic.
+    for (const key of Object.keys(environment).sort()) {
+        const canonicalKey = key.toUpperCase();
+        if (!Object.hasOwn(snapshot, canonicalKey))
+            snapshot[canonicalKey] = environment[key];
+    }
+    return Object.freeze(snapshot);
+};