@clear-capabilities/agentic-security-scanner 0.182.0 → 0.184.0

package/CHANGELOG.md

@@ -9,6 +9,34 @@
 > make the history less accurate, not more.
 
 
+## 0.184.0 - Runtime corroboration reaches GA on real exports, dependency and taint findings get contracts, and a scan says when it could not consult advisories
+
+Runtime corroboration is the first Observe capability to earn GA. The other promotions of the programme's remaining items are contracts and corrections, not new maturity labels, and the ones that stay held say why.
+
+- **Runtime corroboration is GA.** A hosted job, `telemetry-capture` (now a blocking check), runs the real OpenTelemetry JavaScript SDK with its OTLP exporter, Envoy 1.31.2, nginx 1.27.5 and a kind cluster with the Kubernetes audit log on, and records the files they write, untouched, with a manifest of tool, version, command and digest. The adapters are tested against those files: 3 spans, 6 Envoy lines, 4 nginx lines and 79 audit events parse with no error, every record passes the observation contract, and nothing that could carry a payload survives (trace ids, user names, source addresses, agents, paths). A reference page freezes the adapters, the runtime status values, the status report and the six edge states.
+- **Two false security decisions found by the real exports are fixed.** The Envoy adapter read any response flag as a denial, so an upstream failure or a missing route was reported as `denied`; only an authorization-service denial is one now. The Kubernetes adapter read any status of 400 or more as a denial; on the real audit log (2 forbidden, 4 not found, 1 conflict) it would have reported 7 denials instead of 2. Now only 401 and 403 are.
+- **A scan now says when it could not consult advisory data.** An offline scan with nothing cached, or an advisory service that did not answer, used to report `complete` with no vulnerable dependencies. It now reports `scanHealth.freshness.advisories` (the source, how many dependencies were checked and how many were not), becomes `partial`, and says an empty result is not evidence of safety. A dependency finding contract page and test freeze the finding's fields, the reachability tiers and this rule.
+- **Taint findings have a contract.** The core fields of a data-flow finding, the proof and falsification verdicts and the hop fields are frozen on a reference page with a test that deep-scans fixtures. Writing it found a readable-label defect: the last hop of an interprocedural chain read `sink: [object Object]`; it now names the callee.
+- **The model capabilities have frozen contracts, not GA.** Model-assisted validation, agentic discovery (hunt) and local model support each have a reference page and a compatibility test, and a recorded-reply replay harness plays eleven written model replies through the real validator and a set through the real hunt pipeline. Writing them found two defects, both fixed: a hunter reply whose candidates had no file and line was discarded without a word (it is now counted in the coverage reasons), and `--forget-refuted`, which the tool's own output tells you to use, was not read by the command. They stay Preview because the only model a hosted runner can run completes none of their work, so there is no precision to publish.
+- **All ten compliance frameworks have a per-control coverage map.** The five that had none are generated from the framework files, a summary counts all ten, and the doc-drift gate fails when a map is stale or missing or the README count is wrong.
+- **The deterministic context analysis sees Flask ORM operations and judges ownership at the first write.** On the application-shaped benchmark Flask went from 6 of 10 routes unresolved to 0 and Express precision from 82% to 100% (12 of 12), recall 100%. The cases are synthetic and author-labelled, so these are not accuracy on real applications; 2 routes behind a mounted router are still unresolved.
+- **The finding provenance guide's limits were stale and are corrected**: the labelled corpus passes 13 of 13 and renames are followed. Coverage (83.8% of eligible findings against a 95% target) and cold-cache overhead (24 times on a 15-finding fixture, about 70 milliseconds of git work per file) are stated with their measured numbers.
+- **Held, with the reasons on the promotion record:** the three model capabilities, Haskell and Nix (no independent second holdout), and the four Wave 1 Preview capabilities (Code Boundaries needs a lineage-only source catalog and field-identity changes; provenance cannot replay whole-project analyses).
+
+## 0.183.1 - Exploit proof, the proof gate on fixes and source-to-artifact provenance reach GA, measured against the real tools
+
+
+**Release note.** A 0.183.0 tag was created and its hosted release gate failed before anything was published, so these changes ship as 0.183.1. The failure was a contract test that depended on warm local advisory data; it now seeds its own. The container probe also waits for a busy daemon and retries once instead of reading one slow answer as no daemon.
+
+Each promotion is held to the GA bar and rests on a hosted CI job that runs the real tool and fails, rather than skips, when the tool is missing. Those jobs are now blocking checks, so a release cannot go out on a commit where they are red.
+
+- **Execution-backed exploit proof is GA.** Measured on three hosts and committed: macOS 39 of 39 reproductions; Linux under local confinement 36 of 36 (hosted `proof-linux`); Linux in a real container 36 of 36 (hosted `proof-container`, docker 28.0.4). Each has 0 false confirmations and 3 of 3 hanging reproducers represented as degraded. Generation covers command injection, path-writing traversal and request forgery; the contract says so.
+- **The proof gate on applying a fix is GA, and fails closed.** `fix --apply --require-proof` applied 0 of 15 unsafe fixes and 1 of 8 safe fixes on the fix-verification corpus (7 refused for want of a reproducer). The new bench matches its baseline on both Linux jobs.
+- **Source-to-artifact provenance is GA.** The `artifact-real` job builds images with the real container engine, pushes to a real registry and signs with cosign: archive, engine and registry inputs agree (10 advisories), a signed image verifies, the same image with another key is `invalid`, an unsigned image is `missing`, and a source patched against a still-vulnerable image is flagged while an equal source is not.
+- **The first real-tool runs found real defects, now fixed.** Java proofs could not start in the container (the runner replaced the image's `PATH`; 30 of 36 reproductions until fixed). The mismatch detector read a source scan limited to SCA as having no advisories, so a source on the same vulnerable version looked fixed; a source scan with no dependency data is now refused. cosign's wrong-key message was classified `missing` instead of `invalid`. A key-signed image from a registry with no transparency log could not be verified; `image verify --cosign --ignore-tlog` is an explicit opt-in and the result says the log was not checked.
+- **The artifact guide's limits were stale and are rewritten** (it said no engine input, no registry input and no signing tool was exercised).
+- **Held, with the measured reason on the promotion record:** local model support, model-assisted validation and hunt (a real 2B model on the hosted runner passed every contract check but completed 0 of 5 Eval Lab attempts and hunted 0 of 3 areas), runtime corroboration (no recorded real telemetry packs) and Haskell/Nix (no independent second holdout).
+
 ## 0.182.0 - Five Labs capabilities freeze their interfaces and move to Preview, and the strategic metrics become product numbers
 
 Preview is not GA. Each move below gives a capability a reference page that lists every field, flag and exit code, and a compatibility test that runs the real commands and fails when the output gains or loses a field the page does not list.

package/bin/agentic-security.js

@@ -2743,6 +2743,7 @@ async function cmdHunt(args) {
       maxCostUsd: numFlag('max-cost-usd'),
       // PRD C4 — persist and consult cross-run memory.
       scanRoot: args.flags['no-memory'] ? undefined : scanRoot,
+      forgetRefuted: !!args.flags['forget-refuted'],
       // PRD C2 — a comma-separated endpoint list turns on consensus.
       endpoints: args.flags.endpoints,
       costPerCallUsd: numFlag('cost-per-call-usd'),
@@ -6146,7 +6147,7 @@ async function cmdImageVerify(args) {
     const { verifyWithCosign } = await import('../src/artifact/cosign.js');
     const repo = typeof args.flags.repository === 'string' ? args.flags.repository : (resolved.record.source?.kind === 'registry' ? `${resolved.record.source.registry}/${resolved.record.source.repository}` : null);
     signatureResult = repo
-      ? await verifyWithCosign({ repository: repo, digest: inventory.digest, publicKeyPem, certificateIdentity: args.flags['certificate-identity'], certificateOidcIssuer: args.flags['certificate-oidc-issuer'] })
+      ? await verifyWithCosign({ repository: repo, digest: inventory.digest, publicKeyPem, ignoreTlog: !!args.flags['ignore-tlog'], certificateIdentity: args.flags['certificate-identity'], certificateOidcIssuer: args.flags['certificate-oidc-issuer'] })
       : { state: 'unavailable', via: 'cosign', reason: 'cosign verifies against a registry: give --repository <registry/repo>, or scan with --registry so the repository is known' };
   }
   const attestationResult = verifyProvenanceAttestation({ digest: inventory.digest, envelope: attestation, publicKeyPem });
@@ -6194,8 +6195,17 @@ async function cmdProvenanceTrace(args) {
     }
     const sourceScan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
     const { detectSourceArtifactMismatch } = await import('../src/artifact/mismatch.js');
+    // A full scan keeps its dependency findings in `supplyChain`; a scan limited with `--only sca` keeps them in `findings`. Reading only the first
+    // made a source that carried the same advisories look fixed, which is the one reading this comparison must never produce, so both are read
+    // and a source scan with no dependency data at all is refused instead of treated as clean.
+    const sourceVulns = (sourceScan.supplyChain && sourceScan.supplyChain.length) ? sourceScan.supplyChain : (sourceScan.findings || []).filter((x) => x && x.type === 'vulnerable_dep');
+    const sourceHasData = Array.isArray(sourceScan.supplyChain) || sourceVulns.length > 0 || !!(sourceScan.components && sourceScan.components.length);
+    if (!sourceHasData) {
+      process.stderr.write(`agentic-security provenance trace: --source "${args.flags.source}" carries no dependency data (no components and no dependency findings), so nothing can be compared; run "scan" there with SCA enabled.\n`);
+      return 1;
+    }
     mismatch = detectSourceArtifactMismatch({
-      sourceVulnerabilities: sourceScan.supplyChain || [],
+      sourceVulnerabilities: sourceVulns,
       artifactVulnerabilities: vulnerabilities,
       artifactComponents: [...inventory.osPackages, ...inventory.appPackages],
     });

package/dist/2923.index.js

@@ -443,9 +443,10 @@ function parseOtelJsonObservations(text, context) {
  * `destination.service`), `protocol` (normalized — Envoy writes
  * `"HTTP/1.1"`, which contains `/` and is not an approved identifier
  * shape; lowercased and `/` stripped, e.g. `"http1.1"`), and
- * `response_flags` (`'-'`/empty means no flag, i.e. allowed; a non-empty
- * flags string, e.g. `"UAEX"` for unauthorized, is treated as `'denied'`
- * via `network.securityDecision`). `start_time`/`end_time` (or
+ * `response_flags` (`'-'`/empty means no flag, i.e. allowed; `"UAEX"`, the
+ * external authorization service denying the request, is `'denied'` via
+ * `network.securityDecision`; any other flag, such as an upstream failure or
+ * a missing route, is an operational outcome and carries no decision). `start_time`/`end_time` (or
  * `start_time` alone, with `duration` in milliseconds added) feed
  * `firstObservedAt`/`lastObservedAt`. Everything else — client address,
  * request path/query, user agent, request id, response code's own exact
@@ -488,7 +489,13 @@ function parseEnvoyAccessLogObservations(text, context) {
     if (cluster) attributes['destination.service'] = cluster;
     if (protocol) attributes['network.protocol'] = protocol;
     if (typeof record.response_flags === 'string') {
-      attributes['network.securityDecision'] = record.response_flags.trim().length === 0 || record.response_flags.trim() === '-' ? 'allowed' : 'denied';
+      // Only a flag that records an authorization decision is a security decision. UAEX is the external authorization service
+      // denying the request. Every other flag (UF upstream connection failure, NR no route, UT timeout, DC client disconnect) is
+      // an operational outcome, and calling it "denied" would invent a denial, so those make no claim either way.
+      const flags = record.response_flags.trim();
+      const tokens = flags.split(',').map((t) => t.trim()).filter(Boolean);
+      if (flags.length === 0 || flags === '-') attributes['network.securityDecision'] = 'allowed';
+      else if (tokens.includes('UAEX')) attributes['network.securityDecision'] = 'denied';
     }
 
     if (Object.keys(attributes).length === 0) continue; // nothing safe/present to report for this line
@@ -520,10 +527,8 @@ function parseEnvoyAccessLogObservations(text, context) {
  * `destination.service` — never `objectRef.name`, which is frequently a
  * user-chosen, potentially sensitive resource name) and
  * `responseStatus.code` (mapped to `network.securityDecision`: `< 400`
- * is `'allowed'`, `>= 400` is `'denied'` — a client error is treated as a
- * decision here because the audit log's own admission/authorization
- * failures surface as 401/403/409, which is exactly the "security
- * decision" fact this adapter exists to carry). `requestReceivedTimestamp`/
+ * is `'allowed'`, `401`/`403` is `'denied'`, anything else carries no
+ * decision: a not-found or a conflict is not an authorization outcome). `requestReceivedTimestamp`/
  * `stageTimestamp` feed the observed-at window. **`user.username` and
  * every request/response body field are deliberately never read** — a
  * K8s audit event's `user` block is exactly the "authenticated identity"
@@ -565,7 +570,10 @@ function parseK8sAuditLogObservations(text, context) {
     if (namespace && resource) attributes['destination.service'] = `${namespace}:${resource}`;
     else if (resource) attributes['destination.service'] = resource;
     if (typeof code === 'number' && Number.isFinite(code)) {
-      attributes['network.securityDecision'] = code < 400 ? 'allowed' : 'denied';
+      // 401 and 403 are the authentication and authorization outcomes. Any other client or server error (404 not found, 409 conflict,
+      // 422 invalid, 5xx) is an operational outcome and makes no claim, the same rule as the proxy adapters.
+      if (code < 400) attributes['network.securityDecision'] = 'allowed';
+      else if (code === 401 || code === 403) attributes['network.securityDecision'] = 'denied';
     }
 
     if (Object.keys(attributes).length === 0) continue;

package/dist/2946.index.js

@@ -43,7 +43,7 @@ function findTool(name, pathEnv = process.env.PATH || '') {
 }
 
 /** @param {{repository: string, digest: string, publicKeyPem?: string, certificateIdentity?: string, certificateOidcIssuer?: string}} o */
-async function verifyWithCosign({ repository, digest, publicKeyPem = null, certificateIdentity = null, certificateOidcIssuer = null, timeoutMs = 60_000, signal, pathEnv = process.env.PATH } = {}) {
+async function verifyWithCosign({ repository, digest, publicKeyPem = null, certificateIdentity = null, certificateOidcIssuer = null, ignoreTlog = false, timeoutMs = 60_000, signal, pathEnv = process.env.PATH } = {}) {
   const na = (reason) => ({ state: 'unavailable', via: 'cosign', reason });
   if (!DIGEST_RE.test(String(digest))) return na('there is no sha256 image digest to verify a signature against');
   if (!REPO_RE.test(String(repository ?? '')) || String(repository).includes('..') || String(repository).startsWith('-')) return na('the repository name is not valid');
@@ -56,6 +56,9 @@ async function verifyWithCosign({ repository, digest, publicKeyPem = null, certi
   try {
     const args = ['verify'];
     if (publicKeyPem) { const kf = node_path__WEBPACK_IMPORTED_MODULE_2__.join(dir, 'key.pub'); node_fs__WEBPACK_IMPORTED_MODULE_0__.writeFileSync(kf, publicKeyPem, { mode: 0o600 }); args.push('--key', kf); } else args.push('--certificate-identity', certificateIdentity, '--certificate-oidc-issuer', certificateOidcIssuer);
+    // cosign requires a transparency-log entry for a key-signed image unless told otherwise. A private registry or an air-gapped build has none, so
+    // this is an explicit opt-in, never the default, and a result that skipped the log says so. Keyless verification always needs the log.
+    if (ignoreTlog && publicKeyPem) args.push('--insecure-ignore-tlog=true');
     args.push(`${repository}@${digest}`);
     const r = await (0,_sandbox_supervise_js__WEBPACK_IMPORTED_MODULE_3__/* .superviseSpawn */ .u)(bin, args, { cwd: dir, env: (0,_sandbox_trust_domains_js__WEBPACK_IMPORTED_MODULE_4__/* .scrubEnv */ .LK)(process.env), timeoutMs, signal, maxOutputBytes: 2 * 1024 * 1024 });
     if (r.spawnError) return na(`could not start cosign: ${r.spawnError}`);
@@ -66,11 +69,11 @@ async function verifyWithCosign({ repository, digest, publicKeyPem = null, certi
       let payloads = [];
       try { const j = JSON.parse(r.stdout); payloads = Array.isArray(j) ? j : [j]; } catch { /* handled below */ }
       const matching = payloads.filter((p) => p?.critical?.image?.['docker-manifest-digest'] === digest);
-      if (matching.length) return { state: 'verified', via: 'cosign', mode: keyless ? 'keyless' : 'key', signatures: matching.length, identity: keyless ? certificateIdentity : null, reason: null };
+      if (matching.length) return { state: 'verified', via: 'cosign', mode: keyless ? 'keyless' : 'key', signatures: matching.length, identity: keyless ? certificateIdentity : null, reason: null, ...(ignoreTlog && !keyless ? { transparencyLog: 'not-checked' } : {}) };
       return { state: 'invalid', via: 'cosign', reason: 'cosign reported success but none of the verified signatures names this image digest' };
     }
-    if (/no signatures found|no matching signatures|no signatures associated|manifest unknown/.test(err)) return { state: 'missing', via: 'cosign', reason: 'no signature exists for this digest' };
     if (/invalid signature|signature verification failed|crypto\/ecdsa|verification failed|certificate identity|none of the expected identities/.test(err)) return { state: 'invalid', via: 'cosign', reason: 'cosign rejected the signature or the identity' };
+    if (/no signatures found|no matching signatures|no signatures associated|manifest unknown/.test(err)) return { state: 'missing', via: 'cosign', reason: 'no signature exists for this digest' };
     return na(`cosign could not complete the check (exit ${r.exitCode}): ${String(r.stderr).trim().split('\n').pop()?.slice(0, 160) ?? ''}`);
   } finally { try { node_fs__WEBPACK_IMPORTED_MODULE_0__.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } }
 }

package/dist/9382.index.js

@@ -1442,6 +1442,9 @@ const AUTH_NAME = /(?:^|[.:])(?:(?:require|ensure|check|assert|verify|validate|e
 
 const SENSITIVE_NAME = /(?:^|[.:])(?:query|queryOne|queryRow|exec|execute|executeQuery|raw|rawQuery|prepare|find|findAll|findOne|findById|findByPk|findUnique|findFirst|findMany|get|getById|getBy|select|selectList|selectFirst|insert|insertOne|insertMany|insert_|update|updateOne|updateMany|upsert|delete|deleteOne|deleteMany|remove|destroy|save|create|createMany|aggregate|runDB|writeFile|writeFileSync|appendFile|unlink|rm|rmdir|spawn|spawnSync|execSync|execFile|system|popen|fetch|request|post|put|patch)$/i;
 const DB_RECEIVER = /(?:^|\b)(?:db|database|conn|connection|pool|client|cursor|session|repo|repository|dao|model|models|collection|table|prisma|knex|sequelize|orm|store|objects|manager|em|entityManager|mongo|redis|cache|conn|stmt|statement|fs|child_process|cp|axios|http|https|requests|httpx|got|superagent|Database|Persist|Yesod|System)\b/;
+// Flask-SQLAlchemy `Model.query...`, SQLAlchemy `session.query/add/delete/merge/execute/get`, and the query-builder methods that end a chain.
+const PY_ORM = /(?:\b[A-Z]\w*\.query\b|\b(?:db\.)?session\.(?:query|add|add_all|delete|merge|execute|get|bulk_save_objects)\b|\.(?:filter_by|get_or_404|first_or_404|one_or_404)\()/;
+const PY_ORM_WRITE = /\.(?:delete|update|bulk_update_mappings|bulk_insert_mappings)\(|\b(?:db\.)?session\.(?:add|add_all|delete|merge|bulk_save_objects)\b/;
 const SQL_TEXT = /\b(?:select\s[\s\S]{1,120}\sfrom|insert\s+into|update\s+\w+\s+set|delete\s+from)\b/i;
 const HS_SENSITIVE = /(?:^|\.)(?:runDB|selectList|selectFirst|getBy|getJust|insert_?|insertEntity|update|updateWhere|delete|deleteWhere|replace|upsert|query|query_|execute|execute_|readFile|writeFile|callProcess|readProcess)$|^(?:Database\.|System\.Process\.|System\.Directory\.)/;
 
@@ -1601,6 +1604,18 @@ function analyzeSymbolText(symbol, lines, { haskell = false } = {}) {
         }
       }
     }
+    // Python ORM calls. `Model.query.filter_by(...).delete()` and `db.session.add(x)` name no database receiver the call-name rule
+    // recognises, and the chained `.delete()` is not a call on one, so the data operation was invisible and a route that
+    // deletes a row read as touching nothing sensitive. A write is a chained mutation or a session write; anything else is a read.
+    if (!haskell && PY_ORM.test(raw)) {
+      const orm = PY_ORM_WRITE.test(raw) ? 'write' : 'read';
+      push({ line: ln, category: 'sensitive', kind: `data-${orm}`, subkind: orm, evidence: 'observed', basis: 'orm-call', rejectionSeen: null, text: clip(raw) });
+      const stmt = statementAt(lines, ln);
+      const pr = ownerBinding(stmt, extraPrincipal);
+      if (pr) {
+        push({ line: ln, category: 'control', kind: pr.tenant ? 'tenant-scope' : 'ownership', subkind: null, evidence: pr.level === 'qualified' ? 'observed' : 'inferred', basis: pr.level === 'qualified' ? 'query-filter' : 'query-filter-unqualified', rejectionSeen: null, text: clip(raw) });
+      }
+    }
     if (SQL_TEXT.test(raw)) {
       const verb = /\b(?:insert|update|delete)\b/i.test(raw) ? 'write' : 'read';
       push({ line: ln, category: 'sensitive', kind: `data-${verb}`, subkind: verb, evidence: 'observed', basis: 'sql-text', rejectionSeen: null, text: clip(raw) });
@@ -3474,8 +3489,14 @@ function evaluateProtection({ facts, unknowns, omittedWithControls = false, capp
     const ctl = facts.filter(f => f.category === 'control' && kinds.includes(f.kind));
     // A control whose answer is visibly thrown away (a predicate called as a bare statement) guards nothing.
     const effective = (f) => f.rejectionSeen !== false;
-    const before = ctl.filter(f => effective(f) && (firstSens === null || f.effLine < firstSens || (f.basis === 'query-filter' && f.effLine <= firstSens)));
-    const after = ctl.filter(f => firstSens !== null && f.effLine > firstSens);
+    // Ownership is the one dimension where reading before checking is the ordinary safe shape: load the record by id, refuse unless the
+    // principal owns it, and only then act on it. What an unchecked read can do is bounded by the check that follows before anything is
+    // written, so for ownership and tenant scope the line that must be preceded is the first WRITE. With no write in view the first
+    // sensitive operation of any kind still applies, so a read returned without a check is not excused.
+    const writes = sens.filter(f => f.subkind === 'write' || f.kind === 'filesystem' || f.kind === 'process');
+    const gate = dim === 'ownership' && writes.length ? Math.min(...writes.map(f => f.effLine)) : firstSens;
+    const before = ctl.filter(f => effective(f) && (gate === null || f.effLine < gate || (f.basis === 'query-filter' && f.effLine <= gate)));
+    const after = ctl.filter(f => gate !== null && f.effLine > gate);
     let state; let why;
     if (before.length) { state = 'present'; why = 'a control precedes the first sensitive operation'; }
     else if (after.length) { state = 'evaluated_and_ineffective'; why = 'every control of this kind runs after the first sensitive operation'; }

package/dist/9579.index.js

@@ -271,8 +271,12 @@ async function runHunter(focusArea, lens, ctx = {}, opts = {}) {
   }
 
   const candidates = candidatesFromParsed(parsed, focusArea, lens);
-  appendEntry(transcript, { phase: 'result', candidateCount: candidates.length });
-  return { ...base, candidates, degraded: false, reason: null };
+  // A proposed candidate with no file and line has nowhere to point and is dropped; say how many, so a reply full of them
+  // does not read as a reply that found nothing.
+  const proposed = Array.isArray(parsed?.candidates) ? parsed.candidates.length : 0;
+  const discarded = proposed - candidates.length;
+  appendEntry(transcript, { phase: 'result', candidateCount: candidates.length, discarded });
+  return { ...base, candidates, degraded: false, reason: null, discarded };
 }
 
 // EXTERNAL MODULE: ./src/discovery/confirm.js
@@ -835,7 +839,9 @@ async function runDiscovery(ctx = {}, opts = {}) {
   const budget = makeBudget(opts);
   // PRD C4 — what previous runs already judged. scanRoot absent => no memory,
   // which is the correct default for a library call with nowhere to persist.
-  const memory = opts.scanRoot ? loadMemory(opts.scanRoot) : null;
+  let memory = opts.scanRoot ? loadMemory(opts.scanRoot) : null;
+  // `--forget-refuted`: a model, a ruleset or the code changed, so what an earlier run refuted is worth examining again.
+  if (memory && opts.forgetRefuted) memory = forgetRefuted(memory);
   // Every LLM call in this pipeline goes through this one wrapped callback.
   const llmInvoke = budget.wrap(opts.llmInvoke);
 
@@ -870,6 +876,7 @@ async function runDiscovery(ctx = {}, opts = {}) {
       const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {}, scanRoot: opts.scanRoot }, { llmInvoke, scanRoot: opts.scanRoot });
       runs.push({ focusAreaId: run.focusAreaId, lens: run.lens, degraded: run.degraded, reason: run.reason, candidateCount: run.candidates.length });
       if (run.degraded && run.reason) reasons.push(`${area.label} × ${lens.key}: ${run.reason}`);
+      if (run.discarded > 0) reasons.push(`${area.label} × ${lens.key}: ${run.discarded} proposed candidate(s) had no usable file and line and were discarded`);
       if (run.degraded) areaDegradedCount += 1;
       else hunted.add(area.id);
       candidates = candidates.concat(run.candidates);