---

name: lov-reclamation-engineering description: > This Skill should be used when the user asks “设计客户端 App 的安全资源回收”、 “审查后台任务、缓存、会话或外部工作区的生命周期”, or “review fail-closed cleanup and ABA safety” for a concrete desktop, mobile, hybrid, or web client. license: MIT metadata: author: LovStudio / 手工川工作室 version: "0.2.1" card_standard: lovstudio/skill-card/v1 invocation: kit_only tags: - app-runtime - resource-reclamation - lifecycle-engineering - fail-closed - aba-race compatibility: "Portable Agent Skills format; concrete client App source plus host, runtime/framework, lifecycle, and test adapters. Python 3.9+ supports the shared dry-run evidence helper." dependencies: - python

资源回收设计 · Resource Reclamation

把具体客户端 App 的资源治理实现成所有权与生命周期协议，而不是“超过一段时间就 kill/delete”。覆盖 desktop、mobile、hybrid 与 Web/PWA；先服从宿主生命周期，再证明 durable owner、runtime lease、活动真相、恢复路径和实例身份。任一关键证据未知、失败或变化时保护资源。

Triggers

Activate when

• 用户说“设计客户端 App 不误伤用户状态的后台资源回收”“让闲置会话可恢复地休眠”或“检查关闭页面后 listener、worker、timer 为什么仍在运行”。
• 用户要求治理 window/scene/page、subscription、task、timer、worker/service、native handle、WebView/isolate、cache、socket、download 或可选 PTY/tmux/worktree 的生命周期。
• The user asks to review fail-closed cleanup, prevent an ABA race, or build a conservative lifecycle controller for a concrete client App.

Do not activate when

• 用户只要求盘点或定位性能根因，尚未建立资源图；先调用 lov-runtime-audit。
• 用户只要求一次性清空缓存、强杀进程、删除目录或用户数据；改用对应安全工具并单独取得精确授权。
• The request concerns server retention, cloud garbage collection, or abstract lifecycle theory without a concrete client App and host lifecycle.

Invocation contract

• invocation: kit_only
• 把 KIT_DIR 指向包含 kit.yaml 的 lov-app-optimizer 根目录。
• 从 $KIT_DIR/references/ 与 $KIT_DIR/scripts/ 加载共享政策和 helper；不要把本模块当成独立发布包。
• 缺少共享依赖时点名相对路径并输出 blocked，不得生成降级版删除命令。

Kit module I/O contract

Inputs

要求至少提供：

• 具体 App、host、runtime/framework、build identity 与生命周期事件；
• 资源类型、稳定 ID、durable owner、作用域和允许的动作级别；
• authoritative activity、attachment/consumer/registration/lease、恢复路径与 fingerprint；
• 授权边界：review、implementation、dry-run 或针对精确候选的已批准动作；
• 项目 teardown、background/foreground、suspend/resume、process-death 或 page freeze/restore 测试入口。

优先接受 app-runtime-evidence/v1 JSON。缺少 owner、identity、activity、dirty/cwd、host lifecycle 或错误语义时仍可输出设计审查，但相关外部资源必须判为 protect。

Outputs

交付一个可独立评审的回收工程包：

1. resource → scope → owner → lease → activity → resume → fingerprint → dependency-order 表；
2. 动作级别、protect / candidate verdict 与机器可读 reasons；
3. host lifecycle、single-flight、bounded concurrency、两阶段分类和原子最终检查协议；
4. 按需提供项目原生补丁与竞态测试，不提供一次性盲删脚本；
5. dry-run inventory、执行授权门、恢复验证和证据缺口；
6. diagnosed、implemented_not_runtime_verified、partially_verified、verified 或 blocked 终态。

共享 helper 只评估计划，不执行回收。没有真实同类资源的 teardown/resume 证据时，不得把测试通过升级成 verified。

Action levels

按风险从低到高选择动作：

1. scope_release：取消 listener、subscription、timer、task 或 observer；作用域结束时优先执行。
2. hibernate：保留 durable state，释放可重建 runtime，并验证按需恢复。
3. cache_evict：只移除有明确重建来源和容量策略的缓存。
4. external_reclaim：处理 process、PTY/tmux、sidecar、download handle 或 worktree；必须两阶段核验与稳定 fingerprint。
5. persistent_delete：删除用户或持久业务数据；默认不属于自动动作，必须使用产品专用流程和独立授权。

Cross-platform safety invariants

• 对 desktop 持久进程，区分 window close、hidden/tray、background worker、sidecar 和 App exit。
• 对 iOS/Android，服从 foreground/background、suspend、Doze、process death 和系统回收；不得以主动 kill 代替正常生命周期验收。
• 对 React Native/Flutter，同时处理 native host 与 JS/Dart runtime、module/plugin、isolate/channel 的所有权。
• 对 Web/PWA，覆盖 visibility、pagehide/pageshow、freeze/resume、BFCache、tab discard 与 Service Worker 更新/终止；不得依赖 unload 清理。
• 对 external resource，证据缺失、畸形、超预算、陈旧、超时、transport error、跨 owner 或身份不稳时 fail closed。
• working、awaiting_input、unknown、attached、consumer active、registration active 与 operation active 一律保护。
• filesystem/worktree 的 dirty、dirty unknown、cwd in use 与 unregistered 一律不自动删除。
• 同名资源不等于同一实例；最终动作核对 creation time、PID、generation、activity stamp、attachment state 或 adapter fingerprint。
• 先停止无条件 rehydration/restart，再添加 sweep；确认失败时保留 durable identity 以便重试。

User Profile contract

每次调用先读取 skill.yaml 声明的 user-profile/v1。按“当前请求与明确授权 → 当前 App/host 状态 → skills.lov-reclamation-engineering.records → shared preferences → shared user/brand → fail-closed 默认值”解析冲突。

只在用户直接声明并希望长期沿用时，通过 $KIT_DIR/scripts/profile_store.py 保存默认 policy、action level、grace period 或 dry-run 模式。写入必须带 --confirm 并回报 profile path。不得持久化资源 ID、PID、session 名、文件路径、凭据、现场状态或一次性授权。完整契约见 $KIT_DIR/references/user-profile.md。

Workflow (MANDATORY)

必须按顺序执行。任何未知状态都保护外部或持久资源；不得为了提高回收数量放宽判定。

Step 0: Resolve the kit, App identity, and authorization

1. 解析 KIT_DIR，读取 $KIT_DIR/references/evidence-contract.md、$KIT_DIR/references/reclamation-policy.md 与 $KIT_DIR/references/platform-adapters.md；需要运行时复测时再读 $KIT_DIR/references/runtime-playbook.md。
2. 验证 $KIT_DIR/scripts/evidence_report.py 与 $KIT_DIR/scripts/profile_store.py 可读。
3. 固定 App/build、host、runtime/framework、device/OS/browser engine 与生命周期事件。
4. 读取 Profile，并记录本次权限仅为 review、implementation、dry-run 或 exact-target action。
5. 共享资源、目标身份或权限缺失时输出 blocked，并保持所有高风险候选为 protect。

Step 1: Model scopes and ownership before idleness

1. 标出 App、window/scene/page、route/view、background worker/service、runtime/isolate/WebView 与 external resource 的作用域。
2. 为每类资源写清 durable owner、runtime lease、activity truth、resume path、fingerprint 和 dependency order。
3. 把 recent timestamp 与 authoritative idle 分开；把 host suspension 与任务完成分开。
4. 无法回答必需项时，把 external resource 降为 inventory_only，把 scoped resource 保留到明确 owner teardown。

Step 2: Normalize one bounded inventory

1. 每类 marker 只列举一次，批量加载 owner、registration 与 host lifecycle state。
2. 填充 evidence contract 的 activity、attachments、registration、operation、cwd、dirty、identity、evidence 与 retention 状态。
3. 对 artifact、filesystem、provider 与 system query 设置 byte/record/time budget；空、畸形、被系统暂停或预算耗尽不等于 idle。
4. 使用 adapter 显式返回 unsupported；不得为缺失平台能力伪造等价状态。

Step 3: Classify by action level and policy

1. 先应用 universal blockers，再判断 scope_release、hibernate、cache_evict 或 external_reclaim 条件。
2. 对 filesystem/worktree 重读 durable references、registration、canonical path、clean status、live cwd 和 identity。
3. 对 unknown directory、foreign session、corrupt row 与用户数据只输出 inventory/protect。
4. 为每个 verdict 返回稳定 reason code；用 $KIT_DIR/scripts/evidence_report.py 生成只读计划。

Step 4: Block ABA for external actions

1. 完成第一次 inventory/classify 后 yield 或等待业务 grace period。
2. 再列举一次 marker，并重新批量读取 owner 与 host state；不沿用第一次可变状态。
3. fingerprint 变化时视为新实例并跳过。
4. 最终动作前执行 O(1) live lease/registration check，并用原 fingerprint 做 atomic conditional action。
5. 条件失败、自然退出、系统回收、timeout 或 transport error 均返回可重试状态，不扩大目标集合。

Step 5: Repair creation, hydration, and teardown seams

1. 先取消作用域结束后仍活跃的 listener/task/timer，再处理可恢复 runtime 与 external resource。
2. 只启动 pending work、连接 canonical live instance、响应显式可见/恢复请求或宿主许可的后台任务。
3. 把逐实体 inventory 改为 shared snapshot、batch read、point lookup 与 single-flight，并限制 start/stop/scan 并发。
4. 让 parent teardown await child resource；未确认时保留 durable identity 与用户数据。
5. 保留目标仓库现有改动，不用一次性脚本掩盖生命周期缺陷。

Step 6: Test host lifecycle, decisions, and races

至少覆盖 working/awaiting/unknown/idle、attached/consumer/registration/operation、空或畸形 artifact、timeout/permission/provider failure、同名重建 ABA、并发 cleanup single-flight，以及宿主对应的 background/suspend/process-death 或 hidden/freeze/BFCache 流程。

filesystem/worktree adapter 另覆盖 registered clean、dirty、dirty unknown、cwd in use、identity changed 与 unregistered directory；external process adapter 另覆盖自然退出、kill failure 和 resume。

Step 7: Enforce the execution gate and assign status

1. 默认停在 review/implementation/dry-run；helper 永不执行回收。
2. 只在用户授权精确目标与动作后，允许项目代码执行二次核验和原子条件动作。
3. 动作前展示 candidate、fingerprint、owner、reason、依赖顺序与恢复/回滚路径。
4. 动作后验证 durable state、runtime absence 与 on-demand resume；失败时保留 identity 并报告重试条件。
5. 仅设计审查写 diagnosed；代码与测试完成但无 live teardown/resume 写 implemented_not_runtime_verified；部分真实流程完成写 partially_verified；同负载和宿主生命周期验收全部满足才写 verified。

Evidence calibration: Yoda

把 Yoda 保留为首个案例校准，不把其资源或阈值泛化：

• platform_family: desktop
• runtime: electron
• case_version: Yoda v0.18.10
• implementation_commit: 290fbc48c713163f20bd6f956e80e15d00dfa357
• code_fact：tmux-reclamation.ts 实现 snapshot、两阶段 revalidation、fingerprint 与 bounded cleanup；tmux-reclamation.test.ts 覆盖 fail-closed、ABA replacement 与 concurrent single-flight。
• code_fact：worktree-cwd-guard.ts、worktree-service.ts 和对应测试保护 live cwd、dirty、unregistered 与 changed-branch worktree；unregistered-worktree-inventory.ts 只读列举未知目录。
• code_fact：task-runtime-reclamation.ts 与测试让 teardown 在 detached-session sweep 前完成，并在失败时保留可重试结果。
• correctness_gate：案例记录 3,115 tests 及 format/lint/typecheck/build 通过；该门只证明实现回归，不是 live reclamation acceptance。
• boundary：没有执行生产批量 kill、blind worktree remove 或递归删除，也没有完成真实 teardown 后的 on-demand resume 验收。因此终态保持 implemented_not_runtime_verified。

Dependencies

• 目标 App 的 host lifecycle、owner model、runtime/framework adapters、teardown APIs 与测试框架。
• Python 3.9+，用于 $KIT_DIR 中的共享 Profile 和只读证据报告。
• Electron、Tauri、native、iOS、Android、React Native、Flutter 与 Web/PWA adapter 按目标组合加载；Git/tmux/SSH/SQLite 仅是可选 Yoda-style external adapters。

Shared references

• $KIT_DIR/references/reclamation-policy.md — policy、universal blocker、两阶段协议与测试矩阵。
• $KIT_DIR/references/evidence-contract.md — app-runtime-evidence/v1 资源字段与 verdict 契约。
• $KIT_DIR/references/platform-adapters.md — host、runtime/framework 与 optional resource adapter 组合。
• $KIT_DIR/references/runtime-playbook.md — 具体 App 身份、宿主生命周期与运行时复测。
• $KIT_DIR/references/user-profile.md — Profile 读取与持久化规则。