cron-up 26.10.32 → 26.10.34

package/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# 贡献指南
+
+## 开发环境
+
+- macOS，便于验证 launchd、`script(1)`、zsh 和进程行为
+- Node.js 22 或更高版本
+- 无第三方运行时依赖，测试直接使用 `node:test`
+
+```bash
+git clone git@github.com:adaex/cron-up.git
+cd cron-up
+node --test
+```
+
+CI 在 macOS 上分别使用 Node 22、24 运行全部测试。需要本机联调时可执行 `npm link`，它会把开发版链接成全局 `cron-up` 命令；只做测试时不需要这一步
+
+## 代码结构
+
+- `bin/cron-up.mjs`：CLI 入口与顶层异常处理
+- `src/cli.mjs`、`src/args.mjs`：参数解析、帮助和命令分发
+- `src/internals.mjs`：可替换的 `deps` 容器及系统级默认实现
+- `src/` 其他模块：任务发现、cron、巡检、会话、登记、展示、日志与 launchd 服务
+- `test/`、`test-support/`：行为测试和可注入依赖的夹具
+
+业务模块向 `deps` 注册外部依赖，测试通过替换这些依赖隔离文件、进程、时钟和 launchd。修改行为时同步修改测试，不要只让旧断言适配新输出
+
+## 文档同步要求
+
+用户可观察行为变化时，至少检查以下位置，避免命令、README 和实现各自描述一套口径：
+
+| 变化 | 需要同步的位置 |
+| --- | --- |
+| 产品范围、安装、日常使用、限制、卸载或数据保留 | `README.md` |
+| 命令、选项、升级步骤或帮助文案 | `src/cli.mjs`，必要时包括 `src/overview.mjs` |
+| npm 包定位 | `package.json` 的 `description` |
+| 内部机制、生命周期常量、兼容性证据或投递算法 | `docs/internals.md` |
+| 跨版本行为与旧安装收尾 | `docs/migration.md` |
+| 版本号、工作流或发布验收 | `docs/release.md` |
+
+维护文档中的常量表只写语义和派生关系，具体数值链接 `src/constants.mjs`，避免同时维护两份当前值；README 中面向用户的数值仍需随行为变化核对
+
+文档中的兼容版本必须有实际核对依据。没有把某个版本验证过，就写“未验证”，不要用“以上均支持”替代证据
+
+示例输出应与真实命令格式核对；时间、pid 等变化值可以标注为示例，不要伪造验证结果
+
+## 提交前检查
+
+```bash
+node --test
+node bin/cron-up.mjs --help
+npm pack --dry-run
+```
+
+同时检查：
+
+- README 与分拆文档的相对链接有效
+- 新命令或字段有对应测试
+- 文档没有引入“保证一个不少”“绝不可能失败”等超过实现边界的承诺
+- 涉及任务文件写入、权限、联网或卸载时，明确说明影响范围和不会处理的内容
+
+发布是独立流程，见[发布流程](docs/release.md)

package/README.md

@@ -1,191 +1,307 @@
 # cron-up
 
-为命令行 AI agent 的 cron 定时任务**按任务提前启动并保持一个可用的交互会话**：任务到点时，对应目录里早就有一个开着的 claude 会话，任务一个不少地投进各自的会话执行。平台要求 macOS（依赖 launchd、`script(1)`、zsh）。
+为 **Claude Code 的 durable 定时任务**在触发前按需预热交互会话，减少因原会话关闭、电脑上没有在线会话而造成的漏跑。每个需要 cron-up 预热且能唯一识别的任务使用独立后台会话，任务仍由 Claude Code 自己投递和执行
+
+目前仅支持 macOS，依赖 launchd、`script(1)` 和 zsh；不是通用命令行 AI agent 的调度器。会话按任务需要创建，满足回收条件后退出，短周期任务也可能持续复用现有会话
 
 > [!WARNING]
-> cron-up 建立在 **Claude Code 未公开文档的内部机制**之上（`.claude/scheduled_tasks.json` 格式、会话登记 `~/.claude/sessions/`、逐任务调度谓词与目录级调度锁、任务投递抖动、三代进程结构（已核对本机 **2.1.302**））。这些行为可能随版本变化；看到「会话登记格式疑似变更」类告警，或升级 Claude Code 后任务到点没有会话在场，先核对新版本再继续使用。开头的 WARNING 与各章节的逆向注解，就是给这种时刻准备的。
+> cron-up 依赖 Claude Code 未公开且无稳定性承诺的内部实现。当前核心行为以 **2.1.302** 的本机核对结果为依据，其他版本不代表已经验证；不同机制的核对版本见[内部机制与兼容性](docs/internals.md)。升级 Claude Code 后，先运行 `cron-up` 查看告警，再确认任务能正常预热和投递
 
 ## 它解决什么问题
 
-在 Claude Code 里用 CronCreate（durable: true）创建的定时任务，记录在工作目录的 `.claude/scheduled_tasks.json` 里。但这些任务**只有在该目录有一个正在运行的交互 claude 会话时才会到点执行**：会话一旦被关掉，周期任务在该会话直接失效；任务到点时没有会话，一次性任务会在下次打开会话时补执行（会话被休眠期间错过的周期任务不会补）。cron-up 是一个由 launchd 每 5 分钟运行一次的巡检进程，逻辑只有一条：**窗口内每个创建者会话已不在的任务，都有一个只属于它的后台会话在该目录等着**。
+在 Claude Code 中用 CronCreate 创建 `durable: true` 的任务后，任务记录在当前工作目录的 `.claude/scheduled_tasks.json` 中。任务到点时，该目录需要有正在运行的交互 `claude` 会话：
+
+- 原创建者会话还开着时，任务优先投递给它，cron-up 不为其预热或改写归属
+- 原创建者会话已经关闭时，cron-up 在任务进入预热窗口后尝试启动专属后台会话，并改写该任务的归属字段
+- 电脑休眠期间错过的周期任务不会补执行；一次性任务的补执行见[任务时间与执行](#任务时间与执行)
+
+职责边界如下：
+
+| 环节 | 负责方 |
+| --- | --- |
+| 创建和保存任务 | Claude Code 的 CronCreate 工具 |
+| 判断触发时刻、投递 prompt、执行任务 | Claude Code 交互会话 |
+| 提前准备会话、调整任务归属、回收会话 | cron-up |
+| 定时驱动巡检 | macOS launchd |
+
+cron-up 不负责创作任务内容，也不能保证每个任务都执行成功。授权、模型、工具、任务脚本和上游调度仍可能失败
+
+## 安装前须知
+
+### 环境与兼容性
+
+- **macOS**：使用 launchd、`script(1)` 和 zsh，暂不支持其他系统
+- **Node.js 22 或更高版本**：cron-up 没有第三方运行时依赖
+- **Claude Code**：核心行为已在 2.1.302 核对；更低或更高版本均应按未验证版本对待，不要仅凭版本号推断兼容
+- **可用的 `claude` 命令**：已完成登录和所需配置，并且能从交互登录 zsh 中启动；可先用 `zsh -lic 'command -v claude'` 检查
+- **目录信任与工具授权**：先在该工作目录手动启动一次 Claude Code，完成信任确认及无法在无人值守时回答的授权，否则预热可能停在提问界面，随后被判为卡死并进入失败流程
 
-## 任务级预热：一任务一会话
+fnm、volta、Homebrew、官网 pkg 等 Node 安装方式均可用于提供 `node`。nvm 等把 Node 放在版本目录中的安装方式，在切换或删除版本后需要重新运行 `cron-up install`；这里说的是 Node 的启动链，不代表所有 Claude Code 安装和 shell 配置都经过验证
 
-Claude Code 的任务归属是**任务级**的：任务文件里每条任务各自带 `createdBySessionId`，会话调度器逐任务判定投不投递（2.1.302 二进制核对到的谓词，按优先级）：
+### 安全与自动修改
 
-1. 任务没有归属会话 → 只有持目录调度锁的会话投；
-2. 任务归属的就是本会话 → **无条件投，不需要锁**；
-3. 本进程是任务记录的创建者进程（resume 形态）→ 投；
-4. 其余情况 → 必须持锁、任务属于本项目、且创建者进程已死，才接管。
+> [!CAUTION]
+> `roots` 是**任务扫描与信任范围，不是沙箱**。后台会话通过 `claude --permission-mode bypassPermissions` 跳过工具权限确认，并以当前 macOS 用户身份运行；任务可以访问 roots 之外的位置，也可能通过模型、MCP 或任务工具联网
 
-cron-up 利用这套规则：为每个「归属会话已死、6 分钟内需要执行」（一次性任务按最早可能投递时刻计，最多再提前 90 秒）的任务单独拉起一个后台会话，并把该任务的归属字段盖成这个新会话。于是同目录多个任务即使同一时刻触发，也各自投进各自的会话、互不插队；任一个预热中途死了，它的任务还会由另一个持锁活会话按规则 4 兜底接管。你本人的交互会话优先级最高：**只要任务的创建者会话还开着，cron-up 完全不碰它**。
+只扫描你信任其**整个工作区内容**的目录，而不只是检查任务文件。预热会在工作区启动完整的 Claude Code，任务、`CLAUDE.md`、`.claude` 中的项目指令与配置，以及任务可能调用的脚本，都可能影响无人值守会话
 
-| 环节 | 由谁负责 |
-|---|---|
-| 任务登记 | Claude Code 原生命令 CronCreate，写入工作目录下 `.claude` |
-| 定时执行 | Claude Code 交互会话自身（包括补执行和抖动） |
-| 保证每个窗口内死主任务有专属会话在场 | cron-up（按任务拉起、盖印、执行完回收） |
-| 安装与升级 | npm：`~/Library/LaunchAgents/local.cron-up.plist` 与 `~/.local/share/cron-up/cron-up-service` |
+目录归你所有并不等于内容可信：clone 到 roots 下的外部仓库、团队共享仓库或他人可写目录，都可能带来由他人编写的任务和项目指令，不能只审核 `.claude/scheduled_tasks.json`
 
-各部分互不影响：卸载 cron-up 后任务依然有效，只是没人保证会话在场。
+安装后，每轮巡检会按需自动维护扫描到的任务文件：
 
-## 安装
+1. 给所有显式周期任务补 `permanent: true`，使其绕开 Claude Code 的 7 天周期任务回收
+2. 对已经进入预热窗口、原归属会话不在场的任务，改写 `createdBySessionId`、`createdByPid` 和 `createdByProcStart`
+
+这些行为没有任务级开关。即使原创建者会话仍在线，自动续期仍会进行；手动删除 `permanent` 后，只要任务仍在扫描范围内，后续巡检还会补回。不希望某个工作区被修改时，应把它移出 roots；已经写入的字段不会自动恢复，详见[卸载与数据保留](#卸载与数据保留)
+
+## 快速开始
+
+### 1. 安装并选择扫描范围
 
 ```bash
 npm i -g cron-up
 cron-up install --roots ~/code,~/work
 ```
 
-第二步会写入配置与 LaunchAgent 并立即跑首轮巡检；参数都可省略，不带 `--roots` 时沿用现有配置，首次安装默认扫描 `~/space`、`~/workspace`、`~/tasks`。
+`--roots` 接受逗号分隔的目录列表，每次提供的是完整列表，不是在原列表上追加。第二步会写入配置、启动脚本和 LaunchAgent，并立即尝试首轮巡检
+
+不带 `--roots` 时会沿用可读取且 roots 类型有效的现有配置；首次安装使用默认范围 `~/space`、`~/workspace`、`~/tasks`，不存在的目录会跳过。使用默认范围前，同样要确认其中现在及未来出现的任务和项目指令都可信
+
+现有配置无法解读时也会回退默认范围；其写入风险和修复方法见[配置无法解读时](#配置无法解读时)
+
+扫描范围按下面的路径深度计算：
+
+- root 本身，以及 root 下的第 1、2、3 层目录都会检查任务文件
+- 例如 `<root>/<repo>/<subdir>/<nested>` 是 root 下第 3 层，可以发现；再深一层不会发现
+- 不深入符号链接形式的子目录，并跳过依赖目录和常见系统目录，完整名单见 `src/constants.mjs` 中的 `PRUNE_DIRS`
+
+工作区指**包含 `.claude/scheduled_tasks.json` 的那个精确目录**，不自动等同于 Git 仓库根目录。若任务是在仓库子目录的 Claude Code 会话里创建，它属于该子目录
 
-`--roots` 填写存放 agent 工作目录的父目录（逗号分隔）。不填则默认扫描这三个容器（不存在的跳过），两层以内的目录都能发现任务文件。不扫整个家目录的原因见安全说明。
+### 2. 创建第一个任务
 
-`launchd` 的环境变量极少（PATH 只有 `/usr/bin:/bin:/usr/sbin:/sbin`），因此安装时会解析 node 与 cron-up 所在的 bin 目录（fnm/volta/Homebrew/官网安装都支持），把它写进一个自有启动脚本（`cron-up-service`），launchd 每轮从该脚本解析。后台列表里显示 **cron-up-service** 而不是 Node.js 名字。
+进入 roots 覆盖的工作目录并启动 Claude Code，然后在 Claude Code 中提出请求，例如：
 
-### 平台要求
+> 在当前工作目录用 CronCreate 创建一个 `durable: true` 的一次性任务，约 5 分钟后在会话里回复“cron-up 验证成功”；完成后执行 `/exit` 退出会话
 
-- **macOS**（`script(1)`、launchd、zsh 登录 shell）。暂不支持其他系统。
-- **Claude Code 2.1 以上**（在 2.1.302 实测；7 天判定与归属字段从 2.1.300 起核对，逐任务谓词与调度锁核对自 2.1.302）。fnm、bun、volta、Homebrew、官网 pkg 与其他版本管理器均支持——安装时把 node bin 目录与当前安装形态解析进启动脚本。
-- Node.js 22 以上（零运行时依赖，巡检本身只调系统自带工具）。
-- 无人值守时的工具权限：后台会话没有人在场点授权确认。后台会话以 bypass permissions 模式启动，命令在无人授权下照常执行；目录没走过信任确认、或工具需要二次授权，会话会一直停在提问界面，预热失败后连续失败进入冷却。只把 roots 指向你本人信任的目录。
-- 建议在任务描述末尾固定加一句任务结束会话的指令（见下）。
+CronCreate 是 Claude Code 内部工具，不是在终端里直接执行的 shell 命令。推荐让无人值守任务在完成并保存结果后执行 `/exit`，但是否执行该指令仍取决于任务本身
+
+### 3. 验证发现和预热
+
+依次用 `cron-up list` 确认任务已被发现并查看时间，用 `cron-up run` 立即巡检一次，再用 `cron-up` 查看服务、会话和告警。需要查看后台界面时，运行 `cron-up logs <目录名或任务id>`；完整命令和日志选项见[日常使用](#日常使用)
+
+定时巡检每 5 分钟一轮。周期任务在设定时间前 6 分钟进入预热窗口；所有一次性任务都统一再增加 90 秒前瞻，最早可在设定时间前 7.5 分钟进入窗口。实际启动由窗口内的巡检触发，具体时间取决于巡检相位，并不是固定提前 6 或 7.5 分钟
+
+其中，落在 `:00` 或 `:30` 的一次性任务按当前上游规则还可能提前至多 90 秒投递
+
+任务还没到预热窗口时，`cron-up run` 不会为它提前常驻一个会话；若已经有一轮巡检在运行，后到的一轮会跳过
 
 ## 日常使用
 
 ```bash
-cron-up                        # 总览：服务、配置、最近任务、每个预热会话与告警
-cron-up list                   # 逐任务列出设定/预计实际触发时间与预热状态
-cron-up run                    # 立即手动巡检一次（与定时巡检互斥，同时运行时后到者自动退出）
-cron-up logs                   # 查看巡检日志（最近几百行巡检心跳与事件）
-cron-up logs team-space        # 查看匹配的后台会话界面记录（多个任务命中时列出候选）
+cron-up                        # 总览：服务、配置、最近任务、预热会话与告警
+cron-up list                   # 逐任务列出时间、类型、摘要与预热状态
+cron-up run                    # 立即手动巡检一次
+cron-up logs                   # 查看最近 100 行巡检日志
+cron-up logs team-space        # 按文件名片段选择后台会话日志
 cron-up logs team-space--00000002 -f
-cron-up uninstall              # 停止全部预热会话并卸载（配置日志保留；--purge 连产物一起删）
+cron-up --help                 # 查看命令帮助
 ```
 
-巡检固定每 5 分钟一轮、提前 6 分钟为任务备好会话；这些不是可配项。任何任务最迟在执行前一轮巡检被发现；拉起会话后轮内每 3 秒重扫一次会话登记（先扫后睡、至多等 24 秒），健康会话约 10 秒即可完成登记，归属在**同一轮**盖印完成，不再跨一轮。24 秒只是盖印加速的等待上限，不是判死时限：等不到的会话原样留到下轮，仍按跨轮 3 分钟未登记判死，失败计数不因等待而增加。一次性任务在 :00/:30 落点最多提前 90 秒投递，其窗口前沿按最早投递时刻再前推 90 秒，保证任意巡检相位都有一轮在投递前把它发现。
-
-### 自动维护（每轮无条件进行，没有开关）
+会话日志按文件名片段匹配，可以输入目录名、任务 id 或两者组合；命中多个日志时会列出候选，请补充更长的片段
 
-巡检每轮会顺手维护扫描到的任务文件，全部合并在一次带乐观锁的原子写里：
+### 看懂总览和任务列表
 
-- **自动续期**：给显式周期任务补 `permanent: true`，绕开 Claude Code 的 7 天周期任务回收。
-- **自动改小任务 id**：把周期任务的随机大 id 改成分文件不冲突的小序号，投递抖动压到 1 分钟以内，观感近乎准点。只改显式周期任务、幂等；一次性任务不碰。
-- **自动任务级盖印**：把窗口内死主任务的三个归属字段盖成各自预热会话的身份。只改 `createdBySessionId/createdByPid/createdByProcStart`，不碰 `prompt`、`cron`、`id`（除上面的改小）与 `createdInProject`。
+总览优先看三处：
 
-三轮维护与 Claude Code 自己对文件的写入（更新 `lastFiredAt`、执行后删一次性任务）用 mtime 乐观锁互斥：撞上就整轮跳过写入，下轮再来，绝不覆盖它的更新。
+- **服务与上次巡检**：launchd 已加载不等于巡检仍在成功运行，心跳可以帮助识别启动链失效
+- **最近**：按预计投递时间排序，而不是只按 cron 的设定时间排序
+- **需要留意**：配置、启动链、会话登记、预热失败和失去扫描范围的会话等告警
 
-### 让一次性任务结束后自动退出会话
+下面是 `cron-up list` 的输出格式示例，日期、时间和 pid 以本机实际输出为准：
 
-窗口预热会话在任务执行完、界面静默一段时间后自动回收；但推荐在任务描述里要求执行完自己退出，整个过程更干脆：
+```text
+共 1 个工作区、2 个定时任务
 
-> 按本仓工作流存好结果后，执行 `/exit` 退出会话。
+/Users/you/code/my-project
+  10-24 19:52          一次性      52 19 24 10 *     验证 cron-up [预热中 12345]
+  10-25 09:00 → 09:30  周期·永久   0 9 * * *         每日汇总
+```
 
-这样任务结束当刻会话就退出；cron-up 巡检发现任务已离开窗口且会话不在，什么都不用做。即使忘加这句，无人会话也会在执行完并静默后被自动回收，下次窗口重新拉起。
+常见状态和标签：
 
-## 窗口轮转与生命周期
+| 显示 | 含义 |
+| --- | --- |
+| `设定时间 → 预计时间` | 前者是 cron 设定时间，后者是按已知上游规则估算的投递时间；没有偏差时只显示一个时间 |
+| `启动中 <pid>` | 会话进程已启动，尚未在 Claude Code 会话登记中确认 |
+| `预热中 <pid>` | 已确认后台会话登记且预热进程存活；归属是否已写回可结合巡检日志判断 |
+| `待预热` | 已进入预热窗口，但当前还没有承接会话；结合总览告警判断原因 |
+| `冷却中` / `失败N次` | 预热启动失败，正在退避或已经累计失败 |
+| `终端接管` | 用户通过 `--resume` 接管了该会话，cron-up 不再另拉或结束它 |
+| 标签为空 | 可能还没到预热窗口，也可能原创建者会话仍在线，需要结合时间列和总览判断 |
+| `已错过` | 一次性任务的设定时间已经过去；有效 `createdAt` 是 cron-up 判断错过待补的必要字段 |
+| `一年内无` | cron 可解析，但 366 天展示窗口内没有未来落点；二月三十日这类日历上永远不出现的表达式也归入此状态 |
+| `cron 无效` | 表达式解析失败，或字段值域、区间导致合法值集合为空，巡检会跳过该任务 |
 
-预热会话是缓存不是宠物：每个会话只活在「落点前 6 分钟（一次性网格任务至多 7.5 分钟）→ 本任务执行完并静默 3 分钟 → 回收」这一段，任务之间上下文互不累积，内存也只在窗口内占用（每个会话数百 MB，窗口外为零）。回收还要求距该任务下次需要至少 7 分钟——回收后下轮巡检（≤5 分钟）即重新拉起并在当轮完成认亲盖印，余量罩住一次性任务的 90 秒提前投递与唤醒抖动，任务不可能在空档到点。更近的触发直接复用现有会话。
+## 任务时间与执行
 
-其它生命周期规则：
+文档和命令输出中的时间均为 macOS 本机时间，cron-up 也用本地时区计算预热和展示。三个时间概念不要混用：
 
-- **失败冷却**：预热连续 3 次启动失败（通常是缺目录信任、shell 环境损坏），暂停重试 30 分钟，而不是每 5 分钟无限重拉；失败计数按任务各自累积，互不连坐。总览页冷却中的任务合并成一条带排查指引的告警。
-- **卡死退休**：会话进程活了 3 分钟仍没在会话登记里出现（停在信任确认或工具授权提问上），终止并按失败处理。
-- **终端接管**：你随时可以 `claude --resume <预热会话id>` 把一个预热拉回终端。cron-up 发现原后台进程没了、但同一 sessionId 还活着，就停止管理它：不再另拉、绝不碰你的终端进程；该会话关闭后，任务恢复自动预热。
-- **孤儿认领**：state 记录丢失时，巡检能按会话日志路径从进程表里把仍在运行的预热重新认回来。
-- **升级迁移**：从目录级单预热的旧版本升级时，首轮巡检会结束旧版预热，之后按任务重新拉起。
+1. **设定时间**：cron 表达式对应的分钟
+2. **预计投递时间**：计入已知上游抖动规则后的估算，可能早于或晚于设定时间
+3. **实际执行时间**：Claude Code 会话实际收到并开始处理任务的时间，还受秒级轮询、会话状态和上游实现影响
 
-## 恢复或接管后台会话
+周期任务通常在设定时间之后投递，每日任务使用原生随机 id 时经常接近固定的 30 分钟上限；一次性任务落在 `:00` 或 `:30` 时可能提前至多 90 秒。约 5 分钟周期且匹配特定表达式的上游任务还可能走提前 15 秒的分支，当前预测没有复刻该分支，完整规则和例外见[投递时间算法](docs/internals.md#投递时间算法)
 
-后台会话与普通会话一样保存对话记录，可以在任意终端恢复：
+因此，“设定时间到了但还没执行”不一定是故障，应先看 `cron-up list` 的预计时间和总览告警
 
-```bash
-claude --resume <sessionId>      # 或 claude -r 在列表中选择
-```
+电脑休眠期间，launchd 醒来后只补跑一轮巡检：
 
-对话记录在 `~/.claude/projects/<目录编码>/<会话ID>.jsonl`，即使后台进程被结束也能恢复。恢复后该会话如上面「终端接管」所述脱离巡检管理。
+- 错过的周期任务不会补执行
+- 错过的一次性任务通常会在后台会话启动时由 Claude Code 补执行；手写任务缺少有效 `createdAt` 时，cron-up 无法据此识别错过待补
 
-## 投递抖动：设定时间与实际触发时间
+## 会话生命周期与恢复
 
-Claude Code 任务的实际投递不在 cron 落点，而是落点之后加一个按任务 id 确定的偏移（会话内部每秒轮询，实际到点有秒级尾差）。周期任务的延迟 = `min(哈希(id) × 0.5 × 周期, 30 分钟)`，每日任务在不改 id 时几乎必然固定晚到约 30 分钟；一次性任务在 :00/:30 整点最多提前 90 秒。`cron-up list` 的状态列和总览的「最近」显示的是计入抖动后的预计实际时间；自动改小 id 把每日任务的这段延迟压到 1 分钟内。
+预热会话按任务需要创建，周期任务不依靠跨周期累积上下文。复用与回收只在巡检轮次中按启发式条件判断，不等于对任务完成状态做强保证：
 
-巡检判定「任务现在是否需要会话」时，把周期任务落点之后、抖动投递点之前的这段尾窗也算作需要在场，会话不会在任务真正投递前被回收。这些参数逆向自 Claude Code 内部实现，没有稳定性承诺（远程配置键 `tengu_kairos_cron_config` 还能覆盖）；预测与实际系统性偏离时说明上游算法已变。
+- 周期任务的预热窗口从设定时间前 6 分钟开始，一次性任务最早从设定时间前 7.5 分钟开始；具体启动时间取决于窗口内的巡检相位
+- 新会话启动后，当轮每 3 秒重扫一次登记，最多等待 24 秒；这只是加速归属写回，不是启动判死时限
+- 进程超过 3 分钟仍未完成登记时，由后续巡检判定卡死并终止；因为巡检每 5 分钟一轮，实际处置时间不是精确的启动后第 3 分钟
+- 没有成功登记的启动连续失败 3 次后，该任务暂停重试 30 分钟；按任务分别计数，成功登记会清零，已死亡条目的失败记录跨预热窗口保留并在 48 小时后老化
+- 回收除了要求界面静默超过 3 分钟，还要求距该任务下次需要超过 7 分钟；同样只在巡检时判断
+- 距下次需要不超过 7 分钟时会继续复用现有会话，例如每 5 分钟执行的任务通常无法满足回收余量，其会话可能长期在线，不能按“窗口外没有会话”估算内存
+- 同分钟大量任务会同时拉起多个 Claude Code 会话，每个会话可能占用数百 MB，实际以本机为准；正常回收后不再保留这些预热会话的内存开销
 
-## 安全说明
+后台会话与普通会话一样保存对话记录，可以在终端恢复：
 
-- **任务文件是执行输入，root 等同写权限**：任何能在 roots 下写 `.claude/scheduled_tasks.json` 的主体，都登记了一条到点会以你的身份在后台会话里执行的指令。cron-up 读任务文件时严格校验形状，但信任的是文件内容本身——不要把他人可写或共享的目录放进 roots。自动续期还会把扫描到的周期任务补成永久任务，默认 roots 必须是你完全掌控的容器。
-- **预热会话拥有你在 Claude Code 中的全部权限**：后台会话以 bypass permissions 模式无人值守运行。roots 的边界就是无人授权写权限的边界。
-- **归属盖印会改写任务文件**：cron-up 会改窗口内死主任务的 `createdBySessionId/Pid/ProcStart` 字段。写入采用原子替换（临时文件 0600、保留原文件权限），并与 Claude Code 的写入做 mtime 乐观锁互斥。
-- **会话日志可能包含任务输出**：后台会话的界面记录写到 `~/Library/Logs/cron-up/sessions/<工作区>--<任务id>.log`，权限 600、目录 700，每个任务独立文件、轮转保留一代；巡检日志在 `~/Library/Logs/cron-up/`。
-- **扫描不深入符号链接的子目录**，默认还排除系统目录与依赖目录。
-- **巡检、预热与你的 claude 会话之间不发起网络请求**，也不依赖 npm 注册表；网络活动全部来自被启动的会话本身。唯一的网络发生在安装/升级时访问 npm registry 拉包。
+```bash
+claude --resume <sessionId>      # 或 claude -r 在列表中选择
+```
 
-## 已知限制
+对话记录位于 `~/.claude/projects/<目录编码>/<会话ID>.jsonl`。如果恢复后原后台进程已经退出、同一 sessionId 仍在终端运行，cron-up 会停止管理它，不结束终端进程；该终端会话关闭后，后续巡检可重新预热
 
-- 仅支持 macOS。电脑休眠期间错过的周期任务不会补执行（launchd 醒来只补跑一轮巡检）；错过的**一次性**任务会在后台会话启动时补执行。
-- 每个窗口内的死主任务对应一个后台会话：同一分钟内有大量任务同时到期时，会同时存在相应数量的会话（每个数百 MB 内存）。时间错开的日常任务只在各自的 6 分钟窗口内占用（一次性任务至多 7.5 分钟）。
-- 手工创建的任务若缺少 `createdAt`，错过补执行判定不生效。`cron-up list` 对缺字段的手写任务仍显示「已错过/设定时间」，但预热与补执行依赖 Claude Code 与 cron-up 的字段纪律。
-- 工作区从巡检视野里消失（`.claude/scheduled_tasks.json` 被整个删除或移出 roots）后，仍在运行的预热不会被回收，总览会列出这类会话，不需要时手动结束。
-- 预热依据的逐任务谓词、调度锁与三代进程结构是未公开内部实现：新版若调整归属/锁语义，任务级隔离的前提需要重新核对。cron-up 保留了会话登记格式的烟雾告警，格式漂移时在总览页明示。
+## 自动维护的写入边界
 
-## 故障排查
+同一轮中，同一批待处理的自动续期和归属改写会合并为带 mtime 乐观检测的原子写入；新会话在后续完成登记、需要补写归属时，可能另做一次原子写入。若检测到 Claude Code 同时更新了 `lastFiredAt`、删除了一次性任务或进行了其他修改，本轮对应写入会暂缓并在后续重试
 
-| 现象 | 排查方法 |
-|---|---|
-| 总览提示「冷却中」 | 运行 `cron-up logs <目录>--<任务id>` 查看启动界面：停在信任确认就先在该目录手动走完信任；shell 初始化缺命令（command not found）按「启动脚本 PATH」段修 |
-| 任务到点没有执行 | `cron-up list` 看任务与预热状态；预热在则看它的会话日志；总览的「需要留意」按任务给出原因 |
-| 总览提示「启动脚本已失效 / PATH 找不到 node」 | 重跑 `cron-up install`（见下） |
-| 总览提示「巡检已沉默」 | launchd 显示加载但心跳超时：先 `cron-up logs`，再重跑 install |
-| `last exit code=2` | 配置损坏或字段类型不对：修好 `~/.local/share/cron-up/config.json`（只有 roots 一个字段）或重跑 install |
-| 手动 `cron-up run` 正常、定时执行不正常 | 手动测试继承终端 PATH，定时由启动脚本驱动；换过 Node 安装方式后重跑 install |
-| 任务表显示「已错过」 | 一次性任务落点已过：后台会话一启动就会补执行；周期任务没有补执行 |
-| 日志里出现「卡死」 | 会话 3 分钟没完成登记：信任确认/工具授权提问没人应答，手动进目录走一遍授权 |
-| 同目录多个任务互相干扰 | 升级后首轮会结束旧版目录级预热；如仍异常，确认所有预热会话都由新版本拉起（日志名含 `--任务id`） |
+这只是降低并发覆盖概率，不是与 Claude Code 共用的互斥锁。最后一次检查与原子替换之间仍存在极小竞态，详见[内部机制](docs/internals.md#任务文件维护与并发)
 
-## 维护
+卸载 cron-up 不会撤销这些已经写入任务文件的修改
 
-- **修改扫描范围**：`cron-up install --roots "$HOME/code,$HOME/work"`。重跑 install 会重写配置（旧版本留下的废弃字段一并纯化）、启动脚本与 LaunchAgent。
-- **升级**：`npm i -g cron-up@latest` 后重跑一次 `cron-up install`。下一轮巡检自然跑新版；Node 版本与包文件在 install 后自动跟随。fnm 切换默认版本同理。
-- **版本号**：总览首行、心跳文件都带版本；发版收尾跑一次无参数 `cron-up` 确认首行版本、服务已加载且退出码 0、「需要留意」为空。
+## 配置与产物
 
-### 配置文件
-
-配置只有扫描范围一个字段：`~/.local/share/cron-up/config.json`
+配置文件为 `~/.local/share/cron-up/config.json`，只有扫描范围一个字段：
 
 ```json
 { "roots": ["/Users/you/code", "/Users/you/work"] }
 ```
 
-间隔（300 秒）、提前量（360 秒，一次性任务另加至多 90 秒）、扫描深度（3）、轮内等待认亲上限（24 秒）都是固定常量；直接编辑文件改 roots 也可以，最多 5 分钟后的下轮巡检生效。字段损坏时巡检响亮失败（退出码 2），不静默回退。
+可以直接编辑 roots，通常最多等下一轮巡检生效；也可以运行：
+
+```bash
+cron-up install --roots "$HOME/code,$HOME/work"
+```
+
+重跑 install 会重写配置、启动脚本与 LaunchAgent，并移除旧版本遗留的废弃配置字段
+
+巡检间隔、提前量、扫描深度、失败退避等均为固定行为，完整常量和生命周期规则见[内部机制](docs/internals.md#巡检与会话生命周期)
 
 | 产物 | 位置 |
-|---|---|
-| 命令行与代码 | npm 全局目录（fnm 为 `~/.local/share/fnm/aliases/default/...`） |
+| --- | --- |
+| 命令行与代码 | npm 全局目录，具体位置取决于 Node 与 npm 安装方式 |
 | 配置文件 | `~/.local/share/cron-up/config.json` |
-| 运行状态 | 同目录 `state.json`（按工作区与任务 id 两级记录预热） |
-| 配置心跳 | 同目录 `heartbeat`（每轮写一次） |
+| 运行状态 | `~/.local/share/cron-up/state.json`，按工作区与任务 id 记录预热 |
+| 巡检心跳 | `~/.local/share/cron-up/heartbeat`，每轮成功完成后写入 |
 | LaunchAgent | `~/Library/LaunchAgents/local.cron-up.plist` |
 | 启动脚本 | `~/.local/share/cron-up/cron-up-service` |
 | 巡检日志 | `~/Library/Logs/cron-up/launchd.{out,err}.log` |
-| 各任务会话日志 | `~/Library/Logs/cron-up/sessions/<工作区>--<任务id>.log`（轮转保留一代 `.1`） |
+| 各任务会话日志 | `~/Library/Logs/cron-up/sessions/<工作区折名>--<任务id>.log`，轮转保留一代 `.1` |
+| Claude Code 对话记录 | `~/.claude/projects/<目录编码>/<会话ID>.jsonl`，由 Claude Code 管理 |
+
+会话日志可能包含任务输出，文件权限为 0600、目录权限为 0700。日志文件名中的工作区折名由完整工作区路径生成，日常使用建议通过 `cron-up logs` 查找，不要手工猜文件名
+
+cron-up 自身的巡检和会话管理不主动访问 npm registry 或其他网络服务；安装和升级时由 npm 访问 registry。被启动的 Claude Code 会话仍可能联网，cron-up 不对其网络活动作限制
 
-## 开发与测试
+### 配置无法解读时
+
+不带 roots 重跑 install 时，只有可读取且 roots 类型有效的现有配置才会被沿用；配置无法解读时会提示并回退到默认范围 `~/space`、`~/workspace`、`~/tasks`，随后立即尝试首轮巡检，可能续期或改写其中的任务文件
+
+修复时可以直接改正上述配置文件；需要通过 install 重建且不想使用默认范围时，必须显式传入完整的 `--roots`
+
+## 升级与启动链维护
+
+升级 cron-up：
 
 ```bash
-git clone git@github.com:adaex/cron-up.git && cd cron-up
-node --test                 # 全部测试（需要 Node 22+；零依赖）
-npm link                    # 本机把开发版链接成全局 cron-up
+npm i -g cron-up@latest --prefer-online
+cron-up install
+cron-up
 ```
 
-`bin/cron-up.mjs` 是 CLI 入口，`src/` 是各业务模块，通过 `src/internals.mjs` 的 deps 容器注入外部依赖（便于测试打桩）。测试与源码同量，改行为请同步改测试。
+最后一步确认首行版本、launchd 状态、上次退出码和“需要留意”。刚发布新版本时 registry 与本机缓存可能有延迟，维护者发版后的逐机升级使用显式版本号，见[发布后的逐机升级与验收](docs/release.md#每次发版后的逐机升级与验收)
+
+launchd 的初始 PATH 很小，因此 install 会把 `node` 与 `cron-up` 所在 bin 目录写入 `~/.local/share/cron-up/cron-up-service`。预热中的 `claude` 则由 `/bin/zsh -lic` 启动，依赖登录交互 shell 的配置，而不是仅靠前述两个目录
+
+出现以下情况后应重跑 `cron-up install`：
+
+- 切换、删除或更换 Node 安装方式
+- 修改 roots 或需要重建 LaunchAgent
+- 总览提示启动脚本失效、PATH 找不到 node／cron-up，或巡检心跳沉默
+
+若 `zsh -lic 'command -v claude'` 失败，先修复交互 zsh 中的 `claude` 命令及其环境，再重跑 install。手动 `cron-up run` 成功而 launchd 失败时，也应优先比较这两种环境的差异
+
+## 卸载与数据保留
+
+`cron-up uninstall` 管理的是本机服务和 cron-up 自有产物，不等于删除所有相关数据：
+
+| 操作或数据 | `cron-up uninstall` | `cron-up uninstall --purge` |
+| --- | --- | --- |
+| 停止仍可安全跟踪的预热会话 | 是 | 是 |
+| 移除 LaunchAgent 和 plist | 是 | 是 |
+| 删除 `~/.local/share/cron-up` 中的配置、状态、心跳和启动脚本 | 否 | 是 |
+| 删除 `~/Library/Logs/cron-up` 中的巡检与会话日志 | 否 | 是 |
+| 卸载 npm 全局 `cron-up` 命令 | 否 | 否 |
+| 删除 Claude Code 任务或 `~/.claude/projects` 对话记录 | 否 | 否 |
+| 恢复任务文件中的 `permanent`、`createdBy*` 字段 | 否 | 否 |
+
+完全移除命令行和 cron-up 自有产物：
+
+```bash
+cron-up uninstall --purge
+npm uninstall -g cron-up
+```
+
+Claude Code 任务和对话记录需要在 Claude Code 侧另行处理。卸载后任务文件仍然存在，但 cron-up 不再提供预热、续期或会话回收；不要把这个状态理解为任务字段已经恢复原状
+
+## 故障排查
+
+| 现象 | 排查方法 |
+| --- | --- |
+| 总览提示“冷却中” | 运行 `cron-up logs <目录名>--<任务id>` 查看启动界面；常见原因是目录信任、工具授权、登录状态或 shell 环境，冷却结束不代表问题已经修复 |
+| 设定时间到了但没有执行 | 先看 `cron-up list` 的预计投递时间，排除上游抖动；再看总览告警和对应会话日志，并确认当时电脑没有休眠 |
+| 总览提示“启动脚本已失效 / PATH 找不到 node” | 按[升级与启动链维护](#升级与启动链维护)检查并重跑 `cron-up install` |
+| 总览提示“巡检已沉默” | 先运行 `cron-up logs` 查看巡检和 stderr 提示，再检查启动链并重跑 install |
+| `last exit code=2` | 通常是配置损坏或 roots 类型不对；直接修复 `~/.local/share/cron-up/config.json`，或按[配置无法解读时](#配置无法解读时)的说明显式传入完整 roots 重跑 install |
+| 手动 `cron-up run` 正常、定时执行不正常 | 比较终端与 launchd／`zsh -lic` 的 PATH、Node 和 `claude` 环境；换过 Node 安装方式后重跑 install |
+| 任务表显示“已错过” | 对一次性任务检查后台会话是否启动及其日志；手写任务缺少有效 `createdAt` 时，cron-up 不会按错过待补处理 |
+| 日志里出现“卡死” | 表示超过登记宽限后由巡检终止，常见于人工作答界面，也可能是会话登记或启动形态变化；先看会话日志和总览的登记格式告警 |
+| 从旧版升级后仍有目录级预热 | 查看[旧版迁移](docs/migration.md)，核实是否因缺少进程指纹而需要人工处理 |
+
+## 已知限制
+
+- 仅支持 macOS，且依赖未公开的 Claude Code 内部实现；上游升级可能改变任务归属、登记格式、进程结构和投递算法
+- 电脑休眠期间错过的周期任务不会补执行；一次性任务的补执行依赖上游机制和必要任务字段
+- 每个进入窗口且原归属不在场的任务对应一个会话，同分钟大量任务可能带来明显内存压力
+- 手写或第三方生成的任务文件不是推荐入口；任务应有唯一 id、显式 `recurring` 和符合上游语义的字段，一次性任务还需要毫秒时间戳 `createdAt` 才能由 cron-up 判断错过待补
+- 工作区的任务文件被整体删除或目录移出 roots 后，仍在运行的预热可能不再被回收；总览会列出能识别的此类会话，需要人工处理
+- mtime 乐观检测不能完全关闭跨进程写入竞态；需要绝对写入保证时，应由上游提供共享锁或公开写接口
+- 即使预热和投递正常，任务仍可能因模型、工具、权限、网络或 prompt 本身而失败
 
-## 发布
+## 更多文档
 
-- **版本号**：按「年.月.序号」——两位年份、两位月份、累计发布序号（0.x 时代的发布总数，含 0.x，序号永不重置、不随月份归零，始终等于含本次在内的历史发布总次数）。下一序号不用手数：发布前 `git fetch --prune --tags` 后数 v* tag 总数加一，`prune-tags` 让删错的 tag 不计数。
-- **发布方式**：先把 package.json 的 version 改成新版本并合入 main，再打同名 `v<version>` tag（如 `v26.9.21`）；GitHub Actions 会跑通测试（Node 22/24）、校验 package.json 版本与 tag 一致（不符直接失败）、并 publish。tag 失败的 launchd 入口旧 tag 重跑即可，序号不消耗。发布失败的 tag 重跑 release 工作流即可，序号不消耗。
-- npm 经 GitHub OIDC 验证「确为 `adaex/cron-up` 仓库 `v` 触发的运行」后放行，仓库里没有 NPM_TOKEN，token 泄漏这条路不存在。
-- **发版收尾**（每次发版必做）：按上述方式升级后，跑一次无参数的 `cron-up`，确认首行是刚发的版本号、服务已加载且上次退出码 0、「需要留意」为空。
-- **npm 传播延迟**：publish 成功约两分钟才完成处理，本机缓存各自滞后，装到旧版且毫无提示——等两分钟后用显式版本号安装，装完以总览首行版本号为准。
-- **trusted publishing**：npm 包设置页里已登记 GitHub 仓库（repository `adaex/cron-up`，workflow `release.yml`），一次性配置，没了见 Trusted Publisher 文档。
+- [内部机制与兼容性](docs/internals.md)：任务归属、生命周期常量、投递算法、并发与版本证据
+- [旧版迁移](docs/migration.md)：从 26.10.30 及更早版本升级
+- [贡献指南](CONTRIBUTING.md)：开发、测试和文档同步要求
+- [发布流程](docs/release.md)：版本号、签名 tag、trusted publishing 与逐机升级
 
 ## License