Housekeeping

只有当 ThreadCells 能证明运行时工件符合条件时，Housekeeping 才会回收它们。它有意采取保守策略：未知、不可读、活动、被引用或已变更的资源会受到保护，而不会被猜测为可安全删除。

Click to expand

可清理的内容

根据时间和所有权证据，计划可以包含：

• 带有 ThreadCells 所有权标记的过期临时路径；
• 未被活动终端引用的旧终端附件；
• 符合压缩或保留清理条件的日志；
• 由精确进程身份识别的孤立浏览器进程组；
• 未被活动元数据引用的浏览器修订版本和缓存；
• 所有者已失效且未被引用的带有 ThreadCells 标签的容器和卷；
• 具有可测量回收操作的受信任包缓存；
• 由规范暂存元数据表示的非活动候选版本/发布版本。
• 其持久化终端已关闭且进程身份仍匹配的精确已关闭终端运行时窗格和进程后代；
• 在其持久化结果/退役边界被确认并重新验证后的待清理受管子 worktree。
• HEAD 已包含在显式配置的持久 Git ref 中的干净非活动 linked worktree；
• 直接位于已批准缓存根下、所有者已失效且保留期已过的带标记可复现缓存/生成证据。

Housekeeping 不会盲目删除源仓库、活动或未知 worktree、正在运行的终端、打开的文件、当前/回滚发布版本、已暂存候选版本或备份。linked worktree 通过 git worktree remove 和 git worktree prune 退役，绝不使用通用递归删除。退役已关闭的终端运行时不会删除其持久化会话、代理、Inbox、结果或工作流历史。

可复现目录必须是已配置根目录的直接子目录，并带有 .threadcells-reproducible.json：

{"schema_version":1,"owner":"threadcells","kind":"cache","created_at":1790000000,"owner_pid":12345}

支持的种类为 cache、generated、test_evidence 和 candidate。缺失或无效的标记、符号链接、路径逃逸、存活的所有者以及仍在保留窗口内的路径都会保持受保护。

部署还可为向后兼容的 CI 缓存命名由 ThreadCells 拥有的精确缓存前缀。这些条目仍受限于运行时拥有的根目录下的直接子目录，并要求保留期已过，以及相同的活动进程和执行时身份检查。未列出的前缀（包括含糊的发布候选工件）仍受保护。

先规划，再执行

dry-run 计划是只读的。每个候选项包含其类别、规范身份/指纹、拟议操作、总字节数、已知时的预计回收字节数、保留原因和保护原因。类别汇总分别报告可操作/可回收与保留/受保护的占用空间，因此大型受保护类别不会被隐藏为零字节。

Inspect current state
      ↓
Build immutable plan and plan_id
      ↓ operator reviews
Execute exact plan_id
      ↓
Rebuild protected set under lock
      ↓
Revalidate each candidate immediately before action
      ↓
Report reclaimed, skipped, changed, and failed items

如果候选集在计划和执行之间发生变化，手动执行会拒绝过期计划，且不会变更资源。每个剩余候选项都会在变更前再次检查。

Full Cleanup

Settings → Housekeeping 危险区的最后一个操作是 Delete all system files — Full Cleanup。它与普通 Housekeeping 使用相同的规范清单、保护集、不可变计划标识和执行时身份检查，但采用最大化且已证实安全的保留策略：可复现缓存、旧日志、build/candidate/temp 工件、可安全退役的 worktree 以及每个不活跃的本地发布版本都可能符合条件。所有权未知或权限含糊的资源仍受保护，并会在计划和报告中说明原因。

只有当后端生命周期事实证明每个相关智能体均处于 Ready、Exited 或明确等价的非执行状态时，Full Cleanup 才可用。Working、Processing、Starting、已排队的文件系统变更、提供商执行、Heavy 工作、运行时操作和未知生命周期身份都会阻止执行。服务器会取得规范准入栅栏，并在变更前立即重新检查该空闲门；如果智能体在预览后变为活跃，运行会在删除任何内容之前中止。

预览是只读的。执行准入需要现有的短时操作员解锁以及现有的永久操作确认对话框；不存在 Full Cleanup 专用密码或客户端存储的密钥。准入会创建一个绑定到精确 64 字符 plan_id 的不透明操作 ID，且不携带任意路径。操作一旦获准，其持久进度和终态报告会跨越浏览器断开、解锁过期和控制平面重启而保留。重复提交同一操作只会观察其状态，不会启动第二次破坏性执行；不同计划需要新的授权。

每个基于路径名的 Full Cleanup 候选项均由职责受限、通过套接字激活的 root helper 执行；该 helper 会使用一次性服务器能力、重建精确计划、证明空闲门条件成立，并确认控制平面仍持有所有准入栅栏。原始操作员凭据绝不会发送给 helper。Helper 将每个候选项移入同一文件系统中仅 root 可访问的隔离区，锁定已捕获的目录树以防运行时用户修改，然后仅通过目录描述符删除已验证的身份。它会在响应前持久化有界终态报告；重启和轮询协调会保留仍存活的精确 helper，或在不重放破坏性执行的前提下如实报告失败/不确定结果。身份发生变化的资源会被保留并写入报告；非文件系统生命周期资源仍由其规范事务执行器处理。

Full Cleanup 成功后，只保留当前活跃的不可变本地 ThreadCells 发布版本。所有已证实不活跃的回滚/恢复发布版本都会被移除，发布元数据会原子协调，并报告本地回滚不可用。活跃发布版本和活跃指针绝不会成为候选项。Ready 智能体仍可继续使用：其 worktree、写入者权限、当前上下文、当前输出和其他继续执行状态均受保护。安全清理文件系统输出后，Exited 历史记录仍可保留在 SQLite 中；此时 Full Output 会报告持久化输出不可用，而不是失败或伪造文本。

备份、当前源代码/工具权限、提供商凭据/状态、SQLite 数据库以及任何未经证明的资源仍受保护。第二次 Full Cleanup 会安全地产生一个接近零可操作项的计划，只有新近符合条件或之前受保护的项目除外。

安全手动示例

在已安装环境中，先请求 JSON 输出：

threadcells-housekeeping --dry-run --json

审阅每个候选项并复制返回的 plan_id。只执行已检查的计划：

threadcells-housekeeping --plan-id PLAN_ID_FROM_DRY_RUN

在理解计划前，不要编写 plan_id 提取和立即执行的脚本。dry-run 绝不意味着已获准删除。

保护集理念

保护集汇集活动终端和 worktree、写入者/工作流所有权、当前源/运行时谱系、活动与回滚发布版本、已暂存候选版本、被引用的浏览器修订版本、打开文件、存活进程启动身份和终端身份、容器引用元数据、备份和共享锁。

细节对实现很重要，但操作员规则很简单：没有证据并不等于资源已失效的证据。如果无法准确建立保护，Housekeeping 就会跳过该资源并报告原因。

受保护的工作流权限源自持久化根终端身份。启动和频繁协调会取消根终端已不存在的孤立非恢复工作流，然后重新生成保护集。在该关系协调完成前，整个不确定清单中的 worktree 退役都会按 fail-closed 原则拒绝。

计划

Settings → Housekeeping 将策略、计划、规划、执行和报告分开。支持的计划形态包括：

• 15 分钟到 365 天的高频间隔，例如 6h；
• 每周 UTC 计划，例如 Sun 04:00 UTC；
• 使用 on_red 的磁盘压力清理。

已安装的定时器可每 15 分钟轮询一次，并采用错开的初始激活时间，因此高频和每周检查通常不会冲突。持久化收据可防止一个计划类别在到期前运行两次。若计划轮询发现规范 Housekeeping 引擎已在活动，会成功退出并标记为跳过，随后再试；手动锁竞争仍为错误。计划运行会在一个服务锁下创建并执行其到期计划；它不会复用经人工批准的手动计划。

Housekeeping 变更和手动执行受操作员授权保护。

磁盘压力行为

在 YELLOW 时，检查增长情况并运行 dry plan。在 RED 时，即使常规重型工作可能被拒绝，ThreadCells 也可以准入恢复安全的 Housekeeping 重型租约。压力计划会先排序最大的已证实安全候选项，并显示主要受保护类别，但清理仍只算作一次 Heavy 执行，且不会绕过任何候选项保护。

YELLOW 是检查状态，而不是制造可回收字节的许可。当所有剩余的大型类别都受保护时，应扩充外部容量或记录受保护的占用空间，而不是削弱判定条件。

当命令无法证明字节数时，包缓存回收会报告为未知/零；ThreadCells 不会宣称猜测出的回收量。

报告与部分失败

最新报告记录计划/运行身份、资源状态、估算、实际结果、每个候选项的结果和稳定原因代码。一个候选项失败不会削弱后续候选项的保护，也不会掩盖独立的成功。

运行后，验证磁盘压力并检查被跳过/失败的条目。再次执行前重新规划；状态变化后不要复用旧计划。

备份与发布版本

备份仅作清单记录。备份介质的保留决策属于操作员的备份策略，而非自动 Housekeeping。

发布版本和候选版本清理共享规范暂存锁，并要求可信引用元数据。普通 Housekeeping 会保护活跃和回滚运行时。Full Cleanup 只保护活跃发布版本，并在操作员明确确认后有意移除每个已证实不活跃的本地回滚发布版本。请参阅升级。

已安装的定期 Housekeeping 服务会获得回收符合条件的不可变发布版本所需的窄范围发布维护组。主控制平面和普通代理进程不会获得该组。没有该权限的手动/API 运行会以 RELEASE_ADMIN_GROUP_REQUIRED 跳过发布删除，继续独立的安全清理，并让定期服务稍后通过同一计划/执行引擎回收发布版本。

开放路径保护会清点由配置的 ThreadCells 运行时账户拥有的每一个进程，而不论由哪个授权账户调用手动计划。其他主机账户不属于可处置 ThreadCells 状态的所有权边界；来自这些账户的不可读私有 /proc 条目不会禁用整台主机的清理。未知运行时身份，或检查运行时账户进程时的任何不确定性，仍会按 fail-closed 原则拒绝。

常见错误

• 为了回收空间而直接删除 worktree 目录。
• 将预计字节数视为保证可回收量。
• 执行未经检查的计划。
• 假定停止的 PID 足以证明浏览器/进程组就是旧进程。
• 期望 Housekeeping 删除备份。
• 通过提高磁盘阈值而不是解决持续增长问题。