Command Line and Diagnostics
The command-line surface and the diagnostics fragcap prints about its own run.
Authorization plan
A complete description of the scope and consequences that an operator must review before approving an operation.
The plan binds selected resources, effects, limits, sensitive outputs, and cleanup obligations to one exact identity. A lifecycle event reports what happened afterward; the plan alone is not evidence that an effect occurred.
Why it matters here
Deep Capture presents a readable consequence summary alongside the complete canonical plan. Trust and sensitive-output consent remain visible, and neither a summary nor an earlier plan authorizes a different session.
See also: Deep Capture, Terminal report
References:
- Native authorization contract (project primary source for exact plan-bound consent).
Session progress
A presentation of the stages and counters actually observed while an operation is being performed.
Progress distinguishes resource readiness from traffic observation and evidence reconciliation. Live packet counters and later delivered application observations have different timing and authority; neither may imply unavailable decryption or process ownership.
Why it matters here
Deep Capture projects typed lifecycle stages into human progress while preserving existing live Capture counters. Application counters describe post-collection observations, and final artifact and cleanup truth remains independent.
See also: Lifecycle event, Live status block, Terminal report
References:
- Progress and failure reporting (project primary source for progress, output modes, and recovery).
Terminal report
An immutable result that distinguishes an operation's outcome from its evidence completeness and resource cleanup.
A partial or interrupted operation can retain useful sensitive evidence while releasing external resources, or leave unresolved owned cleanup obligations. These independent states must not be collapsed into a single success claim.
Why it matters here
Deep Capture reports the actual post-run outcome, each artifact status and confirmed retained path, and each named cleanup result. Quiet retains this report; silent suppresses optional human text; JSON remains exclusively structured.
See also: Completion summary, Authorization plan
References:
- Session bundle (project primary source for independent terminal and artifact authority).
Doctor probe
A named operation that gathers an environment fact for a diagnostic report.
A probe's pending duration is separate from its result. Timing a phase or nested operation identifies where work is waiting, but does not prove why an external call is slow or whether the environment is ready. A readiness check classifies the facts only after gathering.
Why it matters here
v0.10.1 ships S151 Doctor diagnostics that identify fixed phase and readiness leaf names during blocked work. One-second elapsed progress and completion timing stay on stderr; pending never becomes fabricated unavailability and final report contracts remain unchanged.
See also: Session progress, Scoped worker
References:
- Doctor diagnostics (project primary source for probing, readiness and output contracts).
- Rust Instant (primary source for monotonic elapsed measurement).
Scoped worker
A thread whose owning operation waits for it to finish before leaving its lifetime boundary.
Scoped threads can borrow non-static data because their owner joins them before returning. A bounded channel can carry ordered fixed-size work observations back to a caller without moving that caller's borrowed output writer. Scope and joining establish lifetime ownership, not a cancellation mechanism or a bound on external work duration.
Why it matters here
v0.10.1 ships S151 interactive Doctor with one serial scoped worker and a caller-thread progress coordinator. The finite observation channel disconnects before coordinator unwind joins work, preventing a full diagnostic channel from deadlocking its sender. No blocked probe is detached or reported unavailable merely for taking time.
See also: Doctor probe, Session progress
References:
- Rust thread scope (primary source for scoped thread lifetimes and joining).
- Rust scoped join (primary source for explicit completion and panic propagation).
- Rust bounded synchronous channel (primary source for ordered finite buffering and disconnection).
Readiness check
One line of the fragcap doctor report: a section, a name, a detail, a status,
and, when it fails, a remediation. The status vocabulary is exactly four words:
ok (ready), warn (a non-blocking concern), skip (not applicable or
not built into this binary), and fail (a blocking problem that must be fixed
before capture is possible). The report exits 1 if any check is fail and 0
otherwise.
Why it matters here
skip and fail are deliberately distinct. A process-tracing session that is
not built into the binary is a skip, because attribution still works from
the socket table; a session that could not open while elevated is a fail,
because attribution is then degraded. Collapsing the two would either block a
capture that would have worked or pass one that will not.
See also: npcap, Attribution fidelity
Action layer
The part of fragcap doctor --fix that sits above the pure classifier. doctor
answers whether the machine can capture; the action layer offers to carry out the
remediations that answer named, one at a time, under the operator's confirmation.
It never changes what doctor decides: it consumes the report the classifier
produced and can act only on remediations that report already printed. It is
interactive, so it is refused with --json and when the session is not a terminal.
Why it matters here
The action layer is strictly above the classifier, never inside it. The
classifier stays a pure function from injected inputs to a report, which is what
keeps its whole matrix testable with no capture driver, no elevation, and no
game. The action layer can surprise no operator, valuable in a tool that may run
elevated, because it offers only what doctor first said aloud.
See also: Structured action, Readiness check
Structured action
The machine-facing counterpart of a readiness check's human-readable remediation:
the specific step the action layer can perform for that check (obtain npcap,
register the analyzer integration, fetch the catalog, relaunch elevated, run
discovery). It is carried on the check itself and constructed together with the
remediation string, so the step the operator reads and the step --fix offers
cannot drift. A check with no automatable remedy carries no structured action, and
--fix never offers an action whose check is absent from the current report.
See also: Action layer, Action outcome
Action outcome
The honest result the action layer records for one attempted action: performed (it ran to success), skipped (the operator declined it), degraded (a capability-limited fallback ran, for example opening the download page instead of fetching the installer, reported as what happened rather than as success of the primary form), or failed (it was attempted and could not complete). A failed action is never reported as performed, and the run's final verdict reflects what actually changed.
See also: Action layer
Lifecycle event
One record in the machine-readable event stream fragcap emits on standard error under --json, over a capture's life. Capture lifecycle records cover arming, stage matching and exit, filter narrowing, live progress, streaming consumers, ring eviction, and completion. Deep Capture adds preflight, compatibility calibration, proxy, trust, launch, application, bundle, cleanup, and completion records. Each carries an RFC3339 Z timestamp and a stable event discriminator.
Why it matters here
The event stream is what lets a wrapper react to a capture without parsing human-readable progress, which is what keeps a wrapper thin under constitution principle P-7. It is newline-delimited JSON on standard error, so capture data written to a sink, even one on standard output, is never contaminated by it.
See also: Completion summary
Completion summary
The end-of-run accounting an operator reads: the captured and attributed counts, the stop reason, and every discard counter, the packets discarded while watching before a target was acquired, those discarded out of the capture window, buffer drops, and per-sink drops.
Why it matters here
The summary surfaces the counters the pipeline and session already maintain and invents none, which is what constitution principle P-4 requires: a bare success that hid a watch-time discard or a buffer drop is exactly the silent loss the principle forbids.
See also: Lifecycle event
Shell wrapper
A thin script that handles the environment concerns fragcap's binary leaves
outside itself: Invoke-FragCap.ps1 on Windows (PowerShell) and fragcap.sh for
a Linux or WSL2 shell (Bash), specification section 18.
Why it matters here
A wrapper does privilege elevation, capture-driver detection, interface enumeration, path translation, and output template expansion, and nothing else. It reacts to the lifecycle event stream rather than parsing human-readable output, which is what keeps it thin under constitution principle P-7. A wrapper that needs to grow past those concerns is a missing capability in the binary.
See also: Lifecycle event, WSL2 interop, Path translation
WSL2 interop
The mechanism by which a script in a Windows Subsystem for Linux shell invokes a native Windows executable and exchanges data with it across the subsystem boundary.
Why it matters here
The Bash wrapper's distinguishing job is this boundary: capture runs in the
native Windows binary, so fragcap.sh under WSL2 invokes it through interop and
translates paths in both directions. On a Linux host with no reachable Windows
binary it reports capture unavailable and exits 1, rather than failing
obscurely.
See also: Shell wrapper, Path translation
Path translation
Rewriting a filesystem path between the form one environment uses and the form another expects, here between a Linux or WSL2 path and a Windows path.
Why it matters here
A relative output path given in a WSL2 shell must resolve to the intended Windows location for the native binary, and the resulting file path must be reported back in Linux form. The Bash wrapper does this with the subsystem's own path tool; it is a small pure function, checkable without a capture driver.
See also: WSL2 interop, Output template
Output template
An output-path string carrying tokens a shell wrapper expands
before capture: {profile} to the profile name, {date} to the capture date,
and {time} to the capture time.
Why it matters here
Templating and directory preparation are an environment concern the wrapper
handles so the binary does not have to. The expansion is pure and deterministic
given its inputs, which is what lets a --dry-run preview it with no capture.
See also: Shell wrapper, Path translation
Effective configuration
The capture options actually used, formed by overlaying the command-line options
onto a profile's [capture] defaults. The command line wins, and an option
absent from both stays absent, so a profile that chose a value and a profile that
said nothing remain distinguishable.
Why it matters here
The overlay preserves the declared-versus-absent distinction the profile schema depends on, rather than substituting a default the moment a value is missing. Substituting one would destroy the information an operator supplied and make a later override behave differently than they wrote.
See also: Game profile, Completion summary
Diagnostic record
One structured --json record describing a single problem fragcap profile validate found in a profile: its stable code, the configuration key path, a
line and col into the source text, and a human message. Validation emits
one record per problem, followed by a terminal summary record, on standard
output.
Why it matters here
The record preserves every field the human formatter renders rather than
collapsing all problems into one string. A consumer keys on the code and
path to act on a specific problem; re-parsing a rendered line would tie the
automation to prose that may be reworded without notice.
See also: Lifecycle event, Readiness check
Hero listing
The output of fragcap targets (and a bare fragcap): readiness-grouped numbered tables of the user's registered, capturable targets. Non-empty Ready to capture rows appear before non-empty Needs setup rows, handles are sorted inside each group, and one continuous 1-based index spans both. Each row shows the target handle, capture-readiness status, and two neutral evidence columns (the detected engine, and the detected anti-cheat and DRM products), ending by naming the next command to run. Producing it runs discovery across its tiers and registers any newly found titles first, so a fresh install lists the user's own software; an empty result prints the commands that populate the store instead of an empty table.
Why it matters here
The listing is the one command a new user runs successfully on their own machine that makes attribution concrete using their own data. Every listed row is capturable in principle; the readiness column reports how close, never whether the row is valid.
See also: Listing snapshot, Capture readiness, Sensitivities
Listing snapshot
The exact ready-then-setup ordered set of targets the most recent hero listing displayed, persisted to local.db so a bare-integer selector resolves to the row the user saw. A row index resolves through the snapshot (position to stable identifier to entry), not through the live store order, so fragcap capture 3 names the row that occupied position 3 in the listing even after an intervening add or remove shifts the live store order. A new listing replaces the snapshot; a position past it, or one taken before any listing has run, is an out-of-range usage error.
Why it matters here
Without the snapshot a row number would silently change meaning between the listing and the capture whenever the target set changed, attributing a capture to a different target than the one the user pointed at.
See also: Hero listing, Stable identifier
Capture readiness
The presentational status a hero listing shows for a target in its CAPTURE column and readiness group: ready rows appear under Ready to capture when the entry names a Windows client executable or carries an anchor a capture can resolve; needs a target rows appear under Needs setup when the launch chain is unresolved and no anchor gives a client. Derived from the entry at listing time and stored nowhere.
Why it matters here
Readiness reports how close a row is to a capture, never whether the row is
valid: every registered target is capturable in principle, and a needs a target row becomes ready once a capture observes its socket holder.
See also: Unresolved launch chain, Hero listing
Sensitivities
The hero listing column that names the anti-cheat and DRM products detected in a target's install directory, anti-cheat before DRM. Its sibling column, ENGINE, names the detected engine. The two are partitioned on the category each detection finding already carries, so no column mixes an engine with a protection product. The same partition is recoverable from the target-entry export, so the table and the machine-readable output cannot disagree about what a technology is.
No value in either column is truncated and no row is wrapped: the columns other than the target handle cost a bounded width, and a handle wider than the remaining budget overflows an 80 column terminal visibly rather than being clipped.
Why it matters here
The two columns replaced one, KNOWN, which comma-joined every product regardless of category and substituted a sentence about capture readiness when it had none. A reader could not tell an engine from a protection product, and silently clipping a value to fit would be the same class of loss principle P-4 forbids for a dropped packet.
See also: Coverage state, Hero listing
Coverage state
What a target row records about whether its install directory was scanned for
technologies, and whether that scan covered everything it set out to: complete,
incomplete, or absent. Absent means no scan is recorded, which is what a row
produced by a source that ran no detection carries. It is stored on the target
entry and carried by the target-entry export, so it survives a round trip.
When a technology column has no products to name it renders the row's coverage
state instead: - for a complete scan that matched nothing, incomplete for a
scan whose coverage was reduced, and not scanned when none is recorded.
Why it matters here
"Nothing is here", "the scan could not finish", and "nobody looked" are three different facts, and a single blank cell asserts the first of them for all three. Distinguishing them is a principle P-4 concern rather than a cosmetic one: an operator acting on an empty engine column needs to know whether that is an answer.
See also: Sensitivities, Binary marker
Target-entry export
A dedicated JSON array of target-entry objects, each carrying an entry's identity
(its stable identifier and handle) alongside its classification, fidelity,
anchor, launch chain, install root, and evidence, produced by targets export
and consumed by targets import. Import merges each element on its stable
identifier, so an export round-trips through an import with identical identifiers
and no duplicate rows. It is deliberately not the published capture schema, whose
export records are catalog games and omit the entry identity that merge-on-id
requires.
Why it matters here
The identity travels with the record, so the same target moved between two machines converges to one row rather than duplicating. A representation that dropped the stable identifier, as the capture-schema export does, could not merge and would multiply the target on every import.
See also: Stable identifier, Anchor
Live status block
A status block fragcap capture redraws in place on standard error at least
once a second while a live run is active on a real terminal, showing elapsed
time, the bound process, packets and bytes written against any configured
volume bound, the capture filter's narrowing state, every discard counter,
and the top per-process contributors to the file so far. Rendered only when
standard error is an interactive terminal and verbosity is normal; a
redirected or logged run instead gets today's plain progress lines plus an
occasional heartbeat line (issue #186).
Why it matters here
Before this, a live capture went silent from acquisition until the run stopped, sometimes for many minutes, with no way to notice that most of a file's volume was going to an unrelated process until the run ended and the operator opened the result in a separate tool. The counters the block shows were already computed by the pipeline and session; the block only makes them visible while they still matter.
See also: Redraw, Heartbeat line, Completion summary
Redraw
The mechanism by which a live status block
replaces its previous frame in place rather than appending a new one: a
cursor-up escape sequence for the number of lines the previous frame
occupied, followed by an erase-to-end-of-screen sequence, followed by the new
frame's bytes. Hand-rolled from two ANSI escape sequences, matching the
existing doctor command's hand-rolled color handling rather than adding a
terminal-UI dependency. Never emitted when standard error is not a real
terminal.
See also: Live status block
Heartbeat line
A single plain progress line (still capturing: elapsed HH:MM:SS, N packets written), carrying no escape byte, that fragcap capture appends when
standard error is not a terminal and thirty seconds have passed with no other
progress line. Exists so a redirected or logged run is never silent for an
unbounded stretch the way a terminal-attached run's live status
block already prevents; the
interval resets on every ordinary progress line, so a run with regular
milestones may emit none at all.
See also: Live status block