cron-up 26.10.33 → 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 与实际 cron-up 的 bin 目录解析进启动脚本。
-- Node.js 22 以上（零运行时依赖，巡检本身只调系统自带工具）。
-- 无人值守时的工具权限：后台会话没有人在场点授权确认。后台会话通过 `claude --permission-mode bypassPermissions` 显式以 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 或两者组合；命中多个日志时会列出候选，请补充更长的片段
 
-巡检每轮会顺手维护扫描到的任务文件，全部合并在一次带 mtime 乐观检测的原子写里：
+### 看懂总览和任务列表
 
-- **自动续期**：给显式周期任务补 `permanent: true`，绕开 Claude Code 的 7 天周期任务回收。
-- **自动任务级盖印**：把窗口内死主任务的三个归属字段盖成各自预热会话的身份。只改 `createdBySessionId/createdByPid/createdByProcStart`，不碰 `prompt`、`cron`、`id` 与 `createdInProject`；内容相同但 id 不同的任务仍逐条定位，不会共用盖印目标。
+总览优先看三处：
 
-这些维护与 Claude Code 自己对文件的写入（更新 `lastFiredAt`、执行后删一次性任务）用 mtime 做乐观检测：发现撞车就暂缓本轮该文件的写入，下轮再来。它能降低并发覆盖概率，但不是与 Claude Code 共用的互斥锁；最后一次检查与原子替换之间的极小竞态见「已知限制」。
+- **服务与上次巡检**：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` 的状态列和总览的「最近」显示的是计入抖动后的预计实际时间；cron-up 不改写任务 id，也不会消除这段上游抖动。
+预热会话按任务需要创建，周期任务不依靠跨周期累积上下文。复用与回收只在巡检轮次中按启发式条件判断，不等于对任务完成状态做强保证：
 
-巡检判定「任务现在是否需要会话」时，把周期任务落点之后、抖动投递点之前的这段尾窗也算作需要在场，会话不会在任务真正投递前被回收。这些参数逆向自 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 中的全部权限**：后台会话通过 `--permission-mode bypassPermissions` 显式以 bypass permissions 模式无人值守运行。roots 的边界就是无人授权写权限的边界。
-- **归属盖印会改写任务文件**：cron-up 会改窗口内死主任务的 `createdBySessionId/Pid/ProcStart` 字段。写入采用原子替换（临时文件 0600、保留原文件权限），并用 mtime 乐观检测降低与 Claude Code 并发写入互相覆盖的概率。
-- **会话日志可能包含任务输出**：后台会话的界面记录写到 `~/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）后，仍在运行的预热不会被回收，总览会列出这类会话，不需要时手动结束。
-- 任务文件的 mtime 乐观检测不是跨进程 CAS：另一个写者若恰好赶在最后一次检查之后、原子替换之前写入，仍可能被覆盖。这个窗口无法由 cron-up 单方面彻底关闭；需要绝对保证时，应由上游提供共享写锁或公开写接口。
-- 预热依据的逐任务谓词、调度锁与三代进程结构是未公开内部实现：新版若调整归属/锁语义，任务级隔离的前提需要重新核对。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 成功后到 registry 可查通常两分钟、偶发七八分钟（带 provenance 要等透明日志与后端入库），本机元数据缓存还会再滞后，直接 `npm i -g cron-up` 可能装回旧版且毫无提示——用显式版本号加 `--prefer-online` 安装（`npm i -g cron-up@<新版本> --prefer-online`），装完以总览首行版本号为准。
-- **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
 

package/docs/internals.md

@@ -0,0 +1,190 @@
+# 内部机制与兼容性
+
+本文面向需要排查兼容问题或修改实现的维护者。这里记录的是当前实现依据和行为边界，不是 Claude Code 的公开契约；普通使用从 [README](../README.md) 开始
+
+## 版本证据与验证口径
+
+cron-up 依赖的上游机制没有稳定性承诺，不能把“2.1 以上”视为完整的兼容声明。当前仓库中已有的核对记录如下：
+
+| 机制 | 已有核对依据 | 使用时的含义 |
+| --- | --- | --- |
+| 7 天周期任务回收与任务归属字段 | Claude Code 2.1.300 起有核对记录 | 更早版本不能据此推断可用 |
+| 逐任务调度谓词与目录级调度锁 | Claude Code 2.1.302 二进制 | 一任务一会话的核心依据 |
+| `script → zsh → claude` 三代进程结构 | 本机 Claude Code 2.1.302 | 会话认亲和进程回收依赖这一结构及祖先链识别 |
+| 任务文件与 `~/.claude/sessions/` 会话登记 | 当前实现以 2.1.302 为本机核对基线 | 登记格式漂移时只能提供烟雾告警，不能证明所有语义仍兼容 |
+| 投递抖动默认值与算法 | Claude Code 2.1.285，darwin-arm64，2026-09-30 安装的二进制 | 不能写成已经在 2.1.302 重新验证；远程配置还可能覆盖默认值 |
+
+这张表记录已有证据，不是“只有列出的版本才能运行”的断言。低于或高于核心基线的版本都按未验证处理；升级后应：
+
+1. 运行 `cron-up`，查看会话登记、启动链和预热告警
+2. 用低风险任务验证发现、预热、投递和回收的完整链路
+3. 若预计投递与实际投递持续出现系统性偏差，重新核对上游算法，而不是只调整本地显示常量
+
+`src/constants.mjs` 中的 `CC_JITTER` 注释还记录了上游远程配置键 `tengu_kairos_cron_config`。运行时的远程配置可能改变投递行为，因此本地逆向常量只能用于估算
+
+## 工作区与任务身份
+
+- 工作区是包含 `.claude/scheduled_tasks.json` 的精确目录，不自动等同于 Git 根目录
+- 扫描从 roots 开始，root 本身及其下第 1 至第 3 层都检查候选文件；符号链接形式的子目录不递归，排除名单由 `PRUNE_DIRS` 定义
+- 原生任务优先使用唯一 `id` 作为状态键；缺少 id 的手写任务使用稳定内容摘要形成 `anon:` 键
+- 同一个状态键对应多条任务时，无法唯一映射会话，巡检跳过这些条目的预热与归属改写并给出告警
+- 推荐入口是 Claude Code 的 CronCreate（`durable: true`）；手写或第三方生成文件只是兼容性用法，字段必须遵循上游语义
+
+## 逐任务归属与调度谓词
+
+Claude Code 2.1.302 中核对到的投递判定按以下优先级理解：
+
+1. 任务没有归属会话：只有持目录调度锁的会话投递
+2. 任务归属当前会话：当前会话投递，不需要目录锁
+3. 当前进程是任务记录的创建者进程（resume 形态）：可以投递
+4. 其他情况：会话必须持锁、任务属于本项目，并且记录中的创建者进程已死，才可接管
+
+cron-up 为进入窗口且原归属不在场的任务分别启动会话，认亲后把任务归属写到对应 sessionId 和进程指纹。这样，同目录同时到期的不同任务不必共享一个交互会话
+
+“原创建者在线时不碰任务”只适用于**不预热、不改写归属**；自动续期仍会修改显式周期任务的 `permanent` 字段
+
+某个预热中途退出后，其他符合上游规则的活会话仍可能按第 4 条接管，但这不是 cron-up 对执行结果的额外保证
+
+## 巡检与会话生命周期
+
+主要常量集中在 [`src/constants.mjs`](../src/constants.mjs)，数值以源码为准；本文解释其语义和派生关系。修改常量时应同时核对状态机，而不是只改文档
+
+| 常量 | 含义 |
+| --- | --- |
+| `INTERVAL_SECONDS` | launchd 相邻巡检轮次的目标间隔，休眠时可能漏轮 |
+| `LEAD_SECONDS` | 周期任务的预热前瞻量 |
+| `MAX_SCAN_DEPTH` | root 下最多再下降的层数，最大深度本身仍检查任务文件 |
+| `WARMUP_POLL_MS` | 新会话启动后，当轮重扫会话登记的间隔 |
+| `WARMUP_WAIT_MS` | 当轮等待认亲的上限，不是判死时限 |
+| `WARMUP_GRACE_SECONDS` | 未登记进程超过该年龄后，才在跨轮状态机中判卡死 |
+| `FAIL_LIMIT` | 没有成功登记的启动失败达到该次数后进入冷却 |
+| `COOLDOWN_SECONDS` | 单任务暂停重试的时间 |
+| `FAIL_TTL_SECONDS` | 已死亡条目的失败记录跨预热窗口保留后的老化时限；活条目和冷却条目按各自状态保留 |
+| `SESSION_RECYCLE_IDLE_SECONDS` | 与 `WARMUP_GRACE_SECONDS` 同值；回收判断要求的界面静默时长 |
+| `SESSION_FIRE_MARGIN_SECONDS` | 除一个巡检间隔外，为下次触发预留的余量 |
+| `SESSION_RECYCLE_MARGIN_SECONDS` | 等于 `SESSION_FIRE_MARGIN_SECONDS + INTERVAL_SECONDS`；回收要求距下次需要超过该余量 |
+| `HEARTBEAT_STALE_FACTOR` | 心跳超过该倍数的巡检间隔未更新时提示沉默 |
+| `PATROL_LOG_ROTATE_BYTES` | 单个巡检日志超过该大小后，在轮初轮转 |
+| `DISPLAY_SEARCH_DAYS` | `list` 和总览寻找未来落点的展示窗口 |
+
+一次性任务的预热前瞻统一额外增加 `CC_JITTER.oneShotMaxMs`，窗口前沿为 `落点 - LEAD_SECONDS - CC_JITTER.oneShotMaxMs`。**所有一次性任务都使用该保守窗口**，不是只有 `:00`／`:30` 网格任务；额外前瞻用于覆盖网格任务可能提前投递的相位，非网格任务也采用同一口径。实际启动仍取决于巡检相位和运行状态
+
+### 一轮巡检的主要阶段
+
+1. 获取巡检互斥锁，读取配置、状态、心跳和 Claude Code 会话登记
+2. 发现工作区，按任务逐组处理；单个工作区出错不应阻断后续工作区
+3. 已有条目先尝试认亲，成功后回填 sessionId、Claude pid 和进程启动指纹，并清零失败计数
+4. 依次处理原创建者在线、终端 resume 接管、执行后回收、预热窗口、卡死退休、冷却和重新启动
+5. 合并自动续期与归属改写；新启动的会话在当轮等待认亲后再尝试补写归属
+6. 回收任务已经删除的会话，保存仍有效的状态和本轮心跳
+
+### 启动失败与卡死不是同一计时器
+
+- `WARMUP_WAIT_MS` 的当轮等待结束只会停止等待，不增加失败计数，也不直接杀死仍存活的进程
+- 未登记进程年龄超过 `WARMUP_GRACE_SECONDS` 后，由后续巡检执行卡死退休，而不是由到达阈值就精确触发的独立定时器处置
+- 启动即失败、启动后死亡和卡死退休都会进入失败流程；成功认亲会清零失败计数
+- 已死亡条目的失败记录按任务保留，可跨稀疏任务的多个预热窗口累计，并按 `FAIL_TTL_SECONDS` 老化；因此 `FAIL_LIMIT` 统计的不是“连续若干个巡检轮次”
+
+### 回收是启发式判断
+
+周期任务的会话回收需要同时满足：
+
+- `lastFiredAt` 表明该任务在本代会话启动后已经触发
+- 会话界面日志静默超过 `SESSION_RECYCLE_IDLE_SECONDS`
+- 距该任务下次需要会话超过 `SESSION_RECYCLE_MARGIN_SECONDS`
+
+这些条件只说明“可以按当前模型回收”，不证明 prompt 的所有副作用都已成功完成。任一条件不满足时会继续复用现有会话；高频周期任务可能因始终不满足回收余量而长期复用同一会话
+
+任务被删除或一次性任务执行后从文件中消失时，还会走对应的条目清理路径
+
+若工作区整个离开扫描视野，巡检无法继续按该任务状态做回收；总览会尽量报告仍能识别的运行中会话
+
+## 任务文件维护与并发
+
+每轮维护分两类：
+
+- **续期**：只要 `recurring` 为真且 `permanent` 尚未为真，就写入 `permanent: true`，不依赖任务是否进入预热窗口
+- **归属改写**：只针对进入窗口且需要预热的唯一任务键，写入 `createdBySessionId`、`createdByPid`、`createdByProcStart`
+
+归属改写不以修改 `prompt`、`cron`、`id`、`createdInProject` 为目标。内容相同但 id 不同的任务分别定位；重复 id 或重复匿名键无法唯一映射时跳过
+
+同一批续期和已有条目的归属改写会合并写入；本轮新启动的会话在等待期认亲后，可能通过补盖流程另做一次归属写入。两条路径都使用同目录临时文件和原子替换：
+
+- 临时文件先以 0600 创建，再尽量保留原任务文件权限
+- 读取与写入之间使用 `mtimeNs` 做乐观检测，检测到其他写者改动时放弃本轮写入
+- 这不是跨进程 CAS，也不是与 Claude Code 共用的锁；最后检查之后、`rename` 之前仍有一个无法由 cron-up 单方面关闭的竞态窗口
+
+因此，文档不能把原子替换表述为绝不覆盖并发更新，卸载也不会回滚已经完成的续期或归属改写
+
+## 投递时间算法
+
+以下算法用于 `cron-up list`、总览的“最近”和预热尾窗估算。它是上游内部实现的复刻，不是 cron-up 自己决定的调度策略
+
+### 任务 id 的归一化值
+
+当前实现对原生十六进制任务 id 取前 8 位，解析后除以 `2^32`，得到 `[0, 1)` 范围内的固定值，记作 `h`。同一 id 每次计算相同，不是每次触发重新随机
+
+手写非标准 id 的解析不应被当作稳定兼容接口；推荐让 CronCreate 生成 id
+
+### 周期任务
+
+对某个 cron 落点，先计算它到下一落点的实际间隔 `period`，再估算：
+
+```text
+delay = min(h × 0.5 × period, 30 分钟)
+预计投递 = 本落点 + delay
+```
+
+每日任务周期较长，很多原生随机 id 会触及 30 分钟上限。落点已经过去、预计投递尚未到来时，仍属于需要会话在场的尾窗，不能按“下一次未来落点”提前回收
+
+代码已记录但**没有复刻**一个上游例外：相邻落点间隔约在 `[300000, 315000)` ms、且表达式匹配上游内部步进规则时，存在 `cacheLeadMs` 提前 15 秒的分支，例如部分约 5 分钟周期任务。对这类任务：
+
+- “周期任务一律在落点后投递”的说法不成立
+- 当前 `list` 的预计时间可能与上游实际调度存在约 15 秒或更多的系统性差异
+- 是否补齐该分支需要单独实现和测试，不能只改文档宣称已经支持
+
+### 一次性任务
+
+- 落点分钟不属于 `:00`／`:30` 网格时，当前估算不增加投递提前量
+- 落点属于网格时，按 `h × 90 秒` 提前，且不早于当前时刻
+- 无论是否属于网格，巡检的预热前瞻都统一额外增加 90 秒，原因见生命周期章节
+
+会话内部还存在秒级轮询尾差，因此“预计投递时间”不等于对实际开始执行时刻的保证
+
+### 展示边界
+
+未来落点的展示搜索范围由 `DISPLAY_SEARCH_DAYS` 定义。“一年内无”既包括下一落点超出展示窗口的表达式，例如部分闰日任务，也包括字段可以解析、但日历上永远无法匹配的表达式，例如 `0 0 30 2 *`
+
+“cron 无效”只用于表达式解析失败，或字段值域、区间导致合法值集合为空；它与“一年内无”不是同一状态
+
+## 会话登记、认亲与接管
+
+预热进程的典型结构为：
+
+```text
+/usr/bin/script（cron-up state 记录这一层）
+  └─ /bin/zsh -lic
+      └─ claude（会话登记记录这一层）
+```
+
+巡检读取 `~/.claude/sessions/*.json`，结合进程存活、cwd 和祖先链，把 script 进程与登记的 sessionId 对应起来。登记是上游输出，不是稳定 API；读取器包含三类烟雾告警：
+
+- 有登记文件但识别不到 interactive 会话
+- 存活登记进程都不是可识别的 `claude`
+- interactive 会话缺少有效 pid 或工作目录
+
+这些告警只能覆盖已知漂移形态，不能证明上游所有内部语义均未变化
+
+其他恢复机制：
+
+- **终端接管**：script 层已退出但同一 sessionId 仍在终端存活时，不再另拉或结束该会话
+- **孤儿认领**：state 丢失时，按任务专属日志路径从进程表重新识别仍可确认的预热进程
+- **停止保护**：发信号前核对进程启动指纹，降低 pid 复用时误伤其他进程组的概率
+
+## 日志与隐私
+
+- 巡检日志位于 `~/Library/Logs/cron-up/launchd.{out,err}.log`，默认 `cron-up logs` 展示当前 stdout 日志最近 100 行
+- 会话界面日志按 `<工作区折名>--<任务id>.log` 隔离，启动新代时轮转保留一代 `.1`
+- 工作区折名会转义下划线并把路径分隔符折叠为 `_`，避免不同路径轻易撞名
+- 会话日志可能包含任务输出，文件按 0600、目录按 0700 管理
+- Claude Code 自己仍在 `~/.claude/projects/` 保存对话记录，cron-up 的 `--purge` 不删除这些记录

package/docs/migration.md

@@ -0,0 +1,47 @@
+# 旧版迁移
+
+本文适用于从 **26.10.30 及更早版本**升级到 **26.10.31 或更高版本**。从 26.10.31 开始，预热模型由“每个目录一个会话”改为“每个进入窗口的任务一个会话”，配置也只保留 roots
+
+## 主要变化
+
+| 方面 | 26.10.30 及更早 | 26.10.31 起 |
+| --- | --- | --- |
+| 预热粒度 | 每个工作区一个目录级会话 | 每个进入窗口的任务一个专属会话 |
+| 会话日志 | 目录级命名 | `<工作区折名>--<任务id>.log` |
+| 状态记录 | 扁平的目录级条目 | 按工作区、任务 id 两级记录 |
+| 配置 | 可能留有旧行为开关和字段 | 只保留 `roots`，其他行为常量化 |
+
+## 升级步骤
+
+通用安装、启动链重建和总览验收按 [README 的升级步骤](../README.md#升级与启动链维护)执行。刚发布、需要避免 registry 或本机缓存带回旧版时，按[发布后的逐机升级与验收](release.md#每次发版后的逐机升级与验收)使用显式版本号
+
+重跑 install 会移除旧版废弃配置字段；配置无法解读时的默认 roots 回退与首轮写入风险见 [README 的配置恢复说明](../README.md#配置无法解读时)
+
+迁移后还要检查预热日志名称。新一代任务级日志应包含 `--<任务id>`；`cron-up logs <目录名>` 命中多个任务时，按候选提示补充任务 id
+
+## 旧目录级会话如何收尾
+
+升级后的首轮巡检会结束能够核实身份的旧目录级预热，再按任务重新启动。迁移不会把旧的目录级状态直接伪装成新任务级状态
+
+为防止 pid 复用导致误杀，缺少进程启动指纹的旧条目不会被贸然发信号：
+
+- 对应进程已经退出时，不再需要停止它
+- 对应进程仍在运行且无法安全核实时，巡检会明确告警，不会把“未停止”记成“已回收”
+- 出现这类告警时，先用 `cron-up logs` 找到“旧版迁移”条目，记录其中的 pid、工作区或日志路径；旧版扁平状态不一定会出现在总览中
+- 再把下列命令中的 12345 换成实际 pid，核对进程启动时间、父进程和完整启动命令：
+
+  ```bash
+  /bin/ps -p 12345 -o pid=,ppid=,lstart=,args=
+  ```
+
+  确认它确为旧版预热后再决定如何收尾；无法确认身份时，不要对该进程或其进程组直接发信号
+
+## 不会自动回滚的内容
+
+升级和卸载都不会把任务文件恢复到首次使用 cron-up 之前：
+
+- 已写入的 `permanent` 会保留
+- 已改写的 `createdBySessionId`、`createdByPid`、`createdByProcStart` 不会自动还原
+- Claude Code 的任务和 `~/.claude/projects` 下的对话记录不由迁移流程删除
+
+如果工作区不再纳入 roots，后续巡检不会再维护它，但既有字段和已经运行且失去扫描视野的会话仍需分别核查

package/docs/release.md

@@ -0,0 +1,75 @@
+# 发布流程
+
+本文面向维护者，记录 `adaex/cron-up` 的版本号、tag、npm trusted publishing 和发版后逐机验收。普通升级见 [README](../README.md#升级与启动链维护)
+
+## 版本号
+
+格式为 `YY.MM.serial`，例如 `26.10.33`：
+
+- `YY` 是两位年份，`MM` 是两位月份
+- `serial` 是累计序号，包含 0.x 时代，跨月份不归零
+- 工程上的最终校验口径是**远端 `v*` tag 数量**，不是 npm 成功发布次数；下一序号等于发布前该数量加一
+
+发布前同步并计算：
+
+```bash
+git fetch --prune --prune-tags --tags
+git tag -l 'v*' | wc -l
+```
+
+计数结果加一就是下一序号。release 工作流会重新直接统计远端 tag，防止本地状态与远端不一致；被删除的远端 tag 不再计数。已推送但尚未 publish、且 tag 内容无需改变的失败运行，优先重跑同一工作流，而不是递增序号；需要修复 tag 内容时按下文处理
+
+## 发布步骤
+
+1. 确认 `main` 已包含本次发布内容，测试通过
+2. 按上述规则修改 `package.json` 的 `version`，并将发布提交合入 `main`
+3. 在发布提交上创建同名签名注解 tag 并推送：
+
+   ```bash
+   git tag -s v<version> <发布提交> -m "发布 <version>"
+   git push origin v<version>
+   ```
+
+4. 等待 `.github/workflows/release.yml` 完成。工作流会：
+   - 在 macOS 上用 Node 22、24 运行测试
+   - 校验 `package.json` 版本与 tag 完全一致
+   - 校验 tag 序号与远端 `v*` tag 总数一致
+   - 执行 `npm pack --dry-run`
+   - 通过 `npm publish --provenance` 发布
+
+发布失败时先确认失败发生在 publish 之前，并区分两种情况：
+
+- **tag 内容无需改变**：例如 runner 或 registry 的临时故障，可以直接对同一个 tag 重跑 release 工作流，不消耗新序号
+- **必须修改仓库内容**：例如测试、版本号或工作流本身有误，只修复 main 后重跑旧 tag 仍会检出旧内容。应先把修复提交合入 main，再将同名签名 tag 重新签在修复提交上，并按仓库 tag 保护规则替换远端同名 tag，使新运行检出修复后的内容；同名 tag 不增加远端计数，因此不消耗新序号
+
+只有尚未成功 publish 的版本才能按后一种方式替换 tag。已经成功 publish 的版本不要再移动 tag，后续问题通过新的发布修复
+
+## Trusted publishing 与凭据边界
+
+npm 通过 GitHub OIDC 校验发布工作流身份，仓库中不保存长期 `NPM_TOKEN`。这降低了长期 npm 令牌泄漏的风险，但不等于所有凭据、工作流或账号安全风险都不存在
+
+npm 包设置中需要一次性登记：
+
+- repository：`adaex/cron-up`
+- workflow：`release.yml`（仓库中的 `.github/workflows/release.yml`）
+- 发布触发：同名 `v*` tag 对应的 GitHub Actions 运行
+
+配置缺失或需要重建时，按 npm 官方 [Trusted Publishers 文档](https://docs.npmjs.com/trusted-publishers/)核对，同时确认 workflow 仍具有 `id-token: write`，且发布环境使用满足要求的 npm 版本
+
+## 每次发版后的逐机升级与验收
+
+按 26.10.32 的实际发布记录，publish 成功后 registry 通常约两分钟可查，偶发需要七八分钟；带 provenance 时还要等待透明日志与后端入库，本机元数据缓存可能进一步滞后
+
+对每一台已有安装的机器分别执行：
+
+```bash
+npm i -g cron-up@<新版本> --prefer-online
+cron-up install
+cron-up
+```
+
+- 第一条必须使用显式新版本号和 `--prefer-online`，不要用不带版本的模糊安装命令
+- 第二条重建配置、启动脚本与 LaunchAgent，并尝试首轮巡检
+- 最后以总览首行的实际版本号为准，同时确认服务已加载、上次退出码为 0、“需要留意”为空；不能用 npm 命令退出码或 registry 页面代替本机核验
+
+未安装的机器不借本次升级新装；无法连接的机器明确记为未完成。npm publish 成功只代表包已发布，不代表各台机器已经升级或巡检健康

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "cron-up",
-  "version": "26.10.33",
-  "description": "为命令行 AI agent 的 cron 定时任务提前预热并保活交互式会话",
+  "version": "26.10.34",
+  "description": "为 Claude Code 定时任务在触发前按需预热交互会话",
   "type": "module",
   "bin": {
     "cron-up": "bin/cron-up.mjs"
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "docs",
+    "CONTRIBUTING.md"
   ],
   "scripts": {
     "test": "node --test"

package/src/cli.mjs

@@ -102,17 +102,21 @@ export function parseCli(argv) {
   return result;
 }
 
-const USAGE = `cron-up —— 为定时任务提前备好交互会话（一任务一会话）
+const USAGE = `cron-up —— 为 Claude Code 定时任务按需预热交互会话（一任务一会话）
 
 用法：
   cron-up                    查看总览（服务、配置、任务、预热会话）
   cron-up install            安装配置与 LaunchAgent（可用 --roots 指定扫描目录）
-  cron-up uninstall          卸载并结束全部预热会话（--purge 连配置日志一起删）
-  cron-up list               逐个列出定时任务的设定/预计实际触发时间与预热状态
+  cron-up uninstall          停止预热并移除 LaunchAgent（--purge 另删配置与日志）
+  cron-up list               逐个列出任务的设定/预计投递时间与预热状态
   cron-up run                执行一轮巡检（launchd 入口，也可手动立即跑一轮）
   cron-up logs [目录片段]    查看巡检日志或后台会话记录（-f 跟踪）
 
-升级：npm i -g cron-up@latest`;
+升级：npm i -g cron-up@latest --prefer-online
+      cron-up install
+
+完全移除：cron-up uninstall --purge
+          npm uninstall -g cron-up`;
 
 export async function main(argv = process.argv) {
   const parsed = parseCli(argv.slice(2));

package/src/constants.mjs

@@ -5,7 +5,7 @@
 export const DEFAULT_CONFIG = {
   // 默认只扫本人的三个任务制容器，不扫整个家目录——他人可写仓库里的周期
   // 任务会被自动续期永久化，默认范围必须是用户完全掌控的领地（见 README
-  // 安全说明）。其他布局用 cron-up install --roots 覆盖；目录不存在则跳过。
+  // 「安全与自动修改」）。其他布局用 cron-up install --roots 覆盖；目录不存在则跳过。
   roots: ['~/space', '~/workspace', '~/tasks'],
 };
 
@@ -45,9 +45,8 @@ export const WARMUP_GRACE_SECONDS = 180;
 // 帽与墙钟帽双出口，高负载拖慢 setTimeout 也不会把一轮撑过间隔。
 export const WARMUP_WAIT_MS = 24_000;
 export const WARMUP_POLL_MS = 3_000;
-// window 回收判据一：界面静默超过此时长视为「本任务已执行完」。TUI 工作
-// 时持续渲染（毫秒级刷新 typescript），静默 3 分钟不可能是在执行；取
-// WARMUP_GRACE 同值，结构上对齐「3 分钟定生死」的既有心智。
+// window 回收判据一：界面静默超过此时长，作为本代触发后空闲的启发式，
+// 不是任务完成状态的证明。取 WARMUP_GRACE 同值，结构上对齐既有心智。
 export const SESSION_RECYCLE_IDLE_SECONDS = WARMUP_GRACE_SECONDS;
 // window 回收判据二：距该任务下次「需要会话在场」至少还有这么多秒。回收
 // 后下轮（≤INTERVAL）发现并 spawn，进程即在场，盖印在该轮等待期内完成；
@@ -73,7 +72,7 @@ export const PRUNE_DIRS = new Set([
 ]);
 
 // Claude Code 会话投递定时任务时的抖动参数，两处使用：list/总览预测
-// 「预计实际触发时间」；巡检把「落点之后、延迟投递点之前」这段投递尾窗
+// 「预计投递时间」；巡检把「落点之后、延迟投递点之前」这段投递尾窗
 // 也算作需要会话在场，避免在任务真正投递前把预热回收。逆向自
 // Claude Code v2.1.285
 // （darwin-arm64 原生二进制，2026-09-30 安装）内部 createCronScheduler 的
@@ -81,8 +80,7 @@ export const PRUNE_DIRS = new Set([
 // recurringCapMs)；一次性任务在 :00/:30 网格点提前 0~oneShotMaxMs。
 // 这些值没有稳定性承诺——版本升级可能改，运行时还可能被远程配置键
 // tengu_kairos_cron_config（60 秒刷新，校验失败回退默认）覆盖。预测与
-// 实际系统性对不上时，按 findings 主题
-// claude-code-scheduled-task-jitter 的排查步骤复核新版本。
+// 实际系统性对不上时，按 docs/internals.md 的版本证据与复核步骤核对新版本。
 export const CC_JITTER = {
   recurringFrac: 0.5,
   recurringCapMs: 30 * 60 * 1000,

package/src/cron.mjs

@@ -260,7 +260,7 @@ export function taskWanted(task, now, leadMs) {
 // 两个口径供展示视图复用（同一个已解析 cron 顺带回答巡检问题）。
 export { wantedNow, wantedWithin };
 
-// ---- Claude Code 投递抖动（预计实际触发时间）----
+// ---- Claude Code 投递抖动（预计投递时间）----
 // 复刻 v2.1.285 内部的 M()：任务 id 前 8 位十六进制除以 2^32，得 [0,1) 的
 // 固定哈希——同一任务每次触发的抖动完全相同，不是随机数。id 缺失或前 8
 // 位都不是十六进制时 parseInt 得 NaN，上游回退 0；任务文件由别的程序书
@@ -271,7 +271,7 @@ export function taskIdHash(taskId) {
   return Number.isFinite(n) ? n : 0;
 }
 
-// 任务在展示语境里的「落点 → 预计实际投递」对：一次性任务是落点加网格
+// 任务在展示语境里的「设定时间 → 预计投递」对：一次性任务是落点加网格
 // 提前量；周期任务在投递尾窗内属于上一落点（即将到来的这次延迟投递，
 // 不是 nextAfter 给出的下个落点——后者严格在未来，会把展示拐到明天），
 // 否则是下一落点 + 按 id 的抖动。先于窗口检查尾窗：2 月 29 日这类长周期
@@ -326,7 +326,7 @@ function recurringDelayMs(cron, slot, taskId, withinDays) {
 
 // 周期任务的「投递尾窗」判定：上一落点已过、按 id 算的延迟投递时刻未
 // 到。返回 [落点, 投递时刻 ms]；不在尾窗、找不到上一或下一落点返回
-// null。wanted（保活判定）与 nextDelivery（展示）共用这一口径，两边不会
+// null。wanted（会话需求判定）与 nextDelivery（展示）共用这一口径，两边不会
 // 各说各话；窗口取 TAIL_WINDOW_DAYS，理由见 constants。
 function recurringTailWindow(cron, taskId, now) {
   const prev = cron.prevAtOrBefore(now, TAIL_WINDOW_DAYS);

package/src/display.mjs

@@ -110,7 +110,7 @@ export function taskView(task, now, leadMs) {
     // wanted 恒为 null 或布尔：没传 leadMs（不问）与 cron 无效（问不了）
     // 都是 null，键的形状不随参数变化。
     wanted: leadMs !== undefined ? wantedWithin(cron, task, now, leadMs) : null,
-    // 计入 Claude Code 投递抖动后的预计实际触发时刻；已错过的一次性任务
+    // 计入 Claude Code 投递抖动后的预计投递时刻；已错过的一次性任务
     // 没有未来触发，为 null；尾窗内的周期任务是即将到来的这次延迟投递。
     // 与 nxt 同为 Date 或 null。
     fire: missed ? null : fire,
@@ -135,7 +135,7 @@ export function pad2(n) {
   return String(n).padStart(2, '0');
 }
 
-// 「设定落点 → 预计实际触发」文案。抖动四舍五入到秒（调度器秒级轮询）：
+// 「设定时间 → 预计投递」文案。抖动四舍五入到秒（调度器秒级轮询）：
 // 同日省略第二个日期；预计值带非零秒时显示 HH:MM:SS（如 05:15:37）；落
 // 在同一分钟（无抖动）则只显示落点，不画无意义的箭头。
 export function fmtFireRange(nxt, fire) {

package/src/list.mjs

@@ -19,7 +19,7 @@ function rank(v) {
   return v.nxt ? 1 : 2;
 }
 
-// 状态列文案：有效任务是「设定落点 → 预计实际触发」（无抖动时只有落点）。
+// 状态列文案：有效任务是「设定时间 → 预计投递」（无抖动时只有设定时间）。
 function statusText(v) {
   if (!v.valid) return 'cron 无效';
   if (v.missed) return '已错过';

package/src/overview.mjs

@@ -77,7 +77,7 @@ function overviewTasks(cfg, cols, details, state) {
         bad += 1;
         continue;
       }
-      // 「最近」按计入抖动后的预计实际触发排，而非 cron 落点。
+      // 「最近」按计入抖动后的预计投递时间排，而非 cron 落点。
       const fire = v.fire ?? v.nxt;
       if (fire && (!soonest || fire.getTime() < soonest[0].getTime())) {
         soonest = [fire, ws, v.summary, v.nxt];
@@ -189,18 +189,18 @@ function overviewSessions(cols, state, details, suppressCooling, discovered) {
 }
 
 const COMMANDS = [
-  ['list', '逐个列出任务的内容摘要、设定/预计触发时间与预热状态'],
+  ['list', '逐个列出任务的内容摘要、设定/预计投递时间与预热状态'],
   ['logs [目录片段] [-f]', '查看巡检日志或后台会话记录'],
   ['run', '立即手动巡检一轮'],
-  ['install --roots ~/a,~/b', '更新扫描目录并重新安装（不带参数保留现有配置）'],
+  ['install --roots ~/a,~/b', '更新扫描目录并重新安装（不带参数沿用有效配置）'],
 ];
 
 export async function cmdOverview(args) {
   const cols = deps.terminalWidth();
   const v = packageVersion();
   deps.print(v === null
-    ? 'cron-up —— 为定时任务提前备好交互会话'
-    : `cron-up ${v} —— 为定时任务提前备好交互会话（一任务一会话）`);
+    ? 'cron-up —— 为 Claude Code 定时任务按需预热交互会话'
+    : `cron-up ${v} —— 为 Claude Code 定时任务按需预热交互会话（一任务一会话）`);
 
   const cfgPath = args?.config ?? deps.paths.configPath;
   let cfg = null;
@@ -232,8 +232,8 @@ export async function cmdOverview(args) {
   } else if (cfg === null) {
     deps.print('配置：缺失，运行 cron-up install 生成');
   } else {
-    deps.print(`巡检：每 ${INTERVAL_SECONDS} 秒一轮，提前 ${LEAD_SECONDS} `
-      + '秒为每个窗口内任务启动专属预热会话');
+    deps.print(`巡检：每 ${INTERVAL_SECONDS} 秒一轮，周期任务提前 ${LEAD_SECONDS} `
+      + '秒进入预热窗口');
     if (info && info.interval !== null && info.interval !== undefined
         && info.interval !== INTERVAL_SECONDS) {
       alerts.push(`launchd 实际间隔 ${info.interval} 秒与当前版本的 `

package/src/service.mjs

@@ -360,11 +360,12 @@ export async function cmdInstall(args) {
   validateConfig(cfg, (m) => deps.print(m));
   if (JSON.stringify(cfg.roots)
       === JSON.stringify(normalizeRoots(DEFAULT_CONFIG.roots))) {
-    // 与 README 安全说明同一句话，在配置落定的这一刻当面再说一遍。
+    // 与 README「安全与自动修改」同一口径，在配置落定时再提示一次。
     deps.print(`提示：未指定 --roots，默认扫描 ${DEFAULT_CONFIG.roots.join('、')}`
       + '（不存在的目录跳过）；今后 clone 进这些容器的仓库也会进入巡检，'
-      + '其中的周期任务会被自动续期永久化。目录布局不同或需收窄时用 '
-      + '--roots 指定（见 README 安全说明）');
+      + '其中的周期任务会被自动续期永久化，任务、CLAUDE.md 与项目配置都会'
+      + '影响无人值守会话。目录布局不同或需收窄时用 --roots 指定'
+      + '（见 README「安全与自动修改」）');
   }
 
   const launcher = deps.resolveLauncher();
@@ -515,7 +516,7 @@ export async function cmdUninstall(args) {
       // npm 管的文件不能手删：命令行本身交给 npm 卸载。
       deps.print('命令行本身请运行 npm uninstall -g cron-up 卸载');
     } else {
-      deps.print('配置与日志已保留（--purge 可删除全部产物）');
+      deps.print('配置与日志已保留（--purge 可删除 cron-up 自有配置与日志）');
     }
   } finally {
     deps.releaseRunLock(lock);

package/src/sessions.mjs

@@ -119,11 +119,11 @@ function canSignalProcessGroup(pid) {
 // 为一个任务拉起一个 detached 的 pty TUI，返回 {pid, procStart}。
 export function spawnSession(ws, taskId) {
   const logPath = sessionLogPath(ws, taskId);
-  // 会话日志目录 700（README 承诺）：每任务独立文件，目录只在此处创建。
+  // 会话日志目录 700（README 权限约定）：每任务独立文件，目录只在此处创建。
   ensurePrivateDir(path.dirname(logPath));
-  // 「一代会话 = 一次执行」：script(1) 打开即截断，不轮转的话上一代（上
-  // 一次执行）的界面记录会随本次拉起被抹掉。无条件保留一代（.1）——总
-  // 量上界两代，活着的一代增长再快也只影响自身，不会经轮转放大。
+  // script(1) 启动即截断：每次新拉起前无条件保留上一代（.1），避免上次
+  // 启动以来的界面记录被抹掉。总量上界两代，活着的一代增长再快也只影响
+  // 自身，不会经轮转放大。
   try {
     if (fs.existsSync(logPath)) rotateOnce(logPath);
   } catch {