residoo 0.3.8 → 0.4.0

package/README.md

@@ -121,13 +121,18 @@ won't be built into the tool that writes it.
 - Redacts everything in its own output. You get a shape and a first/last-4
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
-- Every report opens with the exact version and timestamp it was run with
-  (`residoo v0.3.8 · 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. On an
-  interactive terminal, a lightweight spinner shows scan progress on
-  stderr; it is a complete no-op when stdout/stderr are piped, redirected,
-  or run in CI, so it can never interleave with `--json`/`--sarif` output.
+- On an interactive terminal, prints who it is and where it lives before
+  scanning starts (`residoo v0.4.0 · 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.4.0 · 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
+  `--json` and `--seal`. All of the interactive chatter (the intro, the
+  spinner) goes to stderr only and is a complete no-op when stdout/stderr
+  are piped, redirected, or run in CI, so none of it can ever interleave
+  with `--json`/`--sarif` output.
 - `--sarif` emits SARIF 2.1.0 for GitHub code scanning's Security tab and
   inline pull-request annotations, the same format gitleaks/trufflehog/
   agentsweep already speak, so residoo's own Action and pre-commit hook plug
@@ -292,12 +297,21 @@ 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.
 - **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
@@ -305,9 +319,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
 
@@ -324,7 +338,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.3.8
+  - uses: dandovdub/residoo@v0.4.0
 ```
 
 As a pre-commit hook:
@@ -332,7 +346,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.8
+    rev: v0.4.0
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "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

@@ -5,10 +5,10 @@ const fs = require("fs");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderIntegrity, renderJson, renderSarif, makeProgressReporter } = require("./report");
+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;
@@ -404,6 +449,7 @@ async function main(argv) {
   // mutated env var would leak past this one invocation and silently kill
   // color for a later call that never asked for that.
   const noColor = args.includes("--no-color");
+  printIntro(noColor);
 
   // Integrity runs by default: a scan that reports "no secrets leaked" while
   // a planted SessionStart hook sits ready to re-leak them next session is
@@ -466,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();
@@ -481,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" +
@@ -494,11 +542,11 @@ async function main(argv) {
     return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
-  const progress = makeProgressReporter();
+  const progress = makeProgressReporter(noColor);
   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

@@ -32,35 +32,58 @@ function ageDays(mtimeMs) {
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 /**
- * A minimal progress indicator for the scan phase, wired to scan()'s own
+ * Printed once, before scanning starts: what this is, what version, where
+ * it lives. Answers exactly the question a first-time (or every-time)
+ * reader has before results ever appear, without waiting for the report.
+ * Same TTY gate and same stream as the progress spinner below and for the
+ * same reason: stderr only, so a --json/--sarif consumer's stdout is
+ * untouched, and a complete no-op under redirection, piping, or CI.
+ */
+function printIntro(noColor) {
+  if (!process.stderr.isTTY) return;
+  const paint = makePaint(noColor);
+  const { version } = require("../package.json");
+  process.stderr.write(
+    paint(c.bold + c.cyan, `residoo v${version}`) +
+    paint(c.dim, " · find secrets your AI coding agent left on disk\n") +
+    paint(c.dim, "https://github.com/dandovdub/residoo\n\n")
+  );
+}
+
+/**
+ * A progress indicator for the scan phase, wired to scan()'s own
  * onProgress callback. Writes to STDERR only, never stdout: --json/--sarif
  * consumers pipe stdout into a parser, and a spinner corrupting that would
  * be a much worse bug than not having one. Gated on stderr actually being a
  * TTY, so it is a complete no-op under redirection, piping, or CI, exactly
  * the contexts where carriage-return spam in a captured log would be
- * useless or actively annoying, not merely invisible. `stop()` clears the
- * line so whatever prints next (the report, on stdout, is unaffected
- * either way since this never touched stdout, but a plain-text stderr
- * reader watching live should not see a stale line lingering) starts
+ * useless or actively annoying, not merely invisible. Shows the actual
+ * current file (basename only, through the same safeBasename() every other
+ * displayed path in this report goes through — control bytes stripped,
+ * invisible code points made visible), not just a running count: real
+ * signal, not just motion, and genuinely useful if a scan stalls on one
+ * huge file. `stop()` clears the line so whatever prints next starts
  * clean.
  */
-function makeProgressReporter() {
+function makeProgressReporter(noColor) {
   if (!process.stderr.isTTY) return { onProgress: null, stop() {} };
+  const paint = makePaint(noColor);
   let count = 0;
   let lastWriteMs = 0;
   let lastLineLen = 0;
   let frame = 0;
-  const write = (s) => {
+  const write = (s, visibleLen) => {
     process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r" + s);
-    lastLineLen = s.length;
+    lastLineLen = visibleLen;
   };
-  const onProgress = ({ source }) => {
+  const onProgress = ({ source, file }) => {
     count++;
     const now = Date.now();
     if (now - lastWriteMs < 80) return; // throttled: avoid flicker on a fast scan
     lastWriteMs = now;
     frame = (frame + 1) % SPINNER_FRAMES.length;
-    write(`${SPINNER_FRAMES[frame]} scanning… ${count} file${count === 1 ? "" : "s"} checked (${source})`);
+    const label = `scanning ${source}… ${count} file${count === 1 ? "" : "s"}  ${safeBasename(file)}`;
+    write(paint(c.bold + c.cyan, SPINNER_FRAMES[frame]) + " " + paint(c.dim, label), 2 + label.length);
   };
   const stop = () => { if (lastLineLen > 0) process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r"); };
   return { onProgress, stop };
@@ -120,9 +143,13 @@ 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])}`);
@@ -132,11 +159,17 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   // dump. Everything elided here is in --json in full.
   const MAX_SHOWN = 12;
   const shown = entries.slice(0, MAX_SHOWN);
+  const STATUS_TAG = {
+    pending: paint(c.yellow, "pending  "),
+    acked: paint(c.green, "acked    "),
+    dismissed: paint(c.dim, "dismissed"),
+  };
   for (const e of shown) {
-    const tag = e.status === "pending" ? paint(c.yellow, "pending") : paint(c.green, "acked  ");
-    push(`  ${tag}  ${e.fingerprint}  ${e.label}`);
+    push(`  ${STATUS_TAG[e.status]}  ${e.fingerprint}  ${e.label}`);
     if (e.status === "acked") {
       push(paint(c.dim, `           acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""}`));
+    } else if (e.status === "dismissed") {
+      push(paint(c.dim, `           dismissed ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} (not a real secret)`));
     } else {
       const g = e.guidance;
       const where = g.rotateUrl ? `rotate: ${g.rotateUrl}` : `where: ${g.consolePath}`;
@@ -146,7 +179,7 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   if (entries.length > shown.length) {
     push(paint(c.dim, `  … and ${entries.length - shown.length} more; see --json for the full list`));
   }
-  push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · mark one rotated: residoo ack <fingerprint>`));
+  push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · rotated: residoo ack <fp> · not a secret: residoo dismiss <fp>`));
   return lines.join("\n");
 }
 
@@ -264,6 +297,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);
@@ -304,9 +362,13 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
     push(renderIntegrity(integrity, { noColor }));
   }
 
+  push();
+  push(paint(c.bold, "Next steps:"));
+  push(`  residoo scan --json          ${paint(c.dim, "machine-readable output, full detail")}`);
+  push(`  residoo scan --seal          ${paint(c.dim, "encrypt the affected files into a local vault (originals untouched)")}`);
   push();
   push(paint(c.dim, "Values are redacted in this report (first/last 4 characters only). Nothing scanned"));
-  push(paint(c.dim, "here left your machine; residoo makes no network calls. Run with --json for full detail."));
+  push(paint(c.dim, "here left your machine; residoo makes no network calls."));
 
   return lines.join("\n");
 }
@@ -450,4 +512,4 @@ function renderSarif(result) {
   }, null, 2);
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter };
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter, printIntro };

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++) {
@@ -842,7 +899,7 @@ function renderRotation(findings, acks) {
   }
 
   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 +914,9 @@ module.exports = {
   fingerprintFinding,
   statePath,
   loadAcks,
+  loadDismissed,
   ackFinding,
+  dismissFinding,
   pendingSummary,
   renderRotation,
 };