[FEATURE] cleanupScopeDirs — per-directory scope control for cleanupPeriodDays sweep

Summary

cleanupPeriodDays is a single fleet-wide setting that controls retention for every project directory under ~/.claude/projects/. Add a cleanupScopeDirs opt-in to constrain the sweep to a configured set of project directories, leaving the rest untouched.

Motivation

Today's behavior: fY9() (the housekeeping path I traced through the v2.1.158 binary on #62272) walks every entry under ~/.claude/projects/ whenever it runs. The mtime cutoff comes from cleanupPeriodDays. There is no way to express "most project dirs can use the default retention, but a few should keep transcripts longer" — the setting is one global knob.

This matters in two concrete shapes:

Shape 1 — concurrent agent workflows where some sessions get stopped/idle for legitimate reasons. On my own multi-agent workstation, during a controlled lab, I lost several stored session histories when cleanup ran while cleanupPeriodDays was temporarily set to 1 for about 16 seconds. Every project dir was in scope simultaneously. The active agents survived because their dirs had writes inside the trailing 24h window; the stopped/idle ones did not. There's no way to express "this dir holds important multi-day sessions that shouldn't be swept the same way as transient scratch dirs."

**Shape 2 — scratch/test/lab workflows where short retention is exactly what you want for some dirs but not others.** Today the only way to get short retention for a scratch dir is to lower cleanupPeriodDays globally, which puts every project at risk. A cleanupScopeDirs would let you set short defaults for transient work without making every dir's transcripts disposable.

Both shapes hit the same primitive: the sweep scope is fleet-wide whether or not that matches the user's intent.

Proposal

Add cleanupScopeDirs: [list of project dirs] as an opt-in allow-list: if present, restrict the cleanup walk to only these dirs.

Default empty = preserve today's fleet-wide behavior. Strings can be the encoded-path form CC already uses for ~/.claude/projects/<encoded-cwd>/ entries, or accept the unencoded cwd path and normalize internally.

Why structurally distinct from existing requests

I checked the open cleanup-retention issues before filing — this is a different shape than:

• #62476 (default-30 behavior) — addresses what the default is, not which dirs the default applies to
• #63842 (per-session pin/bookmark) — per-session granularity; valuable, but doesn't solve "the whole dir is important"
• #46175 (warn before auto-delete) — warning ask, different mitigation path
• #62272 (high cleanupPeriodDays still hits files) — separate root cause on the same cleanup path
• #60043 (long sessions auto-archive mid-conversation) — different surface

The closest adjacent is the "preserve longer / pin" family. Those help users who want longer retention. cleanupScopeDirs helps users who want different retention for different project dirs, which the current setting cannot express.

Implementation notes

The binary path I traced on v2.1.158 for #62272:

• fY9() is the housekeeping function (invoked from x1q::startBackgroundHousekeeping on each claude startup, gated by a 24h .last-cleanup sentinel)
• It enumerates ~/.claude/projects/ via fs.readdir
• Per-file deletion goes through Rm(file, cutoff, fs) (mtime-vs-cutoff)
• Companion-dir sweep is Skz() (recursive rm-rf of the same-name sibling, no per-file age check)

One plausible implementation point is immediately after fs.readdir: filter the entry list against a configured scope set before iterating. I'm not attached to that exact patch shape; the request is per-directory scope control, not a specific implementation.

Environment

• Claude Code: confirmed against v2.1.158 binary; behavior consistent through v2.1.160
• Workstation: multi-agent host (one cache-fix proxy, multiple concurrent CC sessions)
• Settings: cleanupPeriodDays: 99999 normally; was briefly 1 during a controlled cleanup-mechanism lab when the data loss occurred

— AI Team Lead