residoo 0.3.0 → 0.3.2

package/README.md

@@ -91,8 +91,22 @@ won't be built into the tool that writes it.
 - Scans your local AI-agent session transcripts for high-confidence secret
   patterns: cloud provider keys, private key blocks, OAuth/API tokens,
   database connection strings, and more (see `src/patterns.js`).
+- Sees through two transcript-specific disguises. A credential present only
+  base64-encoded on a line (an env dump piped through `base64`, wrap
+  newlines included) is decoded and rescanned with the high-confidence
+  vendor-prefixed rules; the report marks it `base64-wrapped` and redacts
+  the decoded value. A credential split across two adjacent streaming
+  records, contiguous on neither line, is rejoined at the content boundary
+  and rescanned; the report marks it `split across lines` with the line
+  pair. Both are general mechanisms with stated limits (one decode level,
+  no base64 blocks spanning physical lines, two-way splits only; see
+  `src/decode.js`).
+- Covers Stripe keys in both modes: live (`sk_live`/`rk_live`) and test
+  (`sk_test`/`rk_test`), because a leaked test key still holds real
+  permissions in its sandbox and reveals account structure.
 - Redacts everything in its own output. You get a shape and a first/last-4
-  preview, never the real value, including in `--json` mode.
+  preview, never the real value, including in `--json` mode. A decoded or
+  rejoined secret is redacted exactly like a plain one.
 - Tells you how many **distinct** secrets it found versus how many times one
   got echoed back across tool calls, so the headline number reflects real
   exposure, not repetition.
@@ -123,7 +137,11 @@ packages, because Claude Code's approved-command cache quietly accumulates
 tokens and no packaging tool ignores `.claude/` by default. So as of v0.2.0,
 `residoo scan` includes an **agent config source** covering the home-level
 config files of Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex, and
-Kiro. Every path is verified against a real install or published sources (one
+Kiro. As of v0.3.1 it also reaches project-level Claude Code configs
+(`.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`) by
+resolving the project roots the agent itself recorded at home level
+(`~/.claude.json` and transcript `cwd` fields) rather than by walking or
+guessing directories; only those vendor-fixed per-project filenames are read. Every path is verified against a real install or published sources (one
 disclosed exception, a stealer-target path backed by a single published
 list, argued openly in the source header), with the full verification trail
 written into `src/sources/agent-configs.js`.
@@ -172,7 +190,7 @@ counted as clean.
   │            ├──────────────┬───────────────┤                   │
   │            ▼              │               ▼                   │
   │   stream + match          │        integrity checks           │
-  │   35 verified rules       │        hooks · droppers ·         │
+  │   36 verified rules       │        hooks · droppers ·         │
   │            │              │        zero-width unicode         │
   │            ▼              ▼               │                   │
   │        redacted report (first/last 4 chars only) ◀────────────┤
@@ -231,7 +249,7 @@ it" leaves all of that untouched. So every finding in a residoo report comes
 with the way out:
 
 - **A rotation hint per finding**, from a per-rule guidance map covering all
-  35 detection rules (plus the opt-in noisy ones). Where a rotation URL is
+  36 detection rules (plus the opt-in noisy ones). Where a rotation URL is
   shown, that exact URL was fetched and confirmed to document rotating or
   revoking that credential type; where a vendor's docs are login-walled or
   unfetchable, the report gives the console path in words instead of a link
@@ -454,10 +472,19 @@ submitting. See the note above on why that matters here specifically.
 
 Shape-based detection can't tell a real secret from a realistic-looking
 example in a fetched web page or a piece of documentation your agent read
-aloud back to you. The `--include-suppressed`/placeholder-context heuristic
-catches the common UI-hint case, not every case. Treat every finding as a
-lead to check, not a certainty. The same is true of every tool in this
-category, including the well-established ones.
+aloud back to you. Three suppression layers narrow the gap: known
+vendor-documented example values (AWS's `AKIAIOSFODNN7EXAMPLE` and its
+siblings, GitHub's docs tokens, jwt.io's demo token) are suppressed by
+exact match; a placeholder body built from one repeated character (no
+vendor issues zero-entropy key material) is suppressed by value; and
+placeholder-looking context around a match catches the common UI-hint
+case. The two value-based layers apply identically to base64-decoded and
+boundary-joined findings, since a decoded example is the same non-secret
+as a plain one. None of the three catches every case, and all are
+re-includable with `--include-suppressed`. Treat every finding as a lead
+to check, not a
+certainty. The same is true of every tool in this category, including the
+well-established ones.
 
 ## License
 

package/package.json

@@ -1,19 +1,45 @@
 {
   "name": "residoo",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",
-  "repository": { "type": "git", "url": "git+https://github.com/dandovdub/residoo.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dandovdub/residoo.git"
+  },
   "homepage": "https://github.com/dandovdub/residoo#readme",
-  "bugs": { "url": "https://github.com/dandovdub/residoo/issues" },
-  "bin": { "residoo": "bin/residoo.js" },
+  "bugs": {
+    "url": "https://github.com/dandovdub/residoo/issues"
+  },
+  "bin": {
+    "residoo": "bin/residoo.js"
+  },
   "main": "src/cli.js",
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node tests/smoke.js" },
-  "files": ["bin", "src", "README.md", "SECURITY.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node tests/smoke.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "security", "secrets", "secret-scanning", "ai-agent", "claude-code",
-    "cursor", "copilot", "mcp", "privacy", "cli", "encryption"
+    "security",
+    "secrets",
+    "secret-scanning",
+    "ai-agent",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "mcp",
+    "privacy",
+    "cli",
+    "encryption"
   ]
 }

package/src/decode.js

@@ -0,0 +1,416 @@
+"use strict";
+
+/**
+ * Two general engine mechanisms that recover credentials a line-oriented
+ * regex pass alone cannot see. Both are content transforms feeding the SAME
+ * detection PATTERNS; neither adds a new rule. They are deliberately schema
+ * agnostic (they never look at transcript field names), because residoo scans
+ * many tools' formats and must not key on any one of them.
+ *
+ *   1. base64 decode-then-rescan (findDecodedMatches)
+ *   2. split-line boundary join   (findBoundaryMatches)
+ *
+ * Both return the DECODED / RECONSTRUCTED plaintext secret to the caller,
+ * which is responsible for redaction: like the raw matcher in scan.js, the
+ * secret value lives only in-process and never reaches a report unredacted.
+ * A decoded or reconstructed secret is still a secret.
+ */
+
+// ── Feature 1: base64 decode-then-rescan ────────────────────────────────────
+//
+// Agents routinely print credentials only in encoded form (a `base64 config`
+// dump, an env file pasted as one blob), so the raw pattern never sees the
+// key. We locate base64 runs in a line, decode them, and re-run the
+// high-confidence patterns over the decoded text.
+//
+// WRAP TOLERANCE: `base64` output is line-wrapped (RFC 2045 MIME wraps at 76
+// columns; the base64 CLI does too). When that wrapped output is embedded in
+// a JSON string (a JSONL transcript's tool_result), each wrap newline is
+// serialized as the two characters backslash+n. So a single logical base64
+// blob shows up on one physical line as several runs separated by real
+// whitespace or by the escape sequences \n \r \t. We treat those separators
+// as part of one candidate and strip them before decoding, exactly as any
+// base64 decoder ignores whitespace. This is the transcript-relevant wrap
+// case and stays within one physical line.
+//
+// LIMITS (general, honestly stated):
+//  - Only high-confidence, vendor-prefixed patterns are applied to decoded
+//    text. Random binary that happens to decode to printable bytes can shape
+//    match a generic/entropy rule; a vendor prefix (AKIA, ghp_, ...) cannot
+//    be forged by accident, so restricting to those keeps decode-path false
+//    positives near zero.
+//  - base64 wrapped across REAL physical newlines (a PEM/MIME block spanning
+//    several lines of a plain-text file) is out of this per-line pass's
+//    scope. So is hex encoding. Both are future work, left out here rather
+//    than half-done.
+//  - One decode level only: we do not recursively decode base64-in-base64.
+//  - A neighbor token glued onto a wrapped blob across the wrap newline (a
+//    command word or filename directly above or below the encoded output)
+//    is recovered by retrying the decode with ONE edge chunk dropped — but
+//    only one, and only at an edge: junk on both edges, or prose merged into
+//    the middle of a blob, still loses the whole candidate.
+//  - There is deliberately NO per-line candidate cap. Real transcript lines
+//    routinely hold hundreds of decode-sized alnum runs (uuids, hashes,
+//    request ids), so any cap either silently starves a genuine blob
+//    sitting past it or flags nearly every real file as partially checked.
+//    None is needed for cost: each character belongs to at most one
+//    candidate and decoding is a few linear passes, so total work per line
+//    is O(line length) with small constants, and line length is already
+//    bounded by the sources' own file-read caps.
+
+// A run is made of characters that can appear in base64 or base64url:
+// A-Z a-z 0-9 + / = _ - (see isB64Code). Wrap separators between chunks of
+// one logical blob are line breaks (CR, LF) only — the whitespace that base64
+// line-wrapping actually emits. TAB and space are NOT separators: base64
+// wrapping never uses either, and merging across them splices adjacent cells
+// of tabbed or spaced output into one dead candidate. When wrapped base64 is
+// embedded in a JSON string the line breaks arrive as the escape sequences
+// \n \r \t (two chars, backslash+letter); normalizeEscapes() turns those
+// into the real characters first, so the escape's letter can never leak into
+// a run (a real TAB then dirties the gap like any non-wrap character).
+// Candidate runs are located by a hand-rolled single-pass character scan,
+// NOT a regex. The obvious regex forms both fail on real data: a repeated
+// group (chunk (sep chunk)*) recurses per repetition, and even a plain
+// character-class quantifier pushes a backtrack frame per matched character
+// in V8 — either one overflows the call stack on the multi-megabyte single
+// lines that real transcripts contain (observed on a 7MB tool_result line).
+// A char-code loop is O(n) with O(1) stack, whatever the line looks like.
+const B64_MIN_CHUNK = 4;
+
+const B64_MIN_CHARS = 24;          // fewer chars cannot hide a real credential
+const B64_MAX_ENCODED = 90000;     // ~64KB decoded ceiling; skip bigger runs
+const PRINTABLE_MIN = 0.85;        // decoded bytes must be mostly text to rescan
+
+/** JSON whitespace escapes -> the real line breaks they stand for. */
+function normalizeEscapes(line) {
+  return line.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "\t");
+}
+
+/**
+ * Chunk runs merged into logical candidates: consecutive chunks whose gap
+ * consists solely of wrap line breaks are one wrapped blob (its separators
+ * dropped, exactly as any base64 decoder ignores whitespace); any other gap
+ * (a space, TAB, prose, punctuation) ends the candidate. Iterative on
+ * purpose — see the character-scan note above isB64Code.
+ *
+ * Each candidate is returned as its ARRAY of chunks, not pre-joined: the
+ * decode step needs the chunk boundaries to retry with an edge chunk dropped
+ * (see findDecodedMatches). Candidates shorter than B64_MIN_CHARS joined are
+ * discarded here for free: they can never decode (decodeToText rejects them
+ * by length), and most base64-charset runs on a line are exactly such short
+ * prose words and ids.
+ */
+function isB64Code(c) {
+  return (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) ||
+    c === 43 || c === 47 || c === 61 || c === 95 || c === 45; // + / = _ -
+}
+
+/**
+ * "=" can only be terminal padding in valid base64, so an "=" group with more
+ * base64 characters after it inside one run separates two independent values
+ * glued together — the common shapes being an env assignment (`NAME=<blob>`,
+ * where the variable name and "=" would otherwise poison the blob) and a
+ * padding-terminated blob directly followed by more encoded content. Split
+ * there, keeping the padding attached to the value it terminates.
+ */
+function splitAtPadding(chunk) {
+  const parts = [];
+  let start = 0;
+  for (let k = 0; k < chunk.length - 1; k++) {
+    if (chunk.charCodeAt(k) === 61 && chunk.charCodeAt(k + 1) !== 61) { // "=" then non-"="
+      parts.push(chunk.slice(start, k + 1));
+      start = k + 1;
+    }
+  }
+  parts.push(chunk.slice(start));
+  return parts;
+}
+
+function b64Candidates(norm) {
+  const candidates = []; // array of chunk arrays
+  let current = null;   // chunk array of the candidate in progress
+  let runStart = -1;    // start of the b64 run in progress, -1 when not in one
+  let gapClean = true;  // gap since the last chunk held only \r \n
+  const push = (cand) => {
+    let len = 0;
+    for (const c of cand) len += c.length;
+    if (len >= B64_MIN_CHARS) candidates.push(cand);
+  };
+  const n = norm.length;
+  for (let i = 0; i <= n; i++) {
+    const c = i < n ? norm.charCodeAt(i) : -1; // one virtual terminator flushes the last run
+    if (c !== -1 && isB64Code(c)) {
+      if (runStart < 0) runStart = i;
+      continue;
+    }
+    if (runStart >= 0) {
+      const raw = norm.slice(runStart, i);
+      runStart = -1;
+      if (raw.length >= B64_MIN_CHUNK) {
+        const parts = splitAtPadding(raw);
+        for (let p = 0; p < parts.length; p++) {
+          if (p === 0 && current !== null && gapClean) current.push(parts[p]);
+          else {
+            if (current !== null) push(current);
+            current = [parts[p]];
+          }
+          // A part ending in padding is a complete value: nothing after it —
+          // not even across a clean wrap gap — can belong to the same blob.
+          if (parts[p].charCodeAt(parts[p].length - 1) === 61) {
+            push(current);
+            current = null;
+          }
+        }
+        gapClean = true;
+      } else {
+        // A sub-minimum run is gap content, not a chunk: it breaks the wrap.
+        gapClean = false;
+      }
+    }
+    // Line breaks (CR, LF) keep a wrap gap clean; anything else — TAB and
+    // space included, base64 wrapping uses neither — dirties it.
+    if (c !== -1 && c !== 10 && c !== 13) gapClean = false;
+  }
+  if (current !== null) push(current);
+  return candidates;
+}
+
+/**
+ * Decode a cleaned base64 run to text, or null if it is not decodable, is too
+ * large, or decodes to mostly non-printable bytes (i.e. is not text worth
+ * rescanning). Returns { text, encoding } where encoding is "base64url" when
+ * the run used the URL-safe alphabet, else "base64".
+ */
+function decodeToText(cleaned) {
+  if (cleaned.length < B64_MIN_CHARS || cleaned.length > B64_MAX_ENCODED) return null;
+  // A wrapped blob decodes as one unit; a run that is not wholly base64 after
+  // cleaning is not a base64 blob.
+  if (!/^[A-Za-z0-9+/=_-]+$/.test(cleaned)) return null;
+  const urlSafe = /[-_]/.test(cleaned);
+  const std = urlSafe ? cleaned.replace(/-/g, "+").replace(/_/g, "/") : cleaned;
+  let buf;
+  try {
+    buf = Buffer.from(std, "base64");
+  } catch (e) {
+    return null;
+  }
+  if (!buf.length || buf.length > 65536) return null;
+  // Printable gate first (a cheap byte loop): most non-base64 alnum runs
+  // (uuids, hashes, request ids) decode to non-text and are rejected here
+  // before the costlier round-trip re-encode runs.
+  let printable = 0;
+  for (const b of buf) {
+    if (b === 9 || b === 10 || b === 13 || (b >= 32 && b <= 126)) printable++;
+  }
+  if (printable / buf.length < PRINTABLE_MIN) return null;
+  // Round-trip guard: Buffer.from is lenient and will "decode" strings that
+  // are not really base64 by dropping stray bytes. If re-encoding does not
+  // reproduce the input (modulo padding), this was not a base64 blob and its
+  // "decoded" bytes are noise we should not rescan.
+  const reenc = buf.toString("base64").replace(/=+$/, "");
+  if (reenc !== std.replace(/=+$/, "")) return null;
+  return { text: buf.toString("utf8"), encoding: urlSafe ? "base64url" : "base64" };
+}
+
+/**
+ * Find credentials that appear only base64-encoded on one line. `rules` MUST
+ * be the high-confidence subset (see LIMITS above). Returns
+ * [{ ruleId, label, confidence, value, encoding }] with `value` the DECODED
+ * secret (caller redacts), deduped by rule+value so a blob echoed twice on
+ * one line (content plus tool-result mirror) is one entry.
+ */
+function findDecodedMatches(line, rules) {
+  const out = [];
+  const seen = new Set();
+  const norm = normalizeEscapes(line);
+  for (const chunks of b64Candidates(norm)) {
+    // A wrap-merged candidate can carry one glued-on neighbor token: a word
+    // or filename sitting directly above or below the blob across the wrap
+    // newline merges into the candidate and breaks the decode (alignment
+    // shift or round-trip failure). When the full join fails, retry once
+    // with the first chunk dropped and once with the last chunk dropped —
+    // the two positions a foreign neighbor can occupy. LIMIT: one edge
+    // chunk only; junk on both edges or prose merged mid-blob still loses
+    // the candidate. The round-trip guard in decodeToText applies to every
+    // retry, so a retry can not "decode" junk into findings.
+    const attempts = [chunks.join("")];
+    if (chunks.length > 1) {
+      attempts.push(chunks.slice(1).join(""));
+      attempts.push(chunks.slice(0, -1).join(""));
+    }
+    let decoded = null;
+    for (const a of attempts) { decoded = decodeToText(a); if (decoded) break; }
+    if (!decoded) continue;
+    for (const rule of rules) {
+      rule.re.lastIndex = 0;
+      let m;
+      while ((m = rule.re.exec(decoded.text)) !== null) {
+        const key = rule.id + "\u0000" + m[0];
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push({ ruleId: rule.id, label: rule.label, confidence: rule.confidence, value: m[0], encoding: decoded.encoding });
+        }
+        if (m.index === rule.re.lastIndex) rule.re.lastIndex++;
+      }
+    }
+  }
+  return out;
+}
+
+// ── Feature 2: split-line boundary join ─────────────────────────────────────
+//
+// Streaming agents write a single assistant/user turn as several adjacent
+// records, so a value can be split across two lines and never appear
+// contiguously on either. We reconstruct the boundary and rescan it.
+//
+// The two fragments are the TAIL of the content on line A and the HEAD of the
+// content on line B. In a JSONL transcript the conversational content is one
+// string VALUE buried inside a per-record JSON envelope (ids, usage, cwd,
+// timestamps), often hundreds of characters from the physical line edge. The
+// "JSONL structural seam" separating the two fragments is therefore that
+// whole envelope, not a couple of punctuation chars. We strip it in a general
+// way: project each line to its free-text payload before taking the window.
+//
+// CONTENT PROJECTION: on a JSON line the free-text payload is the longest
+// string VALUE. Conversational text (a sentence, a pasted blob) is long;
+// structural metadata (uuids, model names, enums, paths, timestamps) is
+// short. This is a property of records that wrap a message, true across agent
+// transcript formats, and it never references a field name. Non-JSON lines
+// (plain-text chat logs, shell history) are used as-is.
+//
+// LIMITS (general, honestly stated):
+//  - Two-way splits only. A value broken across three or more records, or
+//    with unrelated records interleaved between the halves, is out of scope.
+//  - The projection assumes the split value lives in the line's LONGEST
+//    string. A record whose longest string is not the conversational content
+//    (e.g. a huge embedded blob or a very long path) defeats it.
+//  - Only BOUNDARY_WINDOW chars from each side of the seam are joined, so a
+//    fragment longer than that window (possible only for unbounded-length
+//    token shapes) is not reconstructed; the raw pass still fires on any
+//    prefix-bearing fragment, so the window never causes a silent all-clear.
+//  - A reconstructed match must straddle the seam; a match lying wholly
+//    within either original line is already reported by the single-line pass
+//    and is dropped here, so nothing is double-counted.
+//  - GREEDY-EXTENSION GUARD: a rule with an open-ended quantifier that
+//    matches a value ending flush at line A's content end would "straddle"
+//    by swallowing whatever alphanumeric characters happen to start line B's
+//    content — fabricating a longer, never-existing value out of a complete
+//    match plus its neighbor. So a straddling match is dropped when the same
+//    rule already produces a complete match ending exactly at the seam (or
+//    starting exactly at it) that the straddling match merely extends. The
+//    cost, accepted knowingly: a token split so that its first fragment is
+//    BY ITSELF a complete valid match of the same rule is reported as that
+//    fragment (by the raw pass) rather than reconstructed — for fixed-length
+//    token shapes, the common case, no such ambiguity exists.
+
+const BOUNDARY_WINDOW = 300;   // chars taken from each side of the seam
+const BOUNDARY_MIN_CONTENT = 24; // shorter "longest string" is treated as non-content
+
+/**
+ * Escape-aware list of JSON string-literal CONTENTS on a line. Field names
+ * are included (this walker does not distinguish keys from values); the
+ * longest-value projection below makes short structural strings lose, which
+ * is what keeps keys out of the projection in practice.
+ */
+function jsonStringValues(line) {
+  const out = [];
+  const n = line.length;
+  let i = 0;
+  while (i < n) {
+    if (line[i] === '"') {
+      let j = i + 1;
+      let buf = "";
+      while (j < n) {
+        const ch = line[j];
+        if (ch === "\\") { buf += ch + (line[j + 1] || ""); j += 2; continue; }
+        if (ch === '"') break;
+        buf += ch;
+        j++;
+      }
+      out.push(buf);
+      i = j + 1;
+    } else i++;
+  }
+  return out;
+}
+
+/** Project a line to its free-text payload (see CONTENT PROJECTION above). */
+function contentProjection(line) {
+  const t = line.trim();
+  if (t[0] === "{" || t[0] === "[") {
+    let longest = "";
+    for (const s of jsonStringValues(line)) if (s.length > longest.length) longest = s;
+    if (longest.length >= BOUNDARY_MIN_CONTENT) return longest;
+  }
+  return line;
+}
+
+/**
+ * Find credentials split across the boundary of two adjacent lines. Takes the
+ * CONTENT PROJECTIONS of the two lines (from contentProjection), which the
+ * caller computes once per line and reuses across both of that line's pairs.
+ * Returns [{ ruleId, label, confidence, value }] for matches that straddle
+ * the seam; `value` is the reconstructed secret (caller redacts). Deduped by
+ * rule+value.
+ */
+function findBoundaryMatches(contentA, contentB, rules) {
+  const tail = contentA.slice(-BOUNDARY_WINDOW);
+  const head = contentB.slice(0, BOUNDARY_WINDOW);
+  if (!tail || !head) return [];
+  const joined = tail + head;
+  const seam = tail.length;
+  const out = [];
+  const seen = new Set();
+
+  // GREEDY-EXTENSION GUARD (see LIMITS above): the start positions of this
+  // rule's complete matches in the tail ALONE that end flush at the seam,
+  // and the end positions (in joined coordinates) of its complete matches
+  // in the head ALONE that start flush at the seam. A straddling match that
+  // shares a start with the former or an end with the latter is a complete
+  // single-line match greedily extended across the seam, not a
+  // reconstruction, and reporting it would fabricate a value that exists
+  // nowhere. Computed lazily: most pairs produce no straddling match.
+  const seamFlush = (rule) => {
+    const startsAtSeamEnd = new Set();
+    const endsFromSeamStart = new Set();
+    let t;
+    rule.re.lastIndex = 0;
+    while ((t = rule.re.exec(tail)) !== null) {
+      if (t.index + t[0].length === seam) startsAtSeamEnd.add(t.index);
+      if (t.index === rule.re.lastIndex) rule.re.lastIndex++;
+    }
+    rule.re.lastIndex = 0;
+    while ((t = rule.re.exec(head)) !== null) {
+      if (t.index === 0) endsFromSeamStart.add(seam + t[0].length);
+      if (t.index === rule.re.lastIndex) rule.re.lastIndex++;
+    }
+    return { startsAtSeamEnd, endsFromSeamStart };
+  };
+
+  for (const rule of rules) {
+    const straddles = [];
+    rule.re.lastIndex = 0;
+    let m;
+    while ((m = rule.re.exec(joined)) !== null) {
+      const start = m.index;
+      const end = m.index + m[0].length;
+      // Straddle-only: the match must cross the seam, else it lay wholly in
+      // one line and the single-line pass already reported it.
+      if (start < seam && end > seam) straddles.push({ start, end, value: m[0] });
+      if (m.index === rule.re.lastIndex) rule.re.lastIndex++;
+    }
+    let flush = null;
+    for (const p of straddles) {
+      if (flush === null) flush = seamFlush(rule);
+      if (flush.startsAtSeamEnd.has(p.start) || flush.endsFromSeamStart.has(p.end)) continue;
+      const key = rule.id + "\u0000" + p.value;
+      if (!seen.has(key)) {
+        seen.add(key);
+        out.push({ ruleId: rule.id, label: rule.label, confidence: rule.confidence, value: p.value });
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = { findDecodedMatches, findBoundaryMatches, contentProjection };

package/src/patterns.js

@@ -26,8 +26,26 @@ const PATTERNS = [
     re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
   { id: "slack_token", label: "Slack token", confidence: "high",
     re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g },
-  { id: "stripe_key", label: "Stripe API key", confidence: "high",
+  { id: "stripe_key", label: "Stripe API key (live mode)", confidence: "high",
     re: /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/g },
+  // The sandbox-mode twin of the rule above, same body charset and the same
+  // 20-char floor. Format verified against two production detectors plus the
+  // vendor (2026-09-02): gitleaks' stripe-access-token rule matches
+  // (sk|rk)_(test|live|prod)_[a-zA-Z0-9]{10,99}; trufflehog's Stripe
+  // detector is [rs]k_live_[a-zA-Z0-9]{20,247} with an explicit
+  // "doesn't include test keys" comment (a scope choice, not a format
+  // claim); and Stripe's own docs (docs.stripe.com/keys) name sk_test_ and
+  // rk_test_ as the sandbox secret/restricted prefixes. A separate rule
+  // rather than a widened live regex so a report can say WHICH mode leaked
+  // and rotation guidance can differ. A test key in a transcript is a real
+  // finding, not noise: the prefix is vendor-unique, the key grants full
+  // API access to the sandbox account (Stripe's docs: a secret key has
+  // unrestricted permissions on all Stripe APIs in its mode, and sandbox
+  // mode exposes ALL of the account's keys to whoever can call it), and a
+  // transcript that pastes sk_test today is the same workflow that will
+  // paste sk_live at go-live.
+  { id: "stripe_test_key", label: "Stripe API key (test mode)", confidence: "high",
+    re: /\b(sk|rk)_test_[A-Za-z0-9]{20,}\b/g },
   // The negative lookahead keeps this rule mutually exclusive with anthropic_key
   // and openrouter_key below — without it, "sk-ant-..." or "sk-or-v1-..." match
   // BOTH this pattern and the more specific one, and get reported twice under

package/src/report.js

@@ -216,7 +216,16 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
     const distinctNote = distinct && distinct !== items.length
       ? paint(c.dim, `  (${distinct} distinct value${distinct === 1 ? "" : "s"}, re-exposed ${items.length - distinct}× across tool output)`)
       : "";
-    push(`  ${paint(c.bold, String(items.length).padStart(4))}  [${tag}]  ${label}${distinctNote}`);
+    // Flag when a rule's matches came from a decode/reconstruct pass rather
+    // than plain text: those would be invisible to a line-oriented scanner,
+    // so the reader should know the value was hidden.
+    const encoded = items.filter((f) => f.encoding).length;
+    const split = items.filter((f) => f.spanLines).length;
+    const marks = [];
+    if (encoded) marks.push(`${encoded} base64-wrapped`);
+    if (split) marks.push(`${split} split across lines`);
+    const markNote = marks.length ? paint(c.yellow, `  [${marks.join(", ")}]`) : "";
+    push(`  ${paint(c.bold, String(items.length).padStart(4))}  [${tag}]  ${label}${distinctNote}${markNote}`);
   }
 
   push();
@@ -268,7 +277,16 @@ function renderJson(result, integrity = null, rotation = null) {
       findings: result.findings.map((f) => ({
         rule: f.ruleId, label: f.label, confidence: f.confidence,
         source: f.source, file: f.relFile, line: f.line, preview: f.preview,
+        // Markers for the two decode/reconstruct passes (absent on ordinary
+        // findings). `encoding` names how the value was wrapped ("base64" /
+        // "base64url"); `spanLines` names the adjacent line pair a split value
+        // was reconstructed across.
+        ...(f.encoding ? { encoding: f.encoding } : {}),
+        ...(f.spanLines ? { spanLines: f.spanLines } : {}),
         fingerprint: fingerprintFinding(f),
+        // Only present on an --include-suppressed run: says WHY this finding
+        // is low-confidence, so a JSON consumer doesn't have to guess.
+        ...(f.suppressedReason ? { suppressedReason: f.suppressedReason } : {}),
       })),
       // orderAdvisory mirrors the human report's ChainDrop ordering warning:
       // remediation order is safety-critical when planted persistence and

package/src/rotation.js

@@ -76,7 +76,7 @@ const ROTATION_ORDER_ADVISORY =
 // ── rotation guidance map ───────────────────────────────────────────────────
 
 /**
- * One entry per rule id in src/patterns.js (all 35 of PATTERNS, plus the two
+ * One entry per rule id in src/patterns.js (all 36 of PATTERNS, plus the two
  * NOISY_PATTERNS ids so an --include-noisy run still renders guidance).
  * Shape: { label, rotateUrl?, consolePath?, steps: [1..3 strings],
  * revokeNote, generic? }. `generic: true` marks entries that cannot name a
@@ -174,6 +174,20 @@ const ROTATION_GUIDANCE = {
     ],
     revokeNote: "Rotating with expiration Now kills the old key immediately; a scheduled rotation keeps both valid for up to 7 days for zero-downtime migration.",
   },
+  // Same URL as stripe_key, and the same fetch check covers it (2026-09-02):
+  // docs.stripe.com/keys documents the Rotate key flow for both modes, the
+  // API keys page's sandbox/live toggle, and that sandbox mode exposes all
+  // of the account's keys to anyone who can open it.
+  stripe_test_key: {
+    label: "Stripe API key (test mode)",
+    rotateUrl: "https://docs.stripe.com/keys",
+    steps: [
+      "Dashboard > Developers > API keys, toggled to sandbox (test) mode",
+      "Overflow menu on the key > Rotate key; choose expiration Now for a compromised key",
+      "Check how the key leaked: test and live keys usually travel the same channel, so verify no live key was exposed alongside it",
+    ],
+    revokeNote: "Test mode is not harmless: the key grants full API access to the sandbox account, and its leak marks a workflow that will handle live keys the same way.",
+  },
   // help.openai.com articles 5112595 and 8304786 exist (surfaced by search)
   // but the help center serves HTTP 403 to this project's fetcher, so no URL
   // is shipped: unverifiable end to end fails the bar above.

package/src/scan.js

@@ -2,6 +2,7 @@
 
 const path = require("path");
 const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
+const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
 
 /**
  * Text immediately before a match that strongly suggests "this is an example
@@ -16,6 +17,84 @@ const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const SUPPRESS_CONTEXT_RE = /(placeholder|example|sample|dummy|<REDACTED>|xxxxxxxx|your[_-]?(api[_-]?)?key|EXAMPLE)/i;
 const CONTEXT_WINDOW = 40;
 
+/**
+ * Exact literals that vendors publish in their own documentation as example
+ * credentials. These pass every shape check by construction (they ARE the
+ * documented shape), and the context heuristic above can't be relied on to
+ * catch them: it only looks at the 40 characters BEFORE a match, so "the
+ * docs show AKIAIOSFODNN7EXAMPLE as the placeholder" sails straight through.
+ * The value itself is the signal here. Same policy as the context heuristic:
+ * suppressed by default, counted, re-includable with --include-suppressed.
+ * gitleaks and other production scanners filter the AWS pair the same way.
+ *
+ * Every literal below was verified against the vendor's own published docs
+ * (2026-09), not copied from another scanner's allowlist:
+ *   - AWS's two documented example access key ids, used across the IAM and
+ *     STS docs (e.g. the GetAccessKeyInfo API reference).
+ *   - GitHub's documented example tokens from docs.github.com: the REST API
+ *     getting-started guide's PAT, and the OAuth-apps guide's access +
+ *     refresh token pair (the same body appears under ghp_ and gho_).
+ *   - jwt.io's default demo token (header {"alg":"HS256","typ":"JWT"},
+ *     payload sub 1234567890 / John Doe), the canonical example JWT quoted
+ *     in tutorials everywhere.
+ */
+/**
+ * A trailing run of 12+ identical characters inside a matched value. No
+ * vendor issues credentials with a repeated-character body — key material is
+ * random, and 12 identical characters in a row in a real random body is a
+ * ~62^-11 event — but placeholder keys built as prefix + XXXX.../0000... are
+ * everywhere in docs and templates, and they match the shape rules by
+ * construction. This is a property of the VALUE, so unlike the context
+ * heuristic it also works where no surrounding text exists: a placeholder
+ * that arrives base64-encoded or split across lines is still zero-entropy
+ * after decoding/joining. gitleaks ships equivalent repeated-character
+ * allowlists. Anchored to the END of the value on purpose: an INTERIOR run
+ * can occur inside a real token (base64 of a zero-byte run is a run of
+ * "A"s, so a genuine JWT payload can contain one), but real key material
+ * never ends in one, and prefix+XXXX placeholders always do. Same policy
+ * as every suppression: counted, re-includable with --include-suppressed,
+ * never silently dropped.
+ *
+ * Implemented as a fixed 12-character look at the END of the value, not as
+ * the equivalent anchored-backreference regex /(.)\1{11,}$/ — that regex is
+ * O(n^2) on a matched value containing a long INTERIOR identical-character
+ * run (the greedy backreference re-tests the anchor at every start
+ * position), and such values are reachable: base64 of zero-heavy bytes is a
+ * long run of "A"s inside a prefix-matched value. Checking only the last 12
+ * code units is exactly equivalent to "ends in 12 or more identical
+ * characters" and O(1) whatever the value looks like.
+ */
+function zeroEntropyTail(value) {
+  if (value.length < 12) return false;
+  const last = value.charCodeAt(value.length - 1);
+  for (let i = value.length - 12; i < value.length - 1; i++) {
+    if (value.charCodeAt(i) !== last) return false;
+  }
+  return true;
+}
+
+const VENDOR_EXAMPLE_VALUES = new Set([
+  "AKIAIOSFODNN7EXAMPLE",
+  "AKIAI44QH8DHBEXAMPLE",
+  "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
+  "gho_16C7e42F292c6912E7710c838347Ae178B4a",
+  "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+  // Stripe's two published sample test keys, verified against Stripe's own
+  // material (2026-09): the API reference authentication page
+  // (docs.stripe.com/api/authentication) embeds the first in its curl
+  // example under "A sample test API key is included in all the examples
+  // here"; the second is Stripe's long-running docs sample key, present
+  // verbatim in Stripe's own repositories (stripe/stripe-java and
+  // stripe/stripe-dotnet test suites) and echoed by virtually every Stripe
+  // tutorial a transcript might read. Both match stripe_test_key by
+  // construction, so without this entry each is reported at high confidence.
+  // Written split (prefix + body) so the faithful example literals do not
+  // trip GitHub push protection; the Set still holds the whole values.
+  "sk_test_" + "BQokikJOvBiI2HlWgH4olfQ2",
+  "sk_test_" + "4eC39HqLyjWDarjtT1zdp7dc",
+]);
+
 /** Matches every finding's own `relFile` convention — never the full path. See SECURITY.md. */
 function safeName(file) { return path.basename(file); }
 
@@ -39,6 +118,11 @@ function safeName(file) { return path.basename(file); }
  */
 async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null } = {}) {
   const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
+  // The decode pass (see decode.js) only applies high-confidence, vendor-
+  // prefixed rules to decoded bytes: random binary that decodes to printable
+  // text can shape-match a generic rule, but not a vendor prefix. NOISY rules
+  // are low confidence and never qualify.
+  const highRules = rules.filter((r) => r.confidence === "high");
   const findings = [];
   let suppressedCount = 0;
   let filesScanned = 0;
@@ -52,35 +136,101 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
   // never leaves this function.
   const distinctByRule = new Map();
 
+  // One place raw matched text turns into a recorded finding: counts the
+  // distinct value and pushes the redacted record. `extra` carries the
+  // encoding / split markers for the decode and boundary passes; the raw pass
+  // passes none.
+  const record = (rule, value, relFile, file, lineNo, mtimeMs, confidence, suppressedReason, extra) => {
+    if (!distinctByRule.has(rule.id)) distinctByRule.set(rule.id, new Set());
+    distinctByRule.get(rule.id).add(value);
+    findings.push({
+      ruleId: rule.id,
+      label: rule.label,
+      confidence,
+      suppressedReason: suppressedReason || null,
+      source: relFile.source,
+      file, relFile: relFile.name,
+      line: lineNo,
+      preview: redact(value),
+      fileMTimeMs: mtimeMs,
+      ...(extra || {}),
+    });
+  };
+
+  // One suppression policy for all three passes (raw, decoded, boundary).
+  // The value-based checks run first: they are exact properties of the match
+  // itself, so they apply identically to a value found raw, decoded out of
+  // base64, or reconstructed across a line boundary — a decoded vendor
+  // example is the same non-secret as a plain one. The context heuristic is
+  // last and only where surrounding text exists (`before` is null for the
+  // decode and boundary passes, whose transforms have no stable "40 chars
+  // before" in the original line).
+  const suppressionReason = (value, before) => {
+    if (VENDOR_EXAMPLE_VALUES.has(value)) return "vendor-documented example value";
+    if (zeroEntropyTail(value)) return "zero-entropy body";
+    if (before !== null && SUPPRESS_CONTEXT_RE.test(before)) return "placeholder-like context";
+    return null;
+  };
+
   const matchLine = (line, file, relFile, lineNo, mtimeMs) => {
     for (const rule of rules) {
       rule.re.lastIndex = 0; // rules are reused across files; reset global regex state
       let m;
       while ((m = rule.re.exec(line)) !== null) {
         const before = line.slice(Math.max(0, m.index - CONTEXT_WINDOW), m.index);
-        const looksLikePlaceholder = SUPPRESS_CONTEXT_RE.test(before);
-        if (looksLikePlaceholder && !includeSuppressed) {
+        const suppressedReason = suppressionReason(m[0], before);
+        if (suppressedReason && !includeSuppressed) {
           suppressedCount++;
         } else {
-          if (!distinctByRule.has(rule.id)) distinctByRule.set(rule.id, new Set());
-          distinctByRule.get(rule.id).add(m[0]);
-          findings.push({
-            ruleId: rule.id,
-            label: rule.label,
-            confidence: looksLikePlaceholder ? "low" : rule.confidence,
-            suppressedReason: looksLikePlaceholder ? "placeholder-like context" : null,
-            source: relFile.source,
-            file, relFile: relFile.name,
-            line: lineNo,
-            preview: redact(m[0]),
-            fileMTimeMs: mtimeMs,
-          });
+          record(rule, m[0], relFile, file, lineNo,
+            mtimeMs,
+            suppressedReason ? "low" : rule.confidence,
+            suppressedReason);
         }
         if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
       }
     }
   };
 
+  // Feature 1: base64 decode-then-rescan. A finding here means a credential
+  // was present only encoded on this line. It redacts from the DECODED value
+  // (the encoded run is treated as secret material and never appears in the
+  // preview), and carries an `encoding` marker the report renders as
+  // "base64-wrapped".
+  const decodeLine = (line, file, relFile, lineNo, mtimeMs) => {
+    for (const d of findDecodedMatches(line, highRules)) {
+      const suppressedReason = suppressionReason(d.value, null);
+      if (suppressedReason && !includeSuppressed) {
+        suppressedCount++;
+        continue;
+      }
+      record({ id: d.ruleId, label: d.label }, d.value, relFile, file, lineNo,
+        mtimeMs, suppressedReason ? "low" : "high", suppressedReason, { encoding: d.encoding });
+    }
+  };
+
+  // Feature 2: split-line boundary join. A finding here means one credential
+  // was split across this line and the next and is contiguous on neither. It
+  // is recorded against BOTH contributing lines (each holds a fragment of the
+  // exposed secret) and carries a `spanLines` marker. `contentA`/`contentB`
+  // are the two lines' content projections, computed once per line by the
+  // caller and reused across both of a line's pairs.
+  const boundaryPair = (contentA, contentB, file, relFile, lineNoA, mtimeMs) => {
+    for (const b of findBoundaryMatches(contentA, contentB, rules)) {
+      const suppressedReason = suppressionReason(b.value, null);
+      if (suppressedReason && !includeSuppressed) {
+        // One straddling match is one suppressed match, even though an
+        // unsuppressed one records against both contributing lines.
+        suppressedCount++;
+        continue;
+      }
+      const span = [lineNoA, lineNoA + 1];
+      const conf = suppressedReason ? "low" : b.confidence;
+      record({ id: b.ruleId, label: b.label }, b.value, relFile, file, lineNoA, mtimeMs, conf, suppressedReason, { spanLines: span });
+      record({ id: b.ruleId, label: b.label }, b.value, relFile, file, lineNoA + 1, mtimeMs, conf, suppressedReason, { spanLines: span });
+    }
+  };
+
   for (const source of sources) {
     let sourceScannedAnything = false;
 
@@ -134,8 +284,43 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
       bytesScanned += bytesRead || sizeBytes || 0;
 
       const relFile = { name: safeName(file), source: source.id() };
+      // Content projection of the PREVIOUS line, kept so each line is
+      // projected once and reused for both pairs it belongs to.
+      let prevContent = null;
+      // Per-file degradation flag, surfaced at most once so a pathological
+      // file produces one visible entry, not thousands.
+      let lineMatchFailed = false;
       for (let i = 0; i < lines.length; i++) {
-        if (lines[i]) matchLine(lines[i], file, relFile, i + 1, mtimeMs);
+        const line = lines[i];
+        if (line) {
+          // A rule regex itself can throw on adversarial input: V8's
+          // backtrack stack overflows (RangeError) when an open-ended
+          // quantifier meets a prefix followed by a multi-megabyte
+          // same-charset run — real transcripts contain such lines. One
+          // unmatched line must degrade to a visible per-file flag, never
+          // abort the scan and discard every finding already collected
+          // (same contract as the readLines catch above).
+          try {
+            matchLine(line, file, relFile, i + 1, mtimeMs);
+            decodeLine(line, file, relFile, i + 1, mtimeMs);
+            const content = contentProjection(line);
+            // Boundary join with the previous line (2-way splits only; see
+            // decode.js). Both lines must be non-empty so a blank separator
+            // never forms a spurious pair.
+            if (prevContent !== null) {
+              boundaryPair(prevContent, content, file, relFile, i, mtimeMs);
+            }
+            prevContent = content;
+          } catch (err) {
+            if (!lineMatchFailed) {
+              lineMatchFailed = true;
+              unreadableFiles.push({ file: safeName(file), reason: "some lines could not be matched" });
+            }
+            prevContent = null;
+          }
+        } else {
+          prevContent = null;
+        }
       }
     }
 
@@ -160,4 +345,7 @@ function emptyResult() {
   };
 }
 
-module.exports = { scan, emptyResult };
+// VENDOR_EXAMPLE_VALUES is exported for the smoke tests, which assert every
+// literal in it is still matched IN FULL by some detection rule — a literal
+// no rule can produce as a whole match is dead weight that suppresses nothing.
+module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES };

package/src/sources/agent-configs.js

@@ -19,15 +19,28 @@ const { createInterface } = require("readline/promises");
  * Bitwarden-CLI-hijack write-up, StepSecurity's Nx Console analysis, the
  * keyv/Shai-Hulud reports) name several of the paths below verbatim.
  *
- * SCOPE — home-level only, and that limitation is real, not rhetorical:
- * project-level configs (`.mcp.json`, `.claude/settings.json`,
- * `.cursor/rules/`, `.vscode/tasks.json`, per-repo CLAUDE.md/AGENTS.md —
- * the files Miasma actually planted in cloned repos) live inside arbitrary
- * repositories this tool has no way to enumerate from a home directory.
- * A clean report from this source therefore says nothing about any
- * project's own config files. v1 ships the home-level set because those
- * paths are fixed and verifiable; the project-level gap is stated here
- * rather than papered over.
+ * SCOPE — fixed home-level paths, plus project-level Claude Code configs
+ * reachable through the agent's own breadcrumbs. Project configs live
+ * inside arbitrary repositories that no home-level scanner can enumerate
+ * by walking a directory tree — but the agent itself records every project
+ * root it has been used in, at home level: `~/.claude.json` keeps a
+ * top-level `projects` map keyed by absolute project path (vendor-
+ * documented per-project state), and every transcript under
+ * `~/.claude/projects/<slug>/` carries the project's absolute path in its
+ * records' `cwd` field (vendor JSONL schema). Following those recorded
+ * roots to the vendor-FIXED per-project config filenames (`.mcp.json`,
+ * `.claude/settings.json`, `.claude/settings.local.json` — the exact
+ * files GitGuardian measured 24k secrets in and Lakera found shipped in
+ * npm packages) is a general mechanism, not path guessing: nothing is
+ * discovered by scanning repositories, only by resolving what the agent
+ * already wrote down. Limits, stated: a machine whose agent state was
+ * wiped yields no roots (discovery degrades to absence, the same
+ * information a human reading the state would have); other agents'
+ * project-level configs (`.cursor/rules/`, `.vscode/tasks.json`, per-repo
+ * CLAUDE.md/AGENTS.md — the files Miasma actually planted) stay
+ * uncovered until their home-level state formats are verified to the same
+ * bar; and a clean report still says nothing about repositories the agent
+ * was never pointed at.
  *
  * PER-PATH VERIFICATION (per CONTRIBUTING.md's no-guessed-paths rule —
  * "real install" below means the populated machine this source was built
@@ -96,8 +109,12 @@ const { createInterface } = require("readline/promises");
  *    Bitwarden-CLI target list.
  *
  * DELIBERATELY NOT READ, and why:
- *  - `~/.claude/projects/**` — claude-code.js's territory. Overlapping it
- *    would double-report every finding. (Named side effect: a
+ *  - `~/.claude/projects/**` AS SCAN CONTENT — claude-code.js's territory;
+ *    overlapping it would double-report every finding. The project-root
+ *    discovery below does open transcripts, but only to read the `cwd`
+ *    field out of the first records (a bounded probe, nothing from the
+ *    content is ever reported), which indexes projects without scanning
+ *    a single transcript line here. (Named side effect: a
  *    `projects/<slug>/memory/MEMORY.md` is covered by NEITHER source
  *    today — a real gap that belongs to the transcript source's scope
  *    discussion, recorded here so it isn't mistaken for covered.)
@@ -257,9 +274,176 @@ function* statIfPresent(p) {
   yield { file: p, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
 }
 
-/** Yield { file, mtimeMs, sizeBytes, broken } for every candidate present. */
+// ── project-level config discovery ──────────────────────────────────────────
+//
+// The per-project config filenames are vendor-fixed (Claude Code's own docs:
+// project-scope MCP servers in `.mcp.json`, shared settings in
+// `.claude/settings.json`, local settings in `.claude/settings.local.json`);
+// what varies per machine is only WHERE the project roots are, and the agent
+// records exactly that in home-level state. Two independent record sources,
+// both vendor artifacts, both read best-effort (a failure to discover a root
+// is absence, never an error — see the SCOPE limits in the header):
+//
+//   1. `~/.claude.json`'s top-level `projects` object, keyed by absolute
+//      project path. Already a scan candidate above; parsed here a second
+//      time only for its keys.
+//   2. The `cwd` field in transcript records under
+//      `~/.claude/projects/<slug>/`. The slug itself also encodes the path,
+//      but lossily (path separators and dashes collapse into the same
+//      character), so the record field is the reliable form. Only the first
+//      few records of the first few files per slug directory are probed,
+//      bounded by bytes and line count: every session in a slug directory
+//      shares one project root by construction.
+//
+// A recorded root that no longer exists usually means the project was
+// deleted — except when the WHOLE home tree has been relocated (a mounted
+// backup, a copied disk image, HOME pinned at a snapshot for auditing), in
+// which case every recorded absolute path is stale by the same prefix. That
+// case is detected generally: a missing root whose prefix is shaped like a
+// home directory (macOS /Users/<u>, Linux /home/<u>, Windows
+// <drive>:\Users\<u>) is retried at the same home-relative path under the
+// CURRENT home, and used only if that directory actually exists. Non-default
+// home locations (e.g. /srv/data/<u>) defeat the re-rooting and are a stated
+// limit, not a silent one.
+//
+// Recorded roots are data read from transcripts and state files, which a
+// hostile transcript can influence — so nothing is ever globbed or walked
+// beneath them: only the three fixed basenames are lstat'd, reads stay
+// read-only through the same readLines every candidate gets, and anything
+// matched is redacted by the report layer like every other finding.
+
+const CLAUDE_STATE_JSON = path.join(HOME, ".claude.json");
+const CLAUDE_PROJECTS_DIR = path.join(CLAUDE_DIR, "projects");
+
+const PROJECT_CONFIG_RELPATHS = [
+  ".mcp.json",
+  path.join(".claude", "settings.json"),
+  path.join(".claude", "settings.local.json"),
+];
+
+// Probe bounds: transcript first-records are KB-scale; 256KB and 20 lines is
+// headroom, not a tuned fit. One resolving file per slug directory suffices.
+const CWD_PROBE_BYTES = 256 * 1024;
+const CWD_PROBE_LINES = 20;
+const CWD_PROBE_FILES_PER_DIR = 3;
+
+function rootsFromClaudeState() {
+  let stat;
+  try { stat = fs.statSync(CLAUDE_STATE_JSON); } catch { return []; }
+  if (!stat.isFile() || stat.size > MAX_BYTES) return [];
+  try {
+    const doc = JSON.parse(fs.readFileSync(CLAUDE_STATE_JSON, "utf-8"));
+    if (doc && typeof doc === "object" && doc.projects &&
+        typeof doc.projects === "object" && !Array.isArray(doc.projects)) {
+      return Object.keys(doc.projects).filter((k) => typeof k === "string" && k.length > 0);
+    }
+  } catch {
+    // Unparseable state: discovery loses this index, but the file itself is
+    // still scanned line-by-line as a fixed candidate above, so no content
+    // goes unexamined because of a parse failure here.
+  }
+  return [];
+}
+
+/** First string `cwd` in the leading records of one transcript, or null. */
+function firstCwdIn(file) {
+  let fd = null;
+  try {
+    fd = fs.openSync(file, "r");
+    const buf = Buffer.alloc(CWD_PROBE_BYTES);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    // A line truncated at the probe boundary simply fails JSON.parse and is
+    // skipped — the bound costs recall on that one record, never a crash.
+    const lines = buf.toString("utf-8", 0, n).split("\n", CWD_PROBE_LINES);
+    for (const line of lines) {
+      try {
+        const rec = JSON.parse(line);
+        if (rec && typeof rec === "object" && typeof rec.cwd === "string" && rec.cwd) return rec.cwd;
+      } catch { /* meta/summary records and non-JSON lines: keep looking */ }
+    }
+  } catch {
+    // Unreadable transcript: claude-code.js owns surfacing that; a root
+    // index probe must not duplicate its error reporting.
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* already closed */ } }
+  }
+  return null;
+}
+
+function rootsFromTranscriptDirs() {
+  let dirs;
+  try { dirs = fs.readdirSync(CLAUDE_PROJECTS_DIR, { withFileTypes: true }); }
+  catch { return []; }
+  const roots = [];
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const dir = path.join(CLAUDE_PROJECTS_DIR, d.name);
+    let entries;
+    // An unlistable slug directory is not silently swallowed overall:
+    // claude-code.js's own files() walk reports that same directory as
+    // broken; this index probe just loses one root.
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    const sessions = entries.filter((n) => n.endsWith(".jsonl")).sort();
+    for (const name of sessions.slice(0, CWD_PROBE_FILES_PER_DIR)) {
+      const cwd = firstCwdIn(path.join(dir, name));
+      if (cwd) { roots.push(cwd); break; }
+    }
+  }
+  return roots;
+}
+
+// Default home-directory shapes for the three platforms Claude Code ships
+// on. Anchored and existence-checked, never a rewrite of arbitrary paths.
+const HOME_SHAPED_PREFIX = /^(?:\/(?:Users|home)\/[^/]+|[A-Za-z]:[\\/]Users[\\/][^\\/]+)(?=[\\/]|$)/;
+
+/** Resolve one recorded project root to an existing directory, or null. */
+function resolveRecordedRoot(recorded) {
+  try { if (fs.statSync(recorded).isDirectory()) return recorded; } catch { /* fall through to re-rooting */ }
+  const m = HOME_SHAPED_PREFIX.exec(recorded);
+  if (!m) return null;
+  const rest = recorded.slice(m[0].length).split(/[\\/]+/).filter(Boolean);
+  const rehomed = rest.length === 0 ? HOME : path.join(HOME, ...rest);
+  try { if (fs.statSync(rehomed).isDirectory()) return rehomed; } catch { /* relocated copy absent too */ }
+  return null;
+}
+
+/**
+ * Yield candidate entries for every discovered project root's fixed config
+ * filenames, deduplicated against paths already yielded (a recorded root
+ * that resolves to the home directory itself would otherwise re-yield
+ * `~/.claude/settings.json`). Sorted for deterministic output across runs —
+ * readdir order is not.
+ */
+function* projectConfigCandidates(seenResolved) {
+  const recorded = new Set([...rootsFromClaudeState(), ...rootsFromTranscriptDirs()]);
+  const resolved = new Set();
+  for (const r of recorded) {
+    const root = resolveRecordedRoot(r);
+    if (root) resolved.add(path.resolve(root));
+  }
+  for (const root of [...resolved].sort()) {
+    for (const rel of PROJECT_CONFIG_RELPATHS) {
+      const p = path.join(root, rel);
+      const key = path.resolve(p);
+      if (seenResolved.has(key)) continue;
+      seenResolved.add(key);
+      yield* statIfPresent(p);
+    }
+  }
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every candidate present:
+ * the fixed home-level paths first, then per-project configs at the roots
+ * the agent's own state records (see the discovery block above).
+ */
 function* files() {
-  for (const p of CANDIDATES) yield* statIfPresent(p);
+  const seen = new Set();
+  for (const p of CANDIDATES) {
+    seen.add(path.resolve(p));
+    yield* statIfPresent(p);
+  }
+  yield* projectConfigCandidates(seen);
 }
 
 /**