Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(process): localize capture truncation diagnostics (#1284)
Ysopwnable33bf585185ff
diff --git a/docs/process-capture.md b/docs/process-capture.mdindex 0c5841470..d93a968f3 100644--- a/docs/process-capture.md+++ b/docs/process-capture.md@@ -119,7 +119,7 @@ all endpoint numbers in comparison text. Captures commit the port-normalizationversion so older broad numeric normalization cannot silently compare as thesame contract.-Output, file count, file size, process sampling, filesystem depth, total+Output retention, file count, aggregate file-hashing bytes, process sampling, filesystem depth, totalruntime, idle time, and post-exit settlement are bounded by the scenario'slimits. The result marks truncated observations and residual unknowns ratherthan treating missing data as proof of equivalence. Cancellation and timeout@@ -127,6 +127,35 @@ run the same owned-process cleanup path. Settlement reports whether thesampled process group quiesced or whether cleanup was needed or unverifiable;sampling cannot prove that every short-lived or detached descendant was seen.+New captures include `truncation_details`, with separate accounting for:++- `raw_terminal`: original UTF-8 PTY chunk bytes and observed/retained chunk+ counts. A chunk that does not fit `limits.output_bytes` is omitted whole;+ a later smaller chunk can still fit.+- `rendered_terminal`: cumulative UTF-8 serialized-state and visible-line+ bytes, plus observed/retained frame counts. This is independent of the raw+ chunk budget and does not count JSON encoding. Repeated screen snapshots can+ exhaust it even when all raw output fits. Rendered states use retained PTY+ input, so raw omissions also limit rendered coverage.+- `filesystem_before` and `filesystem_after`: file-count/depth limits,+ enumeration failures, whole-file hash budget and bytes successfully hashed.+ Each retained regular file without a digest has an aliased path, size,+ remaining budget and reason: `file_bytes_budget` or+ `file_changed_or_short_read`. A file too large for the remaining budget is+ skipped; a later smaller file can still be hashed. Hash omissions do not+ imply incomplete path enumeration.+- `process`: sampling limit and whether sampling ended partially. Coverage+ remains `sampled`, including when that limit was not exhausted.++The legacy `truncated` flag summarizes these observations. Comparisons retain+results for unaffected dimensions and mark affected dimensions unknown; an+incomplete capture cannot locate the first divergence across all dimensions.+Trace assertions use coverage for the sources they select, so an assertion+about complete raw terminal output need not fail because rendered snapshots+were omitted. Older truncated captures without these details retain the+conservative comparison behavior. These diagnostics use the existing scenario+budgets; they do not introduce a separate file-hashing budget.+When the host withholds an unrelated process’s ownership token, REA leaves thatprocess untouched and records its PID and reason in `cleanup.unverified_processes`and process residual unknowns. Successful cleanup verifies the owned group;diff --git a/src/domain/process/processCapture.ts b/src/domain/process/processCapture.tsindex bbfbdfa0c..414c97d4d 100644--- a/src/domain/process/processCapture.ts+++ b/src/domain/process/processCapture.ts@@ -3,6 +3,10 @@ import { jsonValueSchema } from "../jsonValue.js";import { normalizationSchema } from "./processScenario.js";import { collectProcessCaptureIssues } from "./processCaptureValidation.js";+import {+ processCaptureTruncationDetailsSchema,+ type ProcessCaptureTruncationDetails,+} from "./processCaptureCoverage.js";export * from "./processScenario.js";@@ -206,6 +210,8 @@ export interface UnverifiedProcessCapture {readonly files_after: readonly FileState[];readonly filesystem_effects: readonly FileEffect[];readonly truncated: boolean;+ /** Optional on older captures; identifies each producer's actual coverage. */+ readonly truncation_details?: ProcessCaptureTruncationDetails | undefined;readonly limitations: readonly string[];readonly residual_unknowns: readonly {readonly scope:@@ -477,6 +483,7 @@ const processCaptureShapeSchema = z.strictObject({files_after: z.array(fileStateSchema),filesystem_effects: z.array(fileEffectSchema),truncated: z.boolean(),+ truncation_details: processCaptureTruncationDetailsSchema.optional(),limitations: z.array(z.string()),residual_unknowns: z.array(z.object({diff --git a/src/domain/process/processCaptureCoverage.ts b/src/domain/process/processCaptureCoverage.tsnew file mode 100644index 000000000..5365961ef--- /dev/null+++ b/src/domain/process/processCaptureCoverage.ts@@ -0,0 +1,101 @@+import { z } from "zod";+import type { UnverifiedProcessCapture } from "./processCapture.js";+import type { ProcessObservationSource } from "./processObservation.js";++const byteRetentionSchema = z.strictObject({+ budget_bytes: z.number().int().nonnegative(),+ observed_bytes: z.number().int().nonnegative(),+ retained_bytes: z.number().int().nonnegative(),+ observed_frames: z.number().int().nonnegative(),+ retained_frames: z.number().int().nonnegative(),+});++/** Filesystem enumeration and whole-file digest coverage for one checkpoint. */+export const filesystemCoverageSchema = z.strictObject({+ files_limit: z.number().int().nonnegative(),+ depth_limit: z.number().int().nonnegative(),+ enumeration_truncated: z.boolean(),+ enumeration_reasons: z.array(+ z.enum(["files_limit", "depth_limit", "identity_changed"]),+ ),+ hash_budget_bytes: z.number().int().nonnegative(),+ hashed_bytes: z.number().int().nonnegative(),+ hash_omissions: z.array(+ z.strictObject({+ path: z.string(),+ size_bytes: z.number().int().nonnegative(),+ remaining_budget_bytes: z.number().int().nonnegative(),+ reason: z.enum(["file_bytes_budget", "file_changed_or_short_read"]),+ }),+ ),+});+export type FilesystemCoverage = z.infer<typeof filesystemCoverageSchema>;++/** Actual budget accounting; rendered bytes count state and visible lines, not JSON. */+export const processCaptureTruncationDetailsSchema = z.strictObject({+ raw_terminal: byteRetentionSchema.describe(+ "UTF-8 bytes of original PTY chunks; whole chunks are retained or omitted.",+ ),+ rendered_terminal: byteRetentionSchema.describe(+ "Cumulative UTF-8 bytes of serialized state plus visible lines, evaluated from retained PTY input; whole frames are retained or omitted.",+ ),+ filesystem_before: filesystemCoverageSchema,+ filesystem_after: filesystemCoverageSchema,+ process: z.strictObject({+ sample_limit: z.number().int().nonnegative(),+ sampling_partial: z.boolean(),+ retained_samples: z.number().int().nonnegative(),+ sample_limit_reached: z.boolean(),+ sampling_failures: z.number().int().nonnegative(),+ first_sampling_failure: z.string().nullable(),+ coverage: z.literal("sampled"),+ }),+});+export type ProcessCaptureTruncationDetails = z.infer<+ typeof processCaptureTruncationDetailsSchema+>;+export type TerminalRetention = ProcessCaptureTruncationDetails["raw_terminal"];+export type ProcessSamplingCoverage =+ ProcessCaptureTruncationDetails["process"];++const omitted = (retention: TerminalRetention): boolean =>+ retention.observed_frames > retention.retained_frames;+const filesystemTruncated = (coverage: FilesystemCoverage): boolean =>+ coverage.enumeration_truncated || coverage.hash_omissions.length > 0;++/** Derive the legacy aggregate flag from independent producer observations. */+export const hasCaptureTruncation = (+ details: ProcessCaptureTruncationDetails,+): boolean =>+ omitted(details.raw_terminal) ||+ omitted(details.rendered_terminal) ||+ filesystemTruncated(details.filesystem_before) ||+ filesystemTruncated(details.filesystem_after) ||+ details.process.sampling_partial;++/** Older truncated captures lack enough information to localize missing observations. */+export const processSourceTruncated = (+ capture: UnverifiedProcessCapture,+ source: ProcessObservationSource,+): boolean => {+ const details = capture.truncation_details;+ if (details === undefined) return capture.truncated;+ switch (source) {+ case "terminal_raw":+ return omitted(details.raw_terminal);+ case "terminal_rendered":+ return (+ omitted(details.raw_terminal) || omitted(details.rendered_terminal)+ );+ case "filesystem":+ return (+ filesystemTruncated(details.filesystem_before) ||+ filesystemTruncated(details.filesystem_after)+ );+ case "process":+ return details.process.sampling_partial;+ case "interaction":+ case "lifecycle":+ return false;+ }+};diff --git a/src/domain/process/processCaptureValidation.ts b/src/domain/process/processCaptureValidation.tsindex 9ab0f749c..02d0b8157 100644--- a/src/domain/process/processCaptureValidation.ts+++ b/src/domain/process/processCaptureValidation.ts@@ -1,5 +1,6 @@import type { UnverifiedProcessCapture } from "./processCapture.js";import { digestProcessCommitment } from "./processScenario.js";+import { hasCaptureTruncation } from "./processCaptureCoverage.js";/** One pure semantic validation failure in a shaped process capture. */export interface ProcessCaptureValidationIssue {@@ -121,6 +122,81 @@ const validateLifecycle = (null, "exit", "deadline termination cannot declare a normal exit code");};+const validateCoverage = (+ capture: UnverifiedProcessCapture,+ require: RequireInvariant,+): void => {+ const details = capture.truncation_details;+ if (details === undefined) return;+ require(details.process.retained_samples === capture.process_samples.length &&+ details.process.retained_samples <= details.process.sample_limit &&+ details.process.sampling_partial ===+ (details.process.sample_limit_reached ||+ details.process.sampling_failures > 0) &&+ (details.process.sampling_failures === 0) ===+ (details.process.first_sampling_failure ===+ null), "truncation_details.process", "sampling coverage must agree with retained samples and observed failures");+ require(capture.truncated ===+ hasCaptureTruncation(+ details,+ ), "truncation_details", "aggregate truncation must match producer coverage");+ for (const [name, retention, count] of [+ ["raw_terminal", details.raw_terminal, capture.frames.length],+ [+ "rendered_terminal",+ details.rendered_terminal,+ capture.rendered_frames.length,+ ],+ ] as const) {+ require(retention.retained_frames === count &&+ retention.observed_frames >= count &&+ retention.observed_bytes >= retention.retained_bytes &&+ retention.retained_bytes <=+ retention.budget_bytes, `truncation_details.${name}`, "retained observations and budget accounting do not agree");+ }+ for (const [name, coverage, files, checkpoint] of [+ [+ "filesystem_before",+ details.filesystem_before,+ capture.files_before,+ capture.filesystem_checkpoints[0],+ ],+ [+ "filesystem_after",+ details.filesystem_after,+ capture.files_after,+ capture.filesystem_checkpoints[1],+ ],+ ] as const) {+ const unhashedFiles = new Map(+ files+ .filter((file) => file.type === "file" && file.sha256 === null)+ .map((file) => [file.path, file]),+ );+ require(coverage.hash_omissions.length === unhashedFiles.size &&+ new Set(coverage.hash_omissions.map(({ path }) => path)).size ===+ unhashedFiles.size &&+ coverage.hash_omissions.every(+ (omission) =>+ unhashedFiles.get(omission.path)?.size === omission.size_bytes &&+ omission.remaining_budget_bytes <= coverage.hash_budget_bytes,+ ), `truncation_details.${name}.hash_omissions`, "every retained regular file without a digest must have one matching omission reason");+ require(coverage.hashed_bytes ===+ files+ .filter((file) => file.type === "file" && file.sha256 !== null)+ .reduce((sum, file) => sum + file.size, 0) &&+ coverage.hashed_bytes <= coverage.hash_budget_bytes &&+ files.length <=+ coverage.files_limit, `truncation_details.${name}`, "filesystem budget accounting does not match retained observations");+ require(coverage.enumeration_truncated ===+ coverage.enumeration_reasons.length > 0 &&+ checkpoint?.truncated ===+ (coverage.enumeration_truncated ||+ coverage.hash_omissions.length >+ 0), `truncation_details.${name}`, "filesystem checkpoint truncation must match enumeration and digest coverage");+ }+};+/** Recompute commitments and cross-field invariants without side effects. */export const collectProcessCaptureIssues = (capture: UnverifiedProcessCapture,@@ -133,5 +209,6 @@ export const collectProcessCaptureIssues = (validateOrdering(capture, require);validateEventJournal(capture, require);validateLifecycle(capture, require);+ validateCoverage(capture, require);return issues;};diff --git a/src/domain/process/processComparison.ts b/src/domain/process/processComparison.tsindex 04542631a..f0edec0ff 100644--- a/src/domain/process/processComparison.ts+++ b/src/domain/process/processComparison.ts@@ -1,5 +1,7 @@import canonicalize from "canonicalize";import { z } from "zod";+import { processSourceTruncated } from "./processCaptureCoverage.js";+import type { ProcessObservationSource } from "./processObservation.js";import type { ProcessCapture } from "./processCapture.js";import { comparableTerminalFrame } from "./processObservation.js";@@ -363,8 +365,13 @@ const compareDimensions = (scope: ProcessCapture["residual_unknowns"][number]["scope"],leftValues: readonly unknown[],rightValues: readonly unknown[],+ source: ProcessObservationSource,): ComparisonStatus =>- !sameNormalization || hasUnknown(left, scope) || hasUnknown(right, scope)+ !sameNormalization ||+ hasUnknown(left, scope) ||+ hasUnknown(right, scope) ||+ processSourceTruncated(left, source) ||+ processSourceTruncated(right, source)? "unknown": classifyCollection(leftValues, rightValues);return {@@ -372,11 +379,13 @@ const compareDimensions = ("terminal",terminalObservations(left),terminalObservations(right),+ "terminal_rendered",),interaction: classify("interaction",left.interaction_events,right.interaction_events,+ "interaction",),exit:hasUnknown(left, "exit") || hasUnknown(right, "exit")@@ -391,8 +400,14 @@ const compareDimensions = ("filesystem",filesystemObservations(left),filesystemObservations(right),+ "filesystem",+ ),+ process: classify(+ "process",+ left.process_samples,+ right.process_samples,+ "process",),- process: classify("process", left.process_samples, right.process_samples),};};@@ -412,7 +427,10 @@ export const compareProcessCaptures = (} = {},): ProcessCaptureComparison => {assertComparable(left, right, options);- if (left.truncated || right.truncated) {+ if (+ (left.truncated && left.truncation_details === undefined) ||+ (right.truncated && right.truncation_details === undefined)+ ) {const truncated = truncatedComparison();return options.traceSpecification === undefined? truncated@@ -438,11 +456,13 @@ export const compareProcessCaptures = (right,]);const divergenceCandidates = PROCESS_COMPARISON_DIMENSIONS.map((dimension) =>- firstCollectionDivergence(- dimension,- processDimensionObservations(left, dimension),- processDimensionObservations(right, dimension),- ),+ dimensions[dimension] === "unknown"+ ? null+ : firstCollectionDivergence(+ dimension,+ processDimensionObservations(left, dimension),+ processDimensionObservations(right, dimension),+ ),);const observedFirstDivergence = chooseFirstDivergence(divergenceCandidates.map((candidate) =>@@ -454,22 +474,30 @@ export const compareProcessCaptures = (),);const firstDivergence =- trace?.verdict === "equivalent" &&- deriveProcessComparisonStatus(- PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension]),- ) === "unchanged"- ? ({ status: "none" } as const)- : observedFirstDivergence.status === "found"- ? observedFirstDivergence- : !sameNormalization ||- left.residual_unknowns.length > 0 ||- right.residual_unknowns.length > 0- ? ({- status: "unknown",- reason:- "Residual unknowns prevent proving that no divergence occurred.",- } as const)- : observedFirstDivergence;+ left.truncated || right.truncated+ ? ({+ status: "unknown",+ reason:+ "Incomplete observations prevent locating the first divergence; unaffected dimensions retain their comparisons.",+ } as const)+ : trace?.verdict === "equivalent" &&+ deriveProcessComparisonStatus(+ PROCESS_COMPARISON_DIMENSIONS.map(+ (dimension) => dimensions[dimension],+ ),+ ) === "unchanged"+ ? ({ status: "none" } as const)+ : observedFirstDivergence.status === "found"+ ? observedFirstDivergence+ : !sameNormalization ||+ left.residual_unknowns.length > 0 ||+ right.residual_unknowns.length > 0+ ? ({+ status: "unknown",+ reason:+ "Residual unknowns prevent proving that no divergence occurred.",+ } as const)+ : observedFirstDivergence;const observedStatus = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => dimensions[dimension]),);diff --git a/src/domain/process/processTraceEvaluation.ts b/src/domain/process/processTraceEvaluation.tsindex e4c5e7cb8..3a65b3284 100644--- a/src/domain/process/processTraceEvaluation.ts+++ b/src/domain/process/processTraceEvaluation.ts@@ -2,6 +2,7 @@ import { z } from "zod";import type { JsonValue } from "../jsonValue.js";import type { ProcessCapture } from "./processCapture.js";+import { processSourceTruncated } from "./processCaptureCoverage.js";import {processObservationLocationSchema,projectProcessObservation,@@ -414,7 +415,7 @@ export const evaluateProcessTraceSide = (const sources = new Set(specification.events.map(({ source }) => source));const relevantScopes = scopesFor(sources);const incomplete =- capture.truncated ||+ [...sources].some((source) => processSourceTruncated(capture, source)) ||capture.residual_unknowns.some(({ scope }) => relevantScopes.has(scope));if (capture.event_journal.length === 0)return {diff --git a/src/process/capture/FilesystemSnapshot.ts b/src/process/capture/FilesystemSnapshot.tsindex b8880a630..d8fc9bf5e 100644--- a/src/process/capture/FilesystemSnapshot.ts+++ b/src/process/capture/FilesystemSnapshot.ts@@ -7,12 +7,14 @@ import type {ProcessScenario,} from "../../domain/process/processCapture.js";import type { Stats } from "node:fs";+import type { FilesystemCoverage } from "../../domain/process/processCaptureCoverage.js";export interface SnapshotResult {readonly files: readonly FileState[];readonly truncated: boolean;/** Root aliases whose path enumeration was exhausted, regardless of hash coverage. */readonly completeRoots: readonly string[];+ readonly coverage?: FilesystemCoverage;}const hasSameIdentity = (@@ -97,6 +99,10 @@ export const snapshotRoots = async (const completeRoots: string[] = [];let remainingBytes = scenario.limits.file_bytes;let truncated = false;+ const enumerationReasons = new Set<+ FilesystemCoverage["enumeration_reasons"][number]+ >();+ const hashOmissions: FilesystemCoverage["hash_omissions"] = [];const visit = async (root: string,rootAlias: string,@@ -109,6 +115,10 @@ export const snapshotRoots = async (depth > scenario.limits.filesystem_depth) {truncated = true;+ if (entries.length >= scenario.limits.files)+ enumerationReasons.add("files_limit");+ if (depth > scenario.limits.filesystem_depth)+ enumerationReasons.add("depth_limit");return false;}const stats = await lstatIfPresent(path);@@ -119,6 +129,7 @@ export const snapshotRoots = async (const afterRead = await lstat(path);if (!hasSameIdentity(stats, afterRead, "symlink")) {truncated = true;+ enumerationReasons.add("identity_changed");return false;}entries.push({@@ -137,7 +148,18 @@ export const snapshotRoots = async (? await hashFile(path, stats, remainingBytes, signal): null;remainingBytes -= sha256 === null ? 0 : stats.size;- if (sha256 === null) truncated = true;+ if (sha256 === null) {+ truncated = true;+ hashOmissions.push({+ path: `${rootAlias}:${relativePath}`,+ size_bytes: stats.size,+ remaining_budget_bytes: remainingBytes,+ reason:+ remainingBytes < stats.size+ ? "file_bytes_budget"+ : "file_changed_or_short_read",+ });+ }entries.push({path: `${rootAlias}:${relativePath}`,type: "file",@@ -162,6 +184,7 @@ export const snapshotRoots = async (const afterRead = await lstat(path);if (!hasSameIdentity(stats, afterRead, "directory")) {truncated = true;+ enumerationReasons.add("identity_changed");return false;}let complete = true;@@ -179,5 +202,19 @@ export const snapshotRoots = async (}if (await visit(root, alias, root, 0)) completeRoots.push(alias);}- return { files: entries, truncated, completeRoots };+ return {+ files: entries,+ truncated,+ completeRoots,+ coverage: {+ files_limit: scenario.limits.files,+ depth_limit: scenario.limits.filesystem_depth,+ enumeration_truncated:+ completeRoots.length !== scenario.filesystem_observation_paths.length,+ enumeration_reasons: [...enumerationReasons],+ hash_budget_bytes: scenario.limits.file_bytes,+ hashed_bytes: scenario.limits.file_bytes - remainingBytes,+ hash_omissions: hashOmissions,+ },+ };};diff --git a/src/process/capture/ProcessCaptureLifecycle.ts b/src/process/capture/ProcessCaptureLifecycle.tsindex 86cd88d0c..ca183d3c1 100644--- a/src/process/capture/ProcessCaptureLifecycle.ts+++ b/src/process/capture/ProcessCaptureLifecycle.ts@@ -59,6 +59,11 @@ import {} from "./ProcessNormalization.js";import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";import { TerminalRenderer } from "./TerminalRenderer.js";+import {+ hasCaptureTruncation,+ type TerminalRetention,+ type ProcessCaptureTruncationDetails,+} from "../../domain/process/processCaptureCoverage.js";import { scheduleProcessInterval, type ProcessTimer } from "./ProcessTimer.js";interface TerminalExitOptions {@@ -84,6 +89,7 @@ interface CaptureResultOptions {readonly before: SnapshotResult;readonly after: SnapshotResult;readonly truncated: boolean;+ readonly truncationDetails?: ProcessCaptureTruncationDetails;readonly scenario: ProcessScenario;readonly rootPid: number;readonly samplingPartial: boolean;@@ -279,7 +285,13 @@ export const buildCaptureResult = (files_before: options.before.files,files_after: options.after.files,filesystem_effects: filesystemEffects,- truncated: options.truncated,+ 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.",@@ -290,6 +302,11 @@ export const buildCaptureResult = ("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: [@@ -330,10 +347,61 @@ export const buildCaptureResult = (...(hasSensitiveScriptedInput? [{ scope: "interaction" as const, reason: sensitiveInputUnknown }]: []),+ ...(options.truncationDetails === undefined+ ? []+ : captureCoverageUnknowns(options.truncationDetails).filter(+ ({ scope }) => scope !== "terminal",+ )),],};};+const captureCoverageUnknowns = (+ details: ProcessCaptureTruncationDetails,+): UnverifiedProcessCapture["residual_unknowns"] => {+ const unknowns: Array<UnverifiedProcessCapture["residual_unknowns"][number]> =+ [];+ 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],+ ] as const) {+ 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;+};+interface ExecutableFileIdentity {readonly dev: bigint;readonly ino: bigint;@@ -840,14 +908,16 @@ export const captureTerminalFrames = (options: {readonly onOutput: () => void;readonly renderer: TerminalRenderer;readonly recordEvent: RecordProcessCaptureEvent;-}): (() => boolean) => {+}): (() => TerminalRetention) => {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;@@ -871,7 +941,13 @@ export const captureTerminalFrames = (options: {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 = (diff --git a/src/process/capture/ProcessHarness.ts b/src/process/capture/ProcessHarness.tsindex 672e5209b..f573b32c7 100644--- a/src/process/capture/ProcessHarness.ts+++ b/src/process/capture/ProcessHarness.ts@@ -1,4 +1,5 @@import type { IPty } from "@lydell/node-pty";+import type { TerminalRetention } from "../../domain/process/processCaptureCoverage.js";import type {InteractionEvent,ProcessCapture,@@ -65,8 +66,8 @@ interface StartedCaptureRuntime {readonly startedAt: Date;readonly executableIdentity: ReturnType<typeof observeLaunchedExecutable>;readonly lastOutput: () => number;- readonly framesTruncated: () => boolean;- readonly stopSampler: () => Promise<{ readonly partial: boolean }>;+ readonly rawTerminalRetention: () => TerminalRetention;+ readonly stopSampler: ReturnType<typeof startProcessSampler>;}const cleanupFailedStartup = async (options: {@@ -200,7 +201,7 @@ const startCaptureRuntime = async (scenario.executable,selectedExecutable,);- const framesTruncated = captureTerminalFrames({+ const rawTerminalRetention = captureTerminalFrames({...options,terminal,started,@@ -228,7 +229,7 @@ const startCaptureRuntime = async (startedAt,executableIdentity,lastOutput: () => lastOutput,- framesTruncated,+ rawTerminalRetention,stopSampler,};} catch (cause: unknown) {@@ -365,7 +366,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: Awaited<ReturnType<typeof snapshotRoots>>;@@ -439,7 +441,8 @@ const completeCapture = async (options: {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();@@ -450,6 +453,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,diff --git a/src/process/capture/ProcessSampling.ts b/src/process/capture/ProcessSampling.tsindex e8ee7cefb..518d91932 100644--- a/src/process/capture/ProcessSampling.ts+++ b/src/process/capture/ProcessSampling.ts@@ -1,4 +1,5 @@import { readFile, readdir } from "node:fs/promises";+import type { ProcessSamplingCoverage } from "../../domain/process/processCaptureCoverage.js";import type {ProcessSample,RecordProcessCaptureEvent,@@ -455,7 +456,10 @@ export const startProcessSampler = (options: {readonly limit: number;readonly samples: ProcessSample[];readonly recordEvent?: RecordProcessCaptureEvent;-}): (() => Promise<{ readonly partial: boolean }>) => {+}): (() => Promise<{+ readonly partial: boolean;+ readonly coverage: ProcessSamplingCoverage;+}>) => {const { rootPid, runId, started, limit, samples } = options;const identities = new Map<number, string>();const lastObservations = new Map<number, string>();@@ -463,6 +467,9 @@ export const startProcessSampler = (options: {let stopped = false;let abortCurrent: (() => void) | undefined;let partial = false;+ let limitReached = false;+ let samplingFailures = 0;+ let firstSamplingFailure: string | null = null;let rootInitialized = false;const sample = (): void => {@@ -501,6 +508,7 @@ export const startProcessSampler = (options: {if (lastObservations.get(value.pid) === observation) continue;if (samples.length >= limit) {partial = true;+ limitReached = true;continue;}lastObservations.set(value.pid, observation);@@ -510,8 +518,16 @@ export const startProcessSampler = (options: {}}).catch((cause: unknown) => {- 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;@@ -527,6 +543,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",+ },+ };};};diff --git a/src/process/capture/TerminalRenderer.ts b/src/process/capture/TerminalRenderer.tsindex 0a0492008..e7f1a0fc8 100644--- a/src/process/capture/TerminalRenderer.ts+++ b/src/process/capture/TerminalRenderer.ts@@ -1,4 +1,5 @@import { createRequire } from "node:module";+import type { TerminalRetention } from "../../domain/process/processCaptureCoverage.js";import type {RecordProcessCaptureEvent,@@ -36,6 +37,8 @@ export class TerminalRenderer {readonly #frames: RenderedTerminalFrame[] = [];#pending: Promise<void> = Promise.resolve();#capturedBytes = 0;+ #observedBytes = 0;+ #observedFrames = 0;#truncated = false;constructor(private readonly options: TerminalRendererOptions) {@@ -80,6 +83,17 @@ export class TerminalRenderer {return this.#truncated;}+ /** Budget accounting after awaiting queued writes with frames(). */+ retention(): TerminalRetention {+ 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(): Promise<void> {await this.#pending;@@ -107,6 +121,8 @@ export class TerminalRenderer {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;diff --git a/tests/acceptance/tools/localToolContracts.test.ts b/tests/acceptance/tools/localToolContracts.test.tsindex 7bfc9dfc0..c00678633 100644--- a/tests/acceptance/tools/localToolContracts.test.ts+++ b/tests/acceptance/tools/localToolContracts.test.ts@@ -207,16 +207,16 @@ captureTest(60_000,);-captureTest.each(["unknown", "truncated"] as const)(+captureTest.each(["untruncated", "truncated"] as const)("captures real process choices and composes a %s self-comparison",- async (status) => {+ async (captureState) => {const root = await createTestTempDirectory("rea-local-capture-");const { call } = await connectLocalToolsMcp();const captured = await call("capture_process_scenario", {executable: process.execPath,arguments: ["-e",- `require('node:fs').writeFileSync('state','selected');console.log(process.env['app.setting'],process.env.MY_PASSWORD,process.env['REA_PROCESS_RUN_ID'+String.fromCharCode(10)]);${status === "truncated" ? "console.log('x'.repeat(5000))" : ""}`,+ `require('node:fs').writeFileSync('state','selected');console.log(process.env['app.setting'],process.env.MY_PASSWORD,process.env['REA_PROCESS_RUN_ID'+String.fromCharCode(10)]);${captureState === "truncated" ? "console.log('x'.repeat(5000))" : ""}`,],working_directory: root,environment: {@@ -226,14 +226,14 @@ captureTest.each(["unknown", "truncated"] as const)("REA_PROCESS_RUN_ID\n": "caller-value",},filesystem_observation_paths: [root],- limits: status === "truncated" ? { output_bytes: 128 } : {},+ limits: captureState === "truncated" ? { output_bytes: 128 } : {},});expect(captured.isError, JSON.stringify(captured)).not.toBe(true);const capture = toolContract("capture_process_scenario").outputSchema.parse(captured.structuredContent,);const source = capture;- if (status === "unknown")+ if (captureState === "untruncated")expect(capture.normalized_result.frames.map((frame) => frame.data).join(""),).toContain("value ordinary-evidence caller-value");@@ -266,7 +266,13 @@ captureTest.each(["unknown", "truncated"] as const)(const comparison = toolContract("compare_process_captures",).outputSchema.parse(compared.structuredContent);- expect(comparison.normalized_result.status).toBe(status);+ expect(comparison.normalized_result).toMatchObject({+ status: "unknown",+ terminal: captureState === "truncated" ? "unknown" : "unchanged",+ interaction: "unchanged",+ exit: "unchanged",+ process: "unknown",+ });const verification = await call("verify_reconstruction", {specification: {name: "Self comparison retains uncertainty",@@ -304,7 +310,7 @@ captureTest.each(["unknown", "truncated"] as const)(});expect(behavior.isError, JSON.stringify(behavior)).not.toBe(true);expect(behavior.structuredContent).toMatchObject({- normalized_result: { behavior_status: status },+ normalized_result: { behavior_status: "unknown" },});const unknowns = await call("list_unknowns", {domain: "process-comparison",diff --git a/tests/boundary/process/processCaptureNormalization.test.ts b/tests/boundary/process/processCaptureNormalization.test.tsindex 468339c86..9006cd41e 100644--- a/tests/boundary/process/processCaptureNormalization.test.ts+++ b/tests/boundary/process/processCaptureNormalization.test.ts@@ -129,7 +129,7 @@ itWithLinuxCaptureCapability.each([false, true])(state: "quiesced",cleanup_outcome: "not_required",});- expect(capture.cleanup).toEqual({+ expect(capture.cleanup).toMatchObject({owned_process_group: "verified",temporary_root: "removed",});diff --git a/tests/boundary/process/processTruncationAdapters.test.ts b/tests/boundary/process/processTruncationAdapters.test.tsnew file mode 100644index 000000000..7a46e5aab--- /dev/null+++ b/tests/boundary/process/processTruncationAdapters.test.ts@@ -0,0 +1,270 @@+import { execFile } from "node:child_process";+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { promisify } from "node:util";+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { expect, onTestFinished } from "vitest";+import { parseEvidence } from "../../../src/domain/evidence.js";+import {+ compareProcessCaptures,+ parseProcessCapture,+ processCaptureSchema,+} from "../../../src/domain/process/processCapture.js";+import { processSourceTruncated } from "../../../src/domain/process/processCaptureCoverage.js";+import { compareProcessTraces } from "../../../src/domain/process/processTraceComparison.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { itWithCaptureCapability } from "./processCaptureCapability.js";++const exec = promisify(execFile);+const capture = async (+ adapter: "cli" | "mcp",+ scenario: Record<string, unknown>,+) => {+ if (adapter === "cli") {+ const path = join(+ await createTestTempDirectory("rea-truncation-scenario-"),+ "scenario.json",+ );+ await writeFile(path, JSON.stringify(scenario));+ const { stdout } = await exec(process.execPath, [+ "scripts/rea.mjs",+ "capture-process",+ path,+ "--format",+ "json",+ ]);+ return parseProcessCapture(+ parseEvidence(JSON.parse(stdout)).normalized_result,+ );+ }+ const session = createTestBinarySession(() => {+ throw new Error("Capture must not launch a binary provider");+ });+ const server = createServer(session, session);+ const client = new Client({ name: "truncation-coverage", version: "1" });+ onTestFinished(async () => {+ await client.close();+ await server.close();+ await session.close();+ });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ const result = await client.callTool({+ name: "capture_process_scenario",+ arguments: scenario,+ });+ expect(result.isError, JSON.stringify(result)).not.toBe(true);+ await client.ping();+ return parseProcessCapture(+ parseEvidence(result.structuredContent).normalized_result,+ );+};++itWithCaptureCapability.each(["cli", "mcp"] as const)(+ "localizes sparse rendered-state exhaustion through %s",+ async (adapter) => {+ const root = await createTestTempDirectory("rea-rendered-budget-");+ const result = await capture(adapter, {+ executable: process.execPath,+ working_directory: root,+ arguments: [+ "-e",+ "let n=0;const timer=setInterval(()=>{console.log('board '+String(n).padStart(2,'0')+' completed; score '+String(n*10));if(++n===65)clearInterval(timer)},20)",+ ],+ normalization: {+ ports: false,+ pids: false,+ paths: false,+ time_bucket_ms: 1,+ },+ limits: { output_bytes: 30_000 },+ });+ const details = result.truncation_details;+ if (details === undefined) throw new Error("Expected producer coverage");+ expect(result.frames.map(({ data }) => data).join("")).toContain(+ "board 64 completed; score 640",+ );+ expect(details.raw_terminal.observed_bytes).toBe(2004);+ expect(details.raw_terminal.retained_bytes).toBe(+ details.raw_terminal.observed_bytes,+ );+ expect(details.raw_terminal.observed_frames).toBe(result.frames.length);+ expect(details.rendered_terminal.observed_frames).toBeGreaterThan(+ result.rendered_frames.length,+ );+ expect(details.rendered_terminal.retained_bytes).toBeLessThanOrEqual(+ 30_000,+ );+ expect(details.process.coverage).toBe("sampled");+ expect(processSourceTruncated(result, "terminal_raw")).toBe(false);+ expect(processSourceTruncated(result, "terminal_rendered")).toBe(true);+ const events = result.frames.map(({ sequence, at_ms, data }) => ({+ id: `chunk_${String(sequence)}`,+ source: "terminal_raw" as const,+ exact: { sequence, at_ms, data },+ cardinality: { kind: "required" as const },+ }));+ const specification = {+ events,+ language: {+ kind: "finite_traces" as const,+ variants: [{ id: "observed", trace: events.map(({ id }) => id) }],+ },+ };+ expect(compareProcessTraces(result, result, specification).verdict).toBe(+ "equivalent",+ );+ const legacy = parseProcessCapture({+ ...result,+ truncation_details: undefined,+ });+ expect(compareProcessTraces(legacy, legacy, specification).verdict).toBe(+ "unknown",+ );+ expect(compareProcessCaptures(result, result)).toMatchObject({+ terminal: "unknown",+ interaction: "unchanged",+ exit: "unchanged",+ });+ expect(+ processCaptureSchema.safeParse({ ...result, truncated: false }).success,+ ).toBe(false);+ },+ 20_000,+);++itWithCaptureCapability.each(["cli", "mcp"] as const)(+ "distinguishes raw chunk omission and filesystem exhaustion through %s",+ async (adapter) => {+ const root = await createTestTempDirectory("rea-raw-files-budget-");+ await writeFile(join(root, "a.txt"), "abc");+ await writeFile(join(root, "b.txt"), "12345678");+ const result = await capture(adapter, {+ executable: process.execPath,+ working_directory: root,+ arguments: [+ "-e",+ "process.stdout.write('x'.repeat(1000));require('node:fs').writeFileSync('c.txt','new');setTimeout(()=>{},100)",+ ],+ filesystem_observation_paths: [root],+ limits: { output_bytes: 50, files: 3, file_bytes: 4 },+ });+ const details = result.truncation_details;+ if (details === undefined) throw new Error("Expected producer coverage");+ expect(details.raw_terminal.observed_bytes).toBe(1000);+ expect(details.raw_terminal.retained_bytes).toBeLessThan(+ details.raw_terminal.observed_bytes,+ );+ expect(details.filesystem_before).toMatchObject({+ enumeration_truncated: false,+ hashed_bytes: 3,+ hash_omissions: [+ {+ path: "root_0:b.txt",+ size_bytes: 8,+ remaining_budget_bytes: 1,+ reason: "file_bytes_budget",+ },+ ],+ });+ expect(details.filesystem_after.enumeration_reasons).toContain(+ "files_limit",+ );+ expect(+ result.files_after.find(({ path }) => path === "root_0:b.txt")?.sha256,+ ).toBeNull();+ expect(processSourceTruncated(result, "terminal_rendered")).toBe(true);+ expect(compareProcessCaptures(result, result)).toMatchObject({+ terminal: "unknown",+ filesystem: "unknown",+ interaction: "unchanged",+ exit: "unchanged",+ });+ },+ 20_000,+);++itWithCaptureCapability.each(["cli", "mcp"] as const)(+ "keeps terminal facts comparable when only file digests are omitted through %s",+ async (adapter) => {+ const root = await createTestTempDirectory("rea-hash-budget-");+ await writeFile(join(root, "a.txt"), "abc");+ await writeFile(join(root, "b.txt"), "12345678");+ await writeFile(join(root, "c.txt"), "z");+ const result = await capture(adapter, {+ executable: process.execPath,+ working_directory: root,+ arguments: ["-e", "console.log('done');setTimeout(()=>{},100)"],+ filesystem_observation_paths: [root],+ limits: { file_bytes: 4 },+ });+ expect(result.truncation_details?.filesystem_after).toMatchObject({+ enumeration_truncated: false,+ hashed_bytes: 4,+ hash_omissions: [+ {+ path: "root_0:b.txt",+ reason: "file_bytes_budget",+ remaining_budget_bytes: 1,+ },+ ],+ });+ expect(+ result.files_after.find(({ path }) => path === "root_0:c.txt")?.sha256,+ ).toMatch(/^[a-f0-9]{64}$/u);+ expect(compareProcessCaptures(result, result)).toMatchObject({+ terminal: "unchanged",+ filesystem: "unknown",+ interaction: "unchanged",+ exit: "unchanged",+ });+ const differentExit = parseProcessCapture({+ ...result,+ exit: { ...result.exit, code: 1 },+ });+ expect(compareProcessCaptures(result, differentExit)).toMatchObject({+ status: "changed",+ terminal: "unchanged",+ filesystem: "unknown",+ exit: "changed",+ first_divergence: { status: "unknown" },+ });+ },+ 20_000,+);++itWithCaptureCapability.each(["cli", "mcp"] as const)(+ "reports process sample-limit exhaustion without erasing other dimensions through %s",+ async (adapter) => {+ const root = await createTestTempDirectory("rea-process-budget-");+ const result = await capture(adapter, {+ executable: process.execPath,+ working_directory: root,+ arguments: [+ "-e",+ "setTimeout(()=>require('node:child_process').spawn(process.execPath,['-e','setTimeout(()=>{},800)'],{stdio:'ignore'}),100);console.log('ready')",+ ],+ limits: { processes: 1 },+ });+ expect(result.truncation_details?.process).toMatchObject({+ sample_limit: 1,+ sampling_partial: true,+ retained_samples: 1,+ sample_limit_reached: true,+ sampling_failures: 0,+ first_sampling_failure: null,+ coverage: "sampled",+ });+ expect(compareProcessCaptures(result, result)).toMatchObject({+ terminal: "unchanged",+ interaction: "unchanged",+ exit: "unchanged",+ process: "unknown",+ });+ },+ 20_000,+);