@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/orchestrator/pipeline.js

@@ -1,13 +1,9 @@
 'use strict';
 
 /**
- * Multi-agent pipeline coordinator.
- * Orchestrates: threat-researcher → source-validator → skill-updater → report-generator
- *
- * This module coordinates agent handoffs using a structured JSON protocol.
- * Each stage produces a handoff package that the next stage consumes.
- * Agents themselves are defined in agents/ and executed by AI assistants — not by this code.
- * This module tracks state, validates handoffs, and routes between stages.
+ * Multi-agent pipeline coordinator: threat-researcher → source-validator →
+ * skill-updater → report-generator. Tracks state, validates handoffs and routes
+ * between stages; the agents live in agents/ and are run by AI assistants.
  */
 
 const fs = require('fs');
@@ -20,8 +16,6 @@ const REPORTS_DIR = path.join(__dirname, '..', 'reports');
 
 const PIPELINE_STAGES = ['threat-researcher', 'source-validator', 'skill-updater', 'report-generator'];
 
-// --- public API ---
-
 /**
  * Initialize a new pipeline run for a given trigger.
  *
@@ -52,8 +46,7 @@ function initPipeline(triggerType, triggerPayload) {
 }
 
 /**
- * Build the handoff package for a specific pipeline stage.
- * This is what an AI assistant reads to understand what to do and what to pass forward.
+ * Build the handoff package for a pipeline stage — what the next agent reads.
  *
  * @param {object} run - Pipeline run object from initPipeline()
  * @param {number} stageIndex - 0-based stage index
@@ -61,10 +54,8 @@ function initPipeline(triggerType, triggerPayload) {
  * @returns {object} Handoff package for the next stage
  */
 function buildHandoff(run, stageIndex, stageOutput) {
-  // Bounds-check the stage index up front. Without this, an out-of-range
-  // index throws an opaque "cannot read properties of undefined" deep inside
-  // validateHandoff. With it, callers see a structured error that names the
-  // exact invalid input.
+  // Bounds-check up front, else an out-of-range index surfaces as an opaque
+  // "cannot read properties of undefined" from inside validateHandoff.
   if (!run || !Array.isArray(run.stages)) {
     throw new TypeError('buildHandoff: run.stages must be an array');
   }
@@ -102,18 +93,8 @@ function buildHandoff(run, stageIndex, stageOutput) {
   return handoff;
 }
 
-/**
- * Check the currency of all skills and return a report.
- * Used by the scheduler for weekly currency checks.
- *
- * @returns {{ currency_report: object[], action_required: boolean }}
- */
-// Manifest read cache. currencyCheck() runs on every weekly tick AND on every
-// `exceptd currency` invocation; in `watch` mode the scheduler triggers it
-// repeatedly. Re-reading + JSON.parse'ing the (~80 KB) manifest each time is
-// pure waste when the file hasn't changed within the cache window. 60s TTL is
-// short enough that a manual edit during a long-running watcher shows up by
-// the next periodic tick.
+// currencyCheck() runs on every weekly tick and every `exceptd currency` call, so
+// the TTL is short enough that a manual manifest edit shows by the next tick.
 const MANIFEST_CACHE_TTL_MS = 60_000;
 let _manifestCache = { value: null, mtimeMs: 0, readAt: 0 };
 
@@ -121,8 +102,7 @@ function _loadManifestCached() {
   const manifestPath = path.join(__dirname, '..', 'manifest.json');
   const now = Date.now();
   if (_manifestCache.value && (now - _manifestCache.readAt) < MANIFEST_CACHE_TTL_MS) {
-    // Within TTL — return cached value. The cost of a stat() per call is
-    // ~tens of microseconds; trade it for the JSON.parse() cost saved.
+    // Within TTL: one stat() to confirm, in place of a re-parse.
     try {
       const st = fs.statSync(manifestPath);
       if (st.mtimeMs === _manifestCache.mtimeMs) {
@@ -141,25 +121,17 @@ function _loadManifestCached() {
 }
 
 /**
- * Compute the currency row for a single skill against a reference `now`.
- *
- * Pulled out of currencyCheck so the parse-guard is unit-testable without a
- * real manifest read. A malformed `last_threat_review` (e.g. "2026-13-99",
- * which is structurally ISO-shaped but not a real calendar date) must map to
- * maximally STALE — score 0, action_required true — not to the safe-LOOKING
- * 100 a NaN delta would otherwise yield. The misformat is also surfaced via
- * `unparseable_review_date` so a bad date is OBSERVABLE rather than silently
- * defaulting (matching the project rule that a no-match/fall-through path must
- * surface, not silently pass).
+ * Currency row for a single skill against a reference `now`. A malformed
+ * `last_threat_review` maps to maximally STALE — score 0, action_required true,
+ * `unparseable_review_date` set — not the safe-LOOKING 100 a NaN delta yields.
  *
  * @param {object} skill
  * @param {Date} now
  */
 function _skillCurrencyRow(skill, now) {
   const rawDate = skill.last_threat_review || '2020-01-01';
-  // Use the timezone-stable date-only convention the sibling builders use
-  // (append T00:00:00Z for bare YYYY-MM-DD) so the day delta doesn't shift by
-  // the runner's local offset.
+  // A bare YYYY-MM-DD gets an explicit T00:00:00Z, so the day delta does not
+  // shift with the runner's local offset.
   const t = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(rawDate) ? rawDate + 'T00:00:00Z' : rawDate);
   const unparseable = !Number.isFinite(t);
   const reviewDate = unparseable ? new Date('2020-01-01T00:00:00Z') : new Date(t);
@@ -199,10 +171,8 @@ function currencyCheck() {
 }
 
 /**
- * Get the agent definition for a stage.
- *
- * @param {string} stageName - Agent name
- * @returns {string|null} Agent instruction content
+ * Reads agents/<stageName>.md.
+ * @returns {string|null} Agent instruction content, null when unreadable.
  */
 function getAgentDefinition(stageName) {
   const agentPath = path.join(AGENTS_DIR, `${stageName}.md`);
@@ -213,16 +183,10 @@ function getAgentDefinition(stageName) {
   }
 }
 
-// --- private helpers ---
-
 function validateHandoff(stageName, output) {
-  // Guard the `in` deref below: a null / non-object / array `output` would
-  // otherwise throw an opaque "Cannot use 'in' operator …" TypeError deep in
-  // the missing-fields filter. Reject up front with a named error in the same
-  // style as buildHandoff's stageIndex RangeError, so the caller sees which
-  // input was wrong. A handoff payload is a keyed object — an array is not a
-  // valid payload, so Array.isArray is rejected too (today it would yield the
-  // less-precise "missing fields" error).
+  // Guard the `in` deref below: null, a non-object or an array would otherwise
+  // throw an opaque "Cannot use 'in' operator". A payload is keyed, so an array
+  // is rejected here rather than reported as missing fields.
   if (output === null || typeof output !== 'object' || Array.isArray(output)) {
     throw new TypeError(
       `buildHandoff: stageOutput for ${stageName} must be a non-null object`
@@ -264,26 +228,11 @@ function getStageInstructions(stageName, previousOutput) {
 }
 
 function _currencyScore(daysSinceReview, _forwardWatchCount) {
-  // Currency = function of last_threat_review age, period. Earlier
-  // versions subtracted 5 per forward_watch entry, which created a
-  // perverse incentive: skills that diligently track upcoming threats
-  // (e.g. cloud-security with 14 forward_watch items) scored 30%
-  // currency even on the day after a review. forward_watch is a
-  // signal of ACTIVE maintenance, not staleness, so the count no
-  // longer affects the score. The arg is retained for ABI compat.
-  // The penalty schedule must be able to cross the tiers the gate checks
-  // against (currencyCheck: action_required at < 70, critical_count at < 50;
-  // _currencyLabel: 'stale' < 70, 'critical_stale' < 50). A schedule whose
-  // worst penalty was -30 floored the score at 70, so the warn/critical tiers —
-  // and the workflow issue they gate — could never fire. The deeper penalties
-  // only bite past 180/270/365 days, so a normally-maintained skill stays
-  // 'acceptable' while a genuinely abandoned one reaches the gate.
-  //
-  // Belt-and-suspenders: a NaN delta (the day-count derived from an
-  // unparseable last_threat_review) must map to maximally STALE (0), never the
-  // safe-LOOKING 100 the additive schedule below would leave it at. This is an
-  // exported surface other callers/tests use, so guard here even though
-  // _skillCurrencyRow already substitutes a stale fallback date upstream.
+  // Age of last_threat_review alone. A forward_watch entry signals ACTIVE
+  // maintenance, so the count must not penalise the score; the argument stays for
+  // callers. The schedule has to cross the tiers the gate checks — 'stale' below
+  // 70, 'critical_stale' below 50 — so a worst penalty of -30 would floor the
+  // score at 70 and neither tier could fire. A non-finite delta maps to STALE.
   if (!Number.isFinite(daysSinceReview)) return 0;
   let score = 100;
   if (daysSinceReview > 365) score -= 100;      // a year+ unreviewed → 0 (critical_stale)
@@ -302,12 +251,8 @@ function _currencyLabel(score) {
   return 'critical_stale';
 }
 
-// Test-only hook to reset the in-memory manifest cache. Not part of the
-// operator surface. v0.12.14: moved out of the export object literal so
-// the inline { mtimeMs: 0, readAt: 0 } reset values don't get detected
-// by scripts/check-test-coverage.js's extractLibExports regex as
-// pseudo-exports (`mtimeMs` and `readAt` are private cache fields, not
-// module exports).
+// Test-only hook. Defined here rather than inline in the export literal so its
+// reset values are not read as exports by scripts/check-test-coverage.js.
 function _resetManifestCache() {
   _manifestCache = { value: null, mtimeMs: 0, readAt: 0 };
 }
@@ -319,10 +264,8 @@ module.exports = {
   getAgentDefinition,
   MANIFEST_CACHE_TTL_MS,
   _resetManifestCache,
-  // Exported for the gate-reachability contract test: the schedule must be able
-  // to reach the warn (< 70) and critical (< 50) tiers the workflow issues on.
+  // Exported for the gate-reachability contract test (warn < 70, critical < 50).
   _currencyScore,
-  // Exported so the malformed-date staleness guard is unit-testable without a
-  // real manifest read.
+  // Exported so the malformed-date guard is testable without a manifest read.
   _skillCurrencyRow,
 };

package/orchestrator/scanner.js

@@ -1,11 +1,8 @@
 'use strict';
 
 /**
- * Environment scanner. Discovers security posture signals from the current host.
- * Produces structured findings that dispatcher.js routes to relevant skills.
- *
- * Designed to be run by a human operator or an AI assistant — not a background daemon.
- * All discovery is read-only. No writes, no network calls beyond local probes.
+ * Environment scanner: discovers host security-posture signals as structured
+ * findings that dispatcher.js routes to skills.
  */
 
 const fs = require('fs');
@@ -15,22 +12,14 @@ const { execFileSync, spawnSync } = require('child_process');
 
 const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(__dirname, '..', 'data');
 
-// CLI flags that request air-gap (no-egress) operation. `--air-gap` is the
-// documented form; `--offline` / `--no-network` are accepted aliases (the
-// orchestrator's flag allowlists accept all three). The flag MUST be honored
-// equivalently to EXCEPTD_AIR_GAP=1 on the egress path — historically the env
-// var suppressed the outbound TLS probe but the CLI flag did not, so an
-// operator passing `--air-gap` still fired a TLS s_client connect.
+// CLI flags requesting air-gap (no-egress) operation. All three must be honored
+// equivalently to EXCEPTD_AIR_GAP=1 on the egress path.
 const AIR_GAP_FLAGS = ['--air-gap', '--offline', '--no-network'];
 
 /**
- * Resolve whether air-gap mode is active. True when EXCEPTD_AIR_GAP=1, when an
- * explicit `opts.airGap` is passed, OR when any air-gap flag is present on the
- * invoking process's argv. Checking argv makes the CLI flag effective even
- * though the scanner is reached in-process from the orchestrator entry — the
- * flag and the env var are now equivalent on the egress path.
- *
- * @param {{ airGap?: boolean }} [opts]
+ * True for EXCEPTD_AIR_GAP=1, `opts.airGap`, or an air-gap flag on argv. Reading
+ * argv is what makes the CLI flag effective, since the scanner is reached
+ * in-process from the orchestrator entry.
  */
 function isAirGap(opts) {
   if (opts && opts.airGap) return true;
@@ -39,28 +28,12 @@ function isAirGap(opts) {
   return argv.some(a => typeof a === 'string' && AIR_GAP_FLAGS.includes(a));
 }
 
-// --- public API ---
-
 /**
- * Run all scanners and return consolidated findings.
- *
- * DEPRECATED in v0.10.0. This is the pre-seven-phase legacy scanner that
- * shells out from Node — kept as a safety-net path for non-AI operators.
- * New code should call the playbook runner instead:
- *
- *   const runner = require('../lib/playbook-runner');
- *   const result = await runner.run('kernel', 'all-catalogued-kernel-cves', agentSubmission);
- *
- * The runner emits seven-phase findings (govern through close) with full
- * GRC closure: CSAF-2.0 evidence bundles, jurisdiction-aware notification
- * deadlines, auditor-ready exception language, regression schedules.
- * `exceptd scan` will be removed in v1.0.
+ * Run all scanners and return consolidated findings. `opts.airGap` suppresses
+ * the outbound TLS probe.
  *
- * @param {{ airGap?: boolean }} [opts] - When `opts.airGap` is set, the
- *   outbound TLS probe is suppressed exactly as EXCEPTD_AIR_GAP=1 does. The
- *   air-gap CLI flags (--air-gap / --offline / --no-network) are also honored
- *   directly off process.argv, so the flag is equivalent to the env var.
- * @returns {{ timestamp: string, host: object, findings: object[], summary: object }}
+ * Deprecated: new code calls lib/playbook-runner, which emits seven-phase
+ * findings with full GRC closure; this is a safety net for non-AI operators.
  */
 async function scan(opts) {
   const timestamp = new Date().toISOString();
@@ -83,16 +56,9 @@ async function scan(opts) {
   findings.push(...frameworkScan());
 
   const summary = summarize(findings);
-  // _deprecation is a stderr-only banner — it MUST NOT appear in the JSON
-  // shape that downstream consumers ingest. Internal narrative belongs on
-  // stderr (the banner above), never in the structured result body.
   return { timestamp, host, findings, summary };
 }
 
-/**
- * Run a targeted scan for a specific domain.
- * @param {'kernel'|'mcp'|'crypto'|'ai_api'|'framework'} domain
- */
 async function scanDomain(domain, opts) {
   const scanners = { kernel: kernelScan, mcp: mcpScan, crypto: cryptoScan, ai_api: aiApiScan, framework: frameworkScan };
   const fn = scanners[domain];
@@ -100,8 +66,6 @@ async function scanDomain(domain, opts) {
   return fn(opts);
 }
 
-// --- domain scanners ---
-
 function kernelScan() {
   const findings = [];
   if (os.platform() !== 'linux') return findings;
@@ -117,8 +81,8 @@ function kernelScan() {
       value: kernel,
       cve_id: cveId,
       rwep_score: cve.rwep_score,
-      // Carry the catalog CVSS so the CSAF report emits a real cvss_v3 block
-      // (base score + vector) instead of a placeholder base_score:0.
+      // Carried so the CSAF report emits a real cvss_v3 block rather than a
+      // placeholder base_score:0.
       cvss_score: cve.cvss_score,
       cvss_vector: cve.cvss_vector,
       cisa_kev: cve.cisa_kev,
@@ -161,13 +125,8 @@ function mcpScan() {
 
         for (const serverName of serverList) {
           const server = mcpServers[serverName];
-          // A null / non-object / array server entry can't be probed for
-          // signature or pinned-version the way a real server config can.
-          // Dereferencing its fields would throw inside this per-server loop,
-          // which the outer catch would mis-report as a whole-file config
-          // parse error — dropping every sibling server's finding. Emit a
-          // per-server malformed marker and continue so siblings still scan,
-          // mirroring how a genuine parse failure is surfaced per-file.
+          // A non-object entry would throw into the outer catch, mis-reported as
+          // a whole-file parse error that drops every sibling server's finding.
           if (server === null || typeof server !== 'object' || Array.isArray(server)) {
             findings.push({
               domain: 'mcp',
@@ -210,9 +169,8 @@ function mcpScan() {
           tool,
           config_path: p,
           severity: 'low',
-          // Route directly like the successful mcp_server_detected finding, so a
-          // parse-error finding reaches mcp-agent-trust even if the domain
-          // routing table changes — domain fallback alone left it brittle.
+          // Routed directly, so the finding reaches mcp-agent-trust whatever the
+          // domain routing table does.
           skill_hint: 'mcp-agent-trust',
           action_required: 'MCP config file exists but could not be parsed'
         });
@@ -233,10 +191,7 @@ function cryptoScan(opts) {
     const [major, minor] = version.split('.').map(Number);
     const isPqcReady = major > 3 || (major === 3 && minor >= 5);
 
-    // Probe the full NIST PQC suite + stateful hash signatures.
-    // Reports per-algo via boolean flags so downstream callers can
-    // decide which gaps matter for their threat model (ML-KEM for
-    // HNDL exposure, LMS/XMSS for firmware signing, etc.).
+    // Per-algo flags: the caller decides which gaps matter for its threat model.
     const pqc = probePqcAlgorithms();
     const pqcDetail = [
       `ML-KEM=${pqc.ml_kem ? 'avail' : 'missing'}`,    // FIPS 203
@@ -264,12 +219,8 @@ function cryptoScan(opts) {
     });
   }
 
-  // Air-gap mode short-circuits the outbound TLS probe entirely; emit a
-  // skipped annotation so operators can see the probe was intentionally
-  // suppressed rather than failing silently. Honored equivalently for the
-  // EXCEPTD_AIR_GAP=1 env var AND the --air-gap / --offline / --no-network CLI
-  // flags (isAirGap inspects opts, env, and process.argv) — the flag is NOT a
-  // no-op on this egress path.
+  // Air-gap short-circuits the outbound TLS probe; the skipped annotation makes
+  // the suppression visible rather than a silent absence.
   if (isAirGap(opts)) {
     findings.push({
       domain: 'crypto',
@@ -376,8 +327,6 @@ function frameworkScan() {
   return findings;
 }
 
-// --- helpers ---
-
 function hostInfo() {
   return {
     platform: os.platform(),
@@ -415,68 +364,24 @@ function safeExecFile(cmd, args) {
 }
 
 /**
- * Probe runtime for PQC algorithm availability across the full
- * emerging-standards landscape. Returns boolean flags per algorithm
- * + a `provider_hint` indicating which surface confirmed each one.
- *
- *   --- NIST PQC finalized (FIPS 203/204/205, 2024) ---
- *   ml_kem      ML-KEM (Kyber) — FIPS 203, key encapsulation
- *   ml_dsa      ML-DSA (Dilithium) — FIPS 204, signatures
- *   slh_dsa     SLH-DSA (SPHINCS+) — FIPS 205, stateless hash sigs
- *
- *   --- NIST PQC draft / alternate (2025+) ---
- *   fn_dsa      FN-DSA (Falcon) — FIPS 206 draft, compact lattice sigs
- *   hqc         HQC — alternate KEM selected March 2025
- *
- *   --- NIST PQC Round-4 alternates (still relevant in niche / archival) ---
- *   frodo       FrodoKEM — conservative lattice KEM
- *   ntru        NTRU / NTRU-Prime / sNTRU — original lattice KEM family
- *   mceliece    Classic McEliece — code-based, long-term archival use
- *   bike        BIKE — code-based KEM, OQS-Provider exposed
- *
- *   --- NIST additional signature on-ramp (2023+ Round 2) ---
- *   hawk        HAWK — NTRU-based lattice signatures
- *   mayo        MAYO — multivariate
- *   sqisign     SQIsign — isogeny-based, small signatures
- *   cross       CROSS — code-based
- *   uov         UOV / SNOVA — Unbalanced Oil & Vinegar multivariate
- *   sdith       SDitH — code-based (Syndrome Decoding in the Head)
- *   mirath      MIRATH — code-based (rank metric)
- *   faest       FAEST — symmetric-key/AES-based signatures
- *   perk        PERK — code-based (Permuted Kernel Problem)
- *
- *   --- Stateful hash signatures (RFC 8391 / 8554) ---
- *   lms         LMS — Leighton-Micali Signatures (firmware)
- *   xmss        XMSS — eXtended Merkle Signature Scheme
- *   hss         HSS — Hierarchical Signature System
- *
- *   --- IETF hybrid / composite sigs (emerging RFC drafts) ---
- *   composite_sig   Composite Signatures (e.g. RSA+ML-DSA, ECDSA+ML-DSA)
- *   composite_kem   Composite KEMs (e.g. X25519+ML-KEM)
+ * Probes the runtime for PQC algorithm availability. Returns a boolean flag per
+ * algorithm plus a `provider_hint` naming the surface that confirmed each one.
  */
 function probePqcAlgorithms() {
   const result = {
-    // NIST finalized
     ml_kem: false, ml_dsa: false, slh_dsa: false,
-    // NIST draft / alternate
     fn_dsa: false, hqc: false,
-    // NIST Round-4 / niche
     frodo: false, ntru: false, mceliece: false, bike: false,
-    // NIST signature on-ramp (Round 2)
     hawk: false, mayo: false, sqisign: false, cross: false,
     uov: false, sdith: false, mirath: false, faest: false, perk: false,
-    // Stateful hash sigs
     lms: false, xmss: false, hss: false,
-    // IETF composite / hybrid
     composite_sig: false, composite_kem: false,
     provider_hint: {},
   };
   const crypto = require('crypto');
 
-  // Pattern table — values are regexes matching common spellings
-  // emitted by Node / OpenSSL / OQS-Provider / Bouncy Castle. Tested
-  // against algorithm-list output specifically (no English-prose
-  // false positives expected; the lists contain only algo names).
+  // Spellings Node / OpenSSL / OQS-Provider / Bouncy Castle emit. Matched only
+  // against algorithm-list output, never prose, which would false-positive.
   const PATTERNS = {
     // NIST finalized
     ml_kem:        /\b(ml-?kem|kyber)\b/i,
@@ -490,7 +395,7 @@ function probePqcAlgorithms() {
     ntru:          /\b(s?ntru(-?prime)?(-?\d+)?|hrss\d*|hps\d+)\b/i,
     mceliece:      /\b(classic-?)?mceliece(-?\d+)?\b/i,
     bike:          /\bbike(-?l?\d+)?\b/i,
-    // NIST signature on-ramp (Round 2, 2024+)
+    // NIST signature on-ramp (Round 2)
     hawk:          /\bhawk(-?\d+)?\b/i,
     mayo:          /\bmayo(-?\d+)?\b/i,
     sqisign:       /\bsqi-?sign(?:hd)?\b/i,
@@ -516,9 +421,8 @@ function probePqcAlgorithms() {
     }
   }
 
-  // Channel 1 — Node's crypto APIs (no shellouts). Node 24+ exposes
-  // crypto.kemEncapsulate as an experimental ML-KEM gateway; its
-  // presence is itself an ML-KEM availability signal.
+  // Channel 1 — Node's crypto APIs, no shellouts. crypto.kemEncapsulate is an
+  // experimental ML-KEM gateway, so its presence is itself an ML-KEM signal.
   try {
     if (typeof crypto.kemEncapsulate === 'function') {
       record('ml_kem', 'node:crypto.kemEncapsulate');
@@ -535,9 +439,7 @@ function probePqcAlgorithms() {
     }
   } catch (_) { /* probe failure → fall through to openssl */ }
 
-  // Channel 2 — `openssl list` enumerations. KEMs and signature
-  // algorithms split across two list commands; OQS-Provider exposes
-  // the on-ramp / niche algos when installed.
+  // Channel 2 — `openssl list`: KEMs and signatures split across two commands.
   const kemList = safeExecFile('openssl', ['list', '-kem-algorithms']);
   if (kemList) {
     const kemAlgos = ['ml_kem', 'hqc', 'frodo', 'ntru', 'mceliece', 'bike', 'composite_kem'];
@@ -562,8 +464,7 @@ function probePqcAlgorithms() {
 }
 
 function probeTls(target) {
-  // Target is "host:port"; default lives at the call site so the env var
-  // is read once per scan rather than baked in here.
+  // Target is "host:port"; the call site owns the env-var default.
   const t = typeof target === 'string' && target.length > 0 ? target : 'registry.npmjs.org:443';
   const result = spawnSync('openssl', ['s_client', '-connect', t, '-brief'], {
     input: '',
@@ -576,14 +477,11 @@ function probeTls(target) {
   return match ? match[1] : null;
 }
 
-// Key names that signal a credential value, matched case-insensitively at any
-// nesting depth. MCP server configs place real secrets inside `env` and
-// `headers` sub-objects (e.g. env.OPENAI_API_KEY, headers.Authorization), so a
-// top-level-only sweep leaks them into emitted findings.
+// Key names that signal a credential value, matched at any nesting depth: MCP
+// configs put real secrets inside `env` and `headers` sub-objects.
 const SECRET_KEY_RE = /token|key|secret|password|credential|auth|bearer|api[-_]?key|access[-_]?key/i;
 
-// Value shapes that look like live credentials even under an innocuous key name
-// (e.g. args: ['--token', 'sk-...'] or a positional bearer string).
+// Value shapes that look like live credentials under an innocuous key name.
 const SECRET_VALUE_RES = [
   /\bsk-[A-Za-z0-9_-]{8,}/,            // OpenAI-style keys
   /\bAKIA[0-9A-Z]{12,}/,              // AWS access key id
@@ -599,10 +497,8 @@ function looksLikeSecretValue(value) {
   return SECRET_VALUE_RES.some((re) => re.test(value));
 }
 
-// Recursively redact credential-shaped data so nothing emitted to stdout or
-// persisted carries an operator's live secrets. Redacts values of secret-named
-// keys at any depth and any standalone string value that matches a known
-// credential shape. Cycles are guarded with a seen-set.
+// Redacts credential-shaped data at any depth so nothing emitted or persisted
+// carries an operator's live secrets. Cycle-guarded.
 function redactDeep(value, seen) {
   if (value === null || typeof value !== 'object') {
     return looksLikeSecretValue(value) ? '[REDACTED]' : value;