/gc

/cc-enslaver:gc

长期使用插件后，${CLAUDE_PLUGIN_DATA}/sessions/ 下会累积每会话一个 JSON 状态文件。每个文件几 KB，但数量积起来值得清理。本命令调用 hooks/scripts/gc_state.py 按 mtime 阈值 列出 / 删除老旧 state。

安全默认

默认 --dry-run 模式（只打印不删除）。要真正删除必须显式加 --apply。 mtime 是最近一次 state_lib.add_read 的时间戳；30 天没活动的几乎肯定 是已死会话。

你（receiving agent）要做的

按用户传入的参数构造 Bash 调用：

python "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/gc_state.py" --dry-run --older-than 30

或：

python "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/gc_state.py" --apply --older-than 30

参数解释：

• --dry-run / --apply：互斥，必须传一个。无参数默认走 --dry-run。
• --older-than DAYS：阈值（天数）。默认 30。

输出契约

脚本始终打印：

state_dir: <path>
scanned:   <N>
threshold: <M> days
eligible:  <K>
  [dry-run] would delete: <name>  (<age>d old, <size>B)   |   deleted: <name>
  ...
deleted: <K>     |   would delete: <K>
bytes_freed: <B> |   would free: <B>B

用户场景

用户："/gc 看看"          → dry-run, 默认 30 天
用户："/gc 看看 90 天的"   → dry-run, --older-than 90
用户："/gc 真的删 30 天的" → --apply --older-than 30

如果 eligible 为 0 → 报告 "nothing to do" 即可。

禁止

• ❌ 不传任何参数就直接 --apply —— 始终先 dry-run 让用户看清楚再问。
• ❌ 删除 ${CLAUDE_PLUGIN_DATA}/sessions/ 之外的任何文件 —— 脚本本身有 这道防线（只 glob <state_dir>/*.json），不要绕过它。

自动 GC（v0.18 · opt-in）

设置环境变量 CC_ENSLAVER_AUTO_GC_DAYS=N（正整数）即可让 SessionStart 钩子在每次开会话时自动删除 ≥ N 天未触碰的 state 文件。受 24h 速率限制 （marker 文件 <state_dir>/_auto_gc.json），不会每次开会话都重扫。

# Bash / Linux / macOS
export CC_ENSLAVER_AUTO_GC_DAYS=30

# PowerShell
$env:CC_ENSLAVER_AUTO_GC_DAYS = "30"
[Environment]::SetEnvironmentVariable("CC_ENSLAVER_AUTO_GC_DAYS", "30", "User")  # 持久化

未设置 / 设为 0 / 设为非数字 → 自动 GC 完全禁用（默认）。失败 → silent stderr，永不阻塞 SessionStart 注入。/cc-enslaver:gc 手动命令 仍然完全可用，两个入口共用同一份 prune_old_sessions()。