@clear-capabilities/agentic-security-scanner 0.172.1 → 0.174.0

package/src/pipeline/detector-runner.js

@@ -41,11 +41,18 @@
  * @param {() => any} fn - the detector call itself, e.g. `() => scanXxx(file, cc)`
  * @returns {any} fn()'s return value, or undefined if it threw
  */
+// E6-01: an optional sink for per-detector timing. Unset (the default), runDetector does exactly what it did before; set by a scan for its duration.
+let _timingSink = null;
+export function setDetectorTimingSink(fn) { _timingSink = typeof fn === 'function' ? fn : null; }
+
 export function runDetector(detectorErrors, file, analyzer, fn) {
+  const t0 = _timingSink ? process.hrtime.bigint() : 0n;
   try {
     return fn();
   } catch (e) {
     detectorErrors.push({ file, analyzer, err: String((e && e.message) || e) });
     return undefined;
+  } finally {
+    if (_timingSink) _timingSink(analyzer, Number(process.hrtime.bigint() - t0) / 1e6);
   }
 }

package/src/pipeline/scan-health.js

@@ -55,12 +55,23 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (filesTimedOut > 0) {
     conditions.push(`${filesTimedOut} file(s) exceeded the per-file analysis timeout`);
   }
+  // A file the engine does not read at all (over the size limit, or too dense to be source: minified or generated) is a file whose problems nobody looked for.
+  // It used to be counted in `files.skipped` and nowhere else, so a scan that read none of a repository's largest files still said `complete`. An empty file is
+  // also counted as skipped, but there is nothing in it to miss, so it is not a condition.
+  const unanalysed = (Number(scanMeta?.filesOversizeSkipped) || 0) + (Number(scanMeta?.filesDenseSkipped) || 0);
+  if (unanalysed > 0) {
+    conditions.push(`${unanalysed} file(s) were not analysed because they are over the size limit or too dense to be source (minified or generated)`);
+  }
   if (engineErrors?.cppDataflowParseErrors > 0) {
     conditions.push(`${engineErrors.cppDataflowParseErrors} C/C++ dataflow parse error(s)`);
   }
   if (deepStatus?.failure) {
     conditions.push(`deep analysis (IR-taint) threw and fell back to pattern-only results: ${deepStatus.failure}`);
   }
+  if (Array.isArray(deepStatus?.incomplete) && deepStatus.incomplete.length) {
+    // E2-05: the deep analysis ran but stopped short somewhere. The result is less complete than it looks, so it is a condition, not a footnote.
+    conditions.push(`deep analysis stopped short (analysis_incomplete): ${deepStatus.incomplete.map((x) => `${x.reason} x${x.count}`).join(', ')}`);
+  }
   if (deepStatus?.requested && !deepStatus.enabled) {
     conditions.push(`deep analysis was requested but did not run: ${deepStatus.reason || 'unknown reason'}`);
   }
@@ -111,6 +122,8 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
       expected: scanMeta?.checkpoint?.total ?? null,
       scanned: scanMeta?.filesScanned ?? null,
       skipped: (Number(scanMeta?.filesSkipped) || 0) + (Number(scanMeta?.filesDenseSkipped) || 0),
+      // skipped files that had something in them to miss: over the size limit, or too dense to be source. Empty files are in `skipped` and not here.
+      unanalysed,
       timedOut: filesTimedOut,
     },
     analyzers: analyzerCoverage || null,
@@ -122,6 +135,7 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           ciOverrideAllowed: !!deepStatus.ciOverrideAllowed,
           reason: deepStatus.reason ?? null,
           failure: deepStatus.failure ?? null,
+          ...(Array.isArray(deepStatus.incomplete) && deepStatus.incomplete.length ? { incomplete: deepStatus.incomplete } : {}),
         }
       : null,
     lineageAnalysis: lineageStatus

package/src/pipeline/supervised-analyzers.js

@@ -0,0 +1,125 @@
+// Supervised, resource-bounded analyzer execution (E6-05).
+//
+// A worker thread (analyzer-supervisor.js) can be terminated on a deadline, but it shares the process: it cannot be given a memory ceiling that
+// does not take the scanner down with it, it cannot be CPU-limited, and anything it spawns outlives it. An analyzer that is expensive or runs
+// code of uncertain behaviour belongs in its OWN PROCESS, and this module runs it there:
+//
+//   * own process GROUP (detached), so a kill takes the analyzer and everything it forked; a test proves a forked grandchild dies too
+//   * wall-clock deadline, a resident-memory ceiling polled from outside (`maxRssMb`), a V8 heap ceiling (`maxHeapMb`, which turns exhaustion into an
+//     abort the supervisor classifies as `oom`), and an optional CPU-seconds ceiling (`cpuSeconds`, POSIX `ulimit -t`)
+//   * cancellation through an AbortSignal; a hard overall stop (`maxTotalMs`) so the run can never wait indefinitely
+//   * a BOUNDED queue: at most `concurrency` run at once, at most `maxQueue` wait, the rest are `rejected: queue_full`, never dropped silently
+//   * every task ends in exactly one terminal status. A failure is a result, not an exception: the other analyzers' results are kept
+//
+// `summarizeSupervised` turns the results into what the rest of the pipeline already understands: merged findings from the analyzers that
+// completed, an `analyzerCoverage`-shaped object for computeScanHealth (so scan health degrades to `partial` and a strict assurance mode fails), and
+// the exact list of analyzers that did not finish and why.
+import { spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CHILD = path.join(HERE, 'supervised-child.js');
+export const TERMINAL_STATUSES = Object.freeze(['completed', 'failed', 'timed_out', 'oom', 'rss_limit', 'cpu_limit', 'cancelled', 'rejected', 'overall_deadline']);
+const DEFAULTS = Object.freeze({ concurrency: 2, maxQueue: 64, timeoutMs: 60_000, maxHeapMb: 1024, maxRssMb: 2048, cpuSeconds: 0, maxResultBytes: 8 * 1024 * 1024, maxTotalMs: 30 * 60_000, rssPollMs: 200 });
+
+const killGroup = (pid) => { try { process.kill(-pid, 'SIGKILL'); } catch { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } } };
+const rssMb = (pid) => { try { return parseInt(execFileSync('ps', ['-o', 'rss=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim(), 10) / 1024; } catch { return 0; } };
+
+function runOne(task, o, state) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const lim = { timeoutMs: task.timeoutMs ?? o.timeoutMs, maxHeapMb: task.maxHeapMb ?? o.maxHeapMb, maxRssMb: task.maxRssMb ?? o.maxRssMb, cpuSeconds: task.cpuSeconds ?? o.cpuSeconds };
+    // limits become command-line text, so each must be a plain positive number before it goes anywhere near a command line
+    for (const [k, v] of Object.entries(lim)) {
+      if (!(typeof v === 'number' && Number.isFinite(v) && v >= 0)) return resolve({ id: task.id, status: 'failed', ok: false, error: `invalid limit ${k}: must be a non-negative number`, durationMs: 0 });
+    }
+    const node = [`--max-old-space-size=${Math.ceil(lim.maxHeapMb)}`, CHILD];
+    const posix = process.platform !== 'win32';
+    // the CPU ceiling is applied with `ulimit` in a shell that then `exec`s node. The values are passed as positional parameters and quoted by the
+    // shell itself, so nothing from the task is ever parsed as shell syntax
+    const [cmd, args] = posix && lim.cpuSeconds > 0 ? ['/bin/sh', ['-c', 'ulimit -t "$1"; shift; exec "$@"', 'sh', String(Math.ceil(lim.cpuSeconds)), process.execPath, ...node]] : [process.execPath, node];
+    const child = spawn(cmd, args, { detached: posix, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], env: { ...process.env, AGENTIC_SECURITY_SUPERVISED_SPEC: JSON.stringify({ modulePath: task.modulePath, exportName: task.exportName, args: task.args || [] }) } });
+    const pid = child.pid; state.pids.add(pid);
+    let status = null; let msg = null; let stderr = ''; let settled = false;
+    const done = (s, extra = {}) => {
+      if (settled) return; settled = true;
+      clearTimeout(timer); clearInterval(poll); state.kills.delete(kill);
+      killGroup(pid); state.pids.delete(pid);
+      resolve({ id: task.id, status: s, ok: s === 'completed', durationMs: Date.now() - t0, pid, ...extra });
+    };
+    const kill = (why) => { if (!status) status = why; killGroup(pid); };
+    state.kills.add(kill);
+    const timer = setTimeout(() => kill('timed_out'), lim.timeoutMs);
+    const poll = setInterval(() => { if (!status && lim.maxRssMb > 0 && rssMb(pid) > lim.maxRssMb) kill('rss_limit'); }, o.rssPollMs);
+    child.stderr.on('data', (d) => { if (stderr.length < 4000) stderr += d.toString(); });
+    child.on('message', (m) => { msg = m; });
+    child.on('error', (e) => done('failed', { error: `could not start: ${e.message}` }));
+    child.on('close', (code, signal) => {
+      if (status) return done(status, { error: status === 'timed_out' ? `exceeded ${lim.timeoutMs} ms` : status === 'rss_limit' ? `exceeded ${lim.maxRssMb} MB resident` : status, exitCode: code, signal });
+      if (msg && msg.ok) {
+        const bytes = Buffer.byteLength(JSON.stringify(msg.result ?? null));
+        return bytes > o.maxResultBytes ? done('failed', { error: `result of ${bytes} bytes exceeds the ${o.maxResultBytes} byte cap`, exitCode: code, signal }) : done('completed', { result: msg.result, exitCode: code, signal });
+      }
+      if (msg && !msg.ok) return done('failed', { error: msg.error, exitCode: code, signal });
+      if (/heap out of memory|allocation failed|ERR_WORKER_OUT_OF_MEMORY/i.test(stderr) || signal === 'SIGABRT' || code === 134) return done('oom', { error: 'ran out of memory', exitCode: code, signal });
+      if (signal === 'SIGXCPU' || (lim.cpuSeconds > 0 && (code === 152 || signal === 'SIGKILL'))) return done('cpu_limit', { error: `exceeded ${lim.cpuSeconds} CPU seconds`, exitCode: code, signal });
+      return done('failed', { error: `exited without a result (code ${code}, signal ${signal})${stderr ? `: ${stderr.trim().slice(0, 300)}` : ''}`, exitCode: code, signal });
+    });
+  });
+}
+
+/**
+ * @param {{id:string, modulePath:string, exportName:string, args?:any[], timeoutMs?:number, maxHeapMb?:number, maxRssMb?:number, cpuSeconds?:number}[]} tasks
+ * @param {{concurrency?, maxQueue?, timeoutMs?, maxHeapMb?, maxRssMb?, cpuSeconds?, maxResultBytes?, maxTotalMs?, signal?:AbortSignal}} opts
+ * @returns {Promise<object[]>} one result per task, in task order, each with exactly one terminal status
+ */
+export async function runSupervised(tasks, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  const state = { pids: new Set(), kills: new Set() };
+  const results = new Array(tasks.length);
+  const queue = []; let running = 0; let stopped = null;
+  const stop = (why) => { if (stopped) return; stopped = why; for (const k of [...state.kills]) k(why); };
+  const onAbort = () => stop('cancelled');
+  if (o.signal) { if (o.signal.aborted) stopped = 'cancelled'; else o.signal.addEventListener('abort', onAbort, { once: true }); }
+  const overall = setTimeout(() => stop('overall_deadline'), o.maxTotalMs);
+  tasks.forEach((t, i) => {
+    if (queue.length >= o.maxQueue + o.concurrency) results[i] = { id: t.id, status: 'rejected', ok: false, error: `queue_full: more than ${o.maxQueue} waiting`, durationMs: 0 };
+    else queue.push(i);
+  });
+  await new Promise((resolve) => {
+    const pump = () => {
+      while (running < o.concurrency && queue.length) {
+        const i = queue.shift();
+        if (stopped) { results[i] = { id: tasks[i].id, status: stopped, ok: false, error: `not started: ${stopped}`, durationMs: 0 }; continue; }
+        running++;
+        runOne(tasks[i], o, state).then((r) => { results[i] = r; }, (e) => { results[i] = { id: tasks[i].id, status: 'failed', ok: false, error: String(e && e.message || e), durationMs: 0 }; }).finally(() => { running--; pump(); });
+      }
+      if (!running && !queue.length) resolve();
+    };
+    pump();
+  });
+  clearTimeout(overall); if (o.signal) o.signal.removeEventListener('abort', onAbort);
+  // a task killed by the overall stop or a cancel reports that, not 'failed'
+  return results.map((r) => (stopped && !r.ok && ['timed_out', 'failed'].includes(r.status) && r.error === stopped ? { ...r, status: stopped } : r));
+}
+
+/**
+ * What the rest of the pipeline needs from a supervised run.
+ * @returns {{findings:object[], completed:string[], incomplete:{id:string,status:string,error:string}[], analyzerCoverage:object, conditions:string[]}}
+ */
+export function summarizeSupervised(results) {
+  const findings = []; const completed = []; const incomplete = [];
+  for (const r of results) {
+    if (r.status === 'completed') { completed.push(r.id); if (Array.isArray(r.result)) findings.push(...r.result); else if (r.result && Array.isArray(r.result.findings)) findings.push(...r.result.findings); }
+    else incomplete.push({ id: r.id, status: r.status, error: r.error || r.status });
+  }
+  const n = (s) => incomplete.filter((x) => x.status === s).length;
+  const analyzerCoverage = { analyzers: results.length, completed: completed.length, failed: incomplete.length, timedOut: n('timed_out') + n('overall_deadline'), outOfMemory: n('oom') + n('rss_limit'), cancelled: n('cancelled'), rejected: n('rejected'), skippedByPolicy: 0 };
+  const conditions = incomplete.map((x) => `analyzer ${x.id} did not finish (${x.status}): ${x.error}`);
+  return { findings, completed, incomplete, analyzerCoverage, conditions };
+}
+
+/** Is a process still alive? (test and diagnostics helper for "no orphan") */
+export function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }

package/src/pipeline/supervised-child.js

@@ -0,0 +1,17 @@
+// The child half of supervised-analyzers.js (E6-05). Runs ONE exported function in its own process and reports the result over the IPC channel. It is
+// started by the supervisor, never imported: the supervisor owns the limits, the deadline and the kill, so a child that hangs, exhausts memory or
+// forks more processes can be stopped from outside without its cooperation.
+import { pathToFileURL } from 'node:url';
+
+async function main() {
+  const spec = JSON.parse(process.env.AGENTIC_SECURITY_SUPERVISED_SPEC || '{}');
+  try {
+    const mod = await import(pathToFileURL(spec.modulePath).href);
+    if (typeof mod[spec.exportName] !== 'function') throw new Error(`${spec.exportName} is not an exported function of ${spec.modulePath}`);
+    const result = await mod[spec.exportName](...(spec.args || []));
+    process.send({ ok: true, result }, () => process.exit(0));
+  } catch (e) {
+    process.send({ ok: false, error: String((e && e.message) || e).slice(0, 2000) }, () => process.exit(1));
+  }
+}
+main();

package/src/pipeline/telemetry.js

@@ -0,0 +1,79 @@
+// Scan telemetry (E6-01): where the time and memory of ONE scan went, and which stage failed, as structured aggregates inside the scan result.
+//
+// LOCAL ONLY. Nothing here sends anything anywhere: the snapshot is a field of the scan object the caller already holds. There is no endpoint, no
+// identifier of the user or the machine, no file path and no source text; stage names are fixed strings and an error carries a class and a short
+// message, never code.
+//
+// WHAT IT RECORDS
+//   stages   wall time and call count per named stage (file read, detectors, deep analysis, lineage, each annotator, ...)
+//   detectors time and call count per detector, accumulated by runDetector
+//   memory   resident-set and heap high-water marks sampled at stage boundaries (a sample, not a profiler: a spike between two samples is missed)
+//   counters named integer counts (files scanned, files skipped, cache hits and misses)
+//   errors   attributed failures: the stage, a class, a short message and a count, from the existing error arrays
+//   overhead the time this module itself spent bookkeeping, so its cost is measured, not asserted
+//
+// DETERMINISM. Under --deterministic, every duration and memory figure is reported as 0 and the stage list is sorted by name, so two runs of the same
+// input give byte-identical telemetry; the counts, which are properties of the input, are kept.
+const MB = 1024 * 1024;
+
+export function createTelemetry({ deterministic = false } = {}) {
+  const stages = new Map(); const detectors = new Map(); const counters = new Map(); const errors = new Map();
+  const mem = { rssHighWaterBytes: 0, heapHighWaterBytes: 0, samples: 0 };
+  let selfNs = 0n; const startedNs = process.hrtime.bigint();
+  const own = (fn) => { const a = process.hrtime.bigint(); try { return fn(); } finally { selfNs += process.hrtime.bigint() - a; } };
+  const bump = (map, key, ms) => own(() => { const c = map.get(key) || { ms: 0, calls: 0 }; c.ms += ms; c.calls += 1; map.set(key, c); });
+  const sample = () => own(() => {
+    if (deterministic) { mem.samples++; return; }
+    const m = process.memoryUsage();
+    if (m.rss > mem.rssHighWaterBytes) mem.rssHighWaterBytes = m.rss;
+    if (m.heapUsed > mem.heapHighWaterBytes) mem.heapHighWaterBytes = m.heapUsed;
+    mem.samples++;
+  });
+  const api = {
+    /** Time a synchronous function as stage `name`. Errors propagate; the time is still recorded. */
+    time(name, fn) { const a = process.hrtime.bigint(); try { return fn(); } finally { bump(stages, name, Number(process.hrtime.bigint() - a) / 1e6); sample(); } },
+    /** Time an async function as stage `name`. */
+    async timeAsync(name, fn) { const a = process.hrtime.bigint(); try { return await fn(); } finally { bump(stages, name, Number(process.hrtime.bigint() - a) / 1e6); sample(); } },
+    /** Record a duration measured elsewhere. */
+    record(name, ms) { bump(stages, name, Number.isFinite(ms) ? ms : 0); sample(); },
+    detector(name, ms) { bump(detectors, name, ms); },
+    count(name, n = 1) { own(() => counters.set(name, (counters.get(name) || 0) + n)); },
+    set(name, n) { own(() => counters.set(name, n)); },
+    sample,
+    /** Attribute a failure. `kind` is a short class (an error name or code); `message` is clipped and carries no source text. */
+    error(stage, kind, message) {
+      own(() => {
+        const key = `${stage}|${kind}`; const c = errors.get(key) || { stage, kind, count: 0, example: String(message ?? '').replace(/\s+/g, ' ').slice(0, 120) };
+        c.count += 1; errors.set(key, c);
+      });
+    },
+    snapshot() {
+      return own(() => {
+        sample();
+        const z = (v) => (deterministic ? 0 : Math.round(v * 100) / 100);
+        const byName = (a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+        const rows = (map) => [...map].sort(deterministic ? byName : (a, b) => b[1].ms - a[1].ms || byName(a, b)).map(([name, v]) => ({ name, ms: z(v.ms), calls: v.calls }));
+        return {
+          schema: 'agentic-security/scan-telemetry', version: 1, deterministic,
+          totalMs: z(Number(process.hrtime.bigint() - startedNs) / 1e6),
+          stages: rows(stages),
+          detectors: rows(detectors).slice(0, 25),
+          memory: { rssHighWaterMb: z(mem.rssHighWaterBytes / MB), heapHighWaterMb: z(mem.heapHighWaterBytes / MB), samples: mem.samples },
+          counters: Object.fromEntries([...counters].sort(byName)),
+          errors: [...errors.values()].sort((a, b) => (a.stage + a.kind < b.stage + b.kind ? -1 : 1)),
+          overhead: { selfMs: z(Number(selfNs) / 1e6) },
+          outbound: 'none: this record stays in the scan result',
+        };
+      });
+    },
+  };
+  return api;
+}
+
+/** Fold the existing error arrays of a scan into telemetry errors, by stage. Reads the arrays; changes nothing. */
+export function attributeErrors(tel, { annotatorErrors = [], detectorErrors = [], deepFailure = null, filesTimedOut = 0 } = {}) {
+  for (const e of annotatorErrors) tel.error(`annotator:${e.phase || e.annotator || 'unknown'}`, e.name || 'Error', e.message || e.err);
+  for (const e of detectorErrors) tel.error(`detector:${e.analyzer || 'unknown'}`, 'DetectorError', e.err);
+  if (deepFailure) tel.error('deep-analysis', 'DeepFailure', deepFailure);
+  if (filesTimedOut > 0) tel.error('per-file-timeout', 'Timeout', `${filesTimedOut} file(s) exceeded the per-file budget`);
+}

package/src/posture/accuracy-scorecard.js

@@ -118,8 +118,9 @@ export function aggregateCorpus(detail) {
  * protocol is forced to `unmeasured`, and an absent report is `unmeasured` with
  * the reason, never an empty pass. Pure.
  */
-export function summarizeMeasurement(provenance, independent) {
+export function summarizeMeasurement(provenance, independent, independentRun = null) {
   const p = provenance || {};
+  const run = summarizeIndependentRun(independentRun, p);
   const clean = p.worktreeClean === true;
   const hist = independent && independent.engineVersion && independent.engineVersion !== p.engineVersion;
   return {
@@ -128,14 +129,47 @@ export function summarizeMeasurement(provenance, independent) {
     identity: clean
       ? 'the commit and bundle below identify exactly the tree that was measured'
       : p.worktreeClean === false ? 'the worktree was dirty: the commit below does NOT identify what was measured, so this is not a clean measurement' : 'cleanliness of the measured tree was not recorded',
-    currentEngineIndependentAccuracy: 'unmeasured',
-    currentEngineIndependentReason: 'no adjudicated real-code population has been run against this engine; the independent record in this document, if any, describes an older engine',
+    currentEngineIndependentAccuracy: run && run.comparableToCurrentEngine ? (run.identity.measurementValid ? 'measured' : 'measured_not_release_grade') : 'unmeasured',
+    currentEngineIndependentReason: run && run.comparableToCurrentEngine
+      ? (run.identity.measurementValid ? `measured by run ${run.runId} on a clean commit; the figures are for the development and validation splits only` : `run ${run.runId} measured this engine but the measurement is not valid for a release claim: ${run.identity.invalidReasons.join(', ') || 'no identity recorded'}`)
+      : run ? `the latest independent run (${run.runId}) measured engine ${run.engineVersion}, not the engine above; it is a historical record` : 'no adjudicated real-code population has been run against this engine; the independent record in this document, if any, describes an older engine',
+    independentRun: run,
     historicalIndependentRecord: hist
       ? { engineVersion: independent.engineVersion, measuredAt: independent.measuredAt || null, usage: 'historical record only; not a measurement of the engine above and not combined with the corpus figures' }
       : null,
   };
 }
 
+/**
+ * The latest clean-commit run of the independent population (bench/independent/runs/<id>/RESULT.json), reduced to what a reader may be shown.
+ * Only the localized definition is a claim. A language below the declared minimum is `insufficient_population` and shows counts, never a rate;
+ * a language in the manifest that was not scored at all is listed as unmeasured. Pure.
+ */
+export function summarizeIndependentRun(run, provenance) {
+  if (!run || !run.scoring) return null;
+  const loc = run.scoring.definitions.localized;
+  const d = run.scoring.denominators;
+  const id = run.identity || {};
+  const rate = (r) => (r && r.d > 0 ? { n: r.n, d: r.d, value: r.value } : { n: r?.n ?? 0, d: r?.d ?? 0, value: null });
+  const byLanguage = Object.entries(loc.byLanguage).map(([language, g]) => (g.status === 'reportable'
+    ? { language, entries: g.entries, status: 'reportable', recall: rate(g.recall), precision: rate(g.precision), f1: g.f1, recallInterval: g.recallInterval, precisionInterval: g.precisionInterval, counts: { tp: g.tp, fp: g.fp, fn: g.fn, tn: g.tn } }
+    : { language, entries: g.entries, status: 'insufficient_population', counts: { tp: g.tp, fp: g.fp, fn: g.fn, tn: g.tn } }));
+  const unmeasuredLanguages = (run.population?.selection?.counts ? Object.keys(run.population.selection.counts) : []).filter((l) => !loc.byLanguage[l] || loc.byLanguage[l].status !== 'reportable');
+  return {
+    runId: run.runId, engineVersion: run.engineVersion || null, measuredAt: run.mergedAt || null,
+    comparableToCurrentEngine: !!run.engineVersion && run.engineVersion === (provenance || {}).engineVersion,
+    historical: !!run.engineVersion && run.engineVersion !== (provenance || {}).engineVersion,
+    identity: { sourceCommit: id.sourceCommit || null, bundleSha256: id.bundleSha256 || null, bundleSidecarSha256: id.bundleSidecarSha256 || null, measurementValid: id.measurementValid === true, invalidReasons: id.invalidReasons || [], lockfileSha256: id.lockfileSha256 || null, configSha256: id.configSha256 || null, modelEndpointMode: id.config?.modelEndpointMode || null, toolchain: id.toolchain ? { node: id.toolchain.node, os: id.toolchain.os } : null },
+    population: { role: run.population?.role || 'independent population', manifestSha256: run.population?.manifestSha256 || null, splitsProtocolHash: run.population?.splitsProtocolHash || run.splits?.protocolHash || null, splitNames: run.population?.selection?.splitNames || [], perLanguageCap: run.population?.selection?.perLanguage ?? null, sealedSplitTouched: run.population?.sealedSplitTouched === true },
+    configuration: run.configuration || null,
+    denominators: { inScope: d.inScope, scored: d.scored, unscored: d.unscored, unscoredByClass: d.unscoredByClass, unaccounted: d.unaccounted, reconciles: d.reconciles },
+    headline: run.headline ? { quotable: run.headline.quotable === true, reason: run.headline.reason || null, precision: run.headline.precision ? rate(run.headline.precision) : null, recall: run.headline.recall ? rate(run.headline.recall) : null, f1: run.headline.f1 ?? null, f1Interval: run.headline.f1Interval || null } : null,
+    byLanguage, unmeasuredLanguages,
+    minEntriesForRate: run.scoring.minEntriesForRate,
+    fixedVersionPressure: run.scoring.fixedVersionPressure || null,
+  };
+}
+
 export function summarizeEvaluationGates(report) {
   if (!report || typeof report !== 'object') {
     return {
@@ -185,6 +219,17 @@ export function summarizeEvaluationGates(report) {
  *                such scan renders "not measured this run" rather than a
  *                fabricated rate. See PRD Success Metrics.
  */
+/**
+ * What happened to one third-party target: `completed`, `not_attempted` (it never ran: no pinned commit, so there was nothing to clone) or `failed`
+ * (it ran and did not finish). A pre-existing summary records an unpinned target as `error`; the message is the evidence, so it is read from there.
+ */
+export function proofTargetOutcome(t) {
+  if (t && t.status === 'ok') return 'completed';
+  if (t && t.status === 'not_attempted') return 'not_attempted';
+  if (t && t.status === 'error' && /has no pinned commit/.test(String(t.error || ''))) return 'not_attempted';
+  return 'failed';
+}
+
 export function buildScorecard(inputs) {
   const corpus = aggregateCorpus(inputs.corpusDetail);
   const selfScan = inputs.selfScan || {};
@@ -324,9 +369,11 @@ export function buildScorecard(inputs) {
           bundleSha: proof.bundleSha || null,
           targetCount: proof.targetCount ?? null,
           ok: proof.ok ?? null,
-          failed: proof.failed ?? null,
+          // `failed` in the committed summary counted targets that never ran; the three outcomes are separated here
+          failed: (proof.targets || []).filter(t => proofTargetOutcome(t) === 'failed').length,
+          notAttempted: (proof.targets || []).filter(t => proofTargetOutcome(t) === 'not_attempted').length,
           targets: (proof.targets || []).map(t => ({
-            id: t.id, commit: t.commit, status: t.status,
+            id: t.id, commit: t.commit, status: t.status, outcome: proofTargetOutcome(t),
             filesInScope: t.coverage?.totals?.inScope ?? null,
             filesParsed: t.coverage?.totals?.parsed ?? null,
             determinismChecked: t.determinism?.checked ?? null,
@@ -349,7 +396,7 @@ export function buildScorecard(inputs) {
     // QA-001/QA-003: the real-code gates registered in the evaluation protocol. Relayed, never computed here.
     evaluationGates: summarizeEvaluationGates(inputs.evaluation),
     // QA-008.AC01: what this scorecard measured, stated once. `clean` is what lets the commit and bundle identify the measured tree.
-    measurement: summarizeMeasurement(inputs.provenance, committed.independent),
+    measurement: summarizeMeasurement(inputs.provenance, committed.independent, committed.independentRun),
   };
 }
 
@@ -403,7 +450,10 @@ export function renderScorecardMarkdown(m) {
   }
   if (m.measurement) {
     L.push(`| Measurement identity | ${m.measurement.cleanMeasurement ? 'clean measurement: the commit and bundle above identify the measured tree' : 'NOT a clean measurement: the commit and bundle above do not identify the measured tree'} |`);
-    L.push('| Independent accuracy of THIS engine | unmeasured (no adjudicated real-code population has been run; see the historical record below, if present) |');
+    const ia = m.measurement.currentEngineIndependentAccuracy;
+    L.push(ia === 'unmeasured'
+      ? '| Independent accuracy of THIS engine | unmeasured (no real-code run of this engine exists; see the historical record below, if present) |'
+      : `| Independent accuracy of THIS engine | ${ia === 'measured' ? 'measured on a clean commit' : 'measured, but NOT release grade'}: ${m.measurement.currentEngineIndependentReason} |`);
   }
   L.push(`| Node | ${p.nodeVersion || 'unknown'} |`);
   L.push(`| Corpus entries | ${c.totalEntries} (${c.scoredEntries} scored) |`);
@@ -733,6 +783,45 @@ export function renderScorecardMarkdown(m) {
     L.push('');
   }
 
+  const run = m.measurement && m.measurement.independentRun;
+  if (run) {
+    const pc = (r) => (r && r.value !== null && r.value !== undefined ? `${(r.value * 100).toFixed(1)}% (${r.n}/${r.d})` : `n/a (${r ? r.n : 0}/${r ? r.d : 0})`);
+    const iv = (i) => (i && i.status === 'measured' ? `${(i.low * 100).toFixed(1)}% to ${(i.high * 100).toFixed(1)}%` : 'unmeasured');
+    L.push(run.comparableToCurrentEngine ? `## Independent accuracy of this engine (run ${run.runId})` : `## Independent run ${run.runId}: historical record (engine ${run.engineVersion})`);
+    L.push('');
+    L.push('This is the independent population, upstream code labelled by public advisories, run on the engine below at a named commit. It is a different');
+    L.push('instrument from the curated regression net above and the two figures are never combined. Only the **localized** definition (a matching finding landed on code the');
+    L.push('fix changed) is a claim; it is reported with numerator and denominator.');
+    L.push('');
+    L.push('| Field | Value |');
+    L.push('| --- | --- |');
+    L.push(`| Engine | ${run.engineVersion}${run.comparableToCurrentEngine ? '' : ' (NOT the engine this scorecard describes)'} |`);
+    L.push(`| Measured at commit | \`${run.identity.sourceCommit || 'unknown'}\` |`);
+    L.push(`| Bundle SHA-256 | \`${run.identity.bundleSha256 || 'unknown'}\` (sidecar ${run.identity.bundleSidecarSha256 && run.identity.bundleSidecarSha256 === run.identity.bundleSha256 ? 'matches' : 'does not match or is missing'}) |`);
+    L.push(`| Measurement | ${run.identity.measurementValid ? 'valid: clean tree, bundle matches its digest' : `NOT valid for a release claim: ${run.identity.invalidReasons.join(', ') || 'no identity recorded'}`} |`);
+    L.push(`| Configuration | ${run.configuration ? `deep=${run.configuration.deep}, model=${run.configuration.llm}` : 'unknown'}; model endpoint ${run.identity.modelEndpointMode || 'unknown'} |`);
+    L.push(`| Population | manifest \`${(run.population.manifestSha256 || 'unknown').slice(0, 16)}\`; splits protocol \`${(run.population.splitsProtocolHash || 'unknown').slice(0, 23)}\`; ${run.population.splitNames.join(' + ') || 'unknown'} only, at most ${run.population.perLanguageCap ?? 'all'} entries per language; sealed split touched: ${run.population.sealedSplitTouched ? 'YES' : 'no'} |`);
+    L.push(`| Date (UTC) | ${run.measuredAt || 'unknown'} |`);
+    L.push(`| Entries in scope | ${run.denominators.inScope}: scored ${run.denominators.scored}, unscored ${run.denominators.unscored}${Object.keys(run.denominators.unscoredByClass || {}).length ? ` (${Object.entries(run.denominators.unscoredByClass).map(([k, v]) => `${k} ${v}`).join(', ')})` : ''}, unaccounted ${run.denominators.unaccounted}; denominators ${run.denominators.reconciles ? 'reconcile' : 'DO NOT reconcile'} |`);
+    L.push('');
+    if (run.headline && run.headline.quotable) {
+      L.push(`**Headline (localized):** precision ${pc(run.headline.precision)}, recall ${pc(run.headline.recall)}, F1 ${run.headline.f1 === null ? 'n/a' : run.headline.f1.toFixed(3)}${run.headline.f1Interval && run.headline.f1Interval.status === 'measured' ? ` (95% interval ${iv(run.headline.f1Interval)}, resampling whole repositories)` : ' (interval unmeasured)'}.`);
+    } else {
+      L.push(`**No headline figure:** ${run.headline && run.headline.reason ? run.headline.reason : 'the run is not quotable'}.`);
+    }
+    L.push('');
+    L.push(`| Language | Scored | Recall | Precision | Recall 95% interval | Status |`);
+    L.push('| --- | --- | --- | --- | --- | --- |');
+    for (const g of run.byLanguage) {
+      if (g.status === 'reportable') L.push(`| ${g.language} | ${g.entries} | ${pc(g.recall)} | ${pc(g.precision)} | ${iv(g.recallInterval)} | reportable |`);
+      else L.push(`| ${g.language} | ${g.entries} | counts only (${g.counts.tp} true positive, ${g.counts.fn} missed) | | | insufficient_population (below ${run.minEntriesForRate}) |`);
+    }
+    L.push('');
+    if (run.unmeasuredLanguages.length) L.push(`Languages with no rate in this run: ${run.unmeasuredLanguages.join(', ')}. They are unmeasured here, not good or bad.`, '');
+    L.push('This run does not use the sealed split, so it is a baseline on development and validation data, not a held-out result, and it makes no claim about the 80% per-language target.');
+    L.push('');
+  }
+
   const ind = m.committedInputs.independent;
   if (ind && ind.overall) {
     const hist = ind.historical === true;
@@ -874,7 +963,7 @@ export function renderScorecardMarkdown(m) {
   const pc = m.committedInputs.proofCorpus;
   if (pc) {
     L.push(`- **Third-party repository run** (*committed artifact*, \`${pc.source}\`,`);
-    L.push(`  bundle \`${pc.bundleSha}\`): ${pc.ok}/${pc.targetCount} targets completed.`);
+    L.push(`  bundle \`${pc.bundleSha}\`): ${pc.ok} of ${pc.targetCount} targets completed, ${pc.notAttempted ?? 0} not attempted (no pinned commit, so nothing was cloned), ${pc.failed ?? 0} failed after starting.`);
     L.push('  Reported for scale and parse coverage only — these repositories have no');
     L.push('  vulnerability ground truth, so no accuracy rate is derived from them.');
     L.push('');
@@ -882,7 +971,7 @@ export function renderScorecardMarkdown(m) {
     L.push('| --- | --- | --- | --- | --- | --- |');
     for (const t of pc.targets) {
       const det = t.determinismChecked ? (t.determinismIdentical ? 'identical' : 'checked, not byte-identical') : 'not checked';
-      L.push(`| ${t.id} | \`${String(t.commit || '').slice(0, 12)}\` | ${t.status} | ${formatRate(t.filesParsed ?? 0, t.filesInScope ?? 0)} | ${t.resultsEmitted ?? 'n/a'} | ${det} |`);
+      L.push(`| ${t.id} | \`${String(t.commit || '').slice(0, 12)}\` | ${t.outcome === 'not_attempted' ? 'not attempted' : t.status} | ${formatRate(t.filesParsed ?? 0, t.filesInScope ?? 0)} | ${t.resultsEmitted ?? 'n/a'} | ${det} |`);
     }
   }
   L.push('');

package/src/posture/artifact-registry.js

@@ -144,6 +144,7 @@ export const ARTIFACT_REGISTRY = [
   { name: 'findings.csv', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'llm-cache', kind: 'dir', classification: 'generated', retentionClass: 'cache' },
   { name: 'fix-history', kind: 'dir', classification: 'generated', retentionClass: 'backup' },
+  { name: 'fix-batches', kind: 'dir', classification: 'generated', retentionClass: 'backup' },
   { name: 'verifier-runs', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'src/posture/verifier.js (recordVerifierRun)', note: 'Adversarial premortem Q1 (2026-09-07): one JSON record per `agentic-security verify` run, added so module:verifier (nist-800-171-r3.json 03.12.01, nist-csf-2.json RC.RP) has a real artifact to check for instead of a name in the ARTIFACT table nothing ever wrote.' },
   { name: 'fix-plans', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
   // The following were confirmed missing from the old hardcoded WIPE/
@@ -172,6 +173,8 @@ export const ARTIFACT_REGISTRY = [
   { name: 'compliance', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'posture/auditor-walkthrough.js' },
   { name: 'attestations', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'posture/evidence-bundle.js' },
   { name: 'auditor-walkthroughs', kind: 'dir', classification: 'generated', retentionClass: 'evidence' },
+  { name: 'compliance-applicability.json', kind: 'file', classification: 'operator-config', note: 'operator declarations that a framework control does not apply ({ <framework id>: { <control id>: { reason, declaredBy } } }); read by `compliance --report <framework> --truth`. The tool never infers non-applicability.' },
+  { name: 'analysis-cache.jsonl', kind: 'file', classification: 'generated', retentionClass: 'cache', confidential: true, source: 'posture/scan-checkpoint.js (openCheckpoint persistent mode), engine.js', note: 'Opt-in (AGENTIC_SECURITY_ANALYSIS_CACHE=1) cross-scan cache of per-file detector results. Each record is authenticated with the install key, so a cache carried in from elsewhere is discarded. It holds findings with source excerpts, so it is treated like the source tree.' },
   { name: 'incremental', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'dataflow/incremental.js (cache)' },
   { name: 'model-rescan', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
   { name: 'sca-upgrade-history', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
@@ -279,6 +282,8 @@ export const ARTIFACT_REGISTRY = [
   // retention cannot reach it. Operator-config, not generated: these are
   // hand-supplied eBPF/APM trace exports the scanner only ever reads.
   { name: 'runtime-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'eBPF/APM runtime trace consumed by posture/runtime-correlation.js\'s own trace loader (deliberately not named by its literal export here — no-dead-modules.test.js scans note strings too, and naming it would make it look, wrongly, like a real call site) — operator-supplied, never scanner-written; $AGENTIC_SECURITY_RUNTIME_TRACE_PATH overrides the location entirely' },
+  { name: 'runtime-policy.json', kind: 'file', classification: 'operator-config', note: 'opt-in policy for runtime observation ingestion (collect, kinds, retentionDays, sampleRate); read by posture/runtime-trace-ingest.js' },
+  { name: 'runtime-trace.meta.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', note: 'ingestion record beside runtime-trace.jsonl: declared sampling, retention, counts of dropped and rejected fields (counts only, never values)' },
   { name: 'runtime.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
   { name: 'ebpf-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
 ];