cron-up 26.10.32 → 26.10.34

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.32",
-  "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/args.mjs

@@ -1,8 +1,7 @@
 // 子命令选项规格与选项名转换。独立于 cli：选项表是唯一事实源，新增选项
 // 时只改这里。
 
-// 选项类型：string 吃一个值；int 吃一个值且必须是严格十进制；bool 是无
-// 值开关。
+// 选项类型：string 吃一个值；bool 是无值开关，--flag=value 一律拒绝。
 export const SPECS = {
   install: {
     options: {

package/src/cli.mjs

@@ -4,7 +4,7 @@
 
 // 先引全量入口，保证所有业务模块都已向 deps 自注册，再引命令函数。
 import './index.mjs';
-import { deps, ExitError, isDecInt } from './internals.mjs';
+import { deps, ExitError } from './internals.mjs';
 import { cmdRun } from './patrol.mjs';
 import { cmdInstall, cmdUninstall } from './service.mjs';
 import { cmdList } from './list.mjs';
@@ -12,15 +12,6 @@ import { cmdOverview } from './overview.mjs';
 import { cmdLogs } from './logs.mjs';
 import { SPECS, thisCamel } from './args.mjs';
 
-// 严格十进制整数命令行值（谓词 isDecInt 见 internals）：
-// Number("0x10")、parseInt("5x") 都会静默给出错误结果，必须显式拒绝。
-function cliInt(s) {
-  if (!isDecInt(s)) {
-    throw new ExitError(2, `需要整数却得到：${s}`);
-  }
-  return parseInt(s, 10);
-}
-
 function usageExit(message) {
   throw new ExitError(2, message);
 }
@@ -41,22 +32,23 @@ function consumeOption(tok, tokens, i, spec, opts) {
   } else {
     name = tok.slice(1); // -f
   }
-  if (name === 'f' && spec.options.f === 'bool') name = 'follow';
+  if (name === 'f' && Object.hasOwn(spec.options, 'f')
+      && spec.options.f === 'bool') name = 'follow';
+  if (!Object.hasOwn(spec.options, name)) usageExit(`未知选项：${tok}`);
   const kind = spec.options[name];
-  if (!kind) usageExit(`未知选项：${tok}`);
   if (kind === 'bool') {
+    if (inlineValue !== undefined) usageExit(`布尔选项 --${name} 不接受值`);
     opts[thisCamel(name)] = true;
     return i + 1;
   }
-  // string / int 吃一个值（内联或下一 token）。int 类型现已无选项使用，
-  // 保留解析能力给未来。
+  // string 吃一个值（内联或下一 token）。
   let value;
   if (inlineValue !== undefined) value = inlineValue;
   else {
     value = tokens[i + 1];
     if (value === undefined) usageExit(`选项 --${name} 缺少值`);
   }
-  opts[thisCamel(name)] = kind === 'int' ? cliInt(value) : value;
+  opts[thisCamel(name)] = value;
   return inlineValue !== undefined ? i + 1 : i + 2;
 }
 
@@ -86,7 +78,7 @@ export function parseCli(argv) {
       continue;
     }
     if (!tok.startsWith('-') && command === null) {
-      if (!(tok in SPECS)) usageExit(`未知子命令：${tok}`);
+      if (!Object.hasOwn(SPECS, tok)) usageExit(`未知子命令：${tok}`);
       command = tok;
       i += 1;
       continue;
@@ -110,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));
@@ -144,5 +140,7 @@ export async function main(argv = process.argv) {
       return cmdRun(args);
     case 'logs':
       return cmdLogs({ ...args, workspace: parsed.positional[0] });
+    default:
+      return usageExit(`未知子命令：${parsed.command}`);
   }
 }

package/src/config.mjs

@@ -11,7 +11,7 @@ import {
   isDecInt,
   ensurePrivateDir,
 } from './internals.mjs';
-import { DEFAULT_CONFIG, PID_T_MAX, HEARTBEAT_STALE_FACTOR } from './constants.mjs';
+import { PID_T_MAX, HEARTBEAT_STALE_FACTOR } from './constants.mjs';
 import { expandHome, isDir } from './tasks.mjs';
 
 // Shell 的 tilde 展开只发生在词首："--roots ~/a,~/b" 穿过 shell 后第二个
@@ -28,15 +28,9 @@ export function normalizeRoots(roots) {
   return out;
 }
 
-// 配置数值校验用：JSON 的 true 是布尔不能冒充秒数/深度
-// （Number.isInteger(true) === false，天然挡住）。
-export function isInt(x) {
-  return typeof x === 'number' && Number.isInteger(x);
-}
-
-// 宽容整型化（手改的 state/登记文件里字段可能是字符串或浮点）：纯十进制
-// 字符串接受，浮点截断，布尔拒绝；非法输入抛错由调用方按「字段不存在」
-// 处理。
+// 手改的 state/登记文件里的整数字段可能是字符串或浮点：纯十进制字符串接受，
+// 浮点截断，布尔拒绝；非法输入抛错由调用方按「字段不存在」处理。pid 另有
+// 更严的入口，不允许浮点截断。
 function lenientInt(v) {
   if (typeof v === 'boolean') throw new Error('布尔不是整数字段');
   if (typeof v === 'number') {
@@ -53,6 +47,9 @@ function lenientInt(v) {
 // 登记两个外部来源共用同一条入口规则——超大整数能穿过类型转换直到
 // process.kill 才抛，负数 pid 会被 kill 当成进程组号误伤无辜进程组。
 export function parsePid(v) {
+  // number 必须本身就是整数：1.5 截成 1 可能把停止信号发给完全无关的
+  // pid。字符串仍走纯十进制解析，不接受小数、指数或十六进制。
+  if (typeof v === 'number' && !Number.isInteger(v)) return null;
   let pid;
   try {
     pid = lenientInt(v);
@@ -66,7 +63,7 @@ export function parsePid(v) {
 // 「形同空转」，回退成默认家目录扫描则会动到用户没打算纳入的仓库，两个
 // 方向都比停机更危险。
 export function configFieldErrors(cfg) {
-  if (!Array.isArray(cfg.roots)) {
+  if (!Object.hasOwn(cfg, 'roots') || !Array.isArray(cfg.roots)) {
     return [['roots', `roots 应是字符串数组，当前为 ${JSON.stringify(cfg.roots)}`]];
   }
   return [];
@@ -99,13 +96,14 @@ export function loadConfig(file, opts = {}) {
     fail(`配置文件顶层应是 JSON 对象而不是${Array.isArray(cfg) ? '数组' : typeof cfg}：`
       + `${file}；运行 cron-up install 生成，或用 --config 指定路径`);
   }
-  const merged = { ...DEFAULT_CONFIG, ...cfg };
-  const errs = configFieldErrors(merged);
+  // 文件已经存在就必须自己声明 roots；这里绝不补默认值。默认扫描范围只
+  // 属于首次 install 或明确的安装修复，读取配置时补上会静默扩大巡检范围。
+  const errs = configFieldErrors(cfg);
   if (errs.length > 0) {
     fail(`配置字段类型不对：${errs.map(([, m]) => m).join('；')}`
       + `；修复 ${file} 或重跑 cron-up install`);
   }
-  return { roots: normalizeRoots(merged.roots) };
+  return { roots: normalizeRoots(cfg.roots) };
 }
 
 // ---- state.json：两级嵌套 {ws: {taskId: entry}} ----
@@ -115,9 +113,9 @@ export function loadConfig(file, opts = {}) {
 // deadSince、log、notified。pid 为 null 的条目是「当场没拉起/冷却中」的
 // 合法形态；未认亲时 claude* 三字段缺省。
 
-// 旧版顶层标记字段：旧 state 是 {ws: entry}，新 state 是 {ws: {taskId:
-// entry}}。taskId 只可能是 8 位十六进制或 anon: 前缀，永不与这些名字冲
-// 突，因此「顶层值自身是否带 entry 标记」就是两代形状的区分判据。
+// 旧版顶层标记字段只用于识别「值仍是标量的扁平 entry」，不能单独拿键名
+// 判代：手工任务 id 也可以叫 pid/startedAt。新桶的自有值里会有任务 entry
+// 对象，旧扁平 entry 的字段值则是标量或 null，先看这个值结构再分代。
 const LEGACY_MARKERS = ['pid', 'startedAt', 'cooldownUntil', 'fails'];
 
 function cleanEntry(raw, ws, taskId) {
@@ -153,8 +151,13 @@ function cleanEntry(raw, ws, taskId) {
   return ent;
 }
 
+function hasNestedEntries(v) {
+  return isPlainObject(v) && Object.values(v).some(isPlainObject);
+}
+
 function looksLegacyEntry(v) {
-  return isPlainObject(v) && LEGACY_MARKERS.some((k) => k in v);
+  return isPlainObject(v) && !hasNestedEntries(v)
+    && LEGACY_MARKERS.some((k) => Object.hasOwn(v, k));
 }
 
 export function loadState() {
@@ -181,7 +184,7 @@ export function loadState() {
 
 // 旧版扁平 state（{ws: 目录级单 entry}）：升级轮用它停掉旧预热后整体丢
 // 弃，不迁移任务归属（新流程按任务重拉）。与 loadState 读同一个文件，
-// 两个读取器按标记字段互斥，互不污染。
+// 两个读取器按值结构与标记字段互斥，互不污染。
 export function loadLegacyEntries() {
   let state;
   try {

package/src/constants.mjs

@@ -1,11 +1,11 @@
 // 全部调参常量集中一处，改动时便于通盘核对。
 
-// 配置文件只有 roots 一个字段：巡检间隔、提前量、扫描深度、续期、改 id、
-// 任务归属盖印都是不可关闭的唯一行为（见 README），常量化在本文件。
+// 配置文件只有 roots 一个字段：巡检间隔、提前量、扫描深度、续期与任务归属
+// 盖印都是不可关闭的唯一行为（见 README），常量化在本文件。
 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,
@@ -91,14 +89,6 @@ export const CC_JITTER = {
   oneShotMinuteMod: 30,
 };
 
-// autoMinId 改小 id 的目标投递延迟上界。周期延迟 = hash(id)·frac·周期，
-// 按每日周期（86400000ms，周期最短、要求最严）反解 id 数值上界：
-//   maxN = floor(目标延迟 / (frac·每日ms) · 2^32) ≈ 5_965_232 (0x005b05b0)
-// id 数值不超过它的每日任务延迟 ≤ 60 秒；周/月任务周期更长，同阈值下延迟
-// 更小。改小逻辑（src/tasks.mjs 的 minifyIds）从这里与 CC_JITTER 现算
-// maxN，常量只保留「目标延迟」这一个可调项。
-export const AUTO_MIN_ID_TARGET_DELAY_MS = 60 * 1000;
-
 // 投递尾窗判定的回看/前探窗口（wanted 与 nextDelivery 共用，见
 // src/cron.mjs 的 recurringTailWindow）：找上一落点用 prevAtOrBefore、算
 // 周期用 nextAfter，两个方向都要罩住月/年任务之外的 2 月 29 日——相邻落