supercov 1.2.0 → 2.0.1

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:
 
@@ -16,6 +16,8 @@ Scoring needs a [TypeSafe AI](https://typesafe.ai) API key, and your coding agen
 
 Supported languages: [JavaScript](https://supercov.com/docs/javascript) · [TypeScript](https://supercov.com/docs/javascript) · [Rust](https://supercov.com/docs/rust) · [Python](https://supercov.com/docs/python) · [Ruby](https://supercov.com/docs/ruby) · [Go](https://supercov.com/docs/go) · [Java](https://supercov.com/docs/java) · [Kotlin](https://supercov.com/docs/kotlin).
 
+In Claude Code, Codex and Gemini CLI you can also [install it as a plugin](#give-supercov-a-job).
+
 Supported by [Supercorp](https://supercorp.ai).
 
 [Agent workflow](https://supercov.com/docs/agent-loop): ask your coding agent
@@ -56,6 +58,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 +116,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
@@ -143,6 +170,37 @@ exports the editor schema; `assertions validate --file <path>` checks JSON synta
 
 Paste one of these prompts into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any coding agent that can run terminal commands.
 
+Or install the agent skill, and your agent reaches for Supercov on its own when you ask for tests, coverage, refactoring or a security scan. In Claude Code:
+
+```text
+/plugin marketplace add supercorp-ai/supercov
+/plugin install supercov@supercov
+```
+
+In Codex:
+
+```bash
+codex plugin marketplace add supercorp-ai/supercov
+codex plugin add supercov@supercov
+```
+
+In Gemini CLI:
+
+```bash
+gemini extensions install https://github.com/supercorp-ai/supercov
+```
+
+For Cursor, GitHub Copilot and other agents that read skills: `npx skills add supercorp-ai/supercov`.
+
+The Claude Code plugin and the Gemini CLI extension also add four commands you can type:
+
+| Command | What it does |
+| --- | --- |
+| `/supercov:coverage [test command]` | Writes one test for code no test reaches, and reports coverage before and after |
+| `/supercov:security [patch]` | Scans the repository, or a change, for security vulnerabilities |
+| `/supercov:quality [patch]` | Ranks files by code smells, or checks what a change introduced |
+| `/supercov:review [--base ref]` | Checks a branch or uncommitted change for security and quality problems |
+
 ### Write the first useful test
 
 ```text
@@ -286,6 +344,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 +360,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 +376,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)
@@ -328,3 +390,4 @@ npx supercov clean             # remove all runs and the build cache
 - [@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,19 +419,29 @@ 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 `clean` reclaims it -- `--keep N` leaves it alone -- and the summary says
+a full `runs clean` reclaims it -- `--keep N` leaves it alone -- and the summary says
 when it goes.
 
 ## Read bundled documentation

package/docs/evidence.md

@@ -101,9 +101,9 @@ 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
@@ -115,8 +115,8 @@ marker-owned Supercov data.
 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. A full
-`clean` reclaims it; `--keep N` does not.
+and the error names the path. Attach that directory to the bug report.
+`runs clean` reclaims it; `--keep N` does not.
 
 ## Understand test kinds
 

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:
@@ -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/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.2.0",
-  "description": "Code quality and coverage for coding agents",
+  "version": "2.0.1",
+  "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,14 @@
     "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:agent-commands": "cargo build -p supercov && node scripts/check-agent-commands.mjs",
+    "eval:skill": "claude plugin eval plugins/supercov --scaffold --trust-plugin --no-publish --model claude-sonnet-5 --judge-model claude-haiku-4-5 --threshold 0.66 --tag behavior trigger --allow-tools Bash Edit Write --max-cost-usd 15",
+    "eval:skill-triggers": "claude plugin eval plugins/supercov --scaffold --trust-plugin --no-publish --model claude-sonnet-5 --judge-model claude-haiku-4-5 --threshold 0.66 --tag trigger --ablation none --max-cost-usd 5",
     "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",
@@ -79,7 +84,7 @@
     "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": "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",
+    "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:agent-commands && 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 && 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",
@@ -105,14 +110,14 @@
     "test:windows-tls": "node scripts/windows-tls-test.mjs"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "1.2.0",
-    "@supercov/cli-darwin-x64": "1.2.0",
-    "@supercov/cli-linux-arm64-gnu": "1.2.0",
-    "@supercov/cli-linux-arm64-musl": "1.2.0",
-    "@supercov/cli-linux-x64-gnu": "1.2.0",
-    "@supercov/cli-linux-x64-musl": "1.2.0",
-    "@supercov/cli-win32-arm64": "1.2.0",
-    "@supercov/cli-win32-x64": "1.2.0"
+    "@supercov/cli-darwin-arm64": "2.0.1",
+    "@supercov/cli-darwin-x64": "2.0.1",
+    "@supercov/cli-linux-arm64-gnu": "2.0.1",
+    "@supercov/cli-linux-arm64-musl": "2.0.1",
+    "@supercov/cli-linux-x64-gnu": "2.0.1",
+    "@supercov/cli-linux-x64-musl": "2.0.1",
+    "@supercov/cli-win32-arm64": "2.0.1",
+    "@supercov/cli-win32-x64": "2.0.1"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",