Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / cli-evidence-and-runtime-commands

CLI evidence and runtime commands

The evidence and runtime CLI commands turn local records, captured browser artifacts, and live JavaScript observations into portable, structured results. They use the same evidence contracts as the wider CLI and MCP surfaces, but each CLI call is independent, so later work must read saved JSON or an Evidence bundle. See the command-line interface page for shared CLI behavior, the browser workflow page for CDP commands, and session evidence and results for the wider evidence model.

Command groups

The command groups cover related tasks: preserving evidence for later work, collecting passive facts from a Node or Electron runtime, inspecting API declarations, capturing a Linux desktop application session, and analyzing selected browser artifacts without reopening the original session.

GroupMain commandsPurpose
Evidence bundlesevidence-import, evidence-export, compare, inspect-evidence-bundleValidate, canonicalize, compare, and inspect saved Evidence
Saved analysis viewsinspect-analysis-viewProject a smaller view from completed analysis Evidence
API contract evidenceinspect-api-contractInspect local OpenAPI JSON or GraphQL SDL declarations without network access or code execution
Desktop evidencecapture-desktop-application, inspect-desktop-application-state, describe-desktop-application-task, export-desktop-applicationCapture and package a Linux desktop application's state and session changes
JavaScript runtimelist-javascript-runtime-targets, observe-javascript-runtimeDiscover Inspector targets and passively observe one selected target
Browser runtime evidenceobserve-web-execution, inspect-web-event-listenersObserve externally driven page execution or inspect one selected node
Captured web evidencetrace-web-source-location, trace-web-module-importsRelate retained scripts to source maps and native module imports
JavaScript source recoveryrecover-javascript-sourcesProduce readable derived modules with source provenance
Evidence-backed application workreconcile-javascript-runtime, trace-application-feature, trace-javascript-semantics, and comparison commandsRelate saved static and runtime Evidence without reopening the target

Command registration

The CLI builds one one-shot command surface. It creates the shared analysis context, registers evidence, API contract, desktop, browser, and runtime command groups, and applies argument normalization and sensitive-argument filtering before serving a command. Each command validates its caller input before it invokes the application workflow, then converts a successful value or an analysis error into the common CLI result stream. JavaScript runtime observation is registered under the current src/…/javascriptRuntimeCommands.ts path, while the command names remain stable across the rename. Runtime commands also use command cancellation and a runtime-specific error label while retaining the shared analysis error details.

References: src/cli.ts• L71-83 src/cli.ts• L149-181 src/…/apiContractCommand.ts• L43-135 src/…/desktopCaptureCommands.ts• L298-576 src/…/javascriptRuntimeCommands.ts• L37-148 src/cliCommandNames.ts• L68-72 src/cliCommandNames.ts• L157-180

Evidence bundle commands

An Evidence bundle is a saved collection of records and unresolved findings. The bundle commands make that collection safe to move between independent CLI calls while keeping validation and comparison separate from live provider sessions.

Bundle validation and export

evidence-import reads one local bundle and reports its record and unknown counts after validation. evidence-export reads a source bundle and writes deterministic canonical JSON to a destination; an existing destination is preserved unless --overwrite is supplied.

flowchart LR
    A[Source Evidence JSON] --> B[Validate bundle]
    B --> C{Command}
    C -->|evidence-import| D[Counts and validation result]
    C -->|evidence-export| E[Canonical Evidence JSON]

The export result identifies the output path, byte count, and number of records. A failed validation or write is returned as structured error data rather than as a partial success. Evidence written as JSON uses a compact document followed by a newline, so its reported file size represents the emitted result.

References: src/cliEvidenceCommands.ts• L20-48 src/…/EvidenceBundleCommands.ts• L18-67 src/…/EvidenceBundleFiles.ts• L38-44 src/…/EvidenceBundleFiles.ts• L114-147 src/…/environmentEvidenceBytes.ts• L4-18

Bundle comparison and inspection

compare validates two bundles and produces their comparison result without session state; compare-bundles is its alias. inspect-evidence-bundle accepts a JSON descriptor with a bundle path, detail choice, and optional record filters, so a caller can read selected discovery data instead of emitting the complete bundle.

Use inspect-analysis-view for saved analysis results that are already packaged as an analysis-view input. This separates result projection from the original analysis and is useful when a full application result is too large for direct reading.

References: src/cliEvidenceCommands.ts• L50-65 src/…/EvidenceBundleCommands.ts• L69-90 src/…/analysisViewCommands.ts• L25-70 src/…/analysisViewCommands.ts• L72-105

API contract inspection

inspect-api-contract reads one local OpenAPI JSON or GraphQL SDL declaration and produces an offline inventory of operations, field bindings, unresolved references, and diagnostics. The result keeps the source path and digest, and it states the scope and limits of the inspection. It does not fetch a remote schema or execute an API operation.

GraphQL inspection can also read a local operation or fragment document through --operations-path. The command supports complete Evidence or a selected summary page through the shared detail, view, and evidence-output controls.

References: src/…/apiContractCommand.ts• L28-135 src/…/ApiContractService.ts• L73-147 src/…/apiContract.ts• L15-89

Evidence retention and linkage

Evidence can be retained in a session ledger while a smaller summary is returned to the caller. The summary keeps the complete record's ID, so a later workflow can follow the link to the full source rather than treating a bounded response as the whole record.

The ledger accepts the same semantic record only once and rejects conflicting content. It can replace display metadata such as a moved local path without changing the record's identity. Unknown findings are stored as revisioned state and are merged atomically with their supporting Evidence. Workflows that start from selected IDs resolve only the transitive Evidence links, not unrelated session records.

References: src/…/AndroidSearchEvidenceSummary.ts• L7-45 src/…/EvidenceLedger.ts• L56-180 src/…/EvidenceLedger.ts• L217-337 src/…/EvidenceLedger.ts• L340-407 src/…/InvestigationEvidence.ts• L7-26 src/…/recordEvidenceSources.ts• L6-16

Desktop capture commands

The desktop capture commands record the behavior and state changes of a Linux desktop application during a controlled session. They launch from a desktop entry or executable, take a baseline, accept checkpoint requests through standard input, retain selected file content, and write a capture bundle to a new output directory. Capture also accepts separate policies for projected state views and dependency inventories, so reader headroom can be changed without changing the content-retention limits.

The capture result includes application inventory, windows and processes, opened files, checkpoint changes, retained content, and explicit limits. Progress is emitted as JSON lines on standard error so a driver can wait for a window or checkpoint without mixing progress with the structured result.

sequenceDiagram
    participant D as Driver
    participant C as Desktop capture
    participant A as Linux application
    participant O as Capture directory
    D->>C: launch options and checkpoint requests
    C->>O: record baseline
    C->>A: launch and watch session
    A-->>C: windows, processes, opened files
    D->>C: checkpoint request
    C->>O: record changes and retained content
    C-->>D: progress on stderr and Evidence result

Capture duration, walked entries, largest retained file, and total retained content are bounded. Missing starting content, incomplete walks, unconfirmed changes, cancellation, and unverified cleanup remain visible as limitations rather than being presented as complete facts.

Capture inspection and packaging

inspect-desktop-application-state reads a completed capture as typed state views. It can apply a view policy for this call and inspect selected original captured paths. describe-desktop-application-task compares selected seed and end checkpoints and drafts task data. export-desktop-application turns the capture into a computer app bundle and can attach a validated task, package facts, selected checkpoints, withheld-state consent, and a copy of withheld files.

These commands use the capture directory as their source of truth. They do not repeat the application session. A capture that ended by cancellation or could not verify process cleanup remains usable as evidence, but its limitations must stay with the inspected or packaged result. View policy settings also apply to the readers exported with a bundle; they cannot recover content that the capture did not retain.

References: src/…/desktopCaptureCommands.ts• L33-127 src/…/desktopCaptureCommands.ts• L129-159 src/…/desktopCaptureCommands.ts• L258-296 src/…/desktopCaptureCommands.ts• L298-411 src/…/desktopCaptureCommands.ts• L414-506 src/…/DesktopApplicationCapture.ts• L166-191 src/…/DesktopApplicationCapture.ts• L243-376 src/…/desktopCapture.ts• L284-370

JavaScript runtime commands

The runtime commands use selected external targets and do not launch the target or run user actions. The Inspector commands observe a Node or Electron target, while the browser commands observe a page through an existing CDP endpoint or inspect a selected DOM node.

Target discovery

list-javascript-runtime-targets <endpoint> returns the runtime version and the targets exposed by that endpoint. Each target has an identifier, protocol type, attachment state, and a verified or explicitly unresolved location. The result also counts excluded targets and reports limits, so absence from the returned list is distinguishable from a complete empty runtime.

The endpoint is a literal loopback Inspector endpoint. The caller must use the returned target_id with observe-javascript-runtime; the observation command does not select a target by name or guess between targets.

References: src/…/javascriptRuntimeCommands.ts• L50-91 src/…/javascriptRuntimeObservation.ts• L12-18 src/…/javascriptRuntimeObservation.ts• L89-113 src/…/JavaScriptRuntimeObservationService.ts• L16-37

Passive runtime observation

observe-javascript-runtime <endpoint> <target-id> records a bounded snapshot from one Inspector target. The optional --runtime-kind declares whether the target is Node, Electron main, Electron preload, or Electron renderer. This is caller-supplied context and remains marked as unverified because the Inspector does not prove the Electron role.

The default observation window is 100 milliseconds. A longer or shorter nonnegative window can be set with --observation-ms. The result records loaded scripts, execution contexts, event counts, retained metadata, truncation state, directly observed facts, unavailable facts, unknowns, and limitations. Its Evidence envelope keeps the endpoint, exact target ID, runtime role when supplied, and observation window with the result.

The flow from endpoint selection to emitted Evidence is:

sequenceDiagram
    participant C as CLI caller
    participant I as V8 Inspector endpoint
    participant P as Observation service
    participant E as Evidence result
    C->>P: endpoint, target_id, options
    P->>I: list or attach passively
    I-->>P: targets or bounded runtime events
    P->>E: runtime result with limits and unknowns
    E-->>C: structured Evidence JSON

Each successful runtime operation is wrapped as observed Evidence. The operation name and input parameters remain attached to the result so a later workflow can relate the observation to its source endpoint and target. Input and provider failures are projected with the runtime command's error label and the shared analysis error details.

References: src/…/javascriptRuntimeCommands.ts• L24-36 src/…/javascriptRuntimeCommands.ts• L51-91 src/…/javascriptRuntimeCommands.ts• L93-148 src/…/javascriptRuntimeObservation.ts• L20-39 src/…/javascriptRuntimeObservation.ts• L142-177 src/…/JavaScriptRuntimeObservationEvidence.ts• L18-61

Browser execution evidence

observe-web-execution observes one selected page target during a finite window. It resets execution counters and temporarily disables optimized execution so the returned coverage describes the armed observation. It does not execute selected application code, and the requests that appear in the result do not prove causal control flow.

The command accepts a target and frame that remain tied to the selected document. It keeps only requests from the selected main frame and allowed origins. Script ownership requires proven default-world context, so URL text alone cannot join a script to the page. Retained metadata, requests, and source text have separate capacity limits; exceeding one limit fails the operation instead of returning an incomplete result.

The command emits progress updates on stderr while it arms and runs the observation. This keeps progress separate from the structured result on stdout. Cleanup stops coverage, releases owned remote objects, disables enabled domains, detaches the session, and reports whether that cleanup was confirmed.

inspect-web-event-listeners inspects the first main-document match for a caller-provided CSS selector. It returns listener declarations and source locations without dispatching an event. A found listener therefore shows registration evidence, not proof that the listener ran. Both commands preserve explicit unknowns for source ownership, execution causality, missing coverage, and cleanup.

References: src/…/webRuntimeCommands.ts• L15-20 src/…/webRuntimeCommands.ts• L22-108 src/…/CdpExecutionCapture.ts• L18-170 src/…/CdpEventListeners.ts• L11-103 src/…/CdpRuntimeRequests.ts• L27-150 src/…/CdpRuntimeRetention.ts• L5-28 src/…/CdpRuntimeSession.ts• L43-58 src/…/CdpRuntimeSession.ts• L203-325 src/…/CdpRuntimeSources.ts• L24-40 src/…/CdpRuntimeSources.ts• L116-201 src/…/CdpWebRuntimeProvider.ts• L36-145

JavaScript source recovery

recover-javascript-sources reads selected local UTF-8 JavaScript files as data and publishes readable derived modules into an absent output directory. The primary input can be joined by additional files so related chunks can be recovered together, while duplicate paths are rejected. The command never executes the input files.

Callers can choose structural extraction, heuristic fallback, or inspection-only regions. They can also choose a minimal, standard, or aggressive syntax rewrite. The emitted Evidence records published files, source digests, module ranges, producer identity, warnings, and whether the publication is complete or partial. Runtime equivalence remains unknown.

References: src/…/javascriptRecoveryCommands.ts• L11-76 src/…/javascriptRecovery.ts• L6-33 src/…/javascriptRecovery.ts• L51-110 src/…/JavaScriptRecoveryService.ts• L30-121

Captured source and module traces

trace-web-source-location traces one generated position through a caller-selected local source map. The caller selects the exported script by manifest index and supplies one-based generated lines with zero-based UTF-16 columns. The command reads local bytes only; the source-map URL supplies context and is not fetched.

The result keeps all matching map segments, including generated-only points and duplicate positions. It reports source names, resolved URLs, embedded source content when retained, diagnostics, and explicit unknown states for source authenticity and execution.

trace-web-module-imports parses native import, re-export, and dynamic-import syntax from one captured script. It resolves literal specifiers under an optional HTTP(S) importer URL and a paired local import map, then matches resolved URLs to captured scripts. Computed specifiers remain unknown, and a resolved URL or captured candidate does not prove loading or execution.

References: src/…/webSourceLocationCommands.ts• L11-60 src/…/webModuleCommands.ts• L15-72 src/…/webSourceLocation.ts• L11-33 src/…/webSourceLocation.ts• L77-141 src/…/webModuleTrace.ts• L10-39 src/…/webModuleTrace.ts• L78-124 src/…/WebSourceLocationService.ts• L85-181 src/…/WebModuleTraceService.ts• L83-271

JSON workflow inputs

Many evidence-backed commands take one inputJson argument instead of a long list of flags. That argument can contain inline JSON or the path to one local JSON file, which lets callers keep large descriptors and embedded evidence out of the shell command line.

Inline and file JSON

The CLI first treats the value as JSON. If it is not valid inline JSON, it treats it as a local file path and parses strict JSON from that file. File input must resolve to a regular readable file; malformed JSON, invalid UTF-8, a byte-order mark, missing files, and access failures become structured input errors.

File errors preserve input_path and use input_reason to distinguish invalid JSON, an unreadable file, or a resource limit. This makes a failed workflow actionable without confusing a bad descriptor with a failure in the analysis itself.

References: src/cliJsonInput.ts• L13-57 src/cliJsonInput.ts• L127-192 src/…/JsonInputFile.ts• L243-311 tests/…/cliJsonInput.test.ts• L217-307

Path normalization

CLI JSON contracts normally require absolute local paths so that the same input has a stable meaning at the application boundary. Selected path fields are resolved against the caller's working directory before schema validation; blank values and URL references remain unchanged so the shared schema can reject them as invalid local paths.

This normalization is selective rather than global. It changes only fields named by the command, leaves unrelated strings untouched, preserves Windows-style paths, and does not turn file: or other scheme URLs into local paths. Commands for API contract inspection, desktop capture, source recovery, and captured web traces validate their explicit local paths as absolute paths; URL fields remain context and are not fetched.

References: src/cliJsonInput.ts• L68-114 src/…/apiContractCommand.ts• L50-105 src/…/desktopCaptureCommands.ts• L179-207 src/…/electronCommands.ts• L97-114 src/cliJsonPaths.test.ts• L14-93 src/…/javascriptRecoveryCommands.ts• L20-28 src/…/webSourceLocationCommands.ts• L18-35 src/…/webModuleCommands.ts• L22-41

Observation controls

Observation options control the amount and kind of data collected. They are opt-in where content can expose more of the target, while the observation window supplies the time bound for passive collection.

Browser and Electron controls

The browser CLI can restrict collection to exact origins and can opt into accessibility text, console text, JSON body shapes, WebSocket shapes, script sources, storage key names, or storage fingerprints. Browser execution evidence uses the same origin scope and adds a finite execution window; Electron page inspection has a shorter default window of 100 milliseconds and an explicit option for script sources. These controls belong to the browser and Electron workflows described in the browser workflow page; they are listed here because they share the CLI observation contract.

References: src/cliObservationOptions.ts• L5-61 src/…/webRuntimeCommands.ts• L27-39 src/…/webRuntimeCommands.ts• L68-80 src/…/browserCommands.ts• L79-125 src/…/electronCommands.ts• L197-223

Desktop capture controls

Desktop capture options bound the session duration, checkpoint walks, retained file size, and total retained content. Callers can add state paths for starting content, exclude paths from every walk, and choose a desktop entry or executable. Package-file input records package facts and digest data, never the package file itself.

Two JSON policies control work after capture. --view-policy sets positive budgets for projected file, text, XML, JSON, ZIP, and SQLite views; the same policy is used by the exported readers and does not recover bytes that were not retained. --library-policy sets dependency-inventory budgets for libraries, search-path entries, strings, and table bytes; it applies to the capture and does not raise content or worker limits. Both policies are validated before the command starts.

References: src/…/desktopCaptureCommands.ts• L33-127 src/…/desktopCaptureCommands.ts• L298-411 src/…/desktopCaptureCommands.ts• L414-506 src/…/desktopCaptureCommands.ts• L509-576 src/…/desktopViewPolicy.ts• L26-61 src/…/libraryPolicy.ts• L3-16 src/…/DesktopApplicationCapture.ts• L108-163

JavaScript application controls

Static JavaScript or Electron application analysis uses separate controls for semantic-node limits, per-file limits, heap use, and analysis time. Callers can select exact inventoried source paths and choose whether an artifact-format or integrity mismatch fails the operation or is recorded while analysis continues.

These controls affect the size and trust boundary of the saved application Evidence. The resulting application record is derived from a shipped artifact and binds its subject to the analyzed path and digest. A runtime reconciliation is a separate inferred record that links static application layers to selected runtime observations; it does not turn either source into direct execution proof.

References: src/cliObservationOptions.ts• L63-84 src/…/electronCommands.ts• L226-268 src/…/JavaScriptApplicationEvidence.ts• L17-116 src/…/JavaScriptRuntimeReconciliationEvidence.ts• L12-28 src/…/JavaScriptApplicationEvidenceGraph.ts• L84-120 src/…/JavaScriptApplicationEvidenceGraph.ts• L169-209

Result envelopes

Successful commands emit JSON-compatible values that describe the requested evidence or a view of it. Failed commands emit a structured error with a stable code, category, user message, retry guidance, and details when the failure can identify an input path, target, limitation, or partial observation.

Analysis evidence delivery

Evidence-producing analysis commands can return the complete Evidence directly or return a smaller view while saving the complete source bundle. The --detail option selects complete or summary; summary delivery requires --evidence_output, and the optional --view value is parsed and checked before the target opens.

When a bundle path is supplied, the command first finishes the analysis, projects the requested view, and then publishes the complete Evidence and its linked source records to a new path. A file-based invocation can retain its exact caller input path in the delivered Evidence. Failure details redact sensitive invocation values when needed. The command never overwrites the bundle path. A summary response contains the selected summary plus the published bundle path and byte count, while a complete response contains the delivered complete Evidence. Publication errors retain the completed Evidence as partial observation. If publication does not commit, the error can also identify the source closure needed to recover records cited by that observation. If cancellation occurs after a successful write, the error details keep the publication receipt. A receipt omits the output path when that path contains a value marked for redaction.

References: src/…/analysisEvidenceDelivery.ts• L25-35 src/…/analysisEvidenceDelivery.ts• L50-114 src/…/analysisEvidenceDelivery.ts• L116-170 src/…/analysisEvidenceDelivery.ts• L172-237 src/…/analysisEvidenceDelivery.ts• L243-273 src/…/EvidenceBundleCommands.ts• L104-151 src/…/EvidenceBundleCommands.ts• L154-212

Evidence result content

Evidence bundle commands return counts, canonical-write receipts, comparison data, or selected views. API contract commands return source-bound operation inventories and diagnostics. Desktop capture commands return application identity, session state, checkpoint changes, retained content, and capture limitations. JavaScript runtime commands return runtime identity plus target and capture data. Browser runtime commands return target identity, selected observation data, and cleanup or limitation state. Source recovery and captured-artifact traces return file identity, provenance, diagnostics, and explicit unknowns rather than treating derived or historical data as proof of execution.

Evidence also records how the result was obtained. Observed runtime, desktop, and browser records retain their provider, operation, input parameters, confidence, authority, limitations, and links to supporting records. Derived application and reconciliation records use different confidence and authority values, which lets downstream work keep direct observation separate from analysis.

The distinction between observed facts and unavailable facts is part of the result contract. Downstream evidence work can therefore combine static application records with passive runtime records without losing the limits of either source.

References: src/…/EvidenceBundleCommands.ts• L18-29 src/…/EvidenceBundleCommands.ts• L93-103 src/…/ApiContractService.ts• L91-110 src/…/DesktopApplicationCapture.ts• L166-191 src/…/JavaScriptRuntimeObservationEvidence.ts• L18-46 src/…/JavaScriptApplicationEvidence.ts• L73-87 src/…/JavaScriptRuntimeReconciliationEvidence.ts• L12-28 src/…/JavaScriptApplicationWorkflowEvidence.ts• L13-101 src/…/CdpExecutionCapture.ts• L120-170 src/…/CdpEventListeners.ts• L72-103

Structured output behavior

Use --json or --format json when another program will consume the result. Output filters can project a smaller structured document, but token windows cannot be combined with JSON, JSONL, or YAML because a token slice could produce an incomplete document. If a structured filter selects no value, the CLI emits an empty object rather than invalid or truncated JSON.

References: src/cliOutput.ts• L27-89 src/cliOutput.ts• L110-164 tests/…/cliOutput.test.ts• L17-58 tests/…/cliOutput.test.ts• L248-265

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep CLI_COMMANDS, command registration, and any generated command or MCP catalog aligned when a command name or alias changes.
  • Preserve the distinction between inline JSON errors and file-read errors so callers can use input_path and input_reason for recovery.
  • When a JSON contract adds a path field, decide explicitly whether the CLI must resolve it before shared schema validation.
  • Keep API contract format, operation-document rules, selected views, and source digests aligned with the emitted Evidence.
  • Keep desktop checkpoint names, progress events, output admission, and capture fields aligned across the live session and saved bundle.
  • Keep desktop view-policy fields and limits aligned with both live state readers and the readers exported in a desktop bundle.
  • Keep desktop library-policy limits separate from content-retention and worker limits so a dependency inventory cannot claim more data than the capture or reader can provide.
  • Keep runtime result fields aligned with the Evidence wrapper so target identity, observation limits, unknowns, and caller-declared runtime roles remain traceable.
  • Keep selected browser artifact identities aligned with manifest indexes, source-map pairs, importer context, and import-map context.
  • Keep source recovery output identity aligned with the selected inputs and the declared extraction and rewrite options.
  • Keep structured-output validation ahead of command execution so JSON consumers never receive a token-truncated document.
  • Keep Evidence links and confidence or authority values aligned when a command changes from a complete record to a bounded summary or from direct observation to derived analysis.
  • Keep browser source ownership, request filtering, retention limits, and cleanup status aligned when runtime observation fields change.
  • Keep --detail, --view, and --evidence_output validation aligned so summary delivery cannot lose its complete source Evidence.
  • Keep analysis projection ahead of bundle publication so a failed view cannot leave an unreported bundle.
  • Keep publication paths non-overwriting and preserve publication receipts when cancellation occurs after the bundle is written.
  • Keep failed delivery diagnostics able to identify the undelivered source closure without exposing invocation values that require redaction.
  • Keep file-based caller input paths and sensitive invocation values aligned with Evidence binding and failure redaction.
  • Keep runtime command input validation, cancellation, and the runtime-specific error label aligned with the shared analysis error projection.

Important failure modes

TriggerConsequenceGuard
The Inspector or CDP endpoint is unreachable or the target ID is staleTarget discovery or observation returns a structured provider or target errorList targets first and pass the exact returned target ID
The selected browser document, frame, or origin changes during observationSource joins or final coverage are refused because the result no longer describes the selected pageTreat target and document identity as part of the input scope
A runtime observation exceeds its retained event, request, metadata, or source budgetThe result fails instead of silently returning incomplete retained dataTreat capacity errors as operation failures and reduce scope or retention
A runtime observation ends during target loss or cleanup failureA partial observation or cleanup error is returned with the end reason and retained diagnosticsRead cleanup and end-state fields before accepting the result as complete
A JSON argument names malformed, inaccessible, or non-regular-file inputThe workflow does not run and the error identifies the input path and reasonUse a regular UTF-8 JSON file or valid inline JSON
An API contract document is malformed, outside its format, or exceeds parser headroomContract inspection fails before it can produce a complete inventoryUse a valid local document within the file and memory limits
A summary request omits --evidence_output or supplies invalid --view JSONThe command fails before target work or publicationSupply a writable output path and valid view JSON
Analysis view projection fails after analysis completesNo evidence bundle is published and the completed Evidence is retained in the errorTreat projection as a required pre-publication step
Source-bundle publication fails before commitThe error retains the partial observation and can include the cited source closure for recoveryRead partial_observation and source_closure before discarding the failed result
A delivery output path already existsEvidence delivery fails rather than replacing an existing bundleUse a new path; delivery commands do not overwrite
Cancellation arrives after bundle publicationThe command reports cancellation with the publication receipt instead of pretending that no output existsRead cancellation diagnostics and retain the emitted bundle
A desktop capture output directory is not new or emptyThe capture refuses to launch or publishSelect an absent or empty output directory
A desktop checkpoint walk reaches an entry or content limitSome changes or file bytes are omitted and the capture is limitedRead checkpoint truncation and omitted-content fields
A desktop state or dependency policy contains invalid, unknown, or non-positive valuesThe command is rejected before capture or state readingPass strict JSON objects with positive integer budgets
A desktop view exceeds its selected view-policy budgetThe state view refuses the content even when the capture contains the file; the policy cannot restore bytes never retainedRaise the view budget on the next call, then re-read the capture
A desktop dependency inventory reaches a library-policy budgetThe inventory is limited or refused; capture content and worker heap settings do not raise that budgetStart a new capture with a higher --library-policy budget
A desktop session ends with unverified process cleanupThe capture may contain valid partial evidence but cannot claim a clean endRead the session cleanup and end-reason fields
A selected source map, manifest, or import map does not match the requested path or contextThe trace rejects the result instead of returning evidence for a different artifactKeep the selected local files and URL contexts paired with the captured manifest
A source recovery output directory already exists or selected inputs repeatRecovery cannot publish the requested derived artifactsUse an absent output directory and distinct absolute input paths
An export destination already exists without --overwriteCanonical output is not replacedChoose a new path or pass --overwrite deliberately
A structured output command combines JSON-like format with token limitsThe CLI fails before execution to protect document validityUse --filter-output or command pagination instead of token windows
An Evidence bundle contains conflicting semantic content or an invalid unknown revision graphThe ledger rejects the import without committing a partial mergeImport validated bundles and preserve Evidence links and revision identities

Key files

FileWhy to read it
src/cliEvidenceCommands.tsDefines the evidence import, export, and comparison command surface
src/…/EvidenceBundleCommands.tsShows the high-level validation, canonical export, comparison, and delivery behavior
src/…/EvidenceLedger.tsDefines idempotent Evidence retention, atomic bundle merging, and residual unknown state
src/…/InvestigationEvidence.tsShows how selected Evidence links form a bounded analysis closure
src/…/analysisEvidenceDelivery.tsDefines complete or summary delivery, view validation, caller-path binding, source-closure recovery, and publication of source Evidence
src/…/apiContractCommand.tsDefines local API contract input, format selection, and Evidence delivery
src/…/ApiContractService.tsShows how API declarations become offline source-bound Evidence
src/…/desktopCaptureCommands.tsDefines desktop capture, strict policy options, state inspection, task description, and bundle export
src/…/desktopViewPolicy.tsDefines projected-state budgets shared by capture inspection and exported readers
src/…/libraryPolicy.tsDefines dependency-inventory budgets that remain separate from content limits
src/…/DesktopApplicationCapture.tsShows desktop session lifecycle, checkpoints, limits, and cleanup state
src/…/desktopCapture.tsDefines desktop capture results, progress events, checkpoints, and limits
src/…/javascriptRuntimeCommands.tsDefines runtime target discovery, observation arguments, option defaults, cancellation, and runtime errors
src/…/JavaScriptRuntimeObservationEvidence.tsShows how passive Inspector results become observed Evidence
src/…/webRuntimeCommands.tsDefines browser execution observation, progress output, and event-listener inspection
src/…/CdpWebRuntimeProvider.tsShows the high-level browser runtime lifecycle and cleanup result
src/…/CdpRuntimeSession.tsShows target identity checks, command bounds, and owned cleanup
src/…/CdpRuntimeSources.tsShows the rules for source ownership and retained source identity
src/…/CdpExecutionCapture.tsShows how the finite execution window becomes coverage and request evidence
src/…/javascriptRecoveryCommands.tsDefines local source recovery inputs and recovery options
src/…/JavaScriptRecoveryService.tsShows how recovered artifacts bind to source and producer identity
src/…/webSourceLocationCommands.tsDefines selected source-map point tracing
src/…/webModuleCommands.tsDefines selected captured-module import tracing
src/…/WebSourceLocationService.tsShows the high-level source-map trace and its evidence limits
src/…/WebModuleTraceService.tsShows how captured scripts and URL resolution become module evidence
src/…/JavaScriptApplicationEvidence.tsDefines the Evidence envelope for static JavaScript application analysis
src/…/JavaScriptRuntimeReconciliationEvidence.tsDefines derived Evidence that links static layers to runtime observations
src/cliJsonInput.tsDefines inline/file JSON selection and selected path normalization
src/cliObservationOptions.tsDefines shared observation and application-analysis controls
src/cliOutput.tsDefines structured-output safeguards and pre-execution errors
src/cli.tsBuilds the one-shot CLI and registers the evidence, browser, desktop, and JavaScript runtime command groups