codex-cleanup

Codex 清理

回收经过测量的本地存储空间或内存，同时不损坏任务历史记录、SQLite 状态、已安装的发行版或正在运行的任务。先审计，再提出具体目标，并且只修改用户批准的范围。

保留以下边界

• 审计和规划都应保持只读。
• 将当前或适用的较早用户指令中明确指定的清理范围视为该范围的授权。否则，先展示具体目标、后代项、预计字节数、可逆性以及是否需要重启，再征求确认。
• 永久删除任务时，使用受支持的任务生命周期功能。在展示或调用该功能前，通过帮助信息、架构或主要协议文档核实已安装版本的确切接口。切勿臆造便捷的 CLI 命令，也切勿直接删除运行记录文件或任务行。
• 在对目标数据库执行检查点、复制或压缩之前，先停止所有可能访问该数据库的进程。这包括所有共享同一解析后 Codex 主目录的 Desktop、CLI、IDE 扩展、app-server 和辅助会话，即使其中的任务看起来处于空闲状态。只有在能证明某会话使用的有效 Codex 主目录不同的情况下，该会话才可以保持打开；否则应将其视为可能的写入者。
• 切勿终止当前执行进程或其任何祖先进程。如果当前运行位于目标 Desktop 或 CLI 进程树中，请准备好确切的下一步操作，并让用户退出，或从单独的进程继续。
• 切勿一概删除 .tmp、plugins、worktrees、shell_snapshots、状态数据库、凭据或配置。必须先逐一证明每个目标的归属和过时状态。
• 保留无关的用户更改和数据。如果无法确认某个目标属于 Codex，或其安全生命周期未知，请停止操作。

审计

1. 依次从显式路径、CODEX_HOME，再到平台的用户主目录下的 .codex 目录，解析有效的 Codex 主目录。记录解析后的路径。
2. 在此技能目录中运行 scripts/audit_codex_home.py。该脚本为只读，会报告顶层目录大小、历史记录时长、SQLite 空闲页、发行版缓存候选项以及相关进程树。需要保留或比较结果时使用 --json。只有在额外数据库扫描可接受且客户端已停止后，才添加 --quick-check。常规页面指标仅来自主文件头。对于 --quick-check，如果检测到匹配的运行时进程，脚本会拒绝继续；它会检查临时副本，因此绝不会在 Codex 主目录中创建或更改数据库侧文件。其进程清单会有意省略参数和环境变量，因此无法证明每个进程使用的是哪个 Codex 主目录；应保守看待其运行时部分。
3. 如果兼容的 Codex 可执行文件提供只读的 doctor 命令，请运行该命令，并在修改前记录运行记录与数据库的一致性。优先使用活动 Desktop 或 CLI 所用的可执行文件；不要假定 shell 中的 codex 与其为同一构建版本。
4. 解读候选项或执行任何清理时，请阅读 references/storage-contract.md。如果其中的版本说明与已安装构建版本不符，请重新检查已安装的帮助信息或当前主要源代码。
5. 按测得的可回收字节数和可能带来的响应速度提升，对清理机会排序。分别列出磁盘存储、数据库内部空闲页和驻留内存；不要将它们相加成一个容易误导的总数。

操作前先报告审计结果。对于每个重要类别，都要说明当前大小、候选项大小、建议操作、风险／重启要求以及默认建议。

制定获批的清理计划

仅选择有证据支持的操作：

• 任务历史记录： 根据任务的时间、归档状态、项目或用户提供的条件，选择确切的根任务 ID。展开每个根任务的后代任务和子 Agent 任务，并列出这些任务。只有当生命周期 API 报告任务处于非活动状态，或有其他证据证明任务已完成时，才将其计为已完成；不要仅凭过时的生成边标记判断。排除当前任务和所有活动的写入任务。
• 运行时内存： 确定所属的桌面应用或 CLI 进程树、活动工作、当前进程的祖先链，以及过时的残留辅助进程。优先正常退出并重启应用或 CLI。只有在所属进程退出后仍有辅助进程残留时，才提出确切的 PID。
• 独立发布版本： 解析 current 指向的目标。保留该目标，并默认保留最新的不同回滚版本。仅在安装程序和更新程序均已停止时，才考虑其他完整的发布目录。
• 日志数据库： 当测得的空闲页面数所能释放的文件系统空间可观时，建议进行压缩；预计节省空间微不足道时则跳过。SQLite VACUUM 会保留保留的逻辑行，并重建文件以将空闲页面归还给文件系统。它不能替代任务删除或日志保留策略。必须确保有足够的工作空间用于安全副本和 SQLite 临时重写。批准、移交或执行压缩前，请阅读并遵循 workflows/compact-log-database.md。
• 其他缓存： 仅当已安装版本文档说明了所有权和清理语义，或用户审阅后批准了确切的可丢弃文件时，才采取操作。

不要将归档描述为释放空间：归档通常只会移动任务历史记录并更新其索引，不会删除运行记录内容。

按安全顺序执行

仅按下列顺序运行已批准的操作类别及其必需的前置步骤。仅清理历史记录不需要压缩数据库、删除缓存或执行其他非必要的关闭操作。

1. 通过已发现并验证的原生任务删除能力永久删除已批准的任务，例如 app-server thread/delete。记录可执行文件或已连接的能力、版本、方法名称和发现证据。包括已批准的已完成后代任务。让生命周期操作按照其一致性和重试顺序更新 rollout 文件、索引、日志、队列、记忆、目标、动态工具和派生边。如果 API 拒绝删除被外部引用的分支，请报告情况并询问是否扩大范围；不要绕过检查。如果没有已验证且可调用的删除接口，则停在列出缺失能力的计划上；不要将该方法转换为臆想的 codex delete 命令，也不要改用文件系统或 SQLite 删除。
2. 重新运行一致性诊断和历史记录清单。若存在缺失、重复、不匹配或过时的状态，则停止，不要继续执行优先级更低的清理。
3. 停止数据库访问。请用户完成或停止正在进行的工作，并退出所有共享已解析 Codex 主目录的 Desktop、CLI、IDE 扩展、app-server 和辅助程序会话。确认所有相关 PID 均已退出；不要根据会话看似空闲就推断安全。仅对确切的已批准残留 PID 发送正常终止信号；只有获得单独的明确授权后，才能升级为强制终止。
4. 在停止运行期间删除已批准的过时发行版目录。删除前立即重新解析 current 目标；如果它已发生变化或任何候选项与之相同，则中止。
5. 对于已批准的数据库压缩，执行压缩工作流的第 1–5 节：离线检查门槛、恢复副本、逻辑基线、PRAGMA integrity_check、WAL 检查点、VACUUM 和重新打开前检查。任何检查门槛失败或存在歧义时都应中止；不要将工作流简化为单独的 VACUUM 命令。
6. 分阶段重启。压缩后，遵循其工作流的第 6 节；否则，按正常方式重启预期客户端。验证保留的任务，然后使用相同选项重新运行审计，并将测得的字节数和进程与基线进行比较。

如果当前运行无法在停止期间继续存活，则在生成完整的离线交接内容后停止：确切的解析路径、已批准的目标、排除的当前祖先、前置退出检查、命令或 API 操作、验证以及恢复说明。不要安排无人监控的破坏性作业。

完成

对于仅审计请求，以调查结果和可执行的建议结束。 对于清理请求，在已批准的操作完成或已提供准确的离线交接内容后结束。报告适用的结果：

• 按类别统计的回收字节数和剩余磁盘空间；
• 已删除的任务，包括后代任务数量，以及明确保留的任务；
• 数据库完整性和 rollout／数据库一致性结果；
• 保留和删除的发行版目录；
• 已停止或仍处于活动状态的运行时进程；
• 任何跳过的目标、阻碍因素或恢复产物。

区分测量结果与估算和建议。