supercov 1.1.1 → 2.0.0

package/README.md

@@ -1,8 +1,8 @@
-![Code quality and coverage for coding agents](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
+![Coverage, security and code quality for coding agents](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
 
-**Code quality and coverage for coding agents**
+**Coverage, security and code quality for coding agents**
 
-**Supercov tells your coding agent what to fix and what to test.** It scores your code quality with [Jev](https://typesafe.ai), runs the test command you already use, and turns uncovered paths into small, actionable queries. Your agent picks a target, writes a focused test or a focused refactor, proves what improved, and keeps going.
+**Supercov tells your coding agent what to fix and what to test.** It scores your code quality and flags security risks with [Jev](https://typesafe.ai), runs the test command you already use, and turns uncovered paths into small, actionable queries. Your agent picks a target, writes a focused test or a focused refactor, proves what improved, and keeps going.
 
 Paste this to your coding agent to start:
 
@@ -56,6 +56,18 @@ Jev charges for what it reads and nothing for what it writes, so a megabyte of
 source costs a little over a cent. Answers are cached by content, so a second
 run pays only for what changed. See [Understanding quality](docs/quality.md).
 
+## Find security risks
+
+```bash
+npx supercov security
+npx supercov security patch   # what a change introduced
+```
+
+Twelve security checks asked of every file with the same key, from injection
+and secrets in source to paths and redirects taken from a request. Nothing is
+averaged: a file is clean, or it names what fired, with the line and the code on
+it where Jev confirms one. See [Security surface](docs/security.md).
+
 ## Start with the suite you already have
 
 ```bash
@@ -102,6 +114,19 @@ npx supercov -- npm test
 npx supercov diff <previous-run-id> latest
 ```
 
+Want to hand the evidence to a person? Generate one private, interactive file:
+
+```bash
+npx supercov report
+```
+
+The report opens in your browser with up to ten recent runs in a visual history.
+Selecting a run compares it with the previous snapshot automatically. It has no
+server, external assets, account, or file picker. It is written to
+`.supercov/reports/`, where the store's own `.gitignore` keeps it out of git.
+You can attach that one file directly to a pull request; a reviewer downloads
+it and double-clicks it.
+
 Use whichever complete test command the repository already trusts:
 
 ```bash
@@ -233,7 +258,7 @@ Java and Kotlin have no registry of their own here, so a JVM project takes the b
 | PHP | Coming soon | — | — |
 | C | Coming soon | — | — |
 
-The `npx` path requires Node.js 22 or newer; the other installs need no Node. Rust support currently uses Rust 1.95; cargo-nextest 0.9.138 and 0.9.140 are supported. Python support requires CPython 3.12 or newer and measures pytest and unittest runs. Ruby support requires Ruby 3.3 or newer (3.4 or newer for full measurement) and measures RSpec, Minitest, test-unit and Cucumber runs. Go support requires Go 1.22 or newer and measures `go test`. Java and Kotlin support requires a JDK 17 or newer with Maven or Gradle, and measures every JUnit Platform engine -- JUnit 5, JUnit 4 through Vintage, Kotest and Spock -- as well as TestNG.
+The `npx` path requires Node.js 22 or newer; the other installs need no Node. Rust support currently uses Rust 1.95; cargo-nextest 0.9.138 and 0.9.140 are supported. Python support requires CPython 3.9 or newer and measures pytest and unittest runs. Ruby support requires Ruby 3.3 or newer (3.4 or newer for full measurement) and measures RSpec, Minitest, test-unit and Cucumber runs. Go support requires Go 1.22 or newer and measures `go test`. Java and Kotlin support requires a JDK 17 or newer with Maven or Gradle, and measures every JUnit Platform engine -- JUnit 5, JUnit 4 through Vintage, Kotest and Spock -- as well as TestNG.
 
 ## Supported operating systems and architectures
 
@@ -245,7 +270,7 @@ The CLI is a single native binary. `npx supercov` selects the build for the mach
 | Linux | arm64, x64 | glibc 2.28 or newer (Debian 10, Ubuntu 18.10, RHEL 8 and later), or musl (Alpine); chosen automatically |
 | Windows | arm64, x64 | Windows 10 or newer |
 
-JavaScript, TypeScript, Python, Ruby, Rust, Go, Java and Kotlin suites are verified on Linux, macOS and Windows -- CPython 3.12, 3.13 and 3.14, Ruby 3.3, 3.4 and 4.0, and Go 1.22, 1.25, 1.26 and 1.27 on every one, and JDK 17 and 21 on every one that has them (Temurin publishes no 17 for arm64 Windows, so that pairing is 21 alone). Containers, VMs, and remote executors run the same Linux builds. Every release publishes the same binaries to npm, PyPI (`supercov-cli`, a wheel per platform) and RubyGems (`supercov`, a gem per platform except arm64 Windows, which Ruby has no platform for), and the source to crates.io (`supercov`).
+JavaScript, TypeScript, Python, Ruby, Rust, Go, Java and Kotlin suites are verified on Linux, macOS and Windows -- CPython 3.9 through 3.14 (on arm64 Windows, 3.9 and 3.10 as the x64 builds, since python.org publishes no arm64 build before 3.11), Ruby 3.3, 3.4 and 4.0, and Go 1.22, 1.25, 1.26 and 1.27 on every one, and JDK 17 and 21 on every one that has them (Temurin publishes no 17 for arm64 Windows, so that pairing is 21 alone). Containers, VMs, and remote executors run the same Linux builds. Every release publishes the same binaries to npm, PyPI (`supercov-cli`, a wheel per platform) and RubyGems (`supercov`, a gem per platform except arm64 Windows, which Ruby has no platform for), and the source to crates.io (`supercov`).
 
 ## Supported test suites
 
@@ -286,6 +311,9 @@ npx supercov runs latest line app/checkout/session.ts:64
 
 # What changed between two runs
 npx supercov diff <previous-run-id> latest
+
+# A portable interactive report for a person
+npx supercov report
 ```
 
 Collections accept `--limit` and `--offset` and print a copyable next-page command. Machine-readable output is available with `--json` when an integration needs it.
@@ -299,9 +327,9 @@ The Supercov CLI does not contact a Supercov service during a coverage run. Pack
 Supercov does not rewrite your source files, tests, imports, reporter list, runner configuration, dependency tree, or normal build output. An existing user-created `supercov/` directory is never adopted.
 
 ```bash
-npx supercov clean --dry-run   # preview cleanup
-npx supercov clean --keep 20   # keep the 20 newest runs
-npx supercov clean             # remove all runs and the build cache
+npx supercov runs clean --dry-run   # preview cleanup
+npx supercov runs clean --keep 20   # keep the 20 newest runs
+npx supercov runs clean             # remove all runs and the build cache
 ```
 
 ## Documentation
@@ -315,6 +343,7 @@ npx supercov clean             # remove all runs and the build cache
 - [Supported languages and test suites](https://supercov.com/docs/supported-suites)
 - [Understanding coverage](https://supercov.com/docs/coverage-model)
 - [Runs and evidence](https://supercov.com/docs/evidence)
+- [Portable HTML reports](https://supercov.com/docs/reports)
 - [Files, privacy, and cleanup](https://supercov.com/docs/workspace-isolation)
 - [Trusting a result](https://supercov.com/docs/verification)
 - [Speed and storage](https://supercov.com/docs/performance)
@@ -326,3 +355,6 @@ npx supercov clean             # remove all runs and the build cache
 ## Contributors
 
 - [@DaVinciTachyon](https://github.com/DaVinciTachyon)
+- [@Uhbif2](https://github.com/Uhbif2)
+- [@maik-intellicoach](https://github.com/maik-intellicoach)
+- [@untitaker](https://github.com/untitaker)

package/docs/cli.md

@@ -21,12 +21,16 @@ npx supercov --help
 | Inspect one assertion and its flows | `npx supercov runs latest assertion <id>` |
 | Read matching current source code | `npx supercov runs latest source <path>` |
 | Compare two runs | `npx supercov diff <older> <newer>` |
+| Open an interactive report | `npx supercov report` |
 | Find the tests a change affects | `npx supercov runs latest tests affected` |
 | Combine shards | `npx supercov merge <id> <id> [...]` |
-| Remove local data | `npx supercov clean` |
+| Remove stored runs | `npx supercov runs clean` |
 | Assess code quality with Jev | `npx supercov quality` |
 | See only files with findings | `npx supercov quality gaps` |
 | Review what a change introduced | `npx supercov quality patch` |
+| Remove saved assessments | `npx supercov quality clean` |
+| Find security surface with Jev | `npx supercov security` |
+| Review what a change introduced, security only | `npx supercov security patch` |
 | Read bundled guides | `npx supercov docs` |
 
 ## Assess source quality
@@ -39,6 +43,10 @@ supercov quality file src/a.ts   # one file, every check
 supercov quality scope           # which files are assessed, and why
 supercov quality snapshots       # saved assessments
 supercov quality diff <older> <newer>
+supercov security                # twelve security checks, every file
+supercov security gaps           # only files something fired on
+supercov security patch --base origin/main
+supercov security --run latest   # flagged files no test exercises
 ```
 
 With no argument the subject is the repository you are standing in. Every
@@ -56,7 +64,8 @@ the exact requests and contacts nothing.
 health, which properties appeared, and which files entered or left the scope.
 
 Assessing needs a TypeSafe AI API key in `TYPESAFE_API_KEY`; reading a saved
-assessment does not. The command prints a cost estimate before sending anything
+assessment does not. `TYPESAFE_BASE_URL` and `TYPESAFE_DEFAULT_MODEL` use Jev
+through another provider, such as OpenRouter. The command prints a cost estimate before sending anything
 and caches answers by content, so a second run pays only for what changed.
 
 See [Understanding quality](https://supercov.com/docs/quality) for what the
@@ -340,6 +349,30 @@ The same filters can focus a comparison:
 npx supercov diff <older-run> <newer-run> --kind e2e
 ```
 
+## Generate a portable HTML report
+
+```sh
+npx supercov report
+npx supercov report <run-id>
+npx supercov report latest --compare <older-run-id>
+```
+
+`report` turns stored local evidence into one self-contained interactive HTML
+file and opens it in the default browser. It does not rerun tests, start a
+server, load external assets, or upload anything. The default report includes
+up to ten recent runs. Selecting a run compares it with the previous saved run
+automatically.
+
+```sh
+npx supercov report --runs 5
+npx supercov report --output artifacts/supercov-report.html --no-open
+```
+
+Use `--runs N` to include up to 20 stored runs. Reports are capped at 24 MB so
+they remain suitable for a normal pull-request attachment; use `--runs 1` if a
+large project exceeds that target. See [Portable HTML reports](reports.md) for
+the privacy and source-integrity rules.
+
 ## Find a smaller test set
 
 ```sh supercov
@@ -386,15 +419,31 @@ incompatible merge rather than publishing a misleading aggregate.
 ## Clean local data
 
 ```sh supercov
-npx supercov clean --dry-run
-npx supercov clean --keep 20
-npx supercov clean
+npx supercov runs clean --dry-run
+npx supercov runs clean --keep 20
+npx supercov runs clean
 ```
 
-By default, `clean` removes all stored runs and the isolated build cache.
-`--keep N` keeps the newest N runs. Cleanup removes only marker-owned Supercov
+By default, `runs clean` removes all stored runs and the isolated build cache.
+`--keep N` keeps the newest N runs, by when they started rather than by their
+identifiers, which carry no order. Cleanup removes only marker-owned Supercov
 storage.
 
+Saved quality assessments live in their own lane and are never removed here: an
+assessment costs money and cannot be reproduced from the repository. Remove
+those deliberately, with the same options:
+
+```sh supercov
+npx supercov quality clean --dry-run
+npx supercov quality clean --keep 5
+npx supercov quality clean
+```
+If Supercov itself fails to publish a run the tests already paid for, it keeps
+that run's raw evidence in `.supercov/failed-evidence/<run id>` and says so in
+the error. Report the failure with that directory: it is what diagnoses it. Only
+a full `runs clean` reclaims it -- `--keep N` leaves it alone -- and the summary says
+when it goes.
+
 ## Read bundled documentation
 
 ```sh supercov

package/docs/evidence.md

@@ -101,15 +101,23 @@ instrumented build cache may use more space than the compressed run itself.
 Nothing is pruned in the background.
 
 ```sh supercov
-npx supercov clean --dry-run
-npx supercov clean --keep 20
-npx supercov clean
+npx supercov runs clean --dry-run
+npx supercov runs clean --keep 20
+npx supercov runs clean
 ```
 
 Preview cleanup first. The final command removes all runs and the isolated build
 cache; `--keep 20` preserves the 20 newest runs. Cleanup removes only
 marker-owned Supercov data.
 
+### Evidence of a run that failed to publish
+
+A suite pays for its measurement in wall clock. If Supercov itself cannot
+publish a run the tests already finished, the run's raw evidence is kept in
+`.supercov/failed-evidence/<run-id>/` rather than going with the work directory,
+and the error names the path. Attach that directory to the bug report.
+`runs clean` reclaims it; `--keep N` does not.
+
 ## Understand test kinds
 
 Reports group tests by kind, such as unit, integration or E2E. Supercov uses

package/docs/getting-started.md

@@ -21,6 +21,16 @@ Measure code quality with npx supercov.
 
 See [Understanding quality](https://supercov.com/docs/quality).
 
+For security surface with the same key, ask:
+
+```text supercov-prompt
+Find security issues with npx supercov security and show me what it found.
+```
+
+Supercov asks twelve security checks of every file and shows each finding
+with the line and the code on it. See
+[Security surface](https://supercov.com/docs/security).
+
 When it finishes, review the test change and coverage comparison in your
 conversation. Ask separately if you want a commit or pull request.
 
@@ -88,7 +98,16 @@ npx supercov runs latest line app/checkout/session.ts:64
 outcomes and MC/DC witnesses. `line` shows the obligations and tests associated
 with one source line.
 
-### 4. Add a test and prove the gain
+#For a human review, create one interactive file from the same stored evidence:
+
+```sh
+npx supercov report
+```
+
+It opens locally with run comparison, prioritized gaps, source context, test
+attribution, and scope. No test rerun or server is required.
+
+## 4. Add a test and prove the gain
 
 The agent writes one focused test with a meaningful assertion. It then reruns
 the same complete command and compares the two runs:
@@ -119,7 +138,7 @@ if anything is missing.
 - for Rust, the Rust 1.95 toolchain;
 - for Go, Go 1.22 or newer;
 - for Java and Kotlin, JDK 17 or newer, with Maven or Gradle;
-- for Python, CPython 3.12 or newer with pytest or unittest;
+- for Python, CPython 3.9 or newer with pytest or unittest;
 - for Ruby, Ruby 3.4 or newer with RSpec, Minitest, test-unit or Cucumber (3.3 measures lines, methods and simple branches only).
 
 The CLI is a native binary. `npx supercov` picks the build for your operating
@@ -152,9 +171,9 @@ Supercov does not rewrite your source, tests, imports, runner configuration,
 dependencies, or ordinary build output.
 
 ```sh supercov
-npx supercov clean --dry-run   # preview what would be removed
-npx supercov clean --keep 20   # keep the 20 newest runs
-npx supercov clean             # remove all runs and the build cache
+npx supercov runs clean --dry-run   # preview what would be removed
+npx supercov runs clean --keep 20   # keep the 20 newest runs
+npx supercov runs clean             # remove all runs and the build cache
 ```
 
 If the first run does not look right, go to [Troubleshooting](troubleshooting.md)

package/docs/performance.md

@@ -21,6 +21,11 @@ The summary separates:
 | Test command | The wrapped command, including browser, VM, or remote latency |
 | Evidence publication | Validating and storing the completed run |
 
+The line Supercov prints when a run ends also reports publication: analysing
+the evidence once for the stored query views, the summary and the assertion
+map. That is why the first query after a run opens at once rather than
+analysing the evidence itself.
+
 The first `npx` invocation may also download the package. That download happens
 before Supercov starts and is not coverage-engine overhead.
 
@@ -64,6 +69,48 @@ compare a cold package, browser, build, or VM cache with a warm one. Supercov
 never runs the test command a second time automatically because suites may write
 data, call paid services, or be intentionally non-repeatable.
 
+### Python subprocesses
+
+Interpreter count matters as well as test count. Each child initializes the
+Python runtime before executing user code, so a suite that launches thousands
+of short-lived interpreters can have more overhead than a single-process suite
+with the same number of tests. Tight child-startup deadlines can also expire
+before the child produces its first output.
+
+Supercov prepares the run's probe index once and lets later interpreters load
+file and decision data as needed. The compiled-module cache is separate: it
+avoids compiling unchanged measured source, while the prepared index avoids
+repeatedly parsing and indexing the entire coverage plan.
+
+Optional unittest and concurrency adapters install when their libraries are
+imported, rather than importing those libraries into every helper process.
+Libraries already loaded when measurement starts are patched immediately.
+
+For development, `python3 scripts/python-startup-benchmark.py` measures cold
+initialization and repeated child startup against a synthetic plan. Use
+`--runtime /path/to/checkout/runtime/python` to compare implementations. This
+isolates startup cost; it does not predict a complete suite's slowdown, which
+also includes measured execution, concurrency and evidence publication.
+
+For an end-to-end subprocess workload, build a release binary and run:
+
+```sh
+cargo build --release -p supercov
+python3 scripts/python-subprocess-benchmark.py \
+  --output /tmp/supercov-subprocess-benchmark \
+  --children 1000 --tests 400 \
+  --binary candidate="$PWD/target/release/supercov"
+```
+
+Use a new output directory for each experiment. The fixture defaults to 321
+source files and saves plain/measured timings, CLI phase timings, child latency,
+test outcomes and coverage summaries. Add another `--binary label=/path` to
+compare builds; measured coverage and outcomes must agree. Vary `--calls` for
+hot execution, `--statements` for plan size, `--decision-width` for wider MC/DC
+regions, or `--workers` for concurrent children. `--mode noop` isolates helpers
+that run no measured source; `--mode script` exercises native entry scripts and
+allows the corrected unmeasured-file denominator to differ between versions.
+
 ## Understand disk usage
 
 Each completed run stores compressed evidence and metadata under
@@ -74,9 +121,9 @@ The isolated workspace may be larger because it can contain an instrumented
 build cache. Supercov does not delete history in the background.
 
 ```sh supercov
-npx supercov clean --dry-run
-npx supercov clean --keep 20
-npx supercov clean
+npx supercov runs clean --dry-run
+npx supercov runs clean --keep 20
+npx supercov runs clean
 ```
 
 Use `--dry-run` to preview cleanup. Keep enough run history for active reviews

package/docs/quality.md

@@ -35,6 +35,27 @@ Set it the way your environment already sets secrets:
 Reading a saved assessment never needs a key, and `--dry-run` prints the exact
 requests without sending them.
 
+## Use Jev through another provider
+
+Supercov reads the same variables as TypeSafe's own SDKs, so a provider that
+serves Jev, such as [OpenRouter](https://openrouter.ai), needs only its URL, its
+name for the model, and its key:
+
+```bash
+export TYPESAFE_BASE_URL=https://openrouter.ai/api
+export TYPESAFE_DEFAULT_MODEL=typesafe/jev-1.13
+export TYPESAFE_API_KEY=sk-or-...
+npx supercov quality
+```
+
+| Variable | What it is | Default |
+| --- | --- | --- |
+| `TYPESAFE_BASE_URL` | where requests go | `https://api.typesafe.ai` |
+| `TYPESAFE_DEFAULT_MODEL` | the model asked for | `jev-1.13.0` |
+
+Snapshots record the model, and `quality diff` compares only snapshots from the
+same one.
+
 ## Start with the repository
 
 ```bash
@@ -100,15 +121,16 @@ the merge base so commits other people landed after you branched are not
 counted as yours.
 
 It asks the twelve properties differentially, whether the new version shows
-something the old one did not, and adds six checks that only make sense for a
-change:
+something the old one did not, adds three checks that only make sense for a
+change, and asks the twelve [security surface](security.md) checks the same
+differential way:
 
-- a credential written into source
-- untrusted input interpolated into a query
-- a change to how the system decides who may do what
 - a test that now checks less than it did
 - a database schema or data migration
 - debugging left behind
+- a secret in source, an injection sink, unescaped output, a path or
+  destination taken from a caller, a handler with no visible authorisation, and
+  the rest of the security catalog, each only if the change introduced it
 
 Output lists only files where something appeared. A change that introduces
 nothing says so in one line.

package/docs/security.md

@@ -0,0 +1,181 @@
+# Security surface
+
+`supercov security` tells you what security-relevant surface each file shows:
+twelve named checks, asked file by file, each mapped to the weakness classes it
+stands for. There is no score. A file is clean, or it names what fired.
+
+Judgments come from [Jev](https://typesafe.ai), the same way `supercov quality`
+gets them. Set `TYPESAFE_API_KEY`, and optionally another provider, as described
+in [quality](quality.md); reading a saved assessment never needs a key.
+
+## Start with the repository
+
+```bash
+npx supercov security
+```
+
+```
+Security: 6 of 73 files flagged, 67 clean; 4 confirmed at a line.
+  destination_from_input 3, injection_sink 1, missing_authorization 1, unsafe_code_execution 1
+Catalog security-v4, model jev-1.13.0, snapshot q_5e1c…
+
+Flagged:
+  src/routes/invoices.ts
+    0.91  injection_sink
+          line 42  0.88  db.query(`select * from invoices where id = ${req.params.id}`)
+  src/gateways/sseToStdio.ts
+    0.77  destination_from_input  (file-level only)
+```
+
+Every line is a claim you can check against the file in seconds. The value is
+the model's probability that the pattern is present; nothing is averaged,
+because nothing in the evidence supported averaging security answers.
+
+## Two passes, two tiers
+
+Every file is asked the twelve questions once. For the checks that fired at
+all, the parser lists every call, literal, route handler and request-body
+spread the file has (Python, JavaScript and TypeScript), or every template
+expression and configuration value (templates and config files), and the
+model says which of the fired checks, if any, each line shows, one Choice
+per line. Each classified line then gets the check's own question and a
+triage question: would a careful reviewer report this, or dismiss it. A finding confirmed at a line is shown with the line and
+the code on it, and with the line where the outside value enters the program
+when the model can name one; a finding only the first pass made is marked
+file-level only. Three findings of one check within ten lines count as one.
+Authorisation findings stay file-level. Whether a guard reaches a handler
+and which callers it admits is a fact that lives in the wiring, not the
+handler, and no per-line question has been found that decides it: every
+attempt measured on the labelled corpus fired on unguarded handlers the
+application leaves open by design as often as on the ones it should not.
+
+
+Measured with this command on fifteen held-out repositories of a
+140-repository labelled corpus, whole repositories, at finding level: F1
+0.47 with 54% precision and 41% recall, where Semgrep scores 0.14, the
+general agentic LLM scanners 0.50 to 0.60, and the two leaders 0.76 and
+0.77, at about two cents per repository against 30 cents to 4 dollars for
+the agentic scanners. Injection, secrets, path, redirect and mass
+assignment are found at 70 to 90% recall; authorisation and authentication
+at 10%, because the guard that decides them lives in another file. A file
+too large for one request is read in windows at declaration boundaries.
+
+## Across files
+
+The second pass also labels every function of every file, on the same
+request: does it take caller-supplied data, does a parameter reach a
+dangerous operation unprotected inside it, does it sanitise or authorise what
+it receives, and which kind of operation. Supercov then resolves the file's
+imports itself, pairs every function that takes outside data with every
+imported function that reaches a sink without sanitising, where the caller's
+body names the callee, and confirms each pair with one question that carries
+both function bodies. A confirmed path is printed as a call site and a sink:
+
+```
+Cross-file paths confirmed: 2
+  0.79  injection_sink  app/routes/index.js:19 index -> app/routes/allocations.js:11 displayAllocations
+  0.70  injection_sink  app/routes/benefits.js:11 BenefitsHandler -> app/data/benefits-dao.js:2 BenefitsDAO
+```
+
+The model never sees two files at once until a path is confirmed; the graph
+is host code over resolved imports, one hop.
+
+With `--run`, a second kind of edge joins the first: the run's own record of
+which tests executed which lines. A sink function and an entry function that
+took outside data under the same test are paired and confirmed the same way,
+whether or not any import connects them. That is how a handler that reaches
+its sink through a lookup table, a registry, a decorator or a framework is
+followed; no import graph has that edge, and no trace is attempted. On a
+library whose views dispatch to their sinks by name, this took recall of the
+labelled weaknesses from 42% to 75%. Without a run, nothing here is asked. Measured on a third of the same
+corpus, confirmed paths fired on 0.1% of unlabelled files, and on real CVEs
+in mature projects this stage is where the recall has to come from, because
+a real vulnerability rarely sits in one file. JavaScript, TypeScript and
+Python have parsers for this; other languages get the twelve questions and
+the pattern candidates only.
+
+## The twelve checks
+
+| Check | Stands for |
+| --- | --- |
+| secret_in_source | a credential or signing secret written into the source (CWE-798, 259, 321) |
+| injection_sink | a query or command assembled from a caller's value (CWE-89, 78, 77, 943, 90) |
+| unsafe_code_execution | eval, exec, pickle or unsafe deserialisation of outside data (CWE-94, 95, 502, 1336) |
+| unescaped_output | an outside value written into markup without escaping (CWE-79, 116) |
+| path_from_input | a file operation on a caller-controlled path, name or type (CWE-22, 73, 434) |
+| missing_authorization | a handler acting on a caller-chosen record with no visible check (CWE-862, 863, 639, 284, 306) |
+| weak_authentication | a token, session or password handled in a way that weakens it (CWE-287, 613, 614, 347, 384, 1004) |
+| weak_cryptography | a primitive weak for its purpose, or predictable randomness for a secret (CWE-327, 328, 326, 330, 338, 916) |
+| sensitive_data_exposure | a secret, token or internal detail in a log or a response (CWE-200, 209, 532, 312) |
+| destination_from_input | a request or redirect going wherever a caller's value says (CWE-918, 601) |
+| unchecked_mass_assignment | a request body copied wholesale into a record (CWE-915, 1321) |
+| insecure_configuration | a provided protection switched off or weakened, or debug mode left on (CWE-16, 295, 352, 611, 942, 1004, 489, 215) |
+
+Each asks whether a pattern is present, never whether it is exploitable, and
+each states its exception. A value is from outside the program when it arrives
+at run time from a caller, request, message, upload or third-party service; the
+operator's own configuration, arguments, environment and shipped files are not.
+
+## What is known about each check
+
+Measured on 2026-09-20 against constructed pairs, a clean floor, and RealVuln,
+a corpus of 140 deliberately vulnerable repositories with 3,381 labelled
+findings in Python, TypeScript and JavaScript:
+
+- every check caught its constructed positive at 0.97 or above and stayed quiet
+  on a matched safe file, both when asked of a file and of a change;
+- on the labelled corpus, the check a finding's weakness class maps to fired on
+  68% of files carrying a finding, from 96% for secrets in source down to 43%
+  for missing authorisation, and on 5 of 76 certified false-positive traps;
+- on the same files and labels, Semgrep reached 10%, SonarQube 18% and Snyk 21%.
+
+`missing_authorization` is the weak one and is shown with that number. A
+per-file question cannot see a guard in another file, so it is right seven
+times in ten on code people wrote and less on generated corpora that label
+single unguarded routes inside otherwise guarded files.
+
+```bash
+npx supercov security file src/routes/invoices.ts
+```
+
+shows every check with its value and its evidence line, so a finding can be
+weighed without leaving the terminal.
+
+## Cross it with a run
+
+```bash
+npx supercov security --run latest
+```
+
+adds, for every flagged file, whether the saved coverage run executed it and how
+many of its measured lines no test reached. A handler that builds a query from
+request input is one thing; the same handler that no test ever executes is a
+stronger claim, and one that needs both halves of this product to make.
+
+## What a change introduced
+
+```bash
+npx supercov security patch --base origin/main
+npx supercov security patch --annotate github
+```
+
+The same twelve, asked whether the new version shows a surface the old one did
+not. `quality patch` asks them too, alongside its own catalog, so a review of a
+change needs one command; `security patch` is the same answers without the
+complexity findings.
+
+## Reference
+
+```bash
+npx supercov security                             # this repository
+npx supercov security gaps                        # only files something fired on
+npx supercov security file src/server.ts          # one file, every check, with evidence
+npx supercov security scope                       # which files, and why
+npx supercov security snapshots                   # saved assessments
+npx supercov security diff <older> <newer>        # what appeared
+npx supercov security patch                       # what a change introduced
+npx supercov security --run latest                # flagged and untested
+```
+
+Cache and snapshots live under `.supercov/security/`, apart from quality's, so
+one can never be read as the other.

package/docs/supported-suites.md

@@ -184,14 +184,16 @@ attribution.
 
 | Runner | Attribution | Current requirement |
 | --- | --- | --- |
-| pytest | Exact test, worker, retry, and setup/call/teardown phase identity | CPython 3.12 or newer; run with `npx supercov -- pytest` or `python -m pytest` |
+| pytest | Exact test, worker, retry, and setup/call/teardown phase identity | CPython 3.9 or newer; run with `npx supercov -- pytest` or `python -m pytest` |
 | pytest-xdist | Exact per worker | Workers inherit the run through the environment |
 | pytest-rerunfailures | Exact per attempt; flaky tests are reported as such | |
 | `python -m unittest` | Exact test and setUp/test/tearDown phase identity | Serial in-process; skips and expected failures are recorded; subtest failures roll up to the parent test |
 
 Your project runs in place with its own interpreter and virtual environment.
-Supercov adds its monitoring and runner hooks through the process environment;
-you do not need to rewrite tests or configure a different build.
+Supercov adds its runner hooks through the process environment and places a
+probe for every obligation into each measured module as it is imported --
+nothing on disk changes, and tracebacks keep their line numbers. You do not
+need to rewrite tests or configure a different build.
 
 Coverage includes statements, functions, boolean decisions, loops,
 comprehensions, short-circuit operators, `match` cases and exception paths.
@@ -202,9 +204,11 @@ assertion checks.
 
 Interpreters launched with `-I`, `-E` or `-S` ignore the required startup hook
 and are not measured. Code compiled from strings at runtime has no source
-obligations. Completed observations can survive a hard kill, but a corrupt or
-exhausted evidence channel fails the run rather than reporting partial data as
-complete.
+obligations. A measured module imported before Supercov starts, or compiled
+past the import system, runs without probes; the run names it as a limitation
+rather than reporting it uncovered. What a test executed survives the process
+being killed -- `os._exit`, SIGTERM or SIGKILL -- but a corrupt or exhausted
+evidence channel fails the run rather than reporting partial data as complete.
 
 ```sh
 npx supercov -- pytest

package/docs/troubleshooting.md

@@ -74,6 +74,47 @@ Compare the command with [Supported suites](supported-suites.md). If the runner
 should be supported, preserve the summary and exact command when reporting the
 problem.
 
+## A plain Python run behaves differently after using Supercov 1.2.0
+
+Version 1.2.0 could write instrumented bytecode into ordinary Python caches
+through explicit source loaders or `py_compile`. Its fallback for condition
+probes could then change behavior when a later plain run loaded that bytecode.
+
+After updating Supercov, remove the generated bytecode caches for the affected
+project, or discard the dedicated `PYTHONPYCACHEPREFIX` directory used by the
+old run. Rebuild those caches with plain Python before comparing test outcomes.
+Updating Supercov cannot repair bytecode already written by an older version.
+
+## A Python file has tests but no measured lines
+
+Python imports and `python -m package.module` pass through Supercov's probe
+loader. CPython compiles a direct entry script (`python path/to/script.py`)
+outside that loader. Supercov declares this boundary on the affected file,
+including on Python 3.9–3.11. It does not silently rewrite the child command,
+which could change imports, `sys.argv`, or process behavior.
+
+A file can therefore have tests that touched it through an import, while a
+separate direct execution makes its overall coverage unmeasured. Those lines
+are excluded from both the measured denominator and the uncovered-lines list.
+Inspect the file's measurement limitations before treating a zero denominator
+as complete coverage.
+
+## Python subprocess output or timeout assertions fail
+
+Supercov adds interpreter startup and execution time. A timeout that expires
+before the child reaches its first write can return empty partial output.
+When testing timeout handling, synchronize with the child's readiness first;
+when testing an actual performance deadline, compare the plain run separately.
+
+Ordinary helpers that import no application code stay silent. Set
+`SUPERCOV_PYTHON_TIMING=1` only for diagnostics: it deliberately adds stderr
+output. Explicit child environments that omit Supercov's plan are left alone.
+
+Runtime evidence descriptors are close-on-exec. After an exec, Python or
+Supercov may reuse a closed descriptor's number. A descriptor-leak test should
+compare the original open file's identity, rather than only whether its number
+is open in the new process.
+
 ## A Ruby file behaves differently while Supercov measures it
 
 Supercov splices probe calls into Ruby sources in memory as they load, and a
@@ -185,9 +226,9 @@ See [Speed and storage](performance.md) for practical ways to shorten a loop.
 Preview cleanup, then choose how much history to keep:
 
 ```sh supercov
-npx supercov clean --dry-run
-npx supercov clean --keep 20
-npx supercov clean
+npx supercov runs clean --dry-run
+npx supercov runs clean --keep 20
+npx supercov runs clean
 ```
 
 The final command removes all stored runs and the isolated build cache. Cleanup

package/docs/workspace-isolation.md

@@ -75,9 +75,9 @@ staging state. Completed runs remain immutable.
 Preview cleanup before removing anything:
 
 ```sh supercov
-npx supercov clean --dry-run
-npx supercov clean --keep 20
-npx supercov clean
+npx supercov runs clean --dry-run
+npx supercov runs clean --keep 20
+npx supercov runs clean
 ```
 
 The final command removes all runs and the isolated build cache. `--keep 20`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "supercov",
-  "version": "1.1.1",
-  "description": "Code quality and coverage for coding agents",
+  "version": "2.0.0",
+  "description": "Coverage, security and code quality for coding agents",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,7 @@
     "docs/agent-loop.md",
     "docs/assertions.md",
     "docs/quality.md",
+    "docs/security.md",
     "docs/assertion-evidence.md",
     "docs/assertion-maps.md",
     "docs/assertion-agent.md",
@@ -63,10 +64,11 @@
     "test:isolation": "cargo build -p supercov && node scripts/isolation-integration.mjs",
     "test:filesystem": "cargo test --workspace && cargo build -p supercov && node scripts/workspace-crash-integration.mjs",
     "test:watchdog": "cargo build -p supercov && node scripts/watchdog-integration.mjs",
+    "test:html-report": "cargo build -p supercov && node scripts/html-report-integration.mjs",
     "test:engine-contract": "cargo build -p supercov && node scripts/engine-contract.mjs",
     "test:agent": "cargo build -p supercov && node scripts/agent-query-eval.mjs",
     "test:engine": "cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace && npm run test:runtime && npm run test:rust-assets && npm run test:engine-integrations",
-    "test:engine-integrations": "cargo build -p supercov && node scripts/rust-process-supervision.mjs && node scripts/rust-direct-node-integration.mjs && node scripts/rust-public-run-integration.mjs && node scripts/rust-embedded-runtime-integration.mjs && node scripts/rust-direct-vitest-integration.mjs && node scripts/rust-direct-jest-integration.mjs && node scripts/rust-direct-playwright-integration.mjs && node scripts/rust-custom-browser-playwright-integration.mjs && node scripts/rust-generic-esbuild-integration.mjs && node scripts/rust-generic-tsc-integration.mjs && node scripts/rust-generic-build-matrix.mjs && node scripts/rust-vite-playwright-integration.mjs",
+    "test:engine-integrations": "cargo build -p supercov && node scripts/html-report-integration.mjs && node scripts/rust-process-supervision.mjs && node scripts/rust-direct-node-integration.mjs && node scripts/rust-public-run-integration.mjs && node scripts/rust-embedded-runtime-integration.mjs && node scripts/rust-direct-vitest-integration.mjs && node scripts/rust-direct-jest-integration.mjs && node scripts/rust-direct-playwright-integration.mjs && node scripts/rust-custom-browser-playwright-integration.mjs && node scripts/rust-generic-esbuild-integration.mjs && node scripts/rust-generic-tsc-integration.mjs && node scripts/rust-generic-build-matrix.mjs && node scripts/rust-vite-playwright-integration.mjs",
     "test:platform": "cargo test --workspace && cargo build -p supercov && node scripts/rust-process-supervision.mjs && node scripts/workspace-crash-integration.mjs",
     "test:native-package": "cargo build --release -p supercov && node scripts/native-package-integration.mjs && node scripts/native-release-set-integration.mjs",
     "test:pypi-wheel": "node scripts/pypi-wheel-integration.mjs",
@@ -78,9 +80,9 @@
     "test:clang-mcdc": "node scripts/clang-mcdc-oracle.mjs",
     "test:test262": "cargo build --release -p supercov && node scripts/test262-equivalence.mjs",
     "benchmark:check": "cargo build --release -p supercov && node scripts/rust-transform-benchmark.mjs",
-    "benchmark:python-monitoring": "cargo build -p supercov && node scripts/python-monitoring-benchmark.mjs",
+    "benchmark:python": "cargo build -p supercov && node scripts/python-benchmark.mjs",
     "check": "cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && npm run test && npm run test:release-tooling && npm run test:runtime && npm run test:rust-assets && npm run test:assertion-maps && npm run test:sweep-target && npm run test:skip-guard && npm run test:windows-tls && node scripts/package-preflight.mjs && node scripts/verify-binstall-metadata.mjs --offline",
-    "release:check": "cargo clean && node scripts/sweep-target.mjs && npm run check && npm run test:engine && npm run test:go && npm run test:jvm && npm run test:launcher && npm run test:fixture && npm run test:watchdog && npm run test:engine-contract && npm run test:agent && npm run test:child-attribution && npm run test:host-loader && npm run test:python-monitoring && npm run test:ruby-coverage && npm run test:rust-public-cargo && npm run test:packed-npx && npm run test:clang-mcdc && npm run benchmark:check",
+    "release:check": "cargo clean && node scripts/sweep-target.mjs && npm run check && npm run test:engine && npm run test:go && npm run test:jvm && npm run test:launcher && npm run test:fixture && npm run test:watchdog && npm run test:engine-contract && npm run test:agent && npm run test:child-attribution && npm run test:host-loader && npm run test:python && npm run test:ruby-coverage && npm run test:rust-public-cargo && npm run test:packed-npx && npm run test:clang-mcdc && npm run benchmark:check",
     "release:bump": "node scripts/bump-version.mjs",
     "sweep": "node scripts/sweep-target.mjs",
     "oracle:rust": "cargo build --release -p supercov && node scripts/rust-coverage-oracle.mjs",
@@ -88,7 +90,7 @@
     "prepublishOnly": "npm run release:check",
     "test:child-attribution": "cargo build -p supercov && node scripts/rust-child-attribution-integration.mjs",
     "test:host-loader": "cargo build -p supercov && node scripts/rust-host-loader-integration.mjs",
-    "test:python-monitoring": "cargo build -p supercov && node scripts/python-monitoring-integration.mjs",
+    "test:python": "cargo build -p supercov && node scripts/python-integration.mjs",
     "test:ruby-coverage": "cargo build -p supercov && node scripts/ruby-coverage-integration.mjs",
     "test:go": "cargo test --no-fail-fast -p supercov-engine --test go_frontend --test go_run",
     "test:jvm": "cargo test --no-fail-fast -p supercov-engine --test jvm_frontend --test jvm_run -- --include-ignored --test-threads=1",
@@ -105,14 +107,14 @@
     "test:windows-tls": "node scripts/windows-tls-test.mjs"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "1.1.1",
-    "@supercov/cli-darwin-x64": "1.1.1",
-    "@supercov/cli-linux-arm64-gnu": "1.1.1",
-    "@supercov/cli-linux-arm64-musl": "1.1.1",
-    "@supercov/cli-linux-x64-gnu": "1.1.1",
-    "@supercov/cli-linux-x64-musl": "1.1.1",
-    "@supercov/cli-win32-arm64": "1.1.1",
-    "@supercov/cli-win32-x64": "1.1.1"
+    "@supercov/cli-darwin-arm64": "2.0.0",
+    "@supercov/cli-darwin-x64": "2.0.0",
+    "@supercov/cli-linux-arm64-gnu": "2.0.0",
+    "@supercov/cli-linux-arm64-musl": "2.0.0",
+    "@supercov/cli-linux-x64-gnu": "2.0.0",
+    "@supercov/cli-linux-x64-musl": "2.0.0",
+    "@supercov/cli-win32-arm64": "2.0.0",
+    "@supercov/cli-win32-x64": "2.0.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",