residoo 0.3.9 → 0.4.1

package/README.md

@@ -122,10 +122,10 @@ won't be built into the tool that writes it.
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
 - On an interactive terminal, prints who it is and where it lives before
-  scanning starts (`residoo v0.3.9 · find secrets your AI coding agent left
+  scanning starts (`residoo v0.4.1 · find secrets your AI coding agent left
   on disk` plus the repo URL), then a live spinner naming the current file
   as it scans. Every report also opens with the exact version and timestamp
-  it was run with (`residoo v0.3.9 · scanned 2026-01-01 12:00`; `--json`
+  it was run with (`residoo v0.4.1 · scanned 2026-01-01 12:00`; `--json`
   carries the same as `residooVersion`/`scannedAt`), so a report pasted or
   screenshotted later never leaves you guessing which build produced it.
   When there are findings, the report closes with a "Next steps" pointer to
@@ -297,12 +297,32 @@ with the way out:
   type: where to revoke, the steps, and what revocation actually does at
   that vendor. `residoo explain --list` shows the whole catalogue.
 - **`residoo ack <fingerprint>`** records that you rotated one finding.
+  **`residoo dismiss <fingerprint>`** records that you determined it was
+  never a real secret (a test fixture, a vendor example not already
+  recognized), a separate resolution from ack, since nothing was rotated.
   Every finding carries a stable fingerprint (derived only from
   already-redacted material, so the ledger can never leak), shown in the
-  report and in `--json`. Acknowledged findings are reported as such on the
-  next scan instead of re-alarming forever. The ledger lives at
-  `~/.residoo/rotations.json`: residoo's own file, written atomically, ack
-  notes redacted through the same pipeline as previews.
+  report and in `--json`. Acked and dismissed findings are both reported as
+  resolved on the next scan instead of re-alarming forever. Both live in the
+  same ledger at `~/.residoo/rotations.json`: residoo's own file, written
+  atomically, notes redacted through the same pipeline as previews.
+- **A "Recommended actions" summary leads the report**, before the detailed
+  findings breakdown: how many *distinct* values still need a decision,
+  versus how many are already resolved. A machine with a lot of history can
+  report hundreds of raw findings that are really a handful of distinct
+  values echoed repeatedly; the summary is built around what's actually left
+  to triage, not the raw count.
+- **The rotation list is grouped by credential type**, so the rotation URL
+  prints once per type instead of once per finding. Each distinct value's own
+  line shows its redacted preview, which file it's in, and when it was last
+  seen in a transcript, not just a bare fingerprint. "Last seen" is exactly
+  that: the most recent transcript occurrence residoo found, not proof a
+  credential is still live or that an older value was rotated. Most
+  credential formats (AWS access keys, vendor API tokens) carry no shared
+  identifier linking a rotated key to its predecessor, and residoo makes no
+  network calls to ask the provider, so two distinct pending values of the
+  same type are always shown as two separate lines, never collapsed on a
+  guess.
 - **Order matters, and the report says so when it does.** The ChainDrop
   campaign (Aug 2026) shipped a token monitor that fires an attacker payload
   the moment the stolen GitHub token is revoked. When one scan finds both
@@ -310,9 +330,9 @@ with the way out:
   the planted persistence first and rotate second, because "rotate
   everything now" advice can itself trigger the damage.
 
-Acks change what the report says, never what CI does: `--fail-on-find`
-fails on every finding, acknowledged or not, unless you explicitly pass
-`--allow-acked` (integrity warnings always fail either way).
+Acks and dismissals change what the report says, never what CI does:
+`--fail-on-find` fails on every finding, resolved or not, unless you
+explicitly pass `--allow-acked` (integrity warnings always fail either way).
 
 ## CI and pre-commit
 
@@ -329,7 +349,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.3.9
+  - uses: dandovdub/residoo@v0.4.1
 ```
 
 As a pre-commit hook:
@@ -337,7 +357,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.9
+    rev: v0.4.1
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.9",
+  "version": "0.4.1",
   "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)",

package/src/cli.js

@@ -8,7 +8,7 @@ const { scan, emptyResult } = require("./scan");
 const { render, renderIntegrity, renderJson, renderSarif, makeProgressReporter, printIntro } = require("./report");
 const { checkIntegrity } = require("./integrity");
 const {
-  ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
+  ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed, ackFinding, dismissFinding, renderRotation,
 } = require("./rotation");
 
 /**
@@ -48,9 +48,11 @@ const HELP = `residoo: find secrets leaking through your AI agent's session hist
   path, verified against their docs, because a leaked key that is found but
   never rotated is still leaked (64% of leaked secrets stay valid for years).
   "residoo explain <rule-id>" prints the full runbook for one credential
-  type; "residoo ack <fingerprint>" records that you rotated one, in
-  ~/.residoo/rotations.json, the only file residoo ever writes outside an
-  explicit --seal.
+  type; "residoo ack <fingerprint>" records that you rotated one, and
+  "residoo dismiss <fingerprint>" records that you determined it was never a
+  real secret (a test fixture, a vendor example not already recognized).
+  Both are recorded in ~/.residoo/rotations.json, the only file residoo
+  ever writes outside an explicit --seal.
 
   Scanning makes NO network calls and changes nothing on disk. Findings are
   redacted in every output format. Sealing (--seal) writes NEW encrypted
@@ -60,6 +62,7 @@ Usage:
   residoo scan [options]
   residoo explain <rule-id>   (or: residoo explain --list)
   residoo ack <fingerprint> [--note <text>]
+  residoo dismiss <fingerprint> [--note <text>]
   residoo unseal <vault-dir> [--restore <n> --out <path>]
 
 Scan options:
@@ -85,23 +88,29 @@ Scan options:
                           findings and integrity WARNINGS count; integrity
                           info-level review items do not
   --allow-acked           with --fail-on-find: findings whose fingerprint was
-                          acknowledged via "residoo ack" no longer fail the
-                          run; pending findings and integrity warnings still
-                          do. Without this flag, --fail-on-find fails on
-                          every finding, acknowledged or not.
+                          acknowledged via "residoo ack" OR dismissed via
+                          "residoo dismiss" no longer fail the run; pending
+                          findings and integrity warnings still do. Without
+                          this flag, --fail-on-find fails on every finding,
+                          acked, dismissed, or not.
   --no-integrity          skip the integrity checks (planted hooks, dropper
                           files, auto-run tasks, hidden Unicode)
   --no-color              disable ANSI colour
 
 Rotation:
-  residoo explain <rule-id>   full rotation runbook for one detection rule
-                              (where to revoke, steps, what revocation does)
-  residoo explain --list      every rule id with its credential label
-  residoo ack <fingerprint>   mark one finding's rotation done; fingerprints
-                              appear next to findings in the report and in
-                              --json. Optional --note <text> is stored with
-                              the acknowledgement (redacted if it matches a
-                              secret pattern).
+  residoo explain <rule-id>     full rotation runbook for one detection rule
+                                (where to revoke, steps, what revocation does)
+  residoo explain --list        every rule id with its credential label
+  residoo ack <fingerprint>     mark one finding's rotation done; fingerprints
+                                appear next to findings in the report and in
+                                --json. Optional --note <text> is stored with
+                                the acknowledgement (redacted if it matches a
+                                secret pattern).
+  residoo dismiss <fingerprint> mark one finding as reviewed and NOT a real
+                                secret (a test fixture, a vendor example not
+                                already recognized, etc.), distinct from ack:
+                                nothing was rotated, there was nothing to
+                                rotate. Same --note handling as ack.
 
 Seal options (used with scan):
   --seal                  after scanning, encrypt every transcript that carried a
@@ -367,6 +376,41 @@ function runAck(args) {
   return 0;
 }
 
+/**
+ * Record that one finding was reviewed and determined NOT to be a real
+ * secret (a test fixture, a value used to verify residoo's own detection,
+ * a vendor example not already on the built-in suppression list, etc.) —
+ * distinct from `ack`, which means "I rotated a real credential." Without
+ * this, the only way to stop a confirmed-fake finding from reappearing
+ * every scan was to `ack` it, which is semantically wrong (nothing was
+ * rotated) and reads misleadingly in the rotation ledger.
+ */
+function runDismiss(args) {
+  const fp = args[1] && !args[1].startsWith("--") ? args[1] : null;
+  if (!fp) {
+    process.stderr.write("usage: residoo dismiss <fingerprint> [--note <text>]\n" +
+      "Fingerprints (rf1-...) are shown next to findings in the scan report and in --json.\n");
+    return 2;
+  }
+  let res;
+  try {
+    res = dismissFinding(fp, argValue(args, "--note"));
+  } catch (err) {
+    process.stderr.write(`residoo: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 2;
+  }
+  process.stdout.write(
+    `Dismissed ${res.fingerprint} at ${res.at}` +
+    (res.note ? ` with note: ${res.note}` : "") + "\n" +
+    "The next scan reports this finding as dismissed instead of pending, and it is\n" +
+    "excluded from --fail-on-find the same way an acked finding is with --allow-acked.\n" +
+    "(dismiss is stateless, same as ack: it cannot check this fingerprint against a\n" +
+    "scan, so a mistyped one is recorded too; the intended finding would then still\n" +
+    "show as pending on the next scan.)\n"
+  );
+  return 0;
+}
+
 async function main(argv) {
   const args = argv.slice(2);
   if (args.includes("-h") || args.includes("--help") || args.length === 0) {
@@ -378,6 +422,7 @@ async function main(argv) {
   if (cmd === "unseal") return runUnseal(args);
   if (cmd === "explain") return runExplain(args);
   if (cmd === "ack") return runAck(args);
+  if (cmd === "dismiss") return runDismiss(args);
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;
@@ -467,9 +512,11 @@ async function main(argv) {
     sources = availableSources();
   }
 
-  // loadAcks degrades to {} (loudly, on stderr) if the state file is corrupt,
-  // so a broken ack ledger can never block or distort a scan.
+  // loadAcks/loadDismissed degrade to {} (loudly, on stderr) if the state
+  // file is corrupt, so a broken rotation ledger can never block or distort
+  // a scan.
   const acks = loadAcks();
+  const dismissed = loadDismissed();
 
   if (sources.length === 0) {
     const empty = emptyResult();
@@ -482,7 +529,7 @@ async function main(argv) {
       // A --json caller (CI, a script piping into jq) must always get valid JSON
       // on stdout, even on the "nothing to scan" path — a plain-text message on
       // stderr with exit 0 silently breaks that contract.
-      process.stdout.write(renderJson(empty, integrity, renderRotation([], acks)) + "\n");
+      process.stdout.write(renderJson(empty, integrity, renderRotation([], acks, dismissed)) + "\n");
     } else {
       process.stderr.write(
         "No known transcript sources found on this machine.\n" +
@@ -499,7 +546,7 @@ async function main(argv) {
   const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
   progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;
-  const rotation = renderRotation(result.findings, acks);
+  const rotation = renderRotation(result.findings, acks, dismissed);
   process.stdout.write((wantsSarif
     ? renderSarif(result)
     : wantsJson

package/src/report.js

@@ -143,33 +143,101 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   // raw values, while these entries dedupe fingerprints (which include the
   // basename, so one value in two differently-named files is two rotations to
   // track). Two counts under one word would read as a contradiction.
+  const resolvedNote = [
+    counts.acked > 0 ? `${counts.acked} acknowledged` : null,
+    counts.dismissed > 0 ? `${counts.dismissed} dismissed` : null,
+  ].filter(Boolean).join(", ");
   push(paint(c.bold, "Rotation:") +
     ` ${counts.pending} of ${counts.distinct} rotation${counts.distinct === 1 ? "" : "s"} pending` +
-    (counts.acked > 0 ? ` (${counts.acked} acknowledged)` : ""));
+    (resolvedNote ? ` (${resolvedNote})` : ""));
   if (showAdvisory) {
     const wrapped = wrapText(ROTATION_ORDER_ADVISORY, 72, "     ");
     push(`  ${paint(c.red + c.bold, "⚠  " + wrapped[0])}`);
     for (const l of wrapped.slice(1)) push(`  ${paint(c.red, l)}`);
   }
-  // Same anti-flood policy as the by-file table: a report is a summary, not a
-  // dump. Everything elided here is in --json in full.
+  // Grouped by rule, not one row per finding: with several distinct values
+  // of the same credential type pending, the old flat list repeated the
+  // exact same rotation URL once per finding, all noise, no signal.
+  // Guidance now prints once per credential TYPE; what actually differs
+  // between two findings of the same type is which value and where, so
+  // that's what each row shows: the redacted preview (the one piece of
+  // information that lets a reader tell "this looks like my prod key" from
+  // "this looks like the placeholder ending in HERE" without cross-checking
+  // anything else) and how many files it's in, with the fingerprint kept
+  // but de-emphasized, still there for `ack`/`dismiss` but no longer the
+  // only thing on the line.
+  const groups = new Map(); // ruleId -> { label, entries: [] }
+  for (const e of entries) {
+    if (!groups.has(e.ruleId)) groups.set(e.ruleId, { label: e.label, entries: [] });
+    groups.get(e.ruleId).entries.push(e);
+  }
+  // Group order: any group with at least one pending entry first (matches
+  // the report's own "what needs attention" priority throughout), fully
+  // resolved groups after, alphabetical by label within each tier.
+  const groupList = [...groups.values()].sort((a, b) => {
+    const aPending = a.entries.some((e) => e.status === "pending");
+    const bPending = b.entries.some((e) => e.status === "pending");
+    if (aPending !== bPending) return aPending ? -1 : 1;
+    return a.label < b.label ? -1 : 1;
+  });
+
+  const STATUS_TAG = {
+    pending: paint(c.yellow, "pending  "),
+    acked: paint(c.green, "acked    "),
+    dismissed: paint(c.dim, "dismissed"),
+  };
+  // Same anti-flood policy as the by-file table: a report is a summary, not
+  // a dump. Everything elided here is in --json in full. Counted in
+  // individual findings, not groups, so the cap means the same thing here
+  // as it always has.
   const MAX_SHOWN = 12;
-  const shown = entries.slice(0, MAX_SHOWN);
-  for (const e of shown) {
-    const tag = e.status === "pending" ? paint(c.yellow, "pending") : paint(c.green, "acked  ");
-    push(`  ${tag}  ${e.fingerprint}  ${e.label}`);
-    if (e.status === "acked") {
-      push(paint(c.dim, `           acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""}`));
-    } else {
-      const g = e.guidance;
-      const where = g.rotateUrl ? `rotate: ${g.rotateUrl}` : `where: ${g.consolePath}`;
-      push(paint(c.dim, `           ${where}`));
+  let shownCount = 0;
+  let elided = 0;
+  for (const g of groupList) {
+    if (shownCount >= MAX_SHOWN) { elided += g.entries.length; continue; }
+    push();
+    const g0 = g.entries[0];
+    const where = g0.guidance.rotateUrl ? `rotate: ${g0.guidance.rotateUrl}` : `where: ${g0.guidance.consolePath}`;
+    push(`  ${paint(c.bold, g.label)}`);
+    push(paint(c.dim, `    ${where}`));
+    for (const e of g.entries) {
+      if (shownCount >= MAX_SHOWN) { elided++; continue; }
+      shownCount++;
+      // e.files always has exactly one entry: the fingerprint is derived
+      // from this same basename (see fingerprintFinding in rotation.js), so
+      // two findings only ever merge into one entry when they share it. Same
+      // discipline as the "By file:" table: a filename is attacker-
+      // controllable text (a hostile --project checkout picks its own
+      // names), so it goes through safeBasename before it ever reaches the
+      // terminal, control bytes stripped, invisible code points made visible.
+      const fileNote = safeBasename(e.files[0]);
+      // Last SEEN, not last used or last rotated: the most recent transcript
+      // occurrence residoo found, nothing more. There is no reliable way to
+      // tell from a local scan whether an older value of the same rule type
+      // was superseded by a newer one, both because most credential formats
+      // (AWS access keys, vendor API tokens) carry no shared identifier
+      // linking a rotated key to its predecessor, and because residoo makes
+      // no network calls to ask the provider. Two distinct pending values of
+      // the same type are shown as two separate lines on purpose, not
+      // collapsed on a guess.
+      const lastSeenNote = typeof e.lastSeenMs === "number" ? `last seen ~${ageDays(e.lastSeenMs)}d ago` : null;
+      push(`    ${STATUS_TAG[e.status]}  ${e.preview}  ${paint(c.dim, fileNote)}` +
+        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : ""));
+      if (e.status === "acked") {
+        push(paint(c.dim, `               acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} · ${e.fingerprint}`));
+      } else if (e.status === "dismissed") {
+        push(paint(c.dim, `               dismissed ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} (not a real secret) · ${e.fingerprint}`));
+      } else {
+        push(paint(c.dim, `               ${e.fingerprint}`));
+      }
     }
   }
-  if (entries.length > shown.length) {
-    push(paint(c.dim, `  … and ${entries.length - shown.length} more; see --json for the full list`));
+  if (elided > 0) {
+    push();
+    push(paint(c.dim, `  … and ${elided} more; see --json for the full list`));
   }
-  push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · mark one rotated: residoo ack <fingerprint>`));
+  push();
+  push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · rotated: residoo ack <fp> · not a secret: residoo dismiss <fp>`));
   return lines.join("\n");
 }
 
@@ -287,6 +355,31 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   push(paint(c.dim, `   ${filesScanned} files scanned (${(bytesScanned / 1024 / 1024).toFixed(1)} MB) · sources: ${sourcesScanned.join(", ")}`));
   push(paint(c.dim, `   oldest match ~${ageDays(oldest)}d old · most recent ~${ageDays(newest)}d old`) + suppressedNote);
   if (unreadableNote) push(unreadableNote);
+
+  // The practical, act-on-this-now summary, first, before the full
+  // rule-by-rule and file-by-file detail below: a raw count of findings
+  // (which can run into the hundreds on a machine with a lot of history) is
+  // not by itself a to-do list. What actually needs a person's attention is
+  // the count of DISTINCT values not yet triaged (rotated or dismissed) —
+  // everything else is either already handled or a re-exposure of a value
+  // already accounted for.
+  if (rotation && rotation.counts.distinct > 0) {
+    const { pending, distinct, acked, dismissed } = rotation.counts;
+    push();
+    push(paint(c.bold, "Recommended actions:"));
+    if (pending > 0) {
+      push(`  ${paint(c.yellow, "→")} ${pending} of ${distinct} distinct value${distinct === 1 ? "" : "s"} ${pending === 1 ? "needs" : "need"} review: rotate the real ones (residoo ack), dismiss the rest (residoo dismiss)`);
+    } else {
+      push(`  ${paint(c.green, "✓")} Nothing new to review; every distinct value here has already been triaged`);
+    }
+    const resolvedParts = [
+      acked > 0 ? `${acked} acknowledged` : null,
+      dismissed > 0 ? `${dismissed} dismissed` : null,
+    ].filter(Boolean);
+    if (resolvedParts.length > 0) {
+      push(paint(c.dim, `    ${resolvedParts.join(", ")} already, no action needed (see Rotation below for which)`));
+    }
+  }
   push();
 
   const sorted = [...byRule.entries()].sort((a, b) => b[1].items.length - a[1].items.length);

package/src/rotation.js

@@ -668,47 +668,86 @@ function statePath() {
 }
 
 /**
- * Load the ack map: { "<fingerprint>": { at, note } }. Missing file is the
- * normal first-run case and returns {} silently. A corrupt or unreadable
- * file returns {} too, but LOUDLY: one note on stderr, because "your acks
- * are gone" must never be silent, and because the next ackFinding() will
+ * Parse one map (acks, or dismissed) out of the already-JSON-parsed state
+ * file body. Shared by loadFullState() for both keys: same validation, same
+ * per-entry degrade-not-discard behavior, so a hand-edited or foreign
+ * ledger loses only its malformed entries, never the whole file.
+ */
+function parseFpMap(raw) {
+  const out = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  for (const [fp, v] of Object.entries(raw)) {
+    if (!FINGERPRINT_RE.test(fp)) continue;
+    if (!v || typeof v !== "object") continue;
+    // Control bytes stripped on READ as well as on write: this file sits on
+    // disk between the two, and a hand-edited or foreign ledger must not be
+    // able to put a terminal escape into the report via a note.
+    out[fp] = {
+      at: typeof v.at === "string" ? stripControlChars(v.at) : null,
+      note: typeof v.note === "string" ? stripControlChars(v.note) : null,
+    };
+  }
+  return out;
+}
+
+/**
+ * Load the full rotation state: { acks, dismissed }, both shaped
+ * { "<fingerprint>": { at, note } }. Missing file is the normal first-run
+ * case and returns both empty silently. A corrupt or unreadable file
+ * returns both empty too, but LOUDLY: one note on stderr, because "your
+ * acks are gone" must never be silent, and because the next write will
  * start a fresh store over the corrupt one.
  */
-function loadAcks({ file = statePath() } = {}) {
+function loadFullState({ file = statePath() } = {}) {
+  const empty = { acks: {}, dismissed: {} };
   let text;
   try {
     text = fs.readFileSync(file, "utf-8");
   } catch (err) {
-    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return {};
-    process.stderr.write(`residoo: rotation state ${path.basename(file)} could not be read; continuing with no acknowledgements\n`);
-    return {};
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return empty;
+    process.stderr.write(`residoo: rotation state ${path.basename(file)} could not be read; continuing with no acknowledgements or dismissals\n`);
+    return empty;
   }
   let parsed;
   try {
     parsed = JSON.parse(text);
   } catch {
-    process.stderr.write(`residoo: rotation state ${path.basename(file)} is corrupt; continuing with no acknowledgements (a new acknowledgement will start a fresh store)\n`);
-    return {};
+    process.stderr.write(`residoo: rotation state ${path.basename(file)} is corrupt; continuing with no acknowledgements or dismissals (the next write will start a fresh store)\n`);
+    return empty;
   }
-  if (!parsed || typeof parsed !== "object" || parsed.v !== 1 || !parsed.acks || typeof parsed.acks !== "object" || Array.isArray(parsed.acks)) {
-    process.stderr.write(`residoo: rotation state ${path.basename(file)} has an unrecognized shape; continuing with no acknowledgements\n`);
-    return {};
+  if (!parsed || typeof parsed !== "object" || parsed.v !== 1) {
+    process.stderr.write(`residoo: rotation state ${path.basename(file)} has an unrecognized shape; continuing with no acknowledgements or dismissals\n`);
+    return empty;
   }
-  // Only well-formed entries under well-formed keys survive: state written
-  // by a future version (or hand-edited) degrades per-entry, not per-file.
-  const acks = {};
-  for (const [fp, v] of Object.entries(parsed.acks)) {
-    if (!FINGERPRINT_RE.test(fp)) continue;
-    if (!v || typeof v !== "object") continue;
-    // Control bytes stripped on READ as well as on write: this file sits on
-    // disk between the two, and a hand-edited or foreign ledger must not be
-    // able to put a terminal escape into the report via an ack note.
-    acks[fp] = {
-      at: typeof v.at === "string" ? stripControlChars(v.at) : null,
-      note: typeof v.note === "string" ? stripControlChars(v.note) : null,
-    };
+  // dismissed is a later addition to this same file (v stays 1: additive,
+  // tolerant of a file written by an older residoo that never had this key).
+  return { acks: parseFpMap(parsed.acks), dismissed: parseFpMap(parsed.dismissed) };
+}
+
+/** Backward-compatible: the acks half of loadFullState(), same call shape as before dismiss existed. */
+function loadAcks({ file = statePath() } = {}) {
+  return loadFullState({ file }).acks;
+}
+
+/** The dismissed half of loadFullState(). */
+function loadDismissed({ file = statePath() } = {}) {
+  return loadFullState({ file }).dismissed;
+}
+
+/** Atomic write of the full state: temp file in the same directory, then rename; 0o600/0o700, same as before. */
+function writeFullState(file, { acks, dismissed }) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.rotations.json.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+  const body = JSON.stringify({ v: 1, acks, dismissed }, null, 2) + "\n";
+  fs.writeFileSync(tmp, body, { mode: 0o600 });
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    // The rename failing must not strand a temp file next to the state.
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
   }
-  return acks;
 }
 
 /**
@@ -732,42 +771,44 @@ function sanitizeNote(note) {
 }
 
 /**
- * Record that the user acknowledged (rotated / accepted) one finding.
+ * Record that the user acknowledged (rotated) one finding, or dismissed it
+ * (decided it was never a real secret, a test fixture, a vendor example not
+ * already on the suppression list, etc.) — two DIFFERENT resolutions of the
+ * same "this is no longer pending" question, kept as separate maps in one
+ * file rather than a single status field: acked and dismissed have
+ * different guidance implications (an acked finding's guidance stays
+ * relevant if you ever need to re-check the rotation; a dismissed one
+ * never needed guidance in the first place) and different --fail-on-find
+ * semantics may want to diverge later. Shared helper for both:
+ * ackFinding(fp, note) / dismissFinding(fp, note).
+ *
  * Atomic: temp file in the same directory, then rename; 0o600 on the file,
  * 0o700 on the directory, since even a redacted rotation ledger is nobody
  * else's business.
  *
- * Atomic is not serialized: two concurrent `residoo ack` runs each
- * load-modify-write, and the last rename wins, silently dropping the other
- * run's ack. Accepted as a single-writer design: acks are typed by a human
- * one at a time, the ledger is per-user state, and the failure direction is
- * fail-safe (a dropped ack reverts that finding to pending, never the
- * reverse). A lockfile would add a stale-lock recovery path for a race that
- * a person cannot realistically produce.
+ * Atomic is not serialized: two concurrent `residoo ack`/`dismiss` runs
+ * each load-modify-write, and the last rename wins, silently dropping the
+ * other run's change. Accepted as a single-writer design: these are typed
+ * by a human one at a time, the ledger is per-user state, and the failure
+ * direction is fail-safe (a dropped entry reverts that finding to pending,
+ * never the reverse). A lockfile would add a stale-lock recovery path for
+ * a race that a person cannot realistically produce.
  */
-function ackFinding(fp, note, { file = statePath() } = {}) {
+function resolveFinding(kind, fp, note, { file = statePath() } = {}) {
   if (typeof fp !== "string" || !FINGERPRINT_RE.test(fp)) {
-    throw new TypeError("ackFinding expects a fingerprint from fingerprintFinding() (rf1-<32 hex>)");
+    throw new TypeError(`${kind}Finding expects a fingerprint from fingerprintFinding() (rf1-<32 hex>)`);
   }
-  const acks = loadAcks({ file });
+  const state = loadFullState({ file });
   const entry = { at: new Date().toISOString(), note: sanitizeNote(note) };
-  acks[fp] = entry;
-
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const tmp = path.join(dir, `.rotations.json.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
-  const body = JSON.stringify({ v: 1, acks }, null, 2) + "\n";
-  fs.writeFileSync(tmp, body, { mode: 0o600 });
-  try {
-    fs.renameSync(tmp, file);
-  } catch (err) {
-    // The rename failing must not strand a temp file next to the state.
-    try { fs.unlinkSync(tmp); } catch {}
-    throw err;
-  }
+  const key = kind === "ack" ? "acks" : "dismissed";
+  state[key][fp] = entry;
+  writeFullState(file, state);
   return { fingerprint: fp, ...entry, file };
 }
 
+function ackFinding(fp, note, opts) { return resolveFinding("ack", fp, note, opts); }
+function dismissFinding(fp, note, opts) { return resolveFinding("dismiss", fp, note, opts); }
+
 // ── summaries for the report layer ──────────────────────────────────────────
 
 /**
@@ -776,42 +817,58 @@ function ackFinding(fp, note, { file = statePath() } = {}) {
  * across a transcript are one rotation to do, not five (the same
  * distinct-vs-re-exposed reasoning scan.js applies to counting).
  */
-function pendingSummary(findings, acks) {
+function pendingSummary(findings, acks, dismissed = {}) {
   const list = Array.isArray(findings) ? findings : [];
   const ackMap = acks && typeof acks === "object" ? acks : {};
+  const dismissMap = dismissed && typeof dismissed === "object" ? dismissed : {};
   const statuses = [];
-  const distinct = new Map();
+  const distinctStatus = new Map(); // fp -> "acked" | "dismissed" | "pending"
   for (const f of list) {
     const fp = fingerprintFinding(f);
     const ack = ackMap[fp] || null;
+    const dismiss = dismissMap[fp] || null;
+    // Precedence when a fingerprint somehow has both (not reachable through
+    // the CLI today, but the state file is hand-editable): acked wins. "I
+    // rotated it" is the more thorough resolution of the two, and reverting
+    // to "acked" from a stray dismissed entry is the fail-safe direction —
+    // it keeps guidance attached rather than silently dropping a real
+    // rotation's record.
+    const status = ack ? "acked" : dismiss ? "dismissed" : "pending";
+    const resolved = ack || dismiss;
     statuses.push({
       fingerprint: fp,
-      status: ack ? "acked" : "pending",
-      ackedAt: ack ? ack.at : null,
-      ackNote: ack ? ack.note : null,
+      status,
+      ackedAt: resolved ? resolved.at : null,
+      ackNote: resolved ? resolved.note : null,
     });
-    if (!distinct.has(fp)) distinct.set(fp, !!ack);
+    if (!distinctStatus.has(fp)) distinctStatus.set(fp, status);
+  }
+  let acked = 0, dismissedCount = 0;
+  for (const status of distinctStatus.values()) {
+    if (status === "acked") acked++;
+    else if (status === "dismissed") dismissedCount++;
   }
-  let acked = 0;
-  for (const isAcked of distinct.values()) if (isAcked) acked++;
   return {
     counts: {
       findings: list.length,
-      distinct: distinct.size,
-      pending: distinct.size - acked,
+      distinct: distinctStatus.size,
+      pending: distinctStatus.size - acked - dismissedCount,
       acked,
+      dismissed: dismissedCount,
     },
     statuses,
   };
 }
 
+const STATUS_ORDER = { pending: 0, acked: 1, dismissed: 2 };
+
 /**
  * Pure data for the report layer: one entry per distinct fingerprint, with
  * rotation guidance attached and pending entries first. Prints nothing.
  */
-function renderRotation(findings, acks) {
+function renderRotation(findings, acks, dismissed = {}) {
   const list = Array.isArray(findings) ? findings : [];
-  const { counts, statuses } = pendingSummary(list, acks);
+  const { counts, statuses } = pendingSummary(list, acks, dismissed);
 
   const byFp = new Map();
   for (let i = 0; i < list.length; i++) {
@@ -831,6 +888,7 @@ function renderRotation(findings, acks) {
         status: st.status,
         ackedAt: st.ackedAt,
         ackNote: st.ackNote,
+        lastSeenMs: null,
       };
       byFp.set(st.fingerprint, e);
     }
@@ -839,10 +897,18 @@ function renderRotation(findings, acks) {
     if (rel && !e.files.includes(rel)) e.files.push(rel);
     const src = f.source != null ? String(f.source) : null;
     if (src && !e.sources.includes(src)) e.sources.push(src);
+    // Most recent occurrence across all files this value showed up in: the
+    // honest, locally-derivable signal for "how stale is this." NOT proof a
+    // credential was rotated or revoked, only that residoo hasn't seen it
+    // paste anywhere more recently than this. residoo makes no network
+    // calls, so it never checks a provider for whether a key is still live.
+    if (typeof f.fileMTimeMs === "number" && (e.lastSeenMs === null || f.fileMTimeMs > e.lastSeenMs)) {
+      e.lastSeenMs = f.fileMTimeMs;
+    }
   }
 
   const entries = [...byFp.values()].sort((a, b) => {
-    if (a.status !== b.status) return a.status === "pending" ? -1 : 1;
+    if (a.status !== b.status) return STATUS_ORDER[a.status] - STATUS_ORDER[b.status];
     if (a.ruleId !== b.ruleId) return a.ruleId < b.ruleId ? -1 : 1;
     return a.fingerprint < b.fingerprint ? -1 : 1;
   });
@@ -857,7 +923,9 @@ module.exports = {
   fingerprintFinding,
   statePath,
   loadAcks,
+  loadDismissed,
   ackFinding,
+  dismissFinding,
   pendingSummary,
   renderRotation,
 };