residoo 0.2.0 → 0.3.1

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,105 @@ 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". Returns true when the per-line candidate cap left
+  // encoded runs on this line unchecked, so the caller can flag the file as
+  // only partially checked instead of staying silent about the gap.
+  const decodeLine = (line, file, relFile, lineNo, mtimeMs) => {
+    const { matches, truncated } = findDecodedMatches(line, highRules);
+    for (const d of matches) {
+      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 });
+    }
+    return truncated;
+  };
+
+  // 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 +288,47 @@ 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 flags, each surfaced at most once so a
+      // pathological file produces one visible entry, not thousands.
+      let lineMatchFailed = false;
+      let decodeTruncated = 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);
+            decodeTruncated = decodeLine(line, file, relFile, i + 1, mtimeMs) || decodeTruncated;
+            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;
+        }
+      }
+      if (decodeTruncated) {
+        unreadableFiles.push({ file: safeName(file), reason: "some lines held more encoded runs than the per-line bound; checked partially" });
       }
     }
 
@@ -160,4 +353,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);
 }
 
 /**