sinapse-ai 1.8.0 → 1.9.1

package/bin/commands/update.js

@@ -31,6 +31,29 @@ const {
 const { promptLlmChoice } = require('../lib/prompts');
 const { generateCommandMd, generateSquadAwareness } = require('./install');
 const { registerGroundingHooks, HOOK_FILENAMES } = require('../lib/register-grounding-hooks');
+const { execSync } = require('child_process');
+
+// Query the latest version published to npm. Returns null when npm is unreachable.
+function fetchLatestVersion() {
+  try {
+    const out = execSync('npm view sinapse-ai version', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 15000,
+    });
+    return (out || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function isNewerVersion(candidate, current) {
+  try {
+    return require('semver').gt(candidate, current);
+  } catch {
+    return candidate !== current;
+  }
+}
 
 async function cmdUpdateGlobal() {
   const logger = getLogger();
@@ -45,6 +68,35 @@ async function cmdUpdateGlobal() {
   const existing = detectExistingInstall();
   const prevVer = existing.prevMeta && existing.prevMeta.version ? existing.prevMeta.version : 'unknown';
 
+  // Real update (like `claude update`): fetch the latest published version and, if
+  // it is newer than what is running, download + apply it, then hand off to the
+  // freshly installed binary to re-sync. `--local` / `--no-fetch` skip this (used by
+  // the handoff to avoid a loop, and for offline re-sync of the running version).
+  const skipFetch = process.argv.includes('--local') || process.argv.includes('--no-fetch');
+  if (!skipFetch) {
+    const latest = fetchLatestVersion();
+    if (latest && isNewerVersion(latest, VERSION)) {
+      logger.always(`${BOLD}  Nova versão disponível: v${latest}${NC} ${DIM}(você está na v${VERSION})${NC}`);
+      logger.always(`${DIM}  Baixando e aplicando a versão nova...${NC}\n`);
+      try {
+        execSync('npm install -g sinapse-ai@latest', { stdio: 'inherit' });
+        // Hand off to the new version to apply it. No loop: once installed, the new
+        // run sees latest === running and falls through to the local re-sync.
+        execSync('sinapse-ai update --local', { stdio: 'inherit' });
+        logger.always(`\n${GREEN}Atualizado para v${latest}.${NC}`);
+        return;
+      } catch (e) {
+        const reason = (e && e.message ? e.message.split('\n')[0] : 'erro desconhecido');
+        logger.always(`\n${YELLOW}Não consegui atualizar automaticamente (${reason}).${NC}`);
+        logger.always(`${DIM}  Rode manualmente: ${CYAN}! npm install -g sinapse-ai@latest${NC} e depois ${CYAN}sinapse update${NC}.${NC}`);
+        logger.always(`${DIM}  Seguindo com a versão atual por enquanto...${NC}\n`);
+        // fall through to local re-sync below
+      }
+    } else if (latest) {
+      logger.always(`${GREEN}  Você já está na versão mais recente (v${VERSION}).${NC}\n`);
+    }
+  }
+
   // Welcome back screen
   logger.always(`${BOLD}  Que bom que voce voltou!${NC}`);
   logger.always(`${DIM}  Atualizando SNPS AI: v${prevVer} -> v${VERSION}${NC}`);

package/bin/lib/setup-statusline.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * Shared statusline + agent-tracker installer (D4).
+ *
+ * Single source of truth for cabling the SINAPSE statusline feedback loop into
+ * a user's global Claude Code config (`~/.claude/`). Consumed by both:
+ *   - bin/sinapse-init.js  (setupGlobalStatuslineLegacy)
+ *   - packages/installer/src/wizard/index.js
+ *
+ * What it installs:
+ *   - ~/.claude/statusline-script.js          (renders the statusline)
+ *   - ~/.claude/hooks/track-agent.cjs         (UserPromptSubmit detector — writes session-cache)
+ *   - ~/.claude/hooks/track-agent-clear.cjs   (Stop hook — clears session-cache on session end)
+ *   - ~/.claude/session-cache/                (per-cwd cache directory)
+ *   - settings.statusLine                     (graceful skip if already set)
+ *   - settings.hooks.UserPromptSubmit → track-agent.cjs   (idempotent guard)
+ *   - settings.hooks.Stop            → track-agent-clear.cjs (idempotent guard)
+ *
+ * Design notes:
+ *   - FAIL-SOFT: statusline is non-critical. Any unexpected error returns a
+ *     result object with `installed:false` + `reason`, never throws.
+ *   - Idempotent: re-running never duplicates hook entries or clobbers an
+ *     existing user statusLine.
+ *   - Detector is now `.cjs` (Node), not the legacy `.sh` (bash) — works on
+ *     Windows without a bash dependency.
+ */
+
+const os = require('os');
+const path = require('path');
+const fse = require('fs-extra');
+
+/**
+ * Resolve the canonical source paths for the statusline templates.
+ * @param {string} sourceCoreDir Absolute path to the installed `.sinapse-ai` directory.
+ */
+function resolveSources(sourceCoreDir) {
+  const templatesDir = path.join(sourceCoreDir, 'product', 'templates', 'statusline');
+  return {
+    templatesDir,
+    script: path.join(templatesDir, 'statusline-script.js'),
+    detector: path.join(templatesDir, 'track-agent.cjs'),
+    clear: path.join(templatesDir, 'track-agent-clear.cjs'),
+  };
+}
+
+/**
+ * Check whether an event array already has a hook whose command references `needle`.
+ * @param {Array} eventArr settings.hooks[event] array
+ * @param {string} needle substring to look for in the command (e.g. "track-agent-clear")
+ */
+function hasHookCommand(eventArr, needle) {
+  if (!Array.isArray(eventArr)) return false;
+  return eventArr.some((entry) => {
+    if (entry && Array.isArray(entry.hooks)) {
+      return entry.hooks.some((h) => h && h.command && h.command.includes(needle));
+    }
+    return entry && entry.command && entry.command.includes(needle);
+  });
+}
+
+/**
+ * Build the `node "<path>"` command string, escaping backslashes for JSON on Windows.
+ * @param {string} targetPath absolute path to the hook script
+ */
+function nodeCommand(targetPath) {
+  return `node "${targetPath.replace(/\\/g, '\\\\')}"`;
+}
+
+/**
+ * Install the SINAPSE statusline + agent trackers into the user's global Claude config.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.sourceCoreDir] Absolute path to the installed `.sinapse-ai` directory.
+ *   Defaults to the repo's `.sinapse-ai` relative to this module (`../../.sinapse-ai`).
+ * @param {string} [opts.homeDir] Override the home directory (testing). Defaults to os.homedir().
+ * @returns {Promise<{installed:boolean, reason?:string, statusLineSet:boolean, detectorHook:boolean, clearHook:boolean, files:string[]}>}
+ */
+async function setupStatusline(opts = {}) {
+  const result = {
+    installed: false,
+    statusLineSet: false,
+    detectorHook: false,
+    clearHook: false,
+    files: [],
+  };
+
+  try {
+    const homeDir = opts.homeDir || os.homedir();
+    const sourceCoreDir =
+      opts.sourceCoreDir || path.join(__dirname, '..', '..', '.sinapse-ai');
+
+    const sources = resolveSources(sourceCoreDir);
+
+    // Source templates must exist (statusline-script + the .cjs detector).
+    // track-agent-clear is best-effort — if missing we still install the rest.
+    if (!(await fse.pathExists(sources.script)) || !(await fse.pathExists(sources.detector))) {
+      result.reason = 'source templates missing (statusline-script.js or track-agent.cjs)';
+      return result;
+    }
+    const hasClear = await fse.pathExists(sources.clear);
+
+    const claudeDir = path.join(homeDir, '.claude');
+    const hooksDir = path.join(claudeDir, 'hooks');
+    const globalSettingsPath = path.join(claudeDir, 'settings.json');
+
+    const scriptTarget = path.join(claudeDir, 'statusline-script.js');
+    const detectorTarget = path.join(hooksDir, 'track-agent.cjs');
+    const clearTarget = path.join(hooksDir, 'track-agent-clear.cjs');
+
+    // Ensure directories (hooks + session-cache the trackers write to).
+    await fse.ensureDir(hooksDir);
+    await fse.ensureDir(path.join(claudeDir, 'session-cache'));
+
+    // Copy templates (overwrite is fine — these are framework-owned).
+    await fse.copy(sources.script, scriptTarget);
+    result.files.push(scriptTarget);
+    await fse.copy(sources.detector, detectorTarget);
+    result.files.push(detectorTarget);
+    if (hasClear) {
+      await fse.copy(sources.clear, clearTarget);
+      result.files.push(clearTarget);
+    }
+
+    // Read existing global settings (back-compat with any prior config).
+    let settings = {};
+    try {
+      if (await fse.pathExists(globalSettingsPath)) {
+        settings = JSON.parse(await fse.readFile(globalSettingsPath, 'utf8'));
+      }
+    } catch {
+      settings = {};
+    }
+
+    // statusLine — graceful skip if the user already configured one.
+    if (!settings.statusLine) {
+      settings.statusLine = {
+        type: 'command',
+        command: nodeCommand(scriptTarget),
+      };
+      result.statusLineSet = true;
+    }
+
+    // Hooks — register the .cjs detector (UserPromptSubmit) + clear (Stop), idempotently.
+    if (!settings.hooks || typeof settings.hooks !== 'object') {
+      settings.hooks = {};
+    }
+
+    if (!Array.isArray(settings.hooks.UserPromptSubmit)) {
+      settings.hooks.UserPromptSubmit = [];
+    }
+    if (!hasHookCommand(settings.hooks.UserPromptSubmit, 'track-agent.cjs')) {
+      settings.hooks.UserPromptSubmit.push({
+        matcher: '',
+        hooks: [{ type: 'command', command: nodeCommand(detectorTarget), timeout: 10 }],
+      });
+      result.detectorHook = true;
+    }
+
+    if (hasClear) {
+      if (!Array.isArray(settings.hooks.Stop)) {
+        settings.hooks.Stop = [];
+      }
+      if (!hasHookCommand(settings.hooks.Stop, 'track-agent-clear.cjs')) {
+        settings.hooks.Stop.push({
+          matcher: '',
+          hooks: [{ type: 'command', command: nodeCommand(clearTarget), timeout: 10 }],
+        });
+        result.clearHook = true;
+      }
+    }
+
+    await fse.ensureDir(path.dirname(globalSettingsPath));
+    await fse.writeFile(globalSettingsPath, JSON.stringify(settings, null, 2), 'utf8');
+
+    result.installed = true;
+    return result;
+  } catch (error) {
+    // Statusline is non-critical — never block an install.
+    result.reason = error && error.message ? error.message : 'unknown error';
+    return result;
+  }
+}
+
+module.exports = {
+  setupStatusline,
+  // Exported for testing / reuse.
+  resolveSources,
+  hasHookCommand,
+  nodeCommand,
+};

package/bin/sinapse-init.js

@@ -1000,92 +1000,20 @@ async function savePMConfig(pmTool, config, projectRoot) {
 }
 
 /**
- * Setup global statusline for Claude Code (legacy installer version)
- * Graceful skip: returns silently if user already has a statusLine configured.
+ * Setup global statusline for Claude Code (legacy installer version).
+ *
+ * Thin wrapper over the shared module (bin/lib/setup-statusline.js) so the
+ * legacy and wizard installers share ONE implementation. Installs:
+ *   - ~/.claude/statusline-script.js (graceful skip if user already has one)
+ *   - ~/.claude/hooks/track-agent.cjs        → UserPromptSubmit detector (.cjs, not .sh)
+ *   - ~/.claude/hooks/track-agent-clear.cjs  → Stop hook (clears session-cache)
+ *   - ~/.claude/session-cache/
+ * FAIL-SOFT: never throws — statusline is non-critical.
  * @param {string} sourceCoreDir - Path to installed .sinapse-ai directory
  */
 async function setupGlobalStatuslineLegacy(sourceCoreDir) {
-  const os = require('os');
-  const homeDir = os.homedir();
-  const globalSettingsPath = path.join(homeDir, '.claude', 'settings.json');
-
-  // Read existing global settings
-  let settings = {};
-  try {
-    if (fs.existsSync(globalSettingsPath)) {
-      settings = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
-    }
-  } catch {
-    settings = {};
-  }
-
-  // GRACEFUL SKIP: User already has a statusLine
-  if (settings.statusLine) {
-    return;
-  }
-
-  // Source templates
-  const templatesDir = path.join(sourceCoreDir, 'product', 'templates', 'statusline');
-  const scriptSource = path.join(templatesDir, 'statusline-script.js');
-  const hookSource = path.join(templatesDir, 'track-agent.sh');
-
-  if (!fs.existsSync(scriptSource) || !fs.existsSync(hookSource)) {
-    return;
-  }
-
-  // Target paths
-  const scriptTarget = path.join(homeDir, '.claude', 'statusline-script.js');
-  const hookTarget = path.join(homeDir, '.claude', 'hooks', 'track-agent.sh');
-
-  try {
-    await fse.ensureDir(path.join(homeDir, '.claude', 'hooks'));
-    await fse.ensureDir(path.join(homeDir, '.claude', 'session-cache'));
-    await fse.copy(scriptSource, scriptTarget);
-    await fse.copy(hookSource, hookTarget);
-  } catch {
-    return;
-  }
-
-  // Add statusLine + hook to settings
-  const scriptPathEscaped = scriptTarget.replace(/\\/g, '\\\\');
-  settings.statusLine = {
-    type: 'command',
-    command: `node "${scriptPathEscaped}"`,
-  };
-
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-  if (!Array.isArray(settings.hooks.UserPromptSubmit)) {
-    settings.hooks.UserPromptSubmit = [];
-  }
-
-  const hookPathEscaped = hookTarget.replace(/\\/g, '\\\\');
-  const alreadyHasTrackAgent = settings.hooks.UserPromptSubmit.some(entry => {
-    if (Array.isArray(entry.hooks)) {
-      return entry.hooks.some(h => h.command && h.command.includes('track-agent'));
-    }
-    return entry.command && entry.command.includes('track-agent');
-  });
-
-  if (!alreadyHasTrackAgent) {
-    settings.hooks.UserPromptSubmit.push({
-      matcher: '',
-      hooks: [
-        {
-          type: 'command',
-          command: `bash "${hookPathEscaped}"`,
-        },
-      ],
-    });
-  }
-
-  try {
-    await fse.ensureDir(path.dirname(globalSettingsPath));
-    await fse.writeFile(globalSettingsPath, JSON.stringify(settings, null, 2), 'utf8');
-  } catch {
-    // Silent failure — statusline is non-critical
-  }
+  const { setupStatusline } = require('./lib/setup-statusline');
+  await setupStatusline({ sourceCoreDir });
 }
 
 // Run installer with error handling

package/bin/utils/framework-guard.js

@@ -66,14 +66,27 @@ function globToRegex(glob) {
 
 /**
  * Read the raw content of core-config.yaml.
+ *
+ * Resolution order (so this works both as the in-repo hook AND when bundled
+ * into .sinapse-ai/git-hooks/lib/ by the installer, where __dirname no longer
+ * sits two levels under the project root):
+ *   1. `<cwd>/.sinapse-ai/core-config.yaml` — git runs hooks from the repo root,
+ *      so cwd is the project root in the pre-commit path.
+ *   2. `<__dirname>/../../.sinapse-ai/core-config.yaml` — the original in-repo
+ *      location (bin/utils -> repo root), kept for direct/test invocation.
  * @returns {string|null}
  */
 function readConfigContent() {
-  const configPath = path.resolve(__dirname, '../../.sinapse-ai/core-config.yaml');
-  if (!fs.existsSync(configPath)) {
-    return null;
+  const candidates = [
+    path.resolve(process.cwd(), '.sinapse-ai/core-config.yaml'),
+    path.resolve(__dirname, '../../.sinapse-ai/core-config.yaml'),
+  ];
+  for (const configPath of candidates) {
+    if (fs.existsSync(configPath)) {
+      return fs.readFileSync(configPath, 'utf8');
+    }
   }
-  return fs.readFileSync(configPath, 'utf8');
+  return null;
 }
 
 /**

package/bin/utils/secret-scanner-core.js

@@ -36,6 +36,16 @@ const NAMED_PATTERNS = [
   { name: 'GitHub Fine-Grained Token', pattern: /github_pat_[A-Za-z0-9_]{22,}/ },
   { name: 'Slack Token', pattern: /xox[bpors]-[0-9]{10,}-[A-Za-z0-9-]+/ },
   { name: 'Stripe Key', pattern: /[sr]k_(live|test)_[A-Za-z0-9]{20,}/ },
+  // OpenAI project-scoped keys (`sk-proj-…`) contain hyphens/underscores, so the
+  // generic `sk-[A-Za-z0-9]{20,}` rule below stops at the first hyphen and never
+  // matches the body. This explicit rule is CONCLUSIVE on shape (the `sk-proj-`
+  // prefix is unambiguous) and is NOT entropy-gated, so a leaked project key is
+  // caught even when its tail happens to score low on Shannon entropy.
+  { name: 'OpenAI Project Key', pattern: /sk-proj-[A-Za-z0-9_-]{40,}/ },
+  // Other OpenAI key families that also carry separators (svcacct / admin).
+  { name: 'OpenAI Service/Admin Key', pattern: /sk-(?:svcacct|admin)-[A-Za-z0-9_-]{20,}/ },
+  // Legacy/classic OpenAI keys (`sk-` + contiguous alnum). Entropy-gated to avoid
+  // tripping on `sk-` prefixed identifiers; threshold lowered to 3.0 (see note).
   { name: 'OpenAI Key', pattern: new RegExp('sk-[A-Za-z0-9]{20,}'), entropyGated: true },
   { name: 'Anthropic Key', pattern: new RegExp('sk-ant-[A-Za-z0-9-]{20,}') },
   { name: 'Supabase Key', pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]{50,}/ },
@@ -51,13 +61,28 @@ const NAMED_PATTERNS = [
   { name: 'Generic Private Key', pattern: new RegExp(BEGIN + PK + END5) },
 
   // Connection Strings
-  { name: 'DB Connection String', pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:]+:[^@]+@[^/\s]+/i },
-  { name: 'Supabase DB URL', pattern: /postgresql:\/\/postgres\.[A-Za-z0-9]+:[^@]+@/i },
+  // user/password are restricted to non-whitespace so the negated classes can't
+  // span newlines and match a bogus region across a whole file (the host part of
+  // a URL followed by an unrelated colon and at-sign on later lines). Real
+  // credentials never contain whitespace, so true detection is unaffected.
+  { name: 'DB Connection String', pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:\s]+:[^@\s]+@[^/\s]+/i, credentialPlaceholderGated: true },
+  { name: 'Supabase DB URL', pattern: /postgresql:\/\/postgres\.[A-Za-z0-9]+:[^@\s]+@/i, credentialPlaceholderGated: true },
 
   // Generic Patterns (broader, lower confidence — placeholder-allowlisted)
   { name: 'Hardcoded Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*['"][^'"]{8,}['"]/i, lowConfidence: true },
   { name: 'Bearer Token', pattern: /[Bb]earer\s+[A-Za-z0-9_\-.]{20,}/, entropyGated: true, lowConfidence: true },
   { name: 'Basic Auth', pattern: /[Bb]asic\s+[A-Za-z0-9+/=]{20,}/, lowConfidence: true },
+
+  // Long pure-hex runs (32–64 chars). The 16-symbol hex alphabet caps Shannon
+  // entropy at ~4.0, BELOW ENTROPY_THRESHOLD (4.5), so the generic entropy
+  // backstop never sees them — Twilio auth tokens (32-hex), webhook signing
+  // secrets and SHA-style 64-hex digests slip through. This explicit rule closes
+  // that gap. It is `hashContextGated`: a hex run sitting in an integrity /
+  // checksum / lockfile / git-sha context (covered by HASH_CONTEXT_PATTERN) is a
+  // legitimate hash, NOT a secret, and is allowlisted. `lowConfidence` keeps it
+  // OUT of the release publish gate (entropy:false there would otherwise match
+  // every documented digest); the diff-scoped commit hook still enforces it.
+  { name: 'Long Hex Token', pattern: /\b[a-f0-9]{32,64}\b/i, hashContextGated: true, lowConfidence: true },
 ];
 
 const PLACEHOLDER_TOKENS = [
@@ -86,19 +111,48 @@ const PLACEHOLDER_PATTERNS = [
 
 const EXAMPLE_HOST_PATTERN = /(?:example\.(?:com|org|net)|localhost|127\.0\.0\.1|host\b|your-host|placeholder)/i;
 
+// A keyword placeholder only allowlists when it DOMINATES the value: once every
+// placeholder occurrence is removed, the TOTAL alphanumeric length that remains
+// is too short to be a secret on its own (< ENTROPY_MIN_LEN). A bare
+// `lower.includes(token)` was a trivial bypass — ANY real secret that happened to
+// contain "abcdef" / "123456" / "example" anywhere in its body got silently
+// allowlisted (e.g. Xq9Zk2…abcdef…Fg5 passed). Measuring the *total* remainder
+// (not just the longest contiguous run) closes that hole even when the buried
+// placeholder splits the secret into two sub-threshold runs: the legitimate
+// cases (your-key-here, placeholder123456, test-key-example, CHANGEME) strip down
+// to nothing, while a 35-char random token minus a 6-char placeholder still has
+// ~29 alphanumeric chars left and is NOT allowlisted.
+function placeholderDominates(lower) {
+  let stripped = lower;
+  let matchedAny = false;
+  for (const token of PLACEHOLDER_TOKENS) {
+    if (stripped.includes(token)) {
+      matchedAny = true;
+      // Replace with a separator so adjacent runs aren't fused into a longer one.
+      stripped = stripped.split(token).join(' ');
+    }
+  }
+  if (!matchedAny) return false;
+  // Total alphanumeric chars left after removing every placeholder occurrence.
+  const remaining = (stripped.match(/[a-z0-9]/g) || []).length;
+  return remaining < ENTROPY_MIN_LEN;
+}
+
 function isAllowlistPlaceholder(value) {
   if (value === null || value === undefined) return false;
   const v = String(value).trim();
   if (v.length === 0) return true;
 
-  const lower = v.toLowerCase();
-  for (const token of PLACEHOLDER_TOKENS) {
-    if (lower.includes(token)) return true;
-  }
+  // Structural placeholders are always safe: <...>, [...], {token}, ${VAR},
+  // SCREAMING_SNAKE env-var names, and repeated single-symbol fillers.
   for (const re of PLACEHOLDER_PATTERNS) {
     if (re.test(v)) return true;
   }
   if (/^(.)\1{5,}$/.test(v)) return true; // repeated single char
+
+  // Keyword placeholders: word-boundary anchored + dominance, NOT raw includes().
+  if (placeholderDominates(v.toLowerCase())) return true;
+
   return false;
 }
 
@@ -168,10 +222,58 @@ function scanContent(content, options = {}) {
       if (isAllowlistPlaceholder(valuePart)) continue;
     }
 
+    if (descriptor.credentialPlaceholderGated) {
+      // A connection string carries a structured user:password@host. When the
+      // password slot is a placeholder/interpolation (${VAR}, <pass>, a
+      // SCREAMING_SNAKE env-var name, your-password…) it is a template/example,
+      // NOT a leaked credential — and is the idiomatic, safe way to document
+      // one. A real leaked password (random/literal) is not allowlisted and is
+      // still flagged.
+      const cred = (matched.match(/:\/\/[^:/\s]+:([^@\s]+)@/) || [null, ''])[1];
+      if (cred && isAllowlistPlaceholder(cred)) continue;
+    }
+
     if (descriptor.entropyGated) {
       const tail = (matched.match(/[A-Za-z0-9_\-/+=]{16,}$/) || [matched])[0];
       if (isAllowlistPlaceholder(tail)) continue;
-      if (shannonEntropy(tail) < 2.5) continue; // clearly non-random
+      // Threshold lowered 2.5 -> 2.0: a short real token (e.g. a 20-char legacy
+      // key with a narrow alphabet) can dip just under 2.5 and would have been a
+      // false-NEGATIVE (leaked secret allowed through). 2.0 still rejects obvious
+      // non-random fixtures (a single repeated char ~ 0.0, repeated words ~1.5)
+      // while no longer dropping legitimately-shaped keys.
+      if (shannonEntropy(tail) < 2.0) continue; // clearly non-random
+    }
+
+    if (descriptor.hashContextGated) {
+      // Long hex runs are flagged as suspected secrets (Twilio token, webhook
+      // signing secret, SHA-style digest) EXCEPT when they sit in an integrity /
+      // checksum / lockfile / git-sha context — those are legitimate hashes, not
+      // leaked credentials. Reuse HASH_CONTEXT_PATTERN over a window around the
+      // match so package-lock integrity:, "resolved" tarball #sha, "checksum",
+      // and 40/64-hex git shas are NOT false-positived. A fully repeated/obvious
+      // placeholder hex (deadbeef…, 000…) is also allowlisted.
+      if (isAllowlistPlaceholder(matched)) continue;
+      if (isLockfilePath(filePath)) continue;
+      // Canonical digest lengths — git SHA-1 (40) and SHA-256 (64) — are
+      // overwhelmingly legitimate hashes (commit refs, file checksums, content
+      // digests) and appear bare in changelogs/docs/lockfiles. Treating every
+      // isolated 40/64-hex run as a leak would false-positive on the entire git
+      // ecosystem, so these exact lengths are hash-shaped by default. The
+      // headline real-secret case (Twilio auth token = 32-hex) and other
+      // non-digest lengths (33–39, 41–63) are NOT standard digests and stay
+      // flagged. A leaked literal hash secret of EXACTLY 40/64 hex is the
+      // accepted blind spot of this length-based heuristic (documented tradeoff
+      // favouring zero false-positives on git/checksum hashes).
+      const hexLen = matched.length;
+      if (hexLen === 40 || hexLen === 64) continue;
+      // For non-canonical lengths, allowlist only when the SURROUNDING context
+      // carries a hash marker (integrity:, sha256-, "resolved", "checksum"). The
+      // window is widened on the left so a marker earlier on the line
+      // (e.g. `"resolved": "https://…/x.tgz#<hex>"`) is still seen.
+      const mIdx = text.indexOf(matched);
+      const before = text.slice(Math.max(0, mIdx - 64), mIdx);
+      const after = text.slice(mIdx + matched.length, mIdx + matched.length + 4);
+      if (HASH_CONTEXT_PATTERN.test(before + ' ' + after)) continue;
     }
 
     findings.push({ name: descriptor.name, redacted: redactMatch(matched), kind: 'pattern' });