Mole bug patterns
Generic review belongs to Waza check; root-cause investigation of a live failure belongs to hunt.
Route before loading details
Choose only the reference families touched by the evidence. A whole-project audit should classify surfaces first instead of loading every incident narrative.
| # |
Recurring shape |
First probe |
Read |
| 1 |
Deletion candidate built from a weak name signal |
Inspect name, bundle-id, and fallback globs |
Deletion evidence and final sink |
| 2 |
Existence or idleness decided by one probe |
Enumerate every legitimate location and unknown outcome |
Deletion evidence and final sink |
| 3 |
Guard present on only one branch |
Diff dry-run, real, direct, fallback, and final-sink paths |
Deletion evidence and final sink |
| 4 |
Unbounded external command |
Count producer, consumer, inner-loop, and action bounds |
Bounds, Shell, TTY, and parsing |
| 5 |
Bash 3.2, errexit, or pipefail trap |
Check empty arrays, `fn |
|
| 6 |
TTY, stdin, or process-group theft |
Inspect background workers and commands that may prompt |
Bounds, Shell, TTY, and parsing |
| 7 |
System output parsed as a stable API |
Force locale and validate shape before accepting data |
Bounds, Shell, TTY, and parsing |
| 8 |
Persisted derived data outlives its algorithm |
Trace schema, TTL, evidence fingerprint, and mutations |
State, accounting, and progress |
| 9 |
Two paths compute one number differently |
Find every producer and choose one definition |
State, accounting, and progress |
| 10 |
Slow work looks frozen |
Find operations over roughly one second outside feedback |
State, accounting, and progress |
| 11 |
Regression test cannot fail |
Prove positive control and pre-fix red state |
Test validity and refusal diagnostics |
| 12 |
Gate cannot explain why it refused |
Map each reason code to one cause and next action |
Test validity and refusal diagnostics |
| 13 |
Mutation target is also accepted as a discovery container |
Compare the recursive scan-root namespace with every purge target basename |
Deletion evidence and final sink |
| 14 |
Owner metadata is treated as a complete, atomic inventory |
Identify who writes it, whether absence is authoritative, and what locks mutation |
Deletion evidence and final sink |
| 15 |
Cancellation stops one helper but later work continues |
Trace 124 and signal statuses across loops, subshells, workers, and section orchestration |
Bounds, Shell, TTY, and parsing |
| 16 |
Async or cached data has no generation or freshness contract |
Bind results to a request epoch and keep each sample's time, stale, and completeness fields together |
State, accounting, and progress |
| 17 |
Publication gate trusts ambiguous or pre-existing state |
Require exact source/tag equality, one generated target, and an expected-absence ref lease |
Test validity and refusal diagnostics |
Trace the complete mutation lifecycle
For cleanup, purge, optimize, analyze deletion, or uninstall work, review the complete chain rather than the reported branch:
discover or plan
-> cheap irreversible filters
-> owner and open-handle probes
-> size or metadata work
-> final owner re-probe
-> parent and target identity rebind
-> deletion or Trash sink
-> accounting, cancellation, and user output
At every transition, answer:
- Does live or unknown state fail closed?
- Do timeout and signal statuses remain observable and stop later mutation?
- Are probe and sink bound to the same physical parent and target?
- Do dry-run and real mode start from the same eligible plan without reusing stale authorization?
- Are cheap missing, protected, whitelisted, and compiled-model filters ahead of recursive probes?
- Does one cumulative deadline cover the dynamic scan scope, with checkpoints in nested loops?
- Do refused, filtered, timed-out, or failed items stay out of cleaned counts and reclaimed bytes?
- Can large candidates avoid per-item size work without making the reported total false?
Do not trade final-sink rebinding or fail-closed owner checks for speed. Optimize absent targets, duplicated discovery probes, report-only work, and wrong-scope scans first.
Working contract
- Sweep siblings by call-site shape, not filename or helper name. Report
checked N / defective M / not applicable K.
- A recurring fix ships with a regression or source invariant that fails against the pre-fix code.
- Treat tests as production consumers only after proving the production helper ran. Negative assertions require a positive trace.
- A cancellation regression makes the next candidate otherwise eligible, then proves its probe and sink never run. Making every candidate fail for the same reason is a false sticky-cancellation test.
- Absence-sensitive tests use an isolated
HOME or fixture root; a shared setup_file home is not isolation.
- Reproduce CI through
MOLE_TEST_NO_AUTH=1 ./scripts/test.sh when possible. If invoking Bats directly with jobs, preserve --no-parallelize-within-files; files share state and raw bats --jobs 6 file.bats changes semantics.
- Treat specialist or AI reports as leads. Read the implementation, callers, fallback branches, and final sink yourself.
Verification bar
Use the hotspot commands in AGENTS.md; do not guess a narrower verifier. A typical Shell safety change finishes with:
./scripts/check.sh --format
MOLE_TEST_NO_AUTH=1 bats tests/<area>.bats
MOLE_TEST_NO_AUTH=1 ./scripts/test.sh
go test ./...
MOLE_TEST_NO_AUTH=1 MOLE_DRY_RUN=1 ./mole clean --dry-run
Never infer a production defect from a function name, comment, string, fixture, or _test.go match. Confirm the live call path and verify red-green before reporting the class fixed.
1---2name: bugs-23description: Mole incident catalog for destructive cleanup safety, bounded Shell/macOS probes, cancellation and concurrency, dry-run/real parity, async freshness, cache and accounting consistency, Bats validity, and actionable gates. Use for a Mole bug or safety-sensitive diff involving deletion evidence, owner metadata, unknown process state, timeouts or signals, parallel workers, stale results, system parsing, persisted derivations, totals, progress, publication gates, or tests. Not for docs, release planning or notes, generic review, or other repositories.4---56# Mole bug patterns78Generic review belongs to Waza `check`; root-cause investigation of a live failure belongs to `hunt`.910## Route before loading details1112Choose only the reference families touched by the evidence. A whole-project audit should classify surfaces first instead of loading every incident narrative.1314| # | Recurring shape | First probe | Read |15|---|---|---|---|16| 1 | Deletion candidate built from a weak name signal | Inspect name, bundle-id, and fallback globs | [Deletion evidence and final sink](references/deletion-evidence-and-final-sink.md) |17| 2 | Existence or idleness decided by one probe | Enumerate every legitimate location and unknown outcome | [Deletion evidence and final sink](references/deletion-evidence-and-final-sink.md) |18| 3 | Guard present on only one branch | Diff dry-run, real, direct, fallback, and final-sink paths | [Deletion evidence and final sink](references/deletion-evidence-and-final-sink.md) |19| 4 | Unbounded external command | Count producer, consumer, inner-loop, and action bounds | [Bounds, Shell, TTY, and parsing](references/shell-and-test-pitfalls.md) |20| 5 | Bash 3.2, errexit, or pipefail trap | Check empty arrays, `fn || handler`, and optional actions | [Bounds, Shell, TTY, and parsing](references/shell-and-test-pitfalls.md) |21| 6 | TTY, stdin, or process-group theft | Inspect background workers and commands that may prompt | [Bounds, Shell, TTY, and parsing](references/shell-and-test-pitfalls.md) |22| 7 | System output parsed as a stable API | Force locale and validate shape before accepting data | [Bounds, Shell, TTY, and parsing](references/shell-and-test-pitfalls.md) |23| 8 | Persisted derived data outlives its algorithm | Trace schema, TTL, evidence fingerprint, and mutations | [State, accounting, and progress](references/state-accounting-and-progress.md) |24| 9 | Two paths compute one number differently | Find every producer and choose one definition | [State, accounting, and progress](references/state-accounting-and-progress.md) |25| 10 | Slow work looks frozen | Find operations over roughly one second outside feedback | [State, accounting, and progress](references/state-accounting-and-progress.md) |26| 11 | Regression test cannot fail | Prove positive control and pre-fix red state | [Test validity and refusal diagnostics](references/test-validity-and-refusal-diagnostics.md) |27| 12 | Gate cannot explain why it refused | Map each reason code to one cause and next action | [Test validity and refusal diagnostics](references/test-validity-and-refusal-diagnostics.md) |28| 13 | Mutation target is also accepted as a discovery container | Compare the recursive scan-root namespace with every purge target basename | [Deletion evidence and final sink](references/deletion-evidence-and-final-sink.md) |29| 14 | Owner metadata is treated as a complete, atomic inventory | Identify who writes it, whether absence is authoritative, and what locks mutation | [Deletion evidence and final sink](references/deletion-evidence-and-final-sink.md) |30| 15 | Cancellation stops one helper but later work continues | Trace 124 and signal statuses across loops, subshells, workers, and section orchestration | [Bounds, Shell, TTY, and parsing](references/shell-and-test-pitfalls.md) |31| 16 | Async or cached data has no generation or freshness contract | Bind results to a request epoch and keep each sample's time, stale, and completeness fields together | [State, accounting, and progress](references/state-accounting-and-progress.md) |32| 17 | Publication gate trusts ambiguous or pre-existing state | Require exact source/tag equality, one generated target, and an expected-absence ref lease | [Test validity and refusal diagnostics](references/test-validity-and-refusal-diagnostics.md) |3334## Trace the complete mutation lifecycle3536For cleanup, purge, optimize, analyze deletion, or uninstall work, review the complete chain rather than the reported branch:3738```text39discover or plan40 -> cheap irreversible filters41 -> owner and open-handle probes42 -> size or metadata work43 -> final owner re-probe44 -> parent and target identity rebind45 -> deletion or Trash sink46 -> accounting, cancellation, and user output47```4849At every transition, answer:5051- Does live or unknown state fail closed?52- Do timeout and signal statuses remain observable and stop later mutation?53- Are probe and sink bound to the same physical parent and target?54- Do dry-run and real mode start from the same eligible plan without reusing stale authorization?55- Are cheap missing, protected, whitelisted, and compiled-model filters ahead of recursive probes?56- Does one cumulative deadline cover the dynamic scan scope, with checkpoints in nested loops?57- Do refused, filtered, timed-out, or failed items stay out of cleaned counts and reclaimed bytes?58- Can large candidates avoid per-item size work without making the reported total false?5960Do not trade final-sink rebinding or fail-closed owner checks for speed. Optimize absent targets, duplicated discovery probes, report-only work, and wrong-scope scans first.6162## Working contract6364- Sweep siblings by call-site shape, not filename or helper name. Report `checked N / defective M / not applicable K`.65- A recurring fix ships with a regression or source invariant that fails against the pre-fix code.66- Treat tests as production consumers only after proving the production helper ran. Negative assertions require a positive trace.67- A cancellation regression makes the next candidate otherwise eligible, then proves its probe and sink never run. Making every candidate fail for the same reason is a false sticky-cancellation test.68- Absence-sensitive tests use an isolated `HOME` or fixture root; a shared `setup_file` home is not isolation.69- Reproduce CI through `MOLE_TEST_NO_AUTH=1 ./scripts/test.sh` when possible. If invoking Bats directly with jobs, preserve `--no-parallelize-within-files`; files share state and raw `bats --jobs 6 file.bats` changes semantics.70- Treat specialist or AI reports as leads. Read the implementation, callers, fallback branches, and final sink yourself.7172## Verification bar7374Use the hotspot commands in `AGENTS.md`; do not guess a narrower verifier. A typical Shell safety change finishes with:7576```bash77./scripts/check.sh --format78MOLE_TEST_NO_AUTH=1 bats tests/<area>.bats79MOLE_TEST_NO_AUTH=1 ./scripts/test.sh80go test ./...81MOLE_TEST_NO_AUTH=1 MOLE_DRY_RUN=1 ./mole clean --dry-run82```8384Never infer a production defect from a function name, comment, string, fixture, or `_test.go` match. Confirm the live call path and verify red-green before reporting the class fixed.
tw93