@clear-capabilities/agentic-security-scanner 0.134.0 → 0.136.9

package/src/posture/reverse-blast-radius.js

@@ -96,7 +96,11 @@ export function annotateScaReverseBlast(findings, fileContents) {
   if (!Object.keys(map).length) return findings;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
-    const pkg = f.package || f.dependency || f.pkg;
+    // SCA findings (engine.js's queryOSV) carry the package name as `.name`
+    // — `.package`/`.dependency`/`.pkg` are never set anywhere in this
+    // codebase; kept as a fallback in case a caller supplies a differently-
+    // shaped finding.
+    const pkg = f.name || f.package || f.dependency || f.pkg;
     if (!pkg || !map[pkg]) continue;
     f.reverseExposure = {
       importerCount: map[pkg].directImporters.length,

package/src/posture/risk-dollars.js

@@ -23,8 +23,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
 
+import { statePath } from './state-dir.js';
 // Base rates per family (annual probability of at-least-one exploit given
 // an exposed instance). Rough industry estimates; tune via config.
 const FAMILY_BASE_PROB = {
@@ -79,7 +79,7 @@ const REACH_DISCOUNT = {
 };
 
 function _loadConfig(scanRoot) {
-  const fp = path.join(scanRoot, STATE, 'risk-config.yml');
+  const fp = statePath(scanRoot, 'risk-config.yml');
   if (!fs.existsSync(fp)) return null;
   try {
     const body = fs.readFileSync(fp, 'utf8');
@@ -110,8 +110,25 @@ function _impactFor(finding, cfg) {
   return table.default;
 }
 
+// SCA entries carry reachabilityTier/routeReachable (engine.js's SCA
+// reachability pass); SAST findings never do — they carry relevanceTier/
+// entrypointReachable instead (posture/relevance.js). Without this
+// fallback, _reachDiscount always read 'unknown' (0.3) for every SAST
+// finding, regardless of whether it was actually route-reachable.
+function _relevanceTierToReachTier(relevanceTier) {
+  switch (relevanceTier) {
+    case 'direct':      return 'route-reachable';
+    case 'indirect':    return 'function-reachable';
+    case 'unreachable': return 'unreachable';
+    default:            return null;
+  }
+}
+
 function _reachDiscount(finding) {
-  const tier = finding.reachabilityTier || finding.routeReachable && 'route-reachable' || 'unknown';
+  const tier = finding.reachabilityTier
+    || (finding.routeReachable && 'route-reachable')
+    || _relevanceTierToReachTier(finding.relevanceTier)
+    || 'unknown';
   return REACH_DISCOUNT[tier] || 0.3;
 }
 

package/src/posture/router.js

@@ -17,6 +17,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { stateDir, statePath } from './state-dir.js';
 function readJson(fp) {
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
@@ -32,7 +33,7 @@ function ageHours(fp) {
 // history to say anything honest. (premortem: never invent a trend from one
 // data point.)
 export function computeScanTrend(scanRoot) {
-  const hist = readJson(path.join(scanRoot, '.agentic-security', 'scan-history.json'));
+  const hist = readJson(statePath(scanRoot, 'scan-history.json'));
   if (!Array.isArray(hist) || hist.length < 2) return {};
   const cur = hist[hist.length - 1];
   const prev = hist[hist.length - 2];
@@ -55,9 +56,9 @@ export function decide(opts) {
 }
 
 function baseDecision({ scanRoot, intent }) {
-  const stateDir = path.join(scanRoot, '.agentic-security');
-  const lastScan = readJson(path.join(stateDir, 'last-scan.json'));
-  const scanAge = ageHours(path.join(stateDir, 'last-scan.json'));
+  const stateDirPath = stateDir(scanRoot);
+  const lastScan = readJson(path.join(stateDirPath, 'last-scan.json'));
+  const scanAge = ageHours(path.join(stateDirPath, 'last-scan.json'));
 
   if (!lastScan) {
     return {

package/src/posture/ruleset-version.js

@@ -25,14 +25,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { SCANNER_VERSION } from './version.js';
 
+import { statePath } from './state-dir.js';
 // Tied to scanner/package.json via posture/version.js — they cannot diverge
 // (premortem 3R1.3).
 export const CURRENT_RULESET_VERSION = SCANNER_VERSION;
 
-const FILE = '.agentic-security/ruleset-version.json';
 
 export function readPinned(scanRoot) {
-  const fp = path.join(scanRoot || process.cwd(), FILE);
+  const fp = statePath(scanRoot || process.cwd(), 'ruleset-version.json');
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
   catch { return null; }

package/src/posture/runtime-correlation.js

@@ -35,12 +35,13 @@ import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { createReadStream } from 'node:fs';
 
+import { statePath } from './state-dir.js';
 const DEFAULT_TRACE_NAMES = ['runtime-trace.jsonl', 'runtime.jsonl', 'ebpf-trace.jsonl'];
 const DEFAULT_OBSERVATION_WINDOW_DAYS = 30;
 
 export async function loadTrace(scanRoot, opts = {}) {
   const explicit = opts.tracePath || process.env.AGENTIC_SECURITY_RUNTIME_TRACE_PATH;
-  const candidates = explicit ? [explicit] : DEFAULT_TRACE_NAMES.map(n => path.join(scanRoot, '.agentic-security', n));
+  const candidates = explicit ? [explicit] : DEFAULT_TRACE_NAMES.map(n => statePath(scanRoot, n));
   let chosen = null;
   for (const c of candidates) {
     if (fs.existsSync(c)) { chosen = c; break; }

package/src/posture/sbom-diff.js

@@ -21,6 +21,7 @@
 // module produces the diff on the next scan.
 
 import * as fs from 'node:fs';
+import { statePath, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { execSync } from 'node:child_process';
@@ -28,7 +29,7 @@ import { execSync } from 'node:child_process';
 const HISTORY_DIR = 'sbom-history';
 
 function _historyDir(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', HISTORY_DIR);
+  return statePath(scanRoot, HISTORY_DIR);
 }
 
 function _gitHead(scanRoot) {
@@ -47,7 +48,11 @@ function _snapshotKey(component) {
  */
 export function persistSbom(scanRoot, components) {
   const dir = _historyDir(scanRoot);
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  // The mkdir is inside the switch too. Guarding only the write still left an
+  // empty `sbom-history/` in the scanned tree — invisible to `git status`,
+  // because git does not track empty directories, and therefore exactly the
+  // kind of mutation that passes a clean-status check while still being one.
+  if (stateWritesEnabled()) { try { fs.mkdirSync(dir, { recursive: true }); } catch {} }
   const sha = _gitHead(scanRoot) || crypto.createHash('sha256').update(JSON.stringify(components)).digest('hex').slice(0, 12);
   const snap = {
     sha, ts: new Date().toISOString(),
@@ -58,7 +63,11 @@ export function persistSbom(scanRoot, components) {
       sha256: c.sha256 || c.integrity || null,
     })),
   };
-  try { fs.writeFileSync(path.join(dir, `${sha}.json`), JSON.stringify(snap, null, 2)); } catch {}
+  // NON_MUTATING_SCAN_PRD S1 — history is a feature, but not at the cost of
+  // mutating a tree the caller only asked us to read.
+  if (stateWritesEnabled()) {
+    try { fs.writeFileSync(path.join(dir, `${sha}.json`), JSON.stringify(snap, null, 2)); } catch {}
+  }
   return snap;
 }
 

package/src/posture/sca-policy.js

@@ -40,6 +40,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 
+import { safeWriteState, stateDir, statePath } from './state-dir.js';
 const DEFAULT_POLICY = {
   acceptRisk: [],
   sla: {},
@@ -49,7 +50,7 @@ const DEFAULT_POLICY = {
 export function loadScaPolicy(scanRoot) {
   if (!scanRoot) return null;
   for (const name of ['sca-policy.yml', 'sca-policy.yaml', 'sca-policy.json']) {
-    const p = path.join(scanRoot, '.agentic-security', name);
+    const p = statePath(scanRoot, name);
     if (!fs.existsSync(p)) continue;
     try {
       const raw = fs.readFileSync(p, 'utf8');
@@ -183,7 +184,7 @@ export function applyScaPolicy(findings, policy, scanTime = new Date()) {
 // If the policy file doesn't exist, one is created with safe defaults.
 export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
   if (!scanRoot || !finding) return { ok: false, reason: 'missing arguments' };
-  const dir = path.join(scanRoot, '.agentic-security');
+  const dir = stateDir(scanRoot);
   const fp = path.join(dir, 'sca-policy.yml');
   let policy = loadScaPolicy(scanRoot);
   if (policy && policy._error) return { ok: false, reason: policy._error };
@@ -209,7 +210,6 @@ export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
   };
   policy.acceptRisk.push(newEntry);
 
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   const serialized = yaml.dump({
     'accept-risk': policy.acceptRisk.map(e => {
       const o = {};
@@ -224,7 +224,10 @@ export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
     sla: policy.sla && Object.keys(policy.sla).length ? Object.fromEntries(Object.entries(policy.sla).map(([k, v]) => [k, _formatSlaDuration(v)])) : undefined,
     'major-version-freeze': policy.majorVersionFreeze && Object.keys(policy.majorVersionFreeze).length ? policy.majorVersionFreeze : undefined,
   });
-  fs.writeFileSync(fp, serialized);
+  // Through the seam. This one is user-initiated (a triage decision), so a
+  // refusal is reported rather than swallowed: silently not recording an
+  // accepted risk would be worse than failing loudly. (PRD M1)
+  if (!safeWriteState(fp, serialized)) return { ok: false, reason: 'state writes disabled or path outside a project root', path: fp };
   return { ok: true, entry: newEntry, path: fp };
 }
 

package/src/posture/scan-checkpoint.js

@@ -43,6 +43,15 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+import { stateWritesEnabled } from './state-dir.js';
+
+// DELIBERATELY NOT routed through statePath(). `resolveProjectRoot()` falls
+// back to walking upward from process.cwd() when the given root does not exist
+// on disk, so `checkpointPath('/some/root')` resolved into the SCANNER'S OWN
+// SOURCE TREE — caught by the test that asserts a checkpoint is never written
+// there. A checkpoint must land in the root it was handed or nowhere; silently
+// relocating it into another directory is the exact failure this line of work
+// exists to prevent. The read-only switch above is still honoured.
 const STATE_DIR = '.agentic-security';
 const FILE_NAME = 'scan-checkpoint.jsonl';
 const FORMAT = 'agentic-security-scan-checkpoint/1';
@@ -191,6 +200,12 @@ function _recover(handle, file, runKey) {
  */
 export function openCheckpoint(scanRoot, { runKey } = {}) {
   if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+  // A read-only scan cannot checkpoint, and must not try. Resume is purely an
+  // optimisation — without it the scan recomputes, which is slower and
+  // identical — so `--no-state` wins over `AGENTIC_SECURITY_RESUME=1` rather
+  // than the two conflicting. The disabled handle no-ops through the rest of
+  // the API, so no caller needs a new branch. (PRD M1)
+  if (!stateWritesEnabled()) return _emptyHandle('state-writes-disabled');
   const handle = _emptyHandle(null);
   try {
     const dir = path.join(scanRoot, STATE_DIR);

package/src/posture/secret-history.js

@@ -31,17 +31,26 @@ export function scanHistoryDiff(diffText, commit, detectFn) {
   if (!added.trim()) return [];
   let findings = [];
   try { findings = detectFn(`git-history@${commit}`, added) || []; } catch { return []; }
-  return findings.map((f) => ({
-    ...f,
-    id: `secret-history:${commit}:${f.id || f.vuln || 'secret'}`,
-    file: `git-history@${commit}`,
-    line: 0,
-    commit,
-    _historical: true,
-    vuln: `${f.vuln || 'Hardcoded Secret'} (in git history)`,
-    description: `${f.description || 'A credential was committed.'} Found in commit ${commit}; even if removed from HEAD it remains recoverable from git and must be rotated.`,
-    remediation: 'Rotate the credential now, then purge it from history (git filter-repo / BFG) and move it to a secrets manager. Removing it from HEAD alone is insufficient.',
-  }));
+  return findings.map((f) => {
+    const remediation = 'Rotate the credential now, then purge it from history (git filter-repo / BFG) and move it to a secrets manager. Removing it from HEAD alone is insufficient.';
+    return {
+      ...f,
+      id: `secret-history:${commit}:${f.id || f.vuln || 'secret'}`,
+      file: `git-history@${commit}`,
+      line: 0,
+      commit,
+      _historical: true,
+      vuln: `${f.vuln || 'Hardcoded Secret'} (in git history)`,
+      description: `${f.description || 'A credential was committed.'} Found in commit ${commit}; even if removed from HEAD it remains recoverable from git and must be rotated.`,
+      remediation,
+      // report/index.js's _remediationOf checks `.fix` before `.remediation`
+      // — the underlying detector already set `.fix` to a generic "remove
+      // the line" string, which would otherwise silently shadow this
+      // history-specific instruction ("removing it from HEAD alone is
+      // insufficient") in every report format.
+      fix: remediation,
+    };
+  });
 }
 
 /**

package/src/posture/security-trend.js

@@ -35,7 +35,13 @@ function _snapshotFromScan(scan, label) {
     medium: findings.filter(f => f.severity === 'medium').length,
     low: findings.filter(f => f.severity === 'low').length,
     kev: findings.filter(f => f.kev).length,
-    ids: new Set(findings.map(f => f.id).filter(Boolean)),
+    // stable-id.js exists specifically because the default `id` embeds file
+    // path + line number, so any refactor that shifts a line rotates the id
+    // — using it here would report the same unfixed vulnerability as one
+    // "fixed" finding and one "introduced" finding on every such shift.
+    // stableId omits the exact line by design; fall back to `id` only for
+    // finding shapes that never got a stableId annotated.
+    ids: new Set(findings.map(f => f.stableId || f.id).filter(Boolean)),
   };
 }
 

package/src/posture/stack-playbook.js

@@ -185,6 +185,18 @@ function _buildPlaybook(stack) {
     ]});
   }
 
+  // Express
+  if (stack.has('express')) {
+    sections.push({ title: 'Express', items: [
+      'Use helmet() to set security headers (X-Frame-Options, X-Content-Type-Options, HSTS) — Express sets none of these by default',
+      'Never use body-parser / express.json() without a size limit — set `limit` explicitly to prevent request-body DoS',
+      'Apply express-rate-limit to authentication and any expensive routes',
+      'Validate and sanitize all req.params / req.query / req.body — Express does not validate input for you',
+      'Set `app.disable(\'x-powered-by\')` so error responses and headers do not advertise the framework/version to attackers',
+      'Use a CSRF middleware (e.g. csrf-csrf) on any route that relies on cookie-based sessions',
+    ]});
+  }
+
   // Django
   if (stack.has('django')) {
     sections.push({ title: 'Django', items: [
@@ -202,7 +214,16 @@ function _buildPlaybook(stack) {
 function _findingFromItem(scanRoot, stackName, item, idx) {
   return {
     id: `stack-playbook:${stackName.replace(/\s+/g, '_').toUpperCase()}:${idx}`,
-    title: `[${stackName} Security Checklist] ${item.slice(0, 80)}`,
+    // The findings schema requires `vuln` (root CLAUDE.md); this used to set
+    // `title` instead, which isn't a schema field at all. engine.js's generic
+    // no-vuln-name filter (`_shouldKeep`) treats any non-SCA finding with no
+    // `vuln` string as unenriched noise and drops it — silently, for every
+    // stack, confirmed live via a real scan whose logicVulns went from 6
+    // playbook findings right after they were pushed to 0 by the time the
+    // scan returned. `vuln` is now the actionable string this finding is
+    // actually about; `description`/`remediation` (already correct) keep
+    // the fuller text.
+    vuln: `[${stackName} Security Checklist] ${item.slice(0, 80)}`,
     severity: 'info',
     file: 'package.json',
     line: 1,

package/src/posture/state-dir.js

@@ -111,9 +111,42 @@ export function isSafeStateDir(dir) {
   return false;
 }
 
+// --- Read-only scanning (NON_MUTATING_SCAN_PRD S1) ---------------------------
+//
+// A scan is an OBSERVATION. Pointing the engine at a directory should not
+// change it. Until this switch existed, `scan .` wrote seven-plus files into the
+// scanned tree, which breaks CI that asserts a clean worktree, leaves artefacts
+// in third-party code the user does not own, and — measured on this project's
+// own benchmark — let a second scan read the first scan's conclusions as source.
+//
+// This is deliberately a KILL SWITCH AT THE SEAM rather than a parameter
+// threaded through 72 call sites. Threading it would mean 72 chances to forget,
+// and the module this lives in exists precisely because that kind of
+// per-caller discipline already failed once: its header records a user who
+// uninstalled the plugin after stray state directories broke their build.
+let _stateWritesEnabled = true;
+
+/** Turn all state writing off (or back on) for this process. */
+export function setStateWritesEnabled(enabled) {
+  _stateWritesEnabled = Boolean(enabled);
+}
+
+/**
+ * False when writing is disabled by the CLI flag or the environment.
+ *
+ * The env var is read at CALL time, not captured at import, so a test or a
+ * caller can set it after the module is loaded — the same mistake that made the
+ * gate verdict cache silently never engage.
+ */
+export function stateWritesEnabled() {
+  if (process.env.AGENTIC_SECURITY_NO_STATE === '1') return false;
+  return _stateWritesEnabled;
+}
+
 // Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
 // Returns the dir on success, null if refused. Logs a warning when refused.
 export function ensureStateDir(scanRoot) {
+  if (!stateWritesEnabled()) return null;
   const dir = stateDir(scanRoot);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
@@ -132,6 +165,7 @@ export function ensureStateDir(scanRoot) {
 // Safe write: only writes if isSafeStateDir(parent) returns true.
 // Returns true on success, false if refused or errored.
 export function safeWriteState(filePath, content) {
+  if (!stateWritesEnabled()) return false;
   const dir = path.dirname(filePath);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {

package/src/posture/telemetry-ingest.js

@@ -26,9 +26,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const CANDIDATE_PATHS = [
-  '.agentic-security/telemetry.json',
-  '.agentic-security/prod-telemetry.json',
+  'telemetry.json',
+  'prod-telemetry.json',
 ];
 
 const HOT_THRESHOLD = 1000;     // requests / window — promotes to hot
@@ -37,7 +38,7 @@ const COLD_THRESHOLD = 0;       // exactly zero requests → cold
 export function loadTelemetry(scanRoot) {
   const root = scanRoot || process.cwd();
   for (const rel of CANDIDATE_PATHS) {
-    const fp = path.join(root, rel);
+    const fp = statePath(root, rel);
     if (!fs.existsSync(fp)) continue;
     try {
       const data = JSON.parse(fs.readFileSync(fp, 'utf8'));

package/src/posture/threat-model-auto.js

@@ -23,6 +23,7 @@
 // .agentic-security/threat-model.md (human-readable).
 
 import * as fs from 'node:fs';
+import { stateDir, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 
 // STRIDE category descriptors
@@ -211,7 +212,9 @@ function _mid(id) { return String(id).replace(/[^A-Za-z0-9]/g, '_').slice(0, 60)
  * Persist threat model to disk: JSON for tooling, Markdown for review.
  */
 export function persistThreatModel(scanRoot, model) {
-  const dir = path.join(scanRoot, '.agentic-security');
+  // NON_MUTATING_SCAN_PRD S1 — a scan must not modify the tree it scans.
+  if (!stateWritesEnabled()) return;
+  const dir = stateDir(scanRoot);
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   try { fs.writeFileSync(path.join(dir, 'threat-model.json'), JSON.stringify(model, null, 2)); } catch {}
   try { fs.writeFileSync(path.join(dir, 'threat-model.md'), renderMarkdown(model)); } catch {}

package/src/posture/threat-model-grounding.js

@@ -13,14 +13,15 @@
 //     SOC2 / HIPAA / GDPR) adds compliance-tag fields to findings in
 //     matching families (PII → HIPAA/GDPR; auth → SOC2 CC6.1; etc.).
 //   - **Stated attacker** — "## Attacker model" / "## Threat actor"
-//     section sets f.attackerProfile = 'script-kiddie' | 'apt' | 'insider'
-//     for use in downstream prioritization.
+//     section sets f.threatModel.attacker = 'script-kiddie' | 'apt' |
+//     'insider' for use in downstream prioritization.
 //
 // Opt-out: AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING=1
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const DOC_PATHS = [
   'CLAUDE.md',
   'docs/THREAT-MODEL.md',
@@ -31,7 +32,16 @@ const DOC_PATHS = [
 ];
 
 function _readDoc(scanRoot, rel) {
-  try { return fs.readFileSync(path.join(scanRoot, rel), 'utf8'); } catch { return ''; }
+  // DOC_PATHS is a MIXED list: most entries are ordinary repository paths
+  // (CLAUDE.md, docs/THREAT-MODEL.md) and exactly one lives under the state
+  // directory. Routing the whole list through statePath() made every document
+  // resolve to `.agentic-security/<name>` and broke threat-model loading
+  // entirely — five tests caught it. Only the state entry uses the seam.
+  const STATE_PREFIX = '.agentic-security/';
+  const fp = rel.startsWith(STATE_PREFIX)
+    ? statePath(scanRoot, rel.slice(STATE_PREFIX.length))
+    : path.join(scanRoot, rel);
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return ''; }
 }
 
 function _allDocs(scanRoot) {

package/src/posture/time-to-fix.js

@@ -13,7 +13,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
+
+import { statePath } from './state-dir.js';
 const HISTORY_FILE = 'fix-history/log.json';
 
 // Family base estimates (hours). Tuned from typical patch shapes.
@@ -50,7 +51,7 @@ const FAMILY_BASE_HOURS = {
 };
 
 function _loadFixHistory(scanRoot) {
-  const fp = path.join(scanRoot, STATE, HISTORY_FILE);
+  const fp = statePath(scanRoot, HISTORY_FILE);
   if (!fs.existsSync(fp)) return [];
   try {
     const arr = JSON.parse(fs.readFileSync(fp, 'utf8'));

package/src/posture/triage-memory.js

@@ -21,11 +21,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE_DIR = '.agentic-security';
+import { stateDir, stateWritesEnabled } from './state-dir.js';
 const MEMORY_FILE = 'triage-memory.jsonl';
 const AGENTS_FILE = 'AGENTS.md';
 
-function _stateDir(scanRoot) { return path.join(scanRoot, STATE_DIR); }
+function _stateDir(scanRoot) { return stateDir(scanRoot); }
 function _memPath(scanRoot)  { return path.join(_stateDir(scanRoot), MEMORY_FILE); }
 function _agentsPath(scanRoot) { return path.join(_stateDir(scanRoot), AGENTS_FILE); }
 
@@ -43,6 +43,7 @@ function _bucketKey(finding) {
 export function recordDecision(scanRoot, finding, decision, reason) {
   if (!scanRoot || !finding || !decision) return null;
   if (!['wont-fix', 'false-positive'].includes(decision)) return null;
+  if (!stateWritesEnabled()) return false;
   try { fs.mkdirSync(_stateDir(scanRoot), { recursive: true }); } catch {}
 
   const entry = {

package/src/posture/validator-metrics.js

@@ -92,15 +92,22 @@ export function recordTriage(scanRoot, { family, verdict, stableId }) {
   const data = _read(scanRoot);
   data.productionTriage = data.productionTriage || {};
   const row = data.productionTriage[family] = data.productionTriage[family] || { tp: 0, fp: 0, wontfix: 0, lastAt: null };
+  void stableId;
+  // Already frozen from a previous call — `_capped: true` was persisted at
+  // the moment the cap was crossed (below), so this is a deliberate,
+  // visible freeze: nothing new is written, but nothing was silently lost
+  // either. Previously the crossing call itself never called _write, so
+  // `_capped` never reached disk and EVERY call after the cap — not just
+  // more of the same verdict, any verdict — silently vanished with the
+  // on-disk row frozen one write short of the real crossing point.
+  if (row._capped) return row;
   row[verdict] = (row[verdict] || 0) + 1;
   row.lastAt = new Date().toISOString();
   // Cap per-family rows so a runaway triage script can't bloat the file.
+  // The crossing call still writes — that's what makes the freeze visible.
   if ((row.tp || 0) + (row.fp || 0) + (row.wontfix || 0) > 10_000) {
-    // Stop accumulating; the trend is well-established by now.
     row._capped = true;
-    return row;
   }
-  void stableId;
   _write(scanRoot, data);
   return row;
 }