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.
| Group | Main commands | Purpose |
|---|---|---|
| Evidence bundles | evidence-import, evidence-export, compare, inspect-evidence-bundle | Validate, canonicalize, compare, and inspect saved Evidence |
| Saved analysis views | inspect-analysis-view | Project a smaller view from completed analysis Evidence |
| API contract evidence | inspect-api-contract | Inspect local OpenAPI JSON or GraphQL SDL declarations without network access or code execution |
| Desktop evidence | capture-desktop-application, inspect-desktop-application-state, describe-desktop-application-task, export-desktop-application | Capture and package a Linux desktop application's state and session changes |
| JavaScript runtime | list-javascript-runtime-targets, observe-javascript-runtime | Discover Inspector targets and passively observe one selected target |
| Browser runtime evidence | observe-web-execution, inspect-web-event-listeners | Observe externally driven page execution or inspect one selected node |
| Captured web evidence | trace-web-source-location, trace-web-module-imports | Relate retained scripts to source maps and native module imports |
| JavaScript source recovery | recover-javascript-sources | Produce readable derived modules with source provenance |
| Evidence-backed application work | reconcile-javascript-runtime, trace-application-feature, trace-javascript-semantics, and comparison commands | Relate 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_pathandinput_reasonfor 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_outputvalidation 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
| Trigger | Consequence | Guard |
|---|---|---|
| The Inspector or CDP endpoint is unreachable or the target ID is stale | Target discovery or observation returns a structured provider or target error | List targets first and pass the exact returned target ID |
| The selected browser document, frame, or origin changes during observation | Source joins or final coverage are refused because the result no longer describes the selected page | Treat target and document identity as part of the input scope |
| A runtime observation exceeds its retained event, request, metadata, or source budget | The result fails instead of silently returning incomplete retained data | Treat capacity errors as operation failures and reduce scope or retention |
| A runtime observation ends during target loss or cleanup failure | A partial observation or cleanup error is returned with the end reason and retained diagnostics | Read cleanup and end-state fields before accepting the result as complete |
| A JSON argument names malformed, inaccessible, or non-regular-file input | The workflow does not run and the error identifies the input path and reason | Use a regular UTF-8 JSON file or valid inline JSON |
| An API contract document is malformed, outside its format, or exceeds parser headroom | Contract inspection fails before it can produce a complete inventory | Use a valid local document within the file and memory limits |
A summary request omits --evidence_output or supplies invalid --view JSON | The command fails before target work or publication | Supply a writable output path and valid view JSON |
| Analysis view projection fails after analysis completes | No evidence bundle is published and the completed Evidence is retained in the error | Treat projection as a required pre-publication step |
| Source-bundle publication fails before commit | The error retains the partial observation and can include the cited source closure for recovery | Read partial_observation and source_closure before discarding the failed result |
| A delivery output path already exists | Evidence delivery fails rather than replacing an existing bundle | Use a new path; delivery commands do not overwrite |
| Cancellation arrives after bundle publication | The command reports cancellation with the publication receipt instead of pretending that no output exists | Read cancellation diagnostics and retain the emitted bundle |
| A desktop capture output directory is not new or empty | The capture refuses to launch or publish | Select an absent or empty output directory |
| A desktop checkpoint walk reaches an entry or content limit | Some changes or file bytes are omitted and the capture is limited | Read checkpoint truncation and omitted-content fields |
| A desktop state or dependency policy contains invalid, unknown, or non-positive values | The command is rejected before capture or state reading | Pass strict JSON objects with positive integer budgets |
| A desktop view exceeds its selected view-policy budget | The state view refuses the content even when the capture contains the file; the policy cannot restore bytes never retained | Raise the view budget on the next call, then re-read the capture |
| A desktop dependency inventory reaches a library-policy budget | The inventory is limited or refused; capture content and worker heap settings do not raise that budget | Start a new capture with a higher --library-policy budget |
| A desktop session ends with unverified process cleanup | The capture may contain valid partial evidence but cannot claim a clean end | Read the session cleanup and end-reason fields |
| A selected source map, manifest, or import map does not match the requested path or context | The trace rejects the result instead of returning evidence for a different artifact | Keep the selected local files and URL contexts paired with the captured manifest |
| A source recovery output directory already exists or selected inputs repeat | Recovery cannot publish the requested derived artifacts | Use an absent output directory and distinct absolute input paths |
An export destination already exists without --overwrite | Canonical output is not replaced | Choose a new path or pass --overwrite deliberately |
| A structured output command combines JSON-like format with token limits | The CLI fails before execution to protect document validity | Use --filter-output or command pagination instead of token windows |
| An Evidence bundle contains conflicting semantic content or an invalid unknown revision graph | The ledger rejects the import without committing a partial merge | Import validated bundles and preserve Evidence links and revision identities |
Key files
| File | Why to read it |
|---|---|
| src/cliEvidenceCommands.ts | Defines the evidence import, export, and comparison command surface |
| src/…/EvidenceBundleCommands.ts | Shows the high-level validation, canonical export, comparison, and delivery behavior |
| src/…/EvidenceLedger.ts | Defines idempotent Evidence retention, atomic bundle merging, and residual unknown state |
| src/…/InvestigationEvidence.ts | Shows how selected Evidence links form a bounded analysis closure |
| src/…/analysisEvidenceDelivery.ts | Defines complete or summary delivery, view validation, caller-path binding, source-closure recovery, and publication of source Evidence |
| src/…/apiContractCommand.ts | Defines local API contract input, format selection, and Evidence delivery |
| src/…/ApiContractService.ts | Shows how API declarations become offline source-bound Evidence |
| src/…/desktopCaptureCommands.ts | Defines desktop capture, strict policy options, state inspection, task description, and bundle export |
| src/…/desktopViewPolicy.ts | Defines projected-state budgets shared by capture inspection and exported readers |
| src/…/libraryPolicy.ts | Defines dependency-inventory budgets that remain separate from content limits |
| src/…/DesktopApplicationCapture.ts | Shows desktop session lifecycle, checkpoints, limits, and cleanup state |
| src/…/desktopCapture.ts | Defines desktop capture results, progress events, checkpoints, and limits |
| src/…/javascriptRuntimeCommands.ts | Defines runtime target discovery, observation arguments, option defaults, cancellation, and runtime errors |
| src/…/JavaScriptRuntimeObservationEvidence.ts | Shows how passive Inspector results become observed Evidence |
| src/…/webRuntimeCommands.ts | Defines browser execution observation, progress output, and event-listener inspection |
| src/…/CdpWebRuntimeProvider.ts | Shows the high-level browser runtime lifecycle and cleanup result |
| src/…/CdpRuntimeSession.ts | Shows target identity checks, command bounds, and owned cleanup |
| src/…/CdpRuntimeSources.ts | Shows the rules for source ownership and retained source identity |
| src/…/CdpExecutionCapture.ts | Shows how the finite execution window becomes coverage and request evidence |
| src/…/javascriptRecoveryCommands.ts | Defines local source recovery inputs and recovery options |
| src/…/JavaScriptRecoveryService.ts | Shows how recovered artifacts bind to source and producer identity |
| src/…/webSourceLocationCommands.ts | Defines selected source-map point tracing |
| src/…/webModuleCommands.ts | Defines selected captured-module import tracing |
| src/…/WebSourceLocationService.ts | Shows the high-level source-map trace and its evidence limits |
| src/…/WebModuleTraceService.ts | Shows how captured scripts and URL resolution become module evidence |
| src/…/JavaScriptApplicationEvidence.ts | Defines the Evidence envelope for static JavaScript application analysis |
| src/…/JavaScriptRuntimeReconciliationEvidence.ts | Defines derived Evidence that links static layers to runtime observations |
| src/cliJsonInput.ts | Defines inline/file JSON selection and selected path normalization |
| src/cliObservationOptions.ts | Defines shared observation and application-analysis controls |
| src/cliOutput.ts | Defines structured-output safeguards and pre-execution errors |
| src/cli.ts | Builds the one-shot CLI and registers the evidence, browser, desktop, and JavaScript runtime command groups |