@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/citation-resolve.js

@@ -1,24 +1,11 @@
 "use strict";
 
 /**
- * lib/citation-resolve.js
- *
- * Answers "is this CVE/RFC citation valid?" so an agent gets the answer FROM
- * exceptd instead of researching each citation against NVD / the IETF
- * datatracker by hand. Offline-first:
- *
- *   CVE: local catalog -> resolved cache -> (opt-in) one NVD lookup, cached.
- *   RFC: local index    -> resolved cache -> (opt-in) one datatracker lookup.
- *
- * The resolved cache lives at .cache/upstream/resolved/<kind>/<id>.json with a
- * 7-day TTL. The FIRST agent to resolve an uncatalogued id pays one network
- * call and writes the cache; sibling agents (and later offline runs) read it —
- * turning N agents x M citations of redundant lookups into one lookup per id.
- *
- * Network is opt-out: --air-gap / EXCEPTD_AIR_GAP=1 / { noNetwork:true } make
- * resolution offline-only (catalog + cache), returning status "unknown" with a
- * reason rather than reaching out. Network-resolved records are transient
- * (cache only) and are never written into the signed catalog.
+ * Answers "is this CVE/RFC citation valid?" offline-first: local catalog or
+ * index, then the resolved cache, then one opt-in network lookup. --air-gap /
+ * EXCEPTD_AIR_GAP=1 / { noNetwork:true } make it offline-only, returning status
+ * "unknown". Network-resolved records live in the cache only and never enter
+ * the signed catalog.
  */
 
 const fs = require("node:fs");
@@ -45,26 +32,16 @@ function rfcIndex() {
   return _rfc;
 }
 
-// --- resolved-id cache (atomic JSON files, TTL-bounded, integrity-checked) ---
-//
-// The cache feeds security verdicts (and, via citation-hygiene --resolve,
-// attestations), so a record is only trusted if it carries a matching content
-// digest AND its own `resolved_at` is within the freshness window. A file an
-// attacker (or a corrupt/half-written process) edits in place without
-// recomputing `_digest` is rejected as a cache-miss — it can never launder a
-// rejected/fabricated citation into "published". This is the resolved-cache
-// analogue of the prefetch cache's sha256+signature model; full maintainer
-// signing isn't possible operator-side (no private key), so the digest binds
-// the record to itself and makes tampering detectable.
+// The resolved-id cache feeds security verdicts, so a record is trusted only when
+// its `_digest` matches and its own `resolved_at` is inside the freshness window —
+// an in-place edit cannot launder a rejected citation into "published".
 function cachePath(kind, id) {
   // Read the env at call time so tests can isolate the cache per-case.
   const dir = process.env.EXCEPTD_RESOLVE_CACHE_DIR || RESOLVE_CACHE_DIR;
   const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
   return path.join(dir, kind, `${safe}.json`);
 }
-// sha256 over the record's canonical bytes (sorted keys, `_digest` excluded).
-// `resolved_at` IS covered, so the staleness clock can't be rewritten apart
-// from the verdict.
+// sha256 over canonical bytes (sorted keys, `_digest` excluded); covers `resolved_at`.
 function recordDigest(record) {
   const canon = {};
   for (const k of Object.keys(record).sort()) {
@@ -78,20 +55,14 @@ function cacheGet(kind, id) {
     const p = cachePath(kind, id);
     const record = JSON.parse(fs.readFileSync(p, "utf8"));
     if (!record || typeof record !== "object") return null;
-    // Integrity: a record without a matching digest is tampered/corrupt → miss.
     if (typeof record._digest !== "string" || record._digest !== recordDigest(record)) return null;
-    // Freshness keyed on the record's own resolved_at (not file mtime, which a
-    // `touch` can reset). Reject future-dated records as a poisoning signal,
-    // mirroring the prefetch cache's future-date guard.
+    // resolved_at, not file mtime which `touch` resets; a future-dated record is poisoning.
     const ts = Date.parse(record.resolved_at || "");
     if (!Number.isFinite(ts)) return null;
     const age = Date.now() - ts;
     if (age < -60_000 || age > CACHE_TTL_MS) return null;
-    // Bind the record to the requested key — a digest proves self-consistency,
-    // not that this is the record FOR the looked-up id/kind. A digest-valid
-    // record written under one filename but carrying a different internal
-    // id/kind would otherwise be served for the wrong lookup (a swapped-file
-    // poisoning that the self-digest cannot catch). Mismatch → cache miss.
+    // The digest proves self-consistency, not that this is the record FOR this
+    // id/kind — a valid record filed under another name must not be served.
     if (record.kind !== kind) return null;
     if (kind === "cve") {
       if (typeof record.id !== "string" || record.id.toUpperCase() !== String(id).toUpperCase()) return null;
@@ -108,9 +79,7 @@ function cachePut(kind, id, record) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     const signed = { ...record };
     signed._digest = recordDigest(signed);
-    // Random suffix (not just pid) so two cachePut calls for the same id in one
-    // process — a Promise.all fan-out or worker threads sharing a pid — don't
-    // race the same tmp path. Matches lib/prefetch.js writeFileAtomic.
+    // Random suffix, not just pid: an in-process fan-out would race the same tmp path.
     const tmp = `${p}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(signed));
     fs.renameSync(tmp, p); // atomic — concurrent readers never see a half-written file
@@ -127,9 +96,7 @@ function isAirGap(opts) {
  * from:   format | catalog | cache | network | offline | error
  */
 async function resolveCve(id, opts = {}) {
-  // Trim before the format test — matches resolveRfc — so a whitespace-only
-  // identifier is "fabricated/malformed" (empty form) rather than a literal
-  // whitespace string fed straight into CVE_RE.
+  // Trim before the format test so a whitespace-only id is malformed, not fed to CVE_RE.
   const cveId = String(id || "").trim().toUpperCase();
   const base = { id: cveId, kind: "cve" };
 
@@ -153,10 +120,7 @@ async function resolveCve(id, opts = {}) {
     };
   }
 
-  // 1b. alias lookup — an id may be carried as an alias of a curated entry
-  //     (e.g. a CVE for a sub-incident folded into a campaign-level MAL-* key).
-  //     Catalogued-by-alias must resolve offline too, or `exceptd cve <alias>`
-  //     would report unknown for an incident the catalog actually covers.
+  // 1b. alias lookup — a catalogued-by-alias id must resolve offline too.
   for (const k of Object.keys(catalog)) {
     if (k === "_meta") continue;
     const e = catalog[k];
@@ -178,7 +142,6 @@ async function resolveCve(id, opts = {}) {
   const cached = cacheGet("cve", cveId);
   if (cached) return { ...cached, from: "cache" };
 
-  // 3. offline / air-gap: cannot resolve uncatalogued ids without network
   if (isAirGap(opts)) {
     return { ...base, status: "unknown", from: "offline",
       reason: "air-gap: not in local catalog and no cached resolution — verify against NVD when online" };
@@ -188,9 +151,7 @@ async function resolveCve(id, opts = {}) {
       reason: "not in local catalog and no cached resolution (network disabled)" };
   }
 
-  // 4. resolve once via NVD, then cache for sibling agents.
-  // opts._validateCve is a test seam (inject a fake validator); production uses
-  // the real NVD-backed validator.
+  // Resolve once via NVD, then cache. opts._validateCve is a test seam.
   let validateCve = opts._validateCve;
   if (!validateCve) {
     try { ({ validateCve } = require("../sources/validators/cve-validator.js")); }
@@ -203,11 +164,8 @@ async function resolveCve(id, opts = {}) {
   if (v.status === "unreachable") {
     return { ...base, status: "unknown", from: "offline", reason: "NVD unreachable — retry online" };
   }
-  // NVD is the authority for a CVE's existence and lifecycle. validateCve only
-  // returns "unreachable" when EVERY source fails — if NVD is down but KEV/EPSS
-  // answer, it returns match/drift with sources.nvd.reachable === false. Do NOT
-  // declare "published" on KEV/EPSS alone during an NVD outage; that would
-  // falsely validate an unconfirmed (or nonexistent) identifier.
+  // "unreachable" means EVERY source failed, so an NVD outage with KEV/EPSS still
+  // answering slips through. NVD is the existence authority: never publish on KEV alone.
   const nvd = v.fetched && v.fetched.sources && v.fetched.sources.nvd;
   if (!nvd || nvd.reachable !== true) {
     return { ...base, status: "unknown", from: "offline",
@@ -223,9 +181,7 @@ async function resolveCve(id, opts = {}) {
     id: cveId, kind: "cve", status,
     cvss: v.fetched?.cvss_score ?? null,
     kev: v.fetched?.in_kev ?? null,
-    // NVD English description — carries the product/scope a citation must match,
-    // so an agent can confirm status=published applies to the right product
-    // without a second manual NVD lookup.
+    // The NVD description carries the product/scope a citation must match.
     product: v.fetched?.description ?? null,
     nvd_vuln_status: v.fetched?.nvd_vuln_status ?? null,
     cve_tags: v.fetched?.cve_tags || [],
@@ -238,11 +194,8 @@ async function resolveCve(id, opts = {}) {
 
 /**
  * Resolve an RFC citation. Returns { id, kind:"rfc", number, title, rfc_status,
- * found, from, ... }. The local index covers the whole RFC series — current
- * AND obsoleted/historic (the latter carry `_obsoleted` + `obsoleted_by`) — so
- * number->title resolution, including "is this RFC superseded?", is fully
- * offline. A number absent from the index is almost certainly nonexistent (or
- * an UNKNOWN-status placeholder); the optional network step confirms.
+ * found, from, ... }. A number absent from the local index is almost certainly
+ * nonexistent; the optional network step confirms.
  */
 async function resolveRfc(id, opts = {}) {
   const raw = String(id || "").trim();
@@ -255,7 +208,7 @@ async function resolveRfc(id, opts = {}) {
   const num = Number(m[1]);
   const key = `RFC-${num}`;
 
-  // 1. local index (offline, whole current series)
+  // 1. local index (offline)
   const entry = rfcIndex()[key];
   if (entry && typeof entry === "object") {
     return {
@@ -268,7 +221,6 @@ async function resolveRfc(id, opts = {}) {
     };
   }
 
-  // 2. resolved cache
   const cached = cacheGet("rfc", String(num));
   if (cached) return { ...cached, from: "cache" };
 

package/lib/collectors/ai-api.js

@@ -1,21 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/ai-api.js
- *
- * Companion collector for the `ai-api` playbook. Scans shell rc
- * files for cleartext AI API key exports, plus the standard
- * credential carriers (~/.aws, ~/.kube, ~/.config/gcloud) for
+ * Companion collector for the `ai-api` playbook: scans shell rc files for
+ * cleartext AI API key exports, plus ~/.aws, ~/.kube and ~/.config/gcloud for
  * long-lived credentials likely to authenticate against AI APIs.
- *
- * Non-deterministic indicators (ai-api-egress-from-unexpected-
- * process, ai-api-anomalous-volume, ai-api-beaconing-cadence,
- * base64-or-encoded-payload-in-prompts) require ss/netstat/auditd
- * traces and process-list correlation that fall outside the
- * stdlib-only collector contract. They stay unflipped — the runner
- * returns inconclusive and operator-supplied evidence completes
- * the verdict.
- *
  * Interface: see lib/collectors/README.md
  */
 
@@ -25,18 +13,40 @@ const os = require("node:os");
 
 const COLLECTOR_ID = "ai-api";
 
-function readSafe(full, max = 256 * 1024) {
+// One definition, named at every call site. Written as a literal in both the
+// default and the callers, the two drift apart the moment the cap is raised,
+// and the only symptom is a credential store that quietly stops being scanned
+// at the old size.
+const SCAN_CAP_BYTES = 256 * 1024;
+
+// `skip` routes a non-read onto the collector_errors channel:
+// { errors, artifact_id, label }. A null return is indistinguishable between
+// "over the cap" and "unreadable", and both mean the file went unscanned — a
+// clean verdict over an unscanned credential store is the failure mode, so the
+// reason travels with the submission. `label` is home-relative: the absolute
+// path is operator-identifying and collector_meta already carries `home`.
+function readSafe(full, max = SCAN_CAP_BYTES, skip = null) {
+  const note = (kind, reason) => {
+    if (!skip || !Array.isArray(skip.errors)) return;
+    const entry = { kind, reason: `${skip.label || path.basename(full)}: ${reason}` };
+    if (skip.artifact_id) entry.artifact_id = skip.artifact_id;
+    skip.errors.push(entry);
+  };
   let fd;
   try {
     fd = fs.openSync(full, "r");
     const s = fs.fstatSync(fd);
-    if (s.size > max) return null;
-    // readFileSync(fd) loops read() to EOF — a single readSync may return
-    // fewer than s.size bytes on network/FUSE/sync-backed fds, which would
-    // leave the buffer tail NUL-filled and silently drop trailing content.
-    // Reading via the already-open fd keeps the fstat-then-read TOCTOU-free.
+    if (s.size > max) {
+      note("file_too_large_skipped", `${s.size} bytes exceeds ${max}-byte scan limit; not scanned`);
+      return null;
+    }
+    // readFileSync(fd) loops to EOF; a single readSync can return short on a
+    // network or FUSE fd. Reading the open fd keeps fstat-then-read TOCTOU-free.
     return fs.readFileSync(fd, "utf8");
-  } catch { return null; }
+  } catch (e) {
+    note("read_failed", e.message);
+    return null;
+  }
   finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } } }
 }
 
@@ -44,9 +54,28 @@ function fileExists(full) {
   try { return fs.statSync(full).isFile(); } catch { return false; }
 }
 
-// Cleartext AI-API-key export patterns. Matches the standard
-// `export VAR=value` and `VAR=value` shell shapes plus fish-style
-// `set -gx VAR value`.
+// A credential store is one of three things, and only "absent" is a negative
+// finding. Truthiness collapses the other two: an empty file reads as "" and is
+// a completed scan, not a skipped one, while readSafe signals a skip with null.
+// The distinction is null-vs-string, and it drives the artifact's captured flag
+// and the indicator's verdict together so the two cannot disagree.
+const ABSENT = "absent";
+const UNREAD = "unread";
+const READ = "read";
+function storeState(exists, content) {
+  if (!exists) return ABSENT;
+  return content === null ? UNREAD : READ;
+}
+
+// A store that was never read cannot answer the question its indicator asks.
+// `miss` there is a clean bill of health over an unscanned file; a hit stands
+// on its own evidence and is unaffected by a sibling going unread.
+function verdict(found, undetermined) {
+  if (found) return "hit";
+  return undetermined ? "inconclusive" : "miss";
+}
+
+// Cleartext key exports: `export VAR=value`, `VAR=value`, fish `set -gx VAR value`.
 const AI_KEY_PATTERNS = [
   { id: "openai",       re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?OPENAI_API_KEY\s*[= ]\s*['"]?sk-[A-Za-z0-9_-]{20,}/m },
   { id: "anthropic",    re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?ANTHROPIC_API_KEY\s*[= ]\s*['"]?sk-ant-[A-Za-z0-9_-]{20,}/m },
@@ -56,20 +85,15 @@ const AI_KEY_PATTERNS = [
   { id: "cohere",       re: /(?:^|\n)\s*(?:export\s+|set\s+-gx\s+)?COHERE_API_KEY\s*[= ]\s*['"]?[A-Za-z0-9-]{30,}/m },
 ];
 
-// Capture the exported value so the false_positive_checks_required entries
-// (placeholder demotion, entropy floor) can be evaluated. The export
-// patterns above end at the prefix; widen to grab the trailing token.
+// The patterns above end at the prefix; these capture the exported value so
+// the placeholder and entropy-floor FP checks have something to evaluate.
 const AI_KEY_VALUE_RE = {
   openai: /OPENAI_API_KEY\s*[= ]\s*['"]?(sk-[A-Za-z0-9_-]+)/,
   anthropic: /ANTHROPIC_API_KEY\s*[= ]\s*['"]?(sk-ant-[A-Za-z0-9_-]+)/,
   huggingface: /(?:HUGGINGFACE_TOKEN|HF_TOKEN)\s*[= ]\s*['"]?(hf_[A-Za-z0-9]+)/,
-  // Azure/Google/Cohere keys carry no vendor prefix, so the captured value IS
-  // the entropy body. Without these, cleartextFpIndices found no value for an
-  // azure/google/cohere-only dotfile, returned an empty attestation, and the
-  // runner downgraded a real cleartext-key hit to inconclusive — the indicator
-  // fired then vanished for half the supported vendors. The 30-char entropy
-  // floor (the `: 30` else-branch below) and PLACEHOLDER_RE both apply, since
-  // the prefix-strip leaves these values unchanged.
+  // Azure, Google and Cohere keys carry no vendor prefix, so the captured value
+  // IS the entropy body. Drop one of these and cleartextFpIndices attests nothing
+  // for such a dotfile, downgrading a real hit to inconclusive.
   azure: /AZURE_OPENAI(?:_API)?_KEY\s*[= ]\s*['"]?([A-Za-z0-9]{20,})/,
   google: /(?:GOOGLE_API_KEY|GOOGLE_GENAI_API_KEY|GEMINI_API_KEY)\s*[= ]\s*['"]?([A-Za-z0-9_-]{20,})/,
   cohere: /COHERE_API_KEY\s*[= ]\s*['"]?([A-Za-z0-9-]{30,})/,
@@ -85,12 +109,9 @@ function scanShellRc(content) {
   return hits;
 }
 
-// Deterministic false_positive_checks_required evaluation for
-// cleartext-api-key-in-dotfile. Returns the satisfiable indices for the
-// exports found across the canonical dotfiles (intersection — an index is
-// only attested if every export satisfies it). Canonical home rc / dotfile
-// paths are never under examples/tests/fixtures, so the path check [1] is
-// always satisfied here.
+// The satisfiable false_positive_checks_required indices for
+// cleartext-api-key-in-dotfile, intersected across every export found. Canonical
+// home dotfiles are never under examples/tests/fixtures, so [1] always holds.
 function cleartextFpIndices(content) {
   const sat = new Set(["0", "1", "2"]);
   let sawAny = false;
@@ -101,8 +122,7 @@ function cleartextFpIndices(content) {
     const value = m[1];
     // [0] not a documented placeholder / sk-test- fixture
     if (PLACEHOLDER_RE.test(value)) sat.delete("0");
-    // [2] entropy floor: OpenAI sk-* >= 48 post-prefix, Anthropic sk-ant-* >= 40,
-    //     HuggingFace hf_* >= 30.
+    // [2] entropy floor, post-prefix: OpenAI 48, Anthropic 40, others 30.
     const floor = vendor === "openai" ? 48 : vendor === "anthropic" ? 40 : 30;
     const body = value.replace(/^sk-ant-(?:api03|admin01)-|^sk-(?:proj-|svcacct-|admin-)?|^hf_/, "");
     if (body.length < floor) sat.delete("2");
@@ -128,9 +148,8 @@ function parseAwsCredentials(content) {
   const staticProfiles = [];
   const accessKeyIds = [];
   for (const [name, kv] of Object.entries(profiles)) {
-    // long-lived-aws-keys: aws_access_key_id present AND no
-    // aws_session_token sibling (STS temporary creds carry the
-    // session token; IAM-user long-lived keys do not).
+    // Long-lived means an access key id with no session-token sibling: STS
+    // temporary credentials always carry one, IAM-user keys never do.
     if (kv["aws_access_key_id"] && !kv["aws_session_token"]) {
       staticProfiles.push(name);
       accessKeyIds.push(kv["aws_access_key_id"]);
@@ -155,7 +174,12 @@ function parseGcloudAdc(content) {
       privateKey: typeof j?.private_key === "string" ? j.private_key : "",
       clientEmail: typeof j?.client_email === "string" ? j.client_email : "",
     };
-  } catch { return { hasServiceAccount: false }; }
+  } catch (e) {
+    // Unparseable ADC is NOT evidence the file holds no service account; the
+    // parse failure travels so `gcp-service-account-json: miss` is not read as
+    // a clean bill of health.
+    return { hasServiceAccount: false, parse_error: e.message };
+  }
 }
 
 function parseKubeStaticToken(content) {
@@ -187,18 +211,26 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const root = path.resolve(cwd);
   const home = (env && env.HOME) || (env && env.USERPROFILE) || os.homedir();
 
-  // Shell rc + dotfile candidates.
   const shellRcs = [
     ".bashrc", ".bash_profile", ".zshrc", ".zprofile", ".profile",
     path.join(".config", "fish", "config.fish"),
   ].map(rel => path.join(home, rel));
-  // Glob fish/conf.d/*.
   try {
     const fishConfD = path.join(home, ".config", "fish", "conf.d");
     for (const e of fs.readdirSync(fishConfD)) {
       if (e.endsWith(".fish")) shellRcs.push(path.join(fishConfD, e));
     }
-  } catch { /* fish not present */ }
+  } catch (e) {
+    // No fish conf.d is the normal case. A permission or I/O failure on one that
+    // IS there means those fragments went unscanned for key exports.
+    if (e.code !== "ENOENT") {
+      errors.push({
+        artifact_id: "shell-rc-files",
+        kind: "readdir_failed",
+        reason: `.config/fish/conf.d: ${e.message} — fragments not scanned`,
+      });
+    }
+  }
 
   const dotfileKeys = [
     ".openai", ".anthropic",
@@ -208,13 +240,24 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     path.join(".config", "azure-openai"),
   ].map(rel => path.join(home, rel));
 
-  const allKeyCarriers = [...shellRcs, ...dotfileKeys];
+  // Two artifacts share one scan loop. The carrier's own artifact_id travels
+  // with it so a skipped `~/.anthropic` is reported against dotfile-api-keys
+  // rather than pointing the operator at the shell-rc row.
+  const allKeyCarriers = [
+    ...shellRcs.map(p => ({ path: p, artifact_id: "shell-rc-files" })),
+    ...dotfileKeys.map(p => ({ path: p, artifact_id: "dotfile-api-keys" })),
+  ];
   const cleartextHitsByFile = {};
+  const cleartextUnread = [];
   let cleartextFp = null;
-  for (const p of allKeyCarriers) {
+  for (const { path: p, artifact_id } of allKeyCarriers) {
     if (!fileExists(p)) continue;
-    const c = readSafe(p);
-    if (c == null) continue;
+    const c = readSafe(p, SCAN_CAP_BYTES, {
+      errors, artifact_id, label: path.relative(home, p),
+    });
+    // Present but unread: the file could still hold a key, so it is a gap in
+    // the scan rather than a carrier with nothing in it.
+    if (c === null) { cleartextUnread.push(path.relative(home, p)); continue; }
     const hits = scanShellRc(c);
     if (hits.length > 0) {
       cleartextHitsByFile[path.relative(home, p)] = hits;
@@ -227,35 +270,70 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   }
   const cleartextAnyHit = Object.keys(cleartextHitsByFile).length > 0;
 
-  // AWS / GCP / kube reuse.
   const awsCredsPath = path.join(home, ".aws", "credentials");
-  const awsCredsContent = fileExists(awsCredsPath) ? readSafe(awsCredsPath) : null;
+  const awsCredsExists = fileExists(awsCredsPath);
+  const awsCredsContent = awsCredsExists
+    ? readSafe(awsCredsPath, SCAN_CAP_BYTES, {
+      errors, artifact_id: "aws-credentials", label: path.relative(home, awsCredsPath),
+    })
+    : null;
   const awsParsed = parseAwsCredentials(awsCredsContent);
   const longLivedAws = awsParsed.staticProfiles.length > 0;
 
   const gcloudAdcPath = path.join(home, ".config", "gcloud", "application_default_credentials.json");
-  const gcloudContent = fileExists(gcloudAdcPath) ? readSafe(gcloudAdcPath) : null;
+  const gcloudAdcExists = fileExists(gcloudAdcPath);
+  const gcloudContent = gcloudAdcExists
+    ? readSafe(gcloudAdcPath, SCAN_CAP_BYTES, {
+      errors, artifact_id: "gcp-credentials", label: path.relative(home, gcloudAdcPath),
+    })
+    : null;
   const gcloudParsed = parseGcloudAdc(gcloudContent);
+  if (gcloudParsed.parse_error) {
+    errors.push({
+      artifact_id: "gcp-credentials",
+      kind: "parse_failed",
+      reason: `${path.relative(home, gcloudAdcPath)}: ${gcloudParsed.parse_error} — service-account presence undetermined, not absent`,
+    });
+  }
 
   const kubeCfgPath = (env && env.KUBECONFIG) || path.join(home, ".kube", "config");
-  const kubeContent = fileExists(kubeCfgPath) ? readSafe(kubeCfgPath) : null;
+  // KUBECONFIG can point outside $HOME, where a home-relative label degrades to
+  // a `..` chain; the basename is enough to name the file that went unread.
+  // The separator is required: a bare prefix test also matches a SIBLING whose
+  // name merely starts with $HOME ("/home/rob" vs "/home/robert-backup"), which
+  // produces exactly the `../…` chain this branch exists to avoid — and leaks
+  // another account's directory name into the warning.
+  const kubeInHome = kubeCfgPath === home || kubeCfgPath.startsWith(home + path.sep);
+  const kubeLabel = kubeInHome ? path.relative(home, kubeCfgPath) : path.basename(kubeCfgPath);
+  const kubeCfgExists = fileExists(kubeCfgPath);
+  const kubeContent = kubeCfgExists
+    ? readSafe(kubeCfgPath, SCAN_CAP_BYTES, {
+      errors, artifact_id: "kube-config", label: kubeLabel,
+    })
+    : null;
   const kubeParsed = parseKubeStaticToken(kubeContent);
   const kubeStaticToken = kubeParsed.found;
 
+  const awsState = storeState(awsCredsExists, awsCredsContent);
+  const gcloudState = storeState(gcloudAdcExists, gcloudContent);
+  const kubeState = storeState(kubeCfgExists, kubeContent);
+
   const signal_overrides = {
-    "cleartext-api-key-in-dotfile": cleartextAnyHit ? "hit" : "miss",
-    "long-lived-aws-keys": longLivedAws ? "hit" : "miss",
-    "gcp-service-account-json": gcloudParsed.hasServiceAccount ? "hit" : "miss",
-    "kubeconfig-with-static-token": kubeStaticToken ? "hit" : "miss",
+    "cleartext-api-key-in-dotfile": verdict(cleartextAnyHit, cleartextUnread.length > 0),
+    "long-lived-aws-keys": verdict(longLivedAws, awsState === UNREAD),
+    // Unread and unparseable are the same answer here: nothing in the file was
+    // validated, so its service-account presence is undetermined rather than
+    // absent. JSON.parse never runs on an unread store, so the state carries it.
+    "gcp-service-account-json": verdict(
+      gcloudParsed.hasServiceAccount,
+      gcloudState === UNREAD || Boolean(gcloudParsed.parse_error),
+    ),
+    "kubeconfig-with-static-token": verdict(kubeStaticToken, kubeState === UNREAD),
   };
 
-  // Per-indicator __fp_checks attestation. Each canonical-path credential
-  // store the collector reads is never under an examples/tests/fixtures path,
-  // so the path-based FP checks are satisfied; value-based checks (placeholder,
-  // entropy, sample-credential, cluster-locality) are evaluated deterministically.
-  // Network / sts-validity checks are left unattested so the runner still
-  // downgrades those. Without this, a real cleartext key or static token
-  // surfaced by `collect` is downgraded to inconclusive after `run`.
+  // Per-indicator __fp_checks attestation. Path checks hold because every store
+  // read here is a canonical home path; network and STS-validity checks stay
+  // unattested. With no attestation at all, a real hit downgrades to inconclusive.
   if (cleartextAnyHit && cleartextFp && cleartextFp.size) {
     const att = {};
     for (const idx of cleartextFp) att[idx] = true;
@@ -278,8 +356,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
     // [1] client_email is a real *@*.gserviceaccount.com (not example/test)
     const ce = gcloudParsed.clientEmail || "";
     if (/@[^@\s]+\.gserviceaccount\.com$/i.test(ce) && !/@example\.com$|@test\./i.test(ce)) att["1"] = true;
-    // [2] canonical ADC path (not under examples/) AND no GOOGLE_APPLICATION_CREDENTIALS
-    //     redirecting away from it
+    // [2] canonical ADC path, with no GOOGLE_APPLICATION_CREDENTIALS redirect
     if (!(env && env.GOOGLE_APPLICATION_CREDENTIALS)) att["2"] = true;
     if (Object.keys(att).length) signal_overrides["gcp-service-account-json__fp_checks"] = att;
   }
@@ -305,15 +382,32 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       value: dotfileKeys.filter(p => fileExists(p)).map(p => path.relative(home, p)).join(", ") || "no AI vendor dotfile carriers found at the canonical paths",
       captured: true,
     },
-    "aws-credentials": awsCredsContent
+    // A null content is two different worlds: the store is not there, or it IS
+    // there and went unread (over the scan cap, permissions, I/O). Only the
+    // first is an absence. The second is captured:false with the reason on
+    // collector_errors — asserting "absent" over a credential file that exists
+    // is the same clean-verdict-over-an-unscanned-store failure the error
+    // channel was added to close.
+    "aws-credentials": awsState === READ
       ? { value: `${awsParsed.staticProfiles.length} long-lived profile(s): ${awsParsed.staticProfiles.join(", ") || "none"}`, captured: true }
-      : { value: "~/.aws/credentials absent", captured: true },
-    "gcp-credentials": gcloudContent
+      : awsState === UNREAD
+        ? { value: "~/.aws/credentials present but unread — profile inventory undetermined, not absent", captured: false, reason: "read skipped or failed; see collector_errors for the reason" }
+        : { value: "~/.aws/credentials absent", captured: true },
+    // Read-but-unparseable is a fourth outcome, distinct from read, unread and
+    // absent: the bytes arrived and nothing in them was validated. Reporting
+    // captured:true there states service_account=false about a file never parsed.
+    "gcp-credentials": gcloudState === READ && !gcloudParsed.parse_error
       ? { value: `application_default_credentials.json present; service_account=${gcloudParsed.hasServiceAccount}`, captured: true }
-      : { value: "no gcloud ADC at the canonical path", captured: true, reason: "credentials.db / legacy_credentials/*/adc.json inspection deferred (no stdlib SQLite reader)" },
-    "kube-config": kubeContent
+      : gcloudState === READ
+        ? { value: "application_default_credentials.json present but unparseable — service-account presence undetermined, not absent", captured: false, reason: "JSON parse failed; see collector_errors for the reason" }
+        : gcloudState === UNREAD
+          ? { value: "application_default_credentials.json present but unread — service-account presence undetermined, not absent", captured: false, reason: "read skipped or failed; see collector_errors for the reason" }
+          : { value: "no gcloud ADC at the canonical path", captured: true, reason: "credentials.db / legacy_credentials/*/adc.json inspection deferred (no stdlib SQLite reader)" },
+    "kube-config": kubeState === READ
       ? { value: `kubeconfig present; static_token=${kubeStaticToken}`, captured: true }
-      : { value: "no kubeconfig at the canonical path", captured: true },
+      : kubeState === UNREAD
+        ? { value: "kubeconfig present but unread — static-token presence undetermined, not absent", captured: false, reason: "read skipped or failed; see collector_errors for the reason" }
+        : { value: "no kubeconfig at the canonical path", captured: true },
     "ai-sdk-inventory": {
       value: "skipped — npm/pip global listing deferred to operator/AI evidence",
       captured: false,