@clear-capabilities/agentic-security-scanner 0.133.0 → 0.136.2

package/src/posture/compliance-policy.js

@@ -40,11 +40,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
+import { statePath, safeWriteState } from './state-dir.js';
 
 const POLICY_FILE = 'compliance.policy.yml';
 
 export function loadPolicy(scanRoot) {
-  const fp = path.join(scanRoot, '.agentic-security', POLICY_FILE);
+  const fp = statePath(scanRoot, POLICY_FILE);
   if (!fs.existsSync(fp)) return null;
   try {
     const raw = fs.readFileSync(fp, 'utf8');
@@ -105,7 +106,7 @@ function _runCheck(check, ctx) {
   }
   if (check['sca-policy-has-entry']) {
     const type = check['sca-policy-has-entry'];
-    const policyPath = path.join(ctx.scanRoot, '.agentic-security', 'sca-policy.yml');
+    const policyPath = statePath(ctx.scanRoot, 'sca-policy.yml');
     if (!fs.existsSync(policyPath)) return { passed: false, reason: 'sca-policy.yml not found' };
     try {
       const policy = yaml.load(fs.readFileSync(policyPath, 'utf8'));
@@ -178,10 +179,9 @@ export function emitEvidenceJsonLd(report, scanRoot) {
       narrative_evidence: c.evidence || [],
     })),
   };
-  try {
-    fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true });
-    fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'compliance-evidence.json'), JSON.stringify(jsonld, null, 2));
-  } catch {}
+  // Through the seam — see the note in pqc-migration-plan.js. The report is
+  // still returned when writing is off; only the artifact is withheld.
+  safeWriteState(statePath(scanRoot, 'compliance-evidence.json'), JSON.stringify(jsonld, null, 2));
   return jsonld;
 }
 
@@ -209,9 +209,7 @@ export function emitEvidenceMarkdown(report, scanRoot) {
     }
     lines.push('');
   }
-  try {
-    fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'compliance-evidence.md'), lines.join('\n'));
-  } catch {}
+  safeWriteState(statePath(scanRoot, 'compliance-evidence.md'), lines.join('\n'));
   return lines.join('\n');
 }
 

package/src/posture/custom-rules.js

@@ -33,6 +33,7 @@ import * as yaml from '../util/yaml.js';
 import { globFiles } from '../util/glob.js';
 import { loadTrustedKeys, verifyRulePack } from './rule-pack-signing.js';
 
+import { statePath, safeWriteState } from './state-dir.js';
 const LANG_EXTS = {
   javascript: ['.js', '.mjs', '.cjs', '.jsx'],
   typescript: ['.ts', '.tsx'],
@@ -48,7 +49,7 @@ const LANG_EXTS = {
 };
 
 function rulesDir(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'rules');
+  return statePath(scanRoot, 'rules');
 }
 
 export function loadCustomRules(scanRoot) {
@@ -318,10 +319,11 @@ export function applyCustomRules(scanRoot, fileContents) {
   }
   if (shadow.length) {
     try {
-      const stateDir = path.join(scanRoot, '.agentic-security');
-      fs.mkdirSync(stateDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(stateDir, 'shadow-findings.json'),
+      // Through the seam, so a read-only scan cannot leave shadow findings
+      // behind. Shadow rules are excluded from gates by design, which made this
+      // the least likely write for anyone to notice. (PRD M1)
+      safeWriteState(
+        statePath(scanRoot, 'shadow-findings.json'),
         JSON.stringify({ generatedAt: new Date().toISOString(), findings: shadow }, null, 2),
       );
     } catch { /* non-fatal */ }

package/src/posture/cve-alert-daemon.js

@@ -27,9 +27,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath, stateWritesEnabled } from './state-dir.js';
 const OSV_API = 'https://api.osv.dev/v1/query';
-const CFG_PATH = '.agentic-security/cve-alerts.json';
-const STATE_PATH = '.agentic-security/cve-alerts-state.json';
+
 
 // Multi-ecosystem dep extraction. Each entry: { manifest filename → ecosystem }
 const ECOSYSTEM_BY_MANIFEST = {
@@ -267,7 +267,7 @@ export async function _queryOsvForDep({ name, ecosystem }, { fetchImpl = globalT
 // ─── State persistence ───────────────────────────────────────────────────
 
 export function loadState(scanRoot) {
-  const fp = path.join(scanRoot, STATE_PATH);
+  const fp = statePath(scanRoot, 'cve-alerts-state.json');
   if (!fs.existsSync(fp)) return { known: new Set(), lastRun: null };
   try {
     const j = JSON.parse(fs.readFileSync(fp, 'utf8'));
@@ -276,7 +276,8 @@ export function loadState(scanRoot) {
 }
 
 export function persistState(scanRoot, state) {
-  const fp = path.join(scanRoot, STATE_PATH);
+  const fp = statePath(scanRoot, 'cve-alerts-state.json');
+  if (!stateWritesEnabled()) return;
   fs.mkdirSync(path.dirname(fp), { recursive: true });
   fs.writeFileSync(fp, JSON.stringify({
     known: [...state.known].sort(),
@@ -285,7 +286,7 @@ export function persistState(scanRoot, state) {
 }
 
 export function loadConfig(scanRoot) {
-  const fp = path.join(scanRoot, CFG_PATH);
+  const fp = statePath(scanRoot, 'cve-alerts.json');
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
 }

package/src/posture/dep-add-guard.js

@@ -19,6 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const CACHE = path.join(process.env.HOME || '/tmp', '.claude', 'agentic-security', 'osv-cache');
 const TYPOSQUAT_LEVENSHTEIN = 2;
 const NEW_PACKAGE_WINDOW_DAYS = 7;
@@ -61,7 +62,7 @@ function _loadPopular(ecosystem) {
 }
 
 function _loadPolicy(scanRoot) {
-  const fp = path.join(scanRoot, '.agentic-security', 'sca-policy.yml');
+  const fp = statePath(scanRoot, 'sca-policy.yml');
   if (!fs.existsSync(fp)) return { deny: [] };
   try {
     const body = fs.readFileSync(fp, 'utf8');

package/src/posture/deterministic.js

@@ -16,6 +16,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { PACKS } from './rule-packs.js';
 
+import { stateDir, statePath } from './state-dir.js';
 export const SCANNER_VERSION = '0.39.2';
 const LOCK_FILE = 'rules.lock.json';
 
@@ -40,7 +41,7 @@ export function buildLockfile() {
 }
 
 export function writeLockfile(scanRoot) {
-  const dir = path.join(scanRoot, '.agentic-security');
+  const dir = stateDir(scanRoot);
   fs.mkdirSync(dir, { recursive: true });
   const fp = path.join(dir, LOCK_FILE);
   const lock = buildLockfile();
@@ -49,7 +50,7 @@ export function writeLockfile(scanRoot) {
 }
 
 export function readLockfile(scanRoot) {
-  const fp = path.join(scanRoot, '.agentic-security', LOCK_FILE);
+  const fp = statePath(scanRoot, LOCK_FILE);
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
 }

package/src/posture/evidence-bundle.js

@@ -0,0 +1,246 @@
+// Per-finding evidence bundles, signed so a THIRD PARTY can verify them.
+// PRD Phase 2 / D2.
+//
+// WHAT WAS MISSING
+// ----------------
+// `attestation.js` already turns a run into a checkable digest, and it is
+// explicit about its own ceiling: the signature is a per-install SYMMETRIC HMAC,
+// so it is "tamper-evidence for the operator, not third-party non-repudiation."
+// Anyone who can verify it can also forge it. That is fine for detecting local
+// corruption and useless for handing a finding to somebody else.
+//
+// This module closes that gap for the artefact that actually travels: a single
+// finding plus the evidence behind it. A buyer, an auditor, or a downstream
+// consumer can check the bundle with the PUBLIC key alone, having never had
+// access to ours.
+//
+// WHY A SEPARATE MODULE RATHER THAN EXTENDING attestation.js
+// ----------------------------------------------------------
+// They answer different questions and must not be conflated. A run attestation
+// says "this set of findings came from this engine, ruleset and bundle". An
+// evidence bundle says "THIS finding is backed by THIS evidence, and here is
+// proof the claim was not edited after the fact." One is about reproducibility,
+// the other about portability. Merging them would produce an artefact that is
+// worse at both.
+//
+// WHAT A BUNDLE PROVES, AND WHAT IT DOES NOT
+// -------------------------------------------
+// PROVES — the bundle's contents are exactly what the holder of the signing key
+// attested, unmodified. Nothing in it has been added, removed, or edited since.
+//
+// DOES NOT PROVE — that the finding is real. A signature is an integrity claim,
+// never a correctness claim. An `unproven` finding in a signed bundle is still
+// an unproven finding; the signature only stops someone silently upgrading the
+// word `unproven` to `execution-proven` in transit. Both statements are carried
+// INSIDE the bundle so they travel with it and cannot be dropped by a
+// summariser.
+//
+// The evidence chain is deliberately the honest one this engine already
+// computes: the proof tier, what the sandbox observed, which backend ran it, the
+// taint path if there is one. A bundle for a regex finding says so plainly
+// rather than dressing it up.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+
+export const BUNDLE_SCHEMA = 'agentic-security/finding-evidence@1';
+
+/** Where the Ed25519 signing key lives. Mirrors integrity.js's key handling. */
+function keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'agentic-security');
+}
+const PRIVATE_KEY_FILE = 'attest-key.pem';
+const PUBLIC_KEY_FILE = 'attest-key.pub.pem';
+
+export function keyPaths(dir = keyDir()) {
+  return {
+    privateKey: path.join(dir, PRIVATE_KEY_FILE),
+    publicKey: path.join(dir, PUBLIC_KEY_FILE),
+  };
+}
+
+/**
+ * Load the signing key pair, generating one on first use.
+ *
+ * Ed25519 from node:crypto — no new dependency, and deliberately not a
+ * transparency-log scheme: those need a network round trip, and this project
+ * does not make runtime cloud calls. A log-backed option can layer on later
+ * without changing the bundle format.
+ */
+export function ensureKeyPair(dir = keyDir()) {
+  const p = keyPaths(dir);
+
+  // NO existsSync-then-read. This project's own scanner flagged the first
+  // version of this function for TOCTOU (CWE-367) and it was right: between an
+  // existence check and the read, an attacker who can write this directory can
+  // swap the file, and the thing being swapped is a SIGNING KEY. Winning that
+  // race means we sign with a key the attacker controls, which defeats the
+  // entire point of the module. Read first and treat absence as the exceptional
+  // case — there is then no window between the check and the use, because there
+  // is no check.
+  try {
+    const privateKeyPem = fs.readFileSync(p.privateKey, 'utf8');
+    const publicKeyPem = fs.readFileSync(p.publicKey, 'utf8');
+    if (privateKeyPem && publicKeyPem) {
+      return { privateKeyPem, publicKeyPem, created: false, ...p };
+    }
+  } catch { /* missing or unreadable — fall through and generate */ }
+
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' });
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  // `wx` — exclusive create. If another process generated a key between our
+  // failed read and this write, we must NOT clobber it: every bundle already
+  // signed with that key would silently stop verifying. On collision, re-read
+  // and use the winner's key.
+  try {
+    fs.writeFileSync(p.privateKey, privateKeyPem, { mode: 0o600, flag: 'wx' });
+    fs.writeFileSync(p.publicKey, publicKeyPem, { mode: 0o644, flag: 'w' });
+    return { privateKeyPem, publicKeyPem, created: true, ...p };
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    return {
+      privateKeyPem: fs.readFileSync(p.privateKey, 'utf8'),
+      publicKeyPem: fs.readFileSync(p.publicKey, 'utf8'),
+      created: false,
+      ...p,
+    };
+  }
+}
+
+/**
+ * Canonical bytes for signing.
+ *
+ * An ALLOWLIST, exactly as attestation.js canonicalises: a field that is not
+ * named here is not signed, so a future addition cannot silently enter the
+ * signed surface. Sorted keys, so serialisation order cannot change the
+ * signature.
+ */
+export function canonicalBytes(bundle) {
+  const signed = {
+    schema: bundle.schema,
+    finding: bundle.finding,
+    evidence: bundle.evidence,
+    engine: bundle.engine,
+    proves: bundle.proves,
+    doesNotProve: bundle.doesNotProve,
+  };
+  return Buffer.from(canonicalJson(signed), 'utf8');
+}
+
+/**
+ * Deterministic JSON: keys sorted at EVERY level, arrays order-preserving.
+ *
+ * Written by hand rather than using JSON.stringify's replacer argument, and the
+ * reason matters. The first version of this function did
+ * `JSON.stringify(signed, Object.keys(signed).sort())`, believing the array
+ * argument was a top-level field allowlist. It is not — a replacer ARRAY is a
+ * key filter applied at every nesting depth, so every nested object serialised
+ * as `{}` and the signature covered nothing but the two prose strings. A bundle
+ * whose severity was edited from `high` to `critical` verified as authentic.
+ *
+ * That is the worst possible failure for this module: a security feature that
+ * appears to work, produces a valid-looking signature, and protects nothing. It
+ * was caught by tampering with a bundle and expecting verification to fail —
+ * which is why the tamper cases in the test file are not optional extras.
+ */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+const PROVES =
+  'The contents of this bundle are exactly what the signer attested, unmodified.';
+const DOES_NOT_PROVE =
+  'That the finding is real. A signature is an integrity claim, never a correctness ' +
+  'claim — read `evidence.proofTier` for how well-supported the finding actually is. ' +
+  'An unproven finding in a signed bundle is still an unproven finding.';
+
+/**
+ * Build an unsigned bundle from a finding.
+ *
+ * Everything here is copied from what the engine already computed. Nothing is
+ * inferred, and a missing field stays missing rather than being defaulted into
+ * something more confident-looking than the truth.
+ */
+export function buildEvidenceBundle(finding, { engineVersion, rulesetVersion, bundleSha, commit } = {}) {
+  if (!finding || typeof finding !== 'object') return null;
+  return {
+    schema: BUNDLE_SCHEMA,
+    finding: {
+      id: finding.id ?? null,
+      stableId: finding.stableId ?? null,
+      severity: finding.severity ?? null,
+      file: finding.file ?? null,
+      line: finding.line ?? null,
+      vuln: finding.vuln ?? null,
+      cwe: finding.cwe ?? null,
+      family: finding.family ?? null,
+      parser: finding.parser ?? null,
+    },
+    evidence: {
+      // The honest chain, in the vocabulary the engine already uses.
+      proofTier: finding.proofTier ?? null,
+      proofEvidence: finding.proofEvidence ?? null,
+      confidence: finding.confidence ?? null,
+      exploitability: finding.exploitability ?? null,
+      unreachable: finding.unreachable ?? null,
+      // Present only for the layers that produce them; absent means absent.
+      taintPath: finding.pathSteps ?? finding.exampleFlows ?? null,
+      discovery: finding.discovery ?? null,
+    },
+    engine: {
+      engineVersion: engineVersion ?? null,
+      rulesetVersion: rulesetVersion ?? null,
+      bundleSha: bundleSha ?? null,
+      commit: commit ?? null,
+    },
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+}
+
+/** Sign a bundle. Returns a new object; the input is not mutated. */
+export function signEvidenceBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, canonicalBytes(bundle), privateKeyPem);
+  return {
+    ...bundle,
+    signature: {
+      algorithm: 'ed25519',
+      canonicalisation: BUNDLE_SCHEMA,
+      value: sig.toString('base64'),
+    },
+  };
+}
+
+/**
+ * Verify a bundle with a PUBLIC key. This is the whole point: the verifier
+ * never needs, and never had, the signing key.
+ *
+ * Returns {ok, reason}. Never throws — a malformed bundle from an untrusted
+ * source is an expected input, not an exceptional one.
+ */
+export function verifyEvidenceBundle(bundle, publicKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  let ok = false;
+  try {
+    ok = crypto.verify(null, canonicalBytes(bundle), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+}

package/src/posture/execution-proof.js

@@ -51,7 +51,31 @@ function _materialise(root, files) {
  *   patch: pass the patched contents and a still-`execution-proven` verdict
  *   means the fix did not close the hole.
  */
-export async function proveFinding(finding, { timeoutMs = 10000, force, files } = {}) {
+// How long a proof-of-concept gets to write its marker.
+//
+// WHY THIS IS GENEROUS, AND WHY THAT IS NEARLY FREE. The budget is only ever
+// spent when a PoC is stuck: a working one writes its marker and exits in about
+// a second, so raising the ceiling costs nothing in the common path. What a
+// tight ceiling DOES cost is correctness — the budget covers spawning a
+// confined process and starting a Node runtime inside it, and on a loaded
+// machine that alone can eat several seconds. At 10s this timed out under
+// ordinary parallel test load and reported "re-verification did not execute",
+// which the release gate then surfaced as a failure. The measurement has to be
+// of the proof-of-concept, not of how busy the machine happened to be.
+//
+// A timeout is still never evidence about the finding: `proven` is decided by
+// the marker file, and a timed-out run falls back to the finding's static tier
+// rather than claiming `proof-failed`. This ceiling only decides how long we
+// wait before giving up, not what we conclude.
+//
+// Override on a slow or heavily-loaded runner, matching the convention used by
+// AGENTIC_SECURITY_PY_PROBE_TIMEOUT_MS and AGENTIC_SECURITY_DEEP_TIMEOUT_MS.
+export const DEFAULT_PROOF_TIMEOUT_MS =
+  Number(process.env.AGENTIC_SECURITY_PROOF_TIMEOUT_MS) > 0
+    ? Number(process.env.AGENTIC_SECURITY_PROOF_TIMEOUT_MS)
+    : 45000;
+
+export async function proveFinding(finding, { timeoutMs = DEFAULT_PROOF_TIMEOUT_MS, force, files } = {}) {
   const poc = finding?.poc;
   if (!poc?.code) {
     return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: 'no proof-of-concept attached' }));

package/src/posture/exploitability-probability.js

@@ -35,6 +35,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { wilsonInterval } from './calibration.js';
 
+import { statePath } from './state-dir.js';
 // CISA KEV-derived base rate per CWE family. These are rough mid-2025
 // observations of "actually exploited in the wild" rates among findings
 // of the family, not academic numbers. Refresh annually.
@@ -138,7 +139,7 @@ function _clamp01(x) { return Math.max(0.001, Math.min(0.999, x)); }
 // (cwe × language × framework) grain.
 function _loadHistory(scanRoot) {
   if (!scanRoot) return [];
-  const fp = path.join(scanRoot, '.agentic-security', 'exploit-history.jsonl');
+  const fp = statePath(scanRoot, 'exploit-history.jsonl');
   if (!fs.existsSync(fp)) return [];
   const out = [];
   try {

package/src/posture/feature-flags.js

@@ -21,6 +21,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const FLAG_PATTERNS = [
   // LaunchDarkly
   [/\bldClient\.variation\s*\(\s*['"`]([^'"`]+)['"`]/g, 'launchdarkly'],
@@ -44,8 +45,8 @@ const FLAG_PATTERNS = [
 
 function loadRollouts(scanRoot) {
   const candidates = [
-    '.agentic-security/feature-flag-rollouts.json',
-    '.agentic-security/feature-flags.json',
+    'feature-flag-rollouts.json',
+    'feature-flags.json',
   ];
   for (const rel of candidates) {
     const fp = path.join(scanRoot || process.cwd(), rel);

package/src/posture/findings-memory.js

@@ -15,10 +15,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
 
+import { statePath } from './state-dir.js';
 function _read(scanRoot, name) {
-  try { return fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8'); } catch { return null; }
+  try { return fs.readFileSync(statePath(scanRoot, name), 'utf8'); } catch { return null; }
 }
 
 function _readJson(scanRoot, name) {
@@ -99,7 +99,7 @@ export function queryFindingsMemory(scanRoot, query) {
 
   // 3. Scan history.
   try {
-    const histDir = path.join(scanRoot, STATE, 'scan-history');
+    const histDir = statePath(scanRoot, 'scan-history');
     if (fs.existsSync(histDir)) {
       const files = fs.readdirSync(histDir).filter(f => f.endsWith('.json')).slice(-10);
       for (const f of files) {

package/src/posture/fix-history.js

@@ -12,7 +12,7 @@ import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { isSafeStateDir, statePath } from './state-dir.js';
+import { isSafeStateDir, statePath, stateWritesEnabled } from './state-dir.js';
 
 function historyDir(scanRoot) {
   return statePath(scanRoot, 'fix-history');
@@ -20,6 +20,9 @@ function historyDir(scanRoot) {
 function logPath(scanRoot) { return path.join(historyDir(scanRoot), 'log.json'); }
 
 function ensure(scanRoot) {
+  // Read-only scan: callers already treat `false` as "history unavailable",
+  // so the switch needs no new branch anywhere else.
+  if (!stateWritesEnabled()) return false;
   const dir = historyDir(scanRoot);
   if (!isSafeStateDir(path.dirname(dir))) return false;
   fs.mkdirSync(dir, { recursive: true });
@@ -65,7 +68,7 @@ function sha(s) { return crypto.createHash('sha256').update(s).digest('hex').sli
 // findings by `id` (the finding's canonical key from the engine) so we can
 // stash the corresponding stableId on the fix entry and verify in recover().
 function _lastScanPath(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  return statePath(scanRoot, 'last-scan.json');
 }
 function _readLastScan(scanRoot) {
   const fp = _lastScanPath(scanRoot);

package/src/posture/fix-metrics.js

@@ -34,9 +34,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isSafeStateDir } from './state-dir.js';
+import { isSafeStateDir, stateDir, statePath, stateWritesEnabled } from './state-dir.js';
 
-const STATE_DIR = '.agentic-security';
 const LOG_FILE = 'fix-metrics.jsonl';
 
 // Below this many samples a percentile is an artifact of the sample, not a
@@ -49,7 +48,7 @@ const RELIABLE_N = 10;
 export const FIX_STAGES = Object.freeze(['rescan', 'lint', 'tests', 'honesty', 'poc']);
 
 function _logPath(scanRoot) {
-  return path.join(scanRoot, STATE_DIR, LOG_FILE);
+  return statePath(scanRoot, LOG_FILE);
 }
 
 /**
@@ -61,9 +60,10 @@ function _logPath(scanRoot) {
 export function recordFixAttempt(scanRoot, record) {
   if (!scanRoot || !record || typeof record !== 'object') return false;
   try {
-    const dir = path.join(scanRoot, STATE_DIR);
+    const dir = stateDir(scanRoot);
     if (!isSafeStateDir(dir)) return false;
-    fs.mkdirSync(dir, { recursive: true });
+    if (!stateWritesEnabled()) return;
+  fs.mkdirSync(dir, { recursive: true });
     // One writeSync of one newline-terminated line: a concurrent reader sees
     // whole records or nothing, and a torn tail is dropped on read.
     fs.appendFileSync(_logPath(scanRoot), JSON.stringify(record) + '\n', 'utf8');

package/src/posture/fix-plan.js

@@ -12,6 +12,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const MAX_FILES = 3;
 const MAX_LOC   = 100;
 
@@ -103,7 +104,7 @@ export function renderFixPlan(finding, opts = {}) {
 // Returns the absolute path of the written file, or null on error.
 export function emitFixPlanFile(scanRoot, finding, opts = {}) {
   if (!scanRoot || !finding) return null;
-  const dir = path.join(scanRoot, '.agentic-security', 'fix-plans');
+  const dir = statePath(scanRoot, 'fix-plans');
   try { fs.mkdirSync(dir, { recursive: true }); } catch { return null; }
   const id = finding.stableId || finding.id || `unknown-${Date.now().toString(36)}`;
   const fp = path.join(dir, `${id}.md`);

package/src/posture/grader-calibration.js

@@ -26,18 +26,17 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const TRIAGE_FILE = '.agentic-security/triage-feedback.json';
-const SCAN_FILE   = '.agentic-security/last-scan.json';
 
+import { statePath } from './state-dir.js';
 function _loadTriageFeedback(scanRoot) {
-  const fp = path.join(scanRoot, TRIAGE_FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
   if (!fs.existsSync(fp)) return [];
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')).entries || []; }
   catch { return []; }
 }
 
 function _loadScanVerdicts(scanRoot) {
-  const fp = path.join(scanRoot, SCAN_FILE);
+  const fp = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(fp)) return [];
   try {
     const scan = JSON.parse(fs.readFileSync(fp, 'utf8'));

package/src/posture/intent-context.js

@@ -29,6 +29,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const INTENT_PATH_RE = /(?:^|\/)(?:examples?|demos?|tutorials?|sandbox|playground|challenges?|ctf)(?:\/|$)/i;
 
 const FILE_HEADER_MARKERS = [
@@ -49,7 +50,7 @@ function _readSafely(fp) {
 }
 
 function _readIntentDeclaration(scanRoot) {
-  const fp = path.join(scanRoot, '.agentic-security', 'current-intent.md');
+  const fp = statePath(scanRoot, 'current-intent.md');
   if (!fs.existsSync(fp)) return null;
   const body = _readSafely(fp);
   if (!body) return null;

package/src/posture/learning.js

@@ -22,11 +22,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const FILE = '.agentic-security/triage-feedback.json';
+import { statePath, stateWritesEnabled } from './state-dir.js';
 
 export function loadFeedback(scanRoot) {
   if (!scanRoot) return { entries: [] };
-  const fp = path.join(scanRoot, FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
   if (!fs.existsSync(fp)) return { entries: [] };
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')) || { entries: [] }; }
   catch { return { entries: [] }; }
@@ -34,7 +34,8 @@ export function loadFeedback(scanRoot) {
 
 export function saveFeedback(scanRoot, data) {
   if (!scanRoot) return;
-  const fp = path.join(scanRoot, FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
+  if (!stateWritesEnabled()) return;
   fs.mkdirSync(path.dirname(fp), { recursive: true });
   fs.writeFileSync(fp, JSON.stringify(data, null, 2));
 }