cron-up 26.10.24 → 26.10.26

package/README.md

@@ -184,6 +184,7 @@ cron-up spawn 的预热会话进程环境里带 `CRON_UP_SESSION=1`（值严格
 - 仅支持 macOS。电脑休眠期间错过的周期任务不会补执行；唤醒后 launchd 会立即跑一轮巡检，错过的**一次性**任务会在后台会话启动时由 Claude Code 补执行。
 - Claude Code 的周期任务本会在创建满 7 天后失效；cron-up 默认已通过给任务补 `permanent` 字段自动续期，仅在关闭 autoRenew 后才需要按「使用定时任务时的三个约定」手动续签。`permanent` 是未公开字段，若新版 Claude Code 改变其语义需重新核对（见开头 WARNING）。
 - autoMinId 改小 id 依赖逆向出来的投递哈希算法（见「投递抖动」），不是官方承诺的接口：新版 Claude Code 若更换算法，小 id 不再能保证准点——届时关掉 autoMinId、改用「cron 往前提 30 分钟」即可，`list` 的预计时间与 findings 的验算脚本可用来发现这种漂移。此外在交互会话里用 `CronCreate` 重建任务会生成新的随机大 id（需等下轮巡检再改回），改时间请直接编辑 cron 字段而不是重建。
+- autoMinId 改写 id 的当轮起，巡检按新 id（投递延迟不足 1 分钟）计算投递尾窗，而**已在运行的会话仍按旧 id 投递**（顶格约 30 分钟后）：若保活会话恰在「新投递时刻 ~ 旧投递时刻」这最长约 29 分钟的空隙里死亡，该次投递漏跑（周期任务无补执行），下个周期恢复。window 模式下会话执行完即回收、重拉的新会话读到新 id，风险窗口至多覆盖一次执行；always 模式则持续到 7 天换代。在意的话，等一轮执行完（会话已重拉）再跑 `cron-up renew` 可完全避开。
 - 默认 `sessionRetain: "window"` 下，周期任务的每次触发各自使用新拉起的会话（触发完毕即回收、下次窗口重拉）；**时间上重叠或紧邻的任务仍会共享同一会话**——任务路由由 Claude Code 决定，无法做到「每个任务专属一个并发会话」，同目录多会话还有重复执行的风险。`sessionRetain: "always"` 恢复常驻：同一周期内每次触发都追加进同一条会话记录，上下文随时间累积（反复 compact、每轮执行都携带全部历史），每个有周期任务的工作区也因此常驻一个 claude 进程。真正的并发任务级隔离需要 Claude Code 官方支持任务路由。
 - 手写的任务文件若缺 `createdAt` 字段，错过补执行的判定不生效：错过的一次性任务不会被预热补救，`list` 也不显示「已错过」。`CronCreate` 创建的任务始终带该字段，不受影响。
 - 工作区从巡检视野里消失（`.claude/scheduled_tasks.json` 被整个删除，或目录被移出 `roots`）后，cron-up 不再巡检它：其中仍在运行的保活会话不会被回收或换代，会一直驻留到进程自己退出。无参数 `cron-up` 的「需要留意」会列出这类会话，不需要时请手动结束对应进程（`kill <pid>`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cron-up",
-  "version": "26.10.24",
+  "version": "26.10.26",
   "description": "为命令行 AI agent 的 cron 定时任务提前预热并保活交互式会话",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -4,7 +4,7 @@
 
 // 先引全量入口，保证所有业务模块都已向 deps 自注册，再引命令函数。
 import './index.mjs';
-import { deps, ExitError } from './internals.mjs';
+import { deps, ExitError, isDecInt } from './internals.mjs';
 import { cmdRun, cmdRenew } from './patrol.mjs';
 import { cmdInstall, cmdUninstall } from './service.mjs';
 import { cmdList } from './list.mjs';
@@ -40,10 +40,10 @@ const SPECS = {
   },
 };
 
-// 严格十进制整数命令行值：Number("0x10")、parseInt("5x") 都会静默给出错
-// 误结果，必须显式拒绝。
+// 严格十进制整数命令行值（谓词 isDecInt 见 internals）：
+// Number("0x10")、parseInt("5x") 都会静默给出错误结果，必须显式拒绝。
 function cliInt(s) {
-  if (!/^-?\d+$/.test(s)) {
+  if (!isDecInt(s)) {
     throw new ExitError(2, `需要整数却得到：${s}`);
   }
   return parseInt(s, 10);
@@ -157,7 +157,7 @@ export function parseCli(argv) {
   return result;
 }
 
-export const USAGE = `cron-up —— 为定时任务提前备好交互会话
+const USAGE = `cron-up —— 为定时任务提前备好交互会话
 
 用法：
   cron-up                    查看总览（服务、配置、任务、会话）

package/src/config.mjs

@@ -4,9 +4,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps, ExitError } from './internals.mjs';
-import { DEFAULT_CONFIG, PID_T_MAX } from './constants.mjs';
-import { expandHome } from './tasks.mjs';
+import { deps, ExitError, isPlainObject, isDecInt } from './internals.mjs';
+import { DEFAULT_CONFIG, PID_T_MAX, HEARTBEAT_STALE_FACTOR } from './constants.mjs';
+import { expandHome, isDir } from './tasks.mjs';
 
 // Shell 的 tilde 展开只发生在词首："--roots ~/a,~/b" 穿过 shell 后第二个
 // 条目前的 ~ 还在。读和写两边都规范化，配置里永远存绝对路径。
@@ -22,10 +22,6 @@ export function normalizeRoots(roots) {
   return out;
 }
 
-function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-
 // 配置数值校验用：JSON 的 true 是布尔不能冒充秒数/深度
 // （Number.isInteger(true) === false，天然挡住）。
 export function isInt(x) {
@@ -41,12 +37,25 @@ export function lenientInt(v) {
     if (!Number.isFinite(v)) throw new Error('数值越界');
     return Math.trunc(v); // 1.5 → 1
   }
-  if (typeof v === 'string' && /^-?\d+$/.test(v.trim())) {
+  if (typeof v === 'string' && isDecInt(v.trim())) {
     return parseInt(v.trim(), 10);
   }
   throw new Error(`无法整型化：${String(v)}`);
 }
 
+// pid 清洗：宽容解析后卡 pid_t 值域，不合法返回 null。state.json 与会话
+// 登记两个外部来源共用同一条入口规则——超大整数能穿过类型转换直到
+// process.kill 才抛，负数 pid 会被 kill 当成进程组号误伤无辜进程组。
+export function parsePid(v) {
+  let pid;
+  try {
+    pid = lenientInt(v);
+  } catch {
+    return null;
+  }
+  return pid > 0 && pid <= PID_T_MAX ? pid : null;
+}
+
 // 配置字段的类型规则，loadConfig 与 install --force 继承旧配置共用。返回
 // [字段名, 人话错误][]：手改把字段写坏时绝不静默回退——回退的两个可能方向
 // （roots 坏 → 回扫整个家目录、autoRenew 坏 → 回开续期）都比停机更危险。
@@ -136,13 +145,7 @@ export function loadState() {
   for (const [ws, raw] of Object.entries(state)) {
     if (!isPlainObject(raw)) continue;
     const ent = { ...raw };
-    let pid = null;
-    try {
-      pid = lenientInt(ent.pid);
-    } catch {
-      pid = null;
-    }
-    ent.pid = pid && pid > 0 && pid <= PID_T_MAX ? pid : null;
+    ent.pid = parsePid(ent.pid);
     for (const k of ['startedAt', 'cooldownUntil', 'fails', 'deadSince']) {
       if (ent[k] !== null && ent[k] !== undefined) {
         try {
@@ -205,6 +208,12 @@ export function saveHeartbeat(doc) {
   atomicSave(deps.paths.heartbeatPath, doc);
 }
 
+// 心跳是否已沉默超过 HEARTBEAT_STALE_FACTOR 个轮次间隔：轮首的漏轮提示与
+// 总览页的「服务在但巡检没在跑」共用同一判据，两边不会各说各话。
+export function heartbeatStale(hb, intervalSeconds, nowSec) {
+  return hb !== null && nowSec - hb.ranAt > intervalSeconds * HEARTBEAT_STALE_FACTOR;
+}
+
 export function saveConfig(cfg) {
   atomicSave(deps.paths.configPath, cfg);
 }
@@ -224,13 +233,7 @@ export function validateConfig(cfg, announce = () => {}) {
       + '两轮巡检之间到期而来不及提前启动会话，建议 lead ≥ interval');
   }
   for (const root of cfg.roots ?? []) {
-    let dir = false;
-    try {
-      dir = fs.statSync(root).isDirectory();
-    } catch {
-      dir = false;
-    }
-    if (!dir) warnings.push(`扫描目录不存在，巡检不会覆盖它：${root}`);
+    if (!isDir(root)) warnings.push(`扫描目录不存在，巡检不会覆盖它：${root}`);
   }
   for (const w of warnings) announce(`警告：${w}`);
   return warnings;

package/src/constants.mjs

@@ -36,8 +36,9 @@ export const COOLDOWN_SECONDS = 1800;
 // 稠密任务生效。保留 48 小时让稀疏任务跨窗口累积；老化防止陈年计数误伤
 // 已修好的环境。
 export const FAIL_TTL_SECONDS = 48 * 3600;
-// pid 合法值域。state.json 与会话登记两个外部来源都在入口处按它校验：
-// 超大整数能穿过类型转换，直到 process.kill 才抛，所以必须入口卡范围。
+// pid 合法值域。state.json 与会话登记两个外部来源的 pid 都在入口处
+// （config 的 parsePid）按它统一校验：超大整数能穿过类型转换，直到
+// process.kill 才抛，所以必须入口卡范围。
 export const PID_T_MAX = 2 ** 31 - 1;
 // 健康会话约 10 秒内完成登记。超时仍存活却没登记，是卡在无人应答的提问
 // 界面（目录信任、工具授权）；只看存活会把它当健康，只有这个时限兜得住。
@@ -48,9 +49,10 @@ export const WARMUP_GRACE_SECONDS = 180;
 export const SESSION_MAX_AGE_SECONDS = 7 * 86400;
 export const SESSION_IDLE_SECONDS = 3600;
 // window 模式回收判据一：界面静默超过此时长视为「本次执行已结束」。TUI
-// 工作时持续渲染（毫秒级刷新 typescript），静默 3 分钟不可能是在执行；与
-// WARMUP_GRACE 同值，对齐「3 分钟定生死」的既有心智。
-export const SESSION_RECYCLE_IDLE_SECONDS = 180;
+// 工作时持续渲染（毫秒级刷新 typescript），静默 3 分钟不可能是在执行；取
+// WARMUP_GRACE 同值，结构上对齐「3 分钟定生死」的既有心智（调一个跟着
+// 动）。
+export const SESSION_RECYCLE_IDLE_SECONDS = WARMUP_GRACE_SECONDS;
 // window 模式回收判据二：距下次「需要会话在场」的时刻至少还有这么多秒。
 // 回收后同轮重拉的新会话约 10 秒完成登记，余量保的是登记抖动；更近的触
 // 发直接复用现有会话（时间紧邻的任务共享）。
@@ -98,11 +100,16 @@ export const CC_JITTER = {
 // maxN，常量只保留「目标延迟」这一个可调项。
 export const AUTO_MIN_ID_TARGET_DELAY_MS = 60 * 1000;
 
+// 投递尾窗判定的回看/前探窗口（wanted 与 predictedFire 共用，见
+// src/cron.mjs 的 recurringTailWindow）：找上一落点用 prevAtOrBefore、算
+// 周期用 nextAfter，两个方向都要罩住月/年任务之外的 2 月 29 日——相邻落
+// 点隔 4 年，世纪非闰年（2100）隔 8 年；窗口小了尾窗会塌缩成零：落点已
+// 过、投递未到，死亡却不重拉。日历快进按月跳，十年窗口也只有百余次迭代。
+export const TAIL_WINDOW_DAYS = 366 * 10 + 1;
+
 // 定时任务 7 天过期（周期任务被调度器删除，一次性任务早就触发过），巡检
 // 不需要看得更远。展示页另算。
 export const SEARCH_DAYS = 7;
 // list/总览回答「下次何时触发」，要看到一年后：年度任务必须显示真实日期，
 // 不能误报成「无安排」。nextAfter 的日历快进让长窗口依然便宜。
 export const DISPLAY_SEARCH_DAYS = 366;
-// list 问「一次性任务是否被错过」，与巡检同一个补执行判定，只是不带前瞻。
-export const ZERO_LEAD_MS = 0;

package/src/cron.mjs

@@ -1,15 +1,21 @@
 // 分钟级 cron 解析与下一次触发计算。字段全是别的程序写的，畸形表达式在
 // 边界处返回 null/不可满足，绝不抛进巡检循环。
 
-import { SEARCH_DAYS, DISPLAY_SEARCH_DAYS, CC_JITTER } from './constants.mjs';
+import {
+  SEARCH_DAYS,
+  DISPLAY_SEARCH_DAYS,
+  CC_JITTER,
+  TAIL_WINDOW_DAYS,
+} from './constants.mjs';
+import { isDecInt } from './internals.mjs';
 
 const MS_DAY = 86400_000;
 const MS_MINUTE = 60_000;
 
-// 严格十进制整数：parseInt("5x") 会静默返回 5，必须自己卡。仅接受可选负号
-// 加纯数字。
+// 严格十进制整数（isDecInt 的谓词见 internals）：parseInt("5x") 会静默返回
+// 5，必须自己卡。
 function strictInt(s) {
-  if (!/^-?\d+$/.test(s)) throw new Error(`不是整数：${s}`);
+  if (!isDecInt(s)) throw new Error(`不是整数：${s}`);
   return parseInt(s, 10);
 }
 
@@ -24,8 +30,12 @@ export function parseCronField(expr, lo, hi) {
     const slash = token.indexOf('/');
     if (slash >= 0) {
       rng = token.slice(0, slash);
-      step = strictInt(token.slice(slash + 1)); // "/0" 必须抛：步进 0 会死循环
-      if (step === 0) throw new Error('cron 步进不能为 0');
+      step = strictInt(token.slice(slash + 1));
+      // 步进必须显式卡正数：strictInt 接受负号，0 让步进循环原地打转、
+      // 负数让 v+=step 递减、v<=end 恒真——两者都是永不退出的死循环，
+      // 而一个含 "/-5" 的任务文件就能挂死整轮巡检。拒绝后由
+      // parseCronOrNone 读作「cron 无效」。
+      if (!(step > 0)) throw new Error('cron 步进必须是正整数');
     } else {
       rng = token;
       step = 1;
@@ -117,7 +127,7 @@ export class Cron {
   // 不晚于 t 所在分钟的最近一次匹配（含当前分钟）；withinDays 天前还没有
   // 则 null。与 nextAfter 对称做整月/整小时快进，366 天窗口也便宜。用于
   // 判断「现在是否落在某次触发的投递延迟尾窗里」。
-  prevAtOrBefore(t, withinDays = SEARCH_DAYS) {
+  prevAtOrBefore(t, withinDays) {
     if (!this.satisfiable) return null;
     const cur = new Date(t.getTime());
     cur.setSeconds(0, 0);
@@ -153,7 +163,7 @@ export class Cron {
 
 // CronCreate 产生的一次性任务形状像 'M H DoM Mon *'，作为没有 recurring
 // 标志时的兜底识别法。
-export function cronLooksOneshot(expr) {
+function cronLooksOneshot(expr) {
   const parts = expr.split(/\s+/);
   return parts.length === 5 && parts[4] === '*'
     && parts.slice(0, 4).every((p) => /^\d+$/.test(p));
@@ -203,21 +213,14 @@ function wanted(cron, task, now, leadMs) {
       new Date(created.getTime() - MS_MINUTE),
       span,
     );
-    if (first && first.getTime() <= now.getTime()) return true;
-    return false;
+    return first !== null && first.getTime() <= now.getTime();
   }
   // 周期任务：投递不是在落点，而是落点 + 按 id 确定的抖动（每日任务通常
   // 30 分）。落点已过、抖动投递时刻未到的这段「投递尾窗」里会话仍必须在
   // 场——否则 window 模式会把执行完近邻任务后空闲下来的会话回收且不重
-  // 拉，让本次触发漏跑（周期任务没有补执行）。找上一落点用 366 天窗口，
-  // 覆盖月/年任务；prevAtOrBefore 有日历快进，不贵。
-  const prev = cron.prevAtOrBefore(now, DISPLAY_SEARCH_DAYS);
-  if (prev !== null) {
-    const fireAt = prev.getTime()
-      + recurringDelayMs(cron, prev, task.id, DISPLAY_SEARCH_DAYS + 1);
-    if (now.getTime() < fireAt) return true;
-  }
-  return false;
+  // 拉，让本次触发漏跑（周期任务没有补执行）。机制与窗口口径见
+  // recurringTailWindow。
+  return recurringTailWindow(cron, task.id, now) !== null;
 }
 
 // 任务是否需要已预热的会话。任务字段全是别的程序写的，畸形条目读作「不
@@ -241,38 +244,60 @@ export function taskIdHash(taskId) {
   return Number.isFinite(n) ? n : 0;
 }
 
-// 任务按 Claude Code 的抖动规则预计的实际触发时刻；cron 无效、不可满足或
-// 窗口内没有落点时返回 null。基准为 now（上游调度器以上次触发时刻为基
-// 准，展示只关心从现在起的下一次，两者算出的落点一致）。
-export function predictedFire(task, now, withinDays = DISPLAY_SEARCH_DAYS) {
-  const cron = parseCronOrNone(task?.cron);
-  if (cron === null || !cron.satisfiable) return null;
-  const i = cron.nextAfter(now, withinDays);
-  if (i === null) return null;
-  const h = taskIdHash(task?.id);
-
+// 任务在展示语境里的「落点 → 预计实际投递」对：一次性任务是落点加网格
+// 提前量；周期任务在投递尾窗内属于上一落点（即将到来的这次延迟投递，
+// 不是 nextAfter 给出的下个落点——后者严格在未来，会把展示拐到明天），
+// 否则是下一落点 + 按 id 的抖动。先于窗口检查尾窗：2 月 29 日这类长周期
+// 任务的下一落点可能在展示窗口之外，正在等待的投递却依然成立。taskView
+// 的 nxt/fire 与 predictedFire 共用这一个口径，落点与投递同源，两边不会
+// 各说各话。返回 {slot, fire}，均为 Date 或 null（窗口内没有落点时双双
+// 为 null）。cron 须已解析且 satisfiable。
+export function nextDelivery(cron, task, now, withinDays = DISPLAY_SEARCH_DAYS) {
   if (taskIsOneshot(task)) {
+    const slot = cron.nextAfter(now, withinDays);
+    if (slot === null) return { slot: null, fire: null };
     // 复刻 Wsn()：只有落点分钟落在 :00/:30 网格上才提前一个按哈希缩放的
     // 小量（0~90 秒），其余分钟整点不抖；提前量不越过 now。
-    if (i.getMinutes() % CC_JITTER.oneShotMinuteMod !== 0) return i;
+    if (slot.getMinutes() % CC_JITTER.oneShotMinuteMod !== 0) {
+      return { slot, fire: slot };
+    }
+    const h = taskIdHash(task?.id);
     const ahead = CC_JITTER.oneShotFloorMs
       + h * (CC_JITTER.oneShotMaxMs - CC_JITTER.oneShotFloorMs);
-    return new Date(Math.max(i.getTime() - ahead, now.getTime()));
+    return { slot, fire: new Date(Math.max(slot.getTime() - ahead, now.getTime())) };
   }
 
+  const tail = recurringTailWindow(cron, task?.id, now);
+  if (tail !== null) return { slot: tail[0], fire: new Date(tail[1]) };
+
+  const slot = cron.nextAfter(now, withinDays);
+  if (slot === null) return { slot: null, fire: null };
   // 复刻 bOt()：抖动按「本落点到下一落点」的周期比例缩放并封顶。nextAfter
   // 语义是严格晚于入参（内部进位一分钟），传 slot 本身即取下一落点；窗口
   // 边缘取不到时与上游一致：视为无后续，不抖动。
-  return new Date(i.getTime() + recurringDelayMs(cron, i, task?.id, withinDays));
+  return {
+    slot,
+    fire: new Date(slot.getTime() + recurringDelayMs(cron, slot, task?.id, withinDays)),
+  };
   // 注：上游 bOt 另有一个 cacheLeadMs 分支——仅当相邻落点间隔落在
   // [300000, 315000)ms（约 5 分钟周期的高频 cron，如 */5）且表达式匹配
   // 其内部步进正则时，调度时刻提前 15 秒。日/周/月任务周期远大于此，不
   // 经过该分支，故不予复刻。
 }
 
+// 任务按 Claude Code 的抖动规则预计的实际触发时刻（nextDelivery 的
+// fire）；cron 无效、不在尾窗内、窗口内没有落点时返回 null。基准为 now
+// （上游调度器以上次触发时刻为基准，展示只关心从现在起的下一次，两者算
+// 出的落点一致）。
+export function predictedFire(task, now, withinDays = DISPLAY_SEARCH_DAYS) {
+  const cron = parseCronOrNone(task?.cron);
+  if (cron === null || !cron.satisfiable) return null;
+  return nextDelivery(cron, task, now, withinDays).fire;
+}
+
 // 周期任务从某个落点起的投递延迟（ms）：hash(id)·frac·周期，封顶 30 分。
 // slot 后取不到下一落点（窗口边缘、不可满足）时返回 0。
-export function recurringDelayMs(cron, slot, taskId, withinDays = SEARCH_DAYS) {
+function recurringDelayMs(cron, slot, taskId, withinDays) {
   const next = cron.nextAfter(new Date(slot.getTime()), withinDays);
   if (next === null) return 0;
   const period = next.getTime() - slot.getTime();
@@ -281,3 +306,16 @@ export function recurringDelayMs(cron, slot, taskId, withinDays = SEARCH_DAYS) {
     CC_JITTER.recurringCapMs,
   );
 }
+
+// 周期任务的「投递尾窗」判定：上一落点已过、按 id 算的延迟投递时刻未
+// 到。返回 [落点, 投递时刻 ms]；不在尾窗、找不到上一或下一落点返回
+// null。wanted（保活判定）与 nextDelivery（展示）共用这一口径，两边不会
+// 各说各话；窗口取 TAIL_WINDOW_DAYS，理由见 constants。
+function recurringTailWindow(cron, taskId, now) {
+  const prev = cron.prevAtOrBefore(now, TAIL_WINDOW_DAYS);
+  if (prev === null) return null;
+  const fireMs = prev.getTime()
+    + recurringDelayMs(cron, prev, taskId, TAIL_WINDOW_DAYS);
+  if (now.getTime() >= fireMs) return null;
+  return [prev, fireMs];
+}

package/src/display.mjs

@@ -4,9 +4,8 @@ import {
   parseCronOrNone,
   taskIsOneshot,
   wanted,
-  predictedFire,
+  nextDelivery,
 } from './cron.mjs';
-import { DISPLAY_SEARCH_DAYS, ZERO_LEAD_MS } from './constants.mjs';
 
 // 等宽终端里的宽字符区间（CJK 文字、全角标点、谚文、常用 emoji）：启发式
 // 只覆盖任务摘要里真实出现的形态，区间外一律按 1 列——判错的代价仅是对
@@ -63,7 +62,7 @@ export function humanDelta(ms) {
 
 // list/总览上代表任务身份的一句话：prompt 的首个非空行。真实任务第一行
 // 通常自带标题；取不到时如实标注，不留空白格。
-export function taskSummary(task) {
+function taskSummary(task) {
   const prompt = task?.prompt;
   if (typeof prompt !== 'string' || !prompt.trim()) return '（无任务描述）';
   const first = prompt.split('\n').map((l) => l.trim()).find((l) => l) ?? '';
@@ -73,7 +72,7 @@ export function taskSummary(task) {
 // 把一个任务整理成展示数据。字段来自别的程序写的文件，畸形也不抛。
 // 传 leadMs 时顺带在同一个已解析 cron 上回答「现在是否需要预热会话」
 // （wanted），总览页就不必为同一任务再解析一遍 cron。
-export function taskView(task, now, leadMs = undefined) {
+export function taskView(task, now, leadMs) {
   const expr = task?.cron;
   const cron = parseCronOrNone(expr);
   if (cron === null || !cron.satisfiable) {
@@ -89,24 +88,31 @@ export function taskView(task, now, leadMs = undefined) {
       fire: null,
     };
   }
-  const nxt = cron.nextAfter(now, DISPLAY_SEARCH_DAYS);
   const oneshot = taskIsOneshot(task);
-  // nxt 按定义严格晚于 now，「已错过」完全由补执行判定回答。
-  const missed = oneshot && wanted(cron, task, now, ZERO_LEAD_MS);
+  // nxt 按定义不晚于展示语境里的下一次投递，「已错过」完全由补执行判定
+  // 回答：lead 传 0（不带前瞻），与巡检的补执行判定同一口径。
+  const missed = oneshot && wanted(cron, task, now, 0);
+  // 落点与投递由 nextDelivery 同源算出：尾窗内的周期任务即将到来的是上
+  // 一落点的这次延迟投递，箭头才画得出「09:00 → 09:30」，而不是从明天
+  // 的落点拐回来（2 月 29 日任务尾窗内 nextAfter 甚至找不到下一落点）。
+  const { slot, fire } = nextDelivery(cron, task, now);
   return {
     valid: true,
-    nxt,
+    // 已错过的一次性任务没有未来触发：nxt 置 null，否则「一年内无」的判
+    // 断和总览「最近」（fire ?? nxt）会把它当成明年同刻的安排。
+    nxt: missed ? null : slot,
     missed,
     kind: oneshot ? '一次性' : '周期',
     permanent: Boolean(task.permanent) && !oneshot,
-    cadence: typeof expr === 'string' ? expr : String(expr),
+    cadence: String(expr),
     summary: taskSummary(task),
     // wanted 恒为 null 或布尔：没传 leadMs（不问）与 cron 无效（问不了）
     // 都是 null，键的形状不随参数变化。
     wanted: leadMs !== undefined ? wanted(cron, task, now, leadMs) : null,
     // 计入 Claude Code 投递抖动后的预计实际触发时刻；已错过的一次性任务
-    // 没有未来触发，为 null。与 nxt 同为 Date 或 null。
-    fire: missed ? null : predictedFire(task, now),
+    // 没有未来触发，为 null；尾窗内的周期任务是即将到来的这次延迟投递。
+    // 与 nxt 同为 Date 或 null。
+    fire: missed ? null : fire,
   };
 }
 
@@ -121,6 +127,12 @@ function sameMinute(a, b) {
     && a.getMinutes() === b.getMinutes();
 }
 
+// 两位数字补零：时间戳格式的公共零件，巡检日志的时间戳（patrol 的 log）
+// 也复用。
+export function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
 // 「设定落点 → 预计实际触发」文案。抖动四舍五入到秒（调度器秒级轮询）：
 // 同日省略第二个日期；预计值带非零秒时显示 HH:MM:SS（如 05:15:37）；落
 // 在同一分钟（无抖动）则只显示落点，不画无意义的箭头。
@@ -130,25 +142,22 @@ export function fmtFireRange(nxt, fire) {
   }
   const r = new Date(Math.round(fire.getTime() / 1000) * 1000);
   if (sameMinute(nxt, r)) return fmtMDHM(nxt);
-  const p = (n) => String(n).padStart(2, '0');
   const tail = sameDay(nxt, r)
-    ? `${p(r.getHours())}:${p(r.getMinutes())}`
-      + (r.getSeconds() ? `:${p(r.getSeconds())}` : '')
-    : `${fmtMDHM(r)}${r.getSeconds() ? `:${p(r.getSeconds())}` : ''}`;
+    ? `${pad2(r.getHours())}:${pad2(r.getMinutes())}`
+      + (r.getSeconds() ? `:${pad2(r.getSeconds())}` : '')
+    : `${fmtMDHM(r)}${r.getSeconds() ? `:${pad2(r.getSeconds())}` : ''}`;
   return `${fmtMDHM(nxt)} → ${tail}`;
 }
 
 // 仅 HH:MM（总览「（设定 HH:MM）」附注用）。
 export function fmtHM(d) {
-  const p = (n) => String(n).padStart(2, '0');
-  return `${p(d.getHours())}:${p(d.getMinutes())}`;
+  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
 }
 
 // MM-DD HH:MM（任务触发点的统一展示格式）。
 export function fmtMDHM(d) {
-  const p = (n) => String(n).padStart(2, '0');
-  return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:`
-    + `${p(d.getMinutes())}`;
+  return `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} `
+    + `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
 }
 
 // 会话年龄的粗粒度中文：长驻按天计，否则按分钟。

package/src/internals.mjs

@@ -18,6 +18,18 @@ export class ExitError extends Error {
   }
 }
 
+// 外部程序写的 JSON 顶层形状守卫：config/state/任务文件三个入口共用，要收紧
+// （如拒绝类实例）只改这一处。
+export function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// 严格十进制整数（可选负号 + 纯数字）：parseInt("5x")、Number("0x10") 都会
+// 静默给出错误结果，来自外部字符串的整数一律先过这个谓词再 parseInt。
+export function isDecInt(s) {
+  return /^-?\d+$/.test(s);
+}
+
 // 非 0 退出不抛：调用 ps/launchctl 的地方只关心 status 与输出，抛了反而
 // 要在每个调用点 catch。返回 {status, stdout, stderr}。
 function execFile(file, args, opts = {}) {

package/src/logs.mjs

@@ -6,8 +6,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { deps, ExitError } from './internals.mjs';
-import { onDiskCase } from './tasks.mjs';
+import { onDiskCase, lexReal } from './tasks.mjs';
 import { sessionLogPath } from './sessions.mjs';
+import { fmtMDHM } from './display.mjs';
 
 export function resolveLogPath(workspace, announce) {
   const say = announce ?? ((m) => deps.printErr(m));
@@ -15,13 +16,7 @@ export function resolveLogPath(workspace, announce) {
     if (path.isAbsolute(workspace)) {
       // 日志名由工作区路径折成，而 spawn 记的是 discover 规范化后的真实
       // 大小写：敲错大小写的绝对路径必须认回同一个文件。
-      let real;
-      try {
-        real = fs.realpathSync(workspace);
-      } catch {
-        real = workspace;
-      }
-      const file = sessionLogPath(onDiskCase(real));
+      const file = sessionLogPath(onDiskCase(lexReal(workspace)));
       return fs.existsSync(file) ? file : null;
     }
     // 只匹配当前日志（*.log）：.log.1 若参与匹配，轮转过一次的工作区会永
@@ -48,11 +43,8 @@ export function resolveLogPath(workspace, announce) {
   if (!fs.existsSync(out)) return err;
   try {
     if (fs.statSync(err).size > 0) {
-      const mtime = fs.statSync(err).mtime;
-      const p = (n) => String(n).padStart(2, '0');
-      const stamp = `${p(mtime.getMonth() + 1)}-${p(mtime.getDate())} `
-        + `${p(mtime.getHours())}:${p(mtime.getMinutes())}`;
-      say(`注：${err} 有内容（最后写入 ${stamp}），巡检若异常先看它`);
+      say(`注：${err} 有内容（最后写入 ${fmtMDHM(fs.statSync(err).mtime)}），`
+        + '巡检若异常先看它');
     }
   } catch {
     // err 不存在：无事。

package/src/overview.mjs

@@ -11,10 +11,11 @@ import {
   loadState,
   validateConfig,
   loadHeartbeat,
+  heartbeatStale,
 } from './config.mjs';
-import { packageVersion, TASK_REL } from './paths.mjs';
+import { taskFileExists } from './tasks.mjs';
+import { packageVersion } from './paths.mjs';
 import { serviceLine, launcherHealth } from './service.mjs';
-import { HEARTBEAT_STALE_FACTOR } from './constants.mjs';
 import {
   humanDelta,
   clip,
@@ -47,7 +48,7 @@ function overviewTasks(cfg, cols, consumers, state) {
     if (tasks === null) {
       // 与巡检同一条规则：文件还在却读不出，总览页要把它摆进「需要留
       // 意」，而不是装作这个工作区不存在。
-      if (fs.existsSync(path.join(ws, TASK_REL))) {
+      if (taskFileExists(ws)) {
         alerts.push(`${ws} 的任务文件读不出：其中的定时任务一个都不会执行`);
       }
       continue;
@@ -94,7 +95,7 @@ function overviewTasks(cfg, cols, consumers, state) {
         // 失败计数放在句子中部：总览告警按终端宽度截尾，计数比尾部的
         // 「下轮会自动启动」更该活下来；满额后的去向由「冷却中」那条合并
         // 告警解释，这里不重复。
-        const fails = (state[ws] ?? {}).fails ?? 0;
+        const fails = ent.fails ?? 0;
         const streak = fails > 0 ? `，近期已失败 ${fails} 次` : '';
         alerts.push(`${ws} 有任务即将执行（或错过待补执行）${streak}，`
           + '但当前没有交互会话，下轮巡检会自动启动');
@@ -124,8 +125,7 @@ function overviewTasks(cfg, cols, consumers, state) {
   return [alerts, coolingWarned, discovered];
 }
 
-function overviewSessions(cols, state, suppressCooling = new Set(),
-  discovered = null) {
+function overviewSessions(cols, state, suppressCooling, discovered) {
   const alerts = [];
   const cur = Math.floor(Date.now() / 1000);
   const live = [];
@@ -243,16 +243,14 @@ export async function cmdOverview(args) {
     // 心跳能戳穿。服务未加载（info 为 null）时不告警，服务行已说明未安装。
     if (heartbeat) {
       deps.print(`上次巡检：${elapsedZh(curOv - heartbeat.ranAt)}前`);
-      if (info
-          && curOv - heartbeat.ranAt
-            > cfg.intervalSeconds * HEARTBEAT_STALE_FACTOR) {
+      if (info && heartbeatStale(heartbeat, cfg.intervalSeconds, curOv)) {
         alerts.push(`巡检已沉默 ${elapsedZh(curOv - heartbeat.ranAt)}：launchd `
           + `显示服务已加载（配置每 ${cfg.intervalSeconds} 秒一轮），但最近没有`
           + '成功跑完的轮次，启动链可能已失效；请运行 cron-up logs 查看巡检'
           + '日志，必要时重跑 cron-up install');
       }
     }
-    alerts.push(...validateConfig(cfg, () => {}));
+    alerts.push(...validateConfig(cfg));
     deps.print('');
     const [taskAlerts, cooled, found] = overviewTasks(cfg, cols, consumers, state);
     alerts.push(...taskAlerts);

package/src/paths.mjs

@@ -12,9 +12,42 @@ const HOME = os.homedir();
 // 被预热的 agent 工作区里，定时任务文件的相对路径。
 export const TASK_REL = path.join('.claude', 'scheduled_tasks.json');
 
+// 派生 getter 只写这一份：生产 paths 与测试重定向用的 tmpPaths
+// （test-support/helpers.mjs）共用同一工厂，派生路径改布局不会出现两处各
+// 改一半。
+export function makePaths({ home, dataDir, logDir, plistPath, sessionDir }) {
+  return {
+    home,
+    dataDir,
+    logDir,
+    plistPath,
+    sessionDir,
+
+    get sessionLogDir() {
+      return path.join(this.logDir, 'sessions');
+    },
+    get configPath() {
+      return path.join(this.dataDir, 'config.json');
+    },
+    get statePath() {
+      return path.join(this.dataDir, 'state.json');
+    },
+    // 巡检心跳：每轮成功跑完写一次，总览页据此判断上次巡检多久前。
+    get heartbeatPath() {
+      return path.join(this.dataDir, 'heartbeat');
+    },
+    // launchd 拉起的启动脚本。ProgramArguments[0] 直接指向它而非 node：
+    // macOS 后台项目列表按可执行文件名显示条目，直连 node 会归到「Node.js
+    // Foundation」名下（node 的签名者），自有脚本则显示脚本自己的名字。
+    get serviceScriptPath() {
+      return path.join(this.dataDir, 'cron-up-service');
+    },
+  };
+}
+
 // 路径对象整体可替换（deps.paths）：测试把产物目录重定向到 tmp，不碰真实
 // HOME。getter 让 sessionLogDir/configPath/statePath 跟随替换后的前缀。
-export const paths = {
+export const paths = makePaths({
   home: HOME,
   // 数据目录用 XDG 风格的 ~/.local/share/cron-up：config、state 与启动脚本
   // 集中一处，purge 一删全清。
@@ -22,27 +55,7 @@ export const paths = {
   logDir: path.join(HOME, 'Library', 'Logs', 'cron-up'),
   plistPath: path.join(HOME, 'Library', 'LaunchAgents', `${LABEL}.plist`),
   sessionDir: path.join(HOME, '.claude', 'sessions'),
-
-  get sessionLogDir() {
-    return path.join(this.logDir, 'sessions');
-  },
-  get configPath() {
-    return path.join(this.dataDir, 'config.json');
-  },
-  get statePath() {
-    return path.join(this.dataDir, 'state.json');
-  },
-  // 巡检心跳：每轮成功跑完写一次，总览页据此判断上次巡检多久前。
-  get heartbeatPath() {
-    return path.join(this.dataDir, 'heartbeat');
-  },
-  // launchd 拉起的启动脚本。ProgramArguments[0] 直接指向它而非 node：
-  // macOS 后台项目列表按可执行文件名显示条目，直连 node 会归到「Node.js
-  // Foundation」名下（node 的签名者），自有脚本则显示脚本自己的名字。
-  get serviceScriptPath() {
-    return path.join(this.dataDir, 'cron-up-service');
-  },
-};
+});
 
 // 版本号读 package.json（用 fs 读而非 JSON import attribute，避免对 Node
 // 版本实验特性的依赖）；读不到返回 null，总览页降级显示。

package/src/patrol.mjs

@@ -24,16 +24,22 @@ import {
   saveState,
   loadHeartbeat,
   saveHeartbeat,
+  heartbeatStale,
 } from './config.mjs';
-import { maintainWorkspace, TaskFileChanged } from './tasks.mjs';
+import {
+  maintainWorkspace,
+  TaskFileChanged,
+  taskFileExists,
+} from './tasks.mjs';
 import { taskWanted, parseCronOrNone, wanted } from './cron.mjs';
 import {
   sessionLogPath,
   sessionLogIdleSeconds,
   scriptProcLogPath,
+  rotateOnce,
 } from './sessions.mjs';
 import { TASK_REL, packageVersion } from './paths.mjs';
-import { elapsedZh } from './display.mjs';
+import { elapsedZh, pad2 } from './display.mjs';
 
 // 事件类型 → 轮末汇总里的中文标签。patrolWorkspace 与 cmdRun 往同一个
 // stats 计数器里记账，平静轮也会打出「本轮无动作」。
@@ -56,10 +62,9 @@ function bump(stats, kind) {
 
 export function log(msg) {
   const d = new Date();
-  const p = (n) => String(n).padStart(2, '0');
   deps.print(
-    `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} `
-    + `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())} ${msg}`,
+    `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} `
+    + `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())} ${msg}`,
   );
 }
 
@@ -137,15 +142,14 @@ export function releaseLock(handle) {
 
 export function rotatePatrolLogs() {
   // launchd 按路径每次重开文件，轮初改名是安全的：本轮 fd 继续写改名后
-  // 的 inode，下轮打开新文件。
+  // 的 inode，下轮打开新文件。超阈值才轮转，与会话日志的「无条件保留一
+  // 代」共用 rotateOnce 的 rm+rename 顺序。
   for (const name of ['launchd.out.log', 'launchd.err.log']) {
     const file = path.join(deps.paths.logDir, name);
     try {
       if (fs.existsSync(file)
           && fs.statSync(file).size > PATROL_LOG_ROTATE_BYTES) {
-        const old = `${file}.1`;
-        fs.rmSync(old, { force: true });
-        fs.renameSync(file, old);
+        rotateOnce(file);
       }
     } catch {
       // 轮转失败不阻断巡检。
@@ -168,9 +172,11 @@ function needHorizonMs(tasks, now) {
 }
 
 // 保证一个工作区里有一个健康的消费者会话。原地修改 state。retain 来自
-// cfg.sessionRetain，直接调用（测试）默认 'always' 保持旧语义。
+// cfg.sessionRetain，直接调用（测试）默认 'always' 保持旧语义。scriptProcs
+// 是进程表快照或 null：null 时仅在需要认领孤儿（state 丢失的兜底分支）当
+// 下才拍快照，平静轮不付全量 ps 的代价。
 export async function patrolWorkspace(
-  ws, state, now, leadMs, cur, consumers, scriptProcs = [],
+  ws, state, now, leadMs, cur, consumers, scriptProcs = null,
   retain = 'always', stats = null,
 ) {
   const tasks = deps.readTasks(ws);
@@ -186,7 +192,7 @@ export async function patrolWorkspace(
     // 任务文件读不出：证据太弱，绝不动会话；但不能不吭声——文件还在却读
     // 不出意味着这个目录的定时任务一个都不会执行。文件已消失则是正常竞
     // 态（一次性任务执行完被删），不报。
-    if (fs.existsSync(path.join(ws, TASK_REL))) {
+    if (taskFileExists(ws)) {
       note('warn', `任务文件读不出 ${ws}：格式损坏或不可读，本轮跳过该目录，`
         + `其中 ${TASK_REL} 里的定时任务都不会执行`);
     }
@@ -222,8 +228,7 @@ export async function patrolWorkspace(
       mineAlive = false;
       // 消费者快照拍于轮初，被换代的这代可能正是快照里的消费者：重扫一
       // 次，别让陈旧登记挡住下面的重拉。
-      const [fresh] = await deps.scanSessions();
-      consumers = fresh;
+      consumers = (await deps.scanSessions())[0];
     }
   }
 
@@ -252,8 +257,7 @@ export async function patrolWorkspace(
     mineAlive = false;
     // 同上：快照里的消费者可能正是刚结束的这代。用户自己的会话若在场，
     // 重扫依旧看见，不会在同目录双开。
-    const [fresh] = await deps.scanSessions();
-    consumers = fresh;
+    consumers = (await deps.scanSessions())[0];
   }
 
   // 登记成功即健康证据，当场清零失败计数，不等「有任务想要会话」的轮
@@ -263,18 +267,17 @@ export async function patrolWorkspace(
     ent.fails = 0;
   }
 
+  // 任务正在被消费。可能是我们的预热会话（已登记——上面的健康清零已覆
+  // 盖），也可能是用户的交互会话——后者放手：不在这里删死条目，失败计数
+  // 要跨任务窗口存活（用户会话在场不证明 launchd 拉起的环境健康），由轮
+  // 末 kept 过滤统一处理。先于 wanted 判定返回：有消费者在场的平稳态不必
+  // 为整组任务跑一遍 cron 求值。
+  if (consumers.has(ws)) return;
+
   if (!tasks.some((t) => taskWanted(t, now, leadMs))) return;
 
   const cooling = Boolean(ent && (ent.cooldownUntil ?? 0) > cur);
 
-  if (consumers.has(ws)) {
-    // 任务正在被消费。可能是我们的预热会话（已登记——上面的健康清零已覆
-    // 盖），也可能是用户的交互会话——后者放手：不在这里删死条目，失败计数
-    // 要跨任务窗口存活（用户会话在场不证明 launchd 拉起的环境健康），由轮
-    // 末 kept 过滤统一处理。
-    return;
-  }
-
   // 活着但没有消费。健康只在真实启动所需的时间内成立；超时就是卡在无人
   // 应答的提问界面，永不登记——退休它并推进失败计数。
   if (ent !== null && mineAlive) {
@@ -316,7 +319,7 @@ export async function patrolWorkspace(
     // 不会出现在登记里，直接再拉就是同目录双开。认回孤儿，重新纳入正常
     // 生命周期（卡死的 3 分钟后照退休处理）。
     const logPath = sessionLogPath(ws);
-    for (const [procPid, procArgs] of scriptProcs) {
+    for (const [procPid, procArgs] of scriptProcs ?? deps.listScriptProcesses()) {
       // alive 复核：快照拍于本轮开头，可能含着刚被换代/回收杀掉的 pid——
       // 把死人认回来会白记一次失败。
       if (scriptProcLogPath(procArgs) === logPath && deps.alive(procPid)) {
@@ -367,13 +370,22 @@ export async function cmdRun(args) {
     return false;
   }
   // 包一层 stopSession 记下本轮主动结束的 pid：轮末凭它区分「我们回收的」
-  // 与「会话自行退出/被外部杀掉的」，后者以前是无声丢失。finally 还原。
+  // 与「会话自行退出/被外部杀掉的」，后者以前是无声丢失。同样包一层
+  // procStartedAt：同一 pid 的 lstart 一轮内不会变，而轮初分区、各工作区
+  // 的 trackedAlive、轮末复核与 kept 过滤都会查指纹，缓存后每个 pid 只
+  // spawn 一次 ps。finally 一并还原。
   const prevStopSession = deps.stopSession;
   const stoppedPids = new Set();
   deps.stopSession = async (ent) => {
     if (ent?.pid) stoppedPids.add(ent.pid);
     return prevStopSession(ent);
   };
+  const prevProcStartedAt = deps.procStartedAt;
+  const lstartCache = new Map();
+  deps.procStartedAt = (pid) => {
+    if (!lstartCache.has(pid)) lstartCache.set(pid, prevProcStartedAt(pid));
+    return lstartCache.get(pid);
+  };
   try {
     const startedAtMs = Date.now();
     const stats = {};
@@ -388,8 +400,7 @@ export async function cmdRun(args) {
     // 时日志会一片寂静，无法和「平安无事」区分。上轮心跳过老说明中间漏
     // 轮——休眠期间错过的 StartInterval，launchd 醒来只补跑一轮。
     const hb = loadHeartbeat();
-    if (hb !== null
-        && cur - hb.ranAt > cfg.intervalSeconds * HEARTBEAT_STALE_FACTOR) {
+    if (heartbeatStale(hb, cfg.intervalSeconds, cur)) {
       bump(stats, 'warn');
       deps.log(`距上次巡检已 ${elapsedZh(cur - hb.ranAt)}，超过 `
         + `${HEARTBEAT_STALE_FACTOR} 个轮次间隔（${cfg.intervalSeconds} 秒），`
@@ -404,27 +415,29 @@ export async function cmdRun(args) {
     }
 
     // 轮初拍一份「上轮末仍相信活着」的会话快照（entry 复制，本轮原地改写
-    // 不影响），分成「轮初已没气」与「轮初还活着」两组。不能只收此刻
+    // 不影响），一遍分成「轮初已没气」与「轮初还活着」两组。不能只收此刻
     // kill -0 成功的——两轮之间崩溃正是最典型的被动死亡，本轮开始时它早
     // 已没气；带 deadSince 的是上轮已报过死亡的旧条目，跳过以免每轮重复报。
-    const prevTracked = Object.entries(state)
-      .filter(([, ent]) => ent.pid && !ent.deadSince)
-      .map(([ws, ent]) => [ws, { ...ent }]);
-    const prevDead = prevTracked.filter(([, ent]) => !deps.trackedAlive(ent));
-    const prevAlive = prevTracked.filter(([, ent]) => deps.trackedAlive(ent));
+    const prevDead = [];
+    const prevAlive = [];
+    for (const [ws, ent] of Object.entries(state)) {
+      if (!ent.pid || ent.deadSince) continue;
+      const copy = [ws, { ...ent }];
+      (deps.trackedAlive(copy[1]) ? prevAlive : prevDead).push(copy);
+    }
     const exitLine = (ws, old) => `会话退出 ${ws} pid=${old.pid}：非巡检主动结束`
       + `（已存活 ${elapsedZh(cur - (old.startedAt ?? cur))}），可能自行退出或`
       + '被外部终止；若反复出现请用 cron-up logs '
       + `${path.basename(ws)} 排查启动过程`;
 
     // 登记每轮只读一次：否则每个工作区都要 readdir + ps 一遍，自检也归
-    // 属这里。
+    // 属这里。进程表快照不在这里拍：只有孤儿认领分支需要，按需现拍（见
+    // patrolWorkspace 的 scriptProcs 形参）。
     const [consumers, registryAlert] = await deps.scanSessions();
     if (registryAlert) {
       bump(stats, 'warn');
       deps.log(`告警：${registryAlert}`);
     }
-    const scriptProcs = deps.listScriptProcesses();
 
     // 轮间死亡在进入工作区循环前先报：随后该工作区若需要会话会打印重拉，
     // 日志时间线就是「退出 → 重拉」，而不是反过来。
@@ -444,7 +457,7 @@ export async function cmdRun(args) {
           const { renewed, minified } = maintainWorkspace(taskfile, {
             renew: cfg.autoRenew,
             minify: cfg.autoMinId,
-          }) ?? { renewed: null, minified: null };
+          }) ?? {};
           if (renewed) {
             deps.log(`已续期 ${ws}：${renewed} 个周期任务标记为 permanent，`
               + '不再受 7 天过期限制');
@@ -467,7 +480,7 @@ export async function cmdRun(args) {
       }
       try {
         await patrolWorkspace(
-          ws, state, now, leadMs, cur, consumers, scriptProcs,
+          ws, state, now, leadMs, cur, consumers, null,
           cfg.sessionRetain, stats);
       } catch (e) {
         bump(stats, 'error');
@@ -525,6 +538,7 @@ export async function cmdRun(args) {
     return true;
   } finally {
     deps.stopSession = prevStopSession;
+    deps.procStartedAt = prevProcStartedAt;
     releaseLock(lock);
   }
 }

package/src/registry.mjs

@@ -7,8 +7,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { deps } from './internals.mjs';
-import { lenientInt } from './config.mjs';
-import { PID_T_MAX } from './constants.mjs';
+import { parsePid } from './config.mjs';
+import { lexReal } from './tasks.mjs';
 
 // npm/bun 形态的 claude 是解释器跑的脚本：进程 comm 是 node/bun/deno，
 // 只能从完整命令行认 claude 入口（bin/claude 符号链接或包目录 cli.js）。
@@ -41,7 +41,7 @@ export function pidIsClaude(pid) {
 // 读一个登记文件；读不出返回 null。Claude Code 会就地（非原子）重写登
 // 记，读写相撞读到半个 JSON 时睡一拍重读一次；文件消失不是竞态，不重
 // 试。
-export async function readSessionFile(file) {
+async function readSessionFile(file) {
   for (let attempt = 0; attempt < 2; attempt++) {
     let text;
     try {
@@ -60,16 +60,6 @@ export async function readSessionFile(file) {
   return null;
 }
 
-// 宽容版 realpath：fs.realpathSync 对不存在的路径抛 ENOENT，这里失败时退
-// 回词法绝对路径（调用方已保证输入是绝对路径）。
-function lexReal(p) {
-  try {
-    return fs.realpathSync(p);
-  } catch {
-    return path.resolve(p);
-  }
-}
-
 // 返回 [拥有活消费者会话的工作区集合, 告警字符串|null]。
 export async function scanSessions() {
   let files = [];
@@ -99,17 +89,11 @@ export async function scanSessions() {
     // 数都读不出活进程。这段代码在 per-workspace 保护圈之外，一个畸形登
     // 记抛出去就是整轮巡检失败；缺失时兜底 -1 还会被 kill(-1,0)（对全
     // 部进程的权限探测，不是存在性检查）误读为存活。
-    let pid;
-    try {
-      pid = lenientInt(s.pid);
-    } catch {
+    const pid = parsePid(s.pid);
+    if (pid === null) {
       suspect += 1; // 正常登记必带可解析 pid：缺失/变质即字段漂移
       continue;
     }
-    if (!(pid > 0 && pid <= PID_T_MAX)) {
-      suspect += 1;
-      continue;
-    }
     if (!deps.alive(pid)) continue; // 陈旧登记（崩溃留下）：正常，不计
     if (!commCache.has(pid)) {
       commCache.set(pid, deps.pidIsClaude(pid)); // ps 调用按 pid 缓存
@@ -120,11 +104,8 @@ export async function scanSessions() {
       // 热被静默跳过。
       const cwd = s.cwd;
       if (typeof cwd === 'string' && path.isAbsolute(cwd)) {
-        const real = lexReal(cwd);
-        if (real) {
-          consumers.add(real);
-          continue;
-        }
+        consumers.add(lexReal(cwd));
+        continue;
       }
       suspect += 1; // 活着的 claude 却没有可用 cwd：cwd 字段漂移
     } else {

package/src/service.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps, ExitError } from './internals.mjs';
+import { deps, ExitError, isPlainObject } from './internals.mjs';
 import { paths, LABEL } from './paths.mjs';
 // paths.home 仅用于 resolveLauncher 的默认 HOME；其余产物路径一律走
 // deps.paths（测试要整体重定向）。
@@ -22,7 +22,7 @@ import {
   configFieldErrors,
 } from './config.mjs';
 
-export function guiTarget() {
+function guiTarget() {
   return `gui/${process.getuid()}`;
 }
 
@@ -51,7 +51,7 @@ const LAUNCHD_STATES = new Map([
   ['not running', '空闲中（按间隔触发）'],
 ]);
 
-export function launchdStateZh(state) {
+function launchdStateZh(state) {
   // launchd 的 "not running" 是间隔触发型服务两轮之间的正常空闲态，直译
   // 会让人以为服务停了；未识别的值原样保留以便排查。
   if (!state) return '未知';
@@ -243,6 +243,17 @@ export function launcherHealth() {
 
 // ---- install / uninstall ----
 
+// install 的可覆盖项（配置键 → 命令行旗标）：--force 缺席时逐项点名「未
+// 生效的参数」，与 SPECS 的选项表保持同一批名字。
+const IGNORED_INSTALL_FLAGS = [
+  ['roots', '--roots'],
+  ['interval', '--interval'],
+  ['lead', '--lead'],
+  ['autoRenew', '--auto-renew'],
+  ['autoMinId', '--auto-min-id'],
+  ['sessionRetain', '--session-retain'],
+];
+
 export async function cmdInstall(args) {
   // --config 在这里只会造成误解：install 写盘、launchd 每轮读取的都是固定
   // 路径的配置，指定别的路径不改变任何行为——静默忽略等于让人以为装到了
@@ -275,13 +286,8 @@ export async function cmdInstall(args) {
     deps.print(`保留现有配置：${deps.paths.configPath}（需要更新时加 --force）`);
     // 不带 --force 时配置原样保留，命令行显式给的参数一律不生效：点名说清
     // 被忽略的是哪些，而不是让用户以为已经改了。
-    const ignored = [];
-    if (args.roots !== undefined) ignored.push('--roots');
-    if (args.interval !== undefined) ignored.push('--interval');
-    if (args.lead !== undefined) ignored.push('--lead');
-    if (args.autoRenew !== undefined) ignored.push('--auto-renew');
-    if (args.autoMinId !== undefined) ignored.push('--auto-min-id');
-    if (args.sessionRetain !== undefined) ignored.push('--session-retain');
+    const ignored = IGNORED_INSTALL_FLAGS
+      .filter(([k]) => args[k] !== undefined).map(([, flag]) => flag);
     if (ignored.length > 0) {
       deps.print(`警告：参数 ${ignored.join('、')} 未生效（现有配置保留）；`
         + '要更新这些字段请带 --force 重跑，--force 只覆盖显式给出的字段');
@@ -296,10 +302,10 @@ export async function cmdInstall(args) {
       try {
         old = JSON.parse(fs.readFileSync(deps.paths.configPath, 'utf-8'));
       } catch {
-        old = null;
+        // 读不出（损坏 JSON）：没有可继承的旧值。
       }
-      // 手改成非对象（123、["a"]）：没有可继承的旧值，静默按默认走。
-      if (old && typeof old === 'object' && !Array.isArray(old)) {
+      // 手改成非对象（123、["a"]）：同样没有可继承的旧值，静默按默认走。
+      if (isPlainObject(old)) {
         // 类型坏的字段不继承（回到默认值）并当面说明，其余照旧——force 不
         // 该把类型错误写进新配置，也不该因一个字段坏了丢掉其余设置。
         const errs = configFieldErrors({ ...DEFAULT_CONFIG, ...old });
@@ -359,8 +365,9 @@ export async function cmdInstall(args) {
   validateConfig(cfg, (m) => deps.print(m));
   if (JSON.stringify(cfg.roots)
       === JSON.stringify(normalizeRoots(DEFAULT_CONFIG.roots))) {
-    // 与 README 安全说明同一句话，在配置落定的这一刻当面再说一遍。
-    deps.print('提示：未指定 --roots，默认扫描 ~/space、~/workspace、~/tasks'
+    // 与 README 安全说明同一句话，在配置落定的这一刻当面再说一遍。默认目
+    // 录清单从 DEFAULT_CONFIG 插值：改默认值时提示不会留在旧清单上。
+    deps.print(`提示：未指定 --roots，默认扫描 ${DEFAULT_CONFIG.roots.join('、')}`
       + '（不存在的目录跳过）；今后 clone 进这些容器的仓库也会进入巡检，'
       + '自动续期会把其中的周期任务永久化。目录布局不同或需收窄时用 '
       + '--roots 指定（见 README 安全说明）');
@@ -406,25 +413,32 @@ export async function cmdUninstall(args) {
   if (r.status === 0) deps.print('已从 launchd 卸载');
 
   // 服务没了就没有回收者：默认结束自己拉起的保活会话，不留以 bypass 权限
-  // 空转的孤儿。--keep-sessions 显式保留（例如马上重装）。
+  // 空转的孤儿。--keep-sessions 显式保留（例如马上重装）。各会话的停轮询
+  // （SIGTERM→等→SIGKILL）互不依赖，先逐个发信号再并行等齐，N 个会话不
+  // 用串行吃 N 轮等待。
   if (!args.keepSessions) {
+    const stopping = [];
+    const handled = new Set();
     for (const [ws, ent] of Object.entries(loadState())) {
       if (deps.trackedAlive(ent)) {
+        handled.add(ent.pid);
         deps.print(`正在结束保活会话 ${ws} pid=${ent.pid}`);
-        await deps.stopSession(ent);
+        stopping.push(deps.stopSession(ent));
       }
     }
     // state 丢失时的兜底：没进登记的孤儿会话（卡在提问界面就不会出现在
     // state 里）从进程表按日志目录精确认领。
     for (const [pid, procArgs] of deps.listScriptProcesses()) {
+      if (handled.has(pid)) continue; // state 循环已发起，别对同 pid 二次发信号
       const log = scriptProcLogPath(procArgs);
       if (log === null
           || !log.startsWith(`${deps.paths.sessionLogDir}${path.sep}`)) continue;
       const ent = { pid, procStart: deps.procStartedAt(pid) };
       if (!deps.trackedAlive(ent)) continue;
       deps.print(`正在结束保活会话（state 已丢失） pid=${pid}`);
-      await deps.stopSession(ent);
+      stopping.push(deps.stopSession(ent));
     }
+    await Promise.all(stopping);
   }
 
   if (fs.existsSync(deps.paths.plistPath)) {

package/src/sessions.mjs

@@ -6,9 +6,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { deps } from './internals.mjs';
-import {
-  SESSION_IDLE_SECONDS,
-} from './constants.mjs';
 
 // pid 是否对应活进程。走到这儿的 pid 已经过入口范围校验。
 export function alive(pid) {
@@ -88,6 +85,15 @@ export function buildChildEnv(parentEnv) {
   return env;
 }
 
+// 日志保留一代（.1）：删旧代后把现役改名顶上。「.1」命名与 rm-先-于-
+// rename 的顺序是两处调用（会话 typescript、launchd 巡检日志）共同的承重
+// 约定——script(1) 打开即截断、launchd 按路径重开，轮转失败都不阻断调用方。
+export function rotateOnce(file) {
+  const old = `${file}.1`;
+  fs.rmSync(old, { force: true });
+  fs.renameSync(file, old);
+}
+
 // 拉起一个 detached 的 pty TUI，返回 {pid, procStart}。
 export function spawnSession(ws) {
   const logPath = sessionLogPath(ws);
@@ -102,11 +108,7 @@ export function spawnSession(ws) {
   // 一代（.1）——总量上界两代，活着的一代增长再快也只影响自身，不会经
   // 轮转放大。
   try {
-    if (fs.existsSync(logPath)) {
-      const old = `${logPath}.1`;
-      fs.rmSync(old, { force: true });
-      fs.renameSync(logPath, old);
-    }
+    if (fs.existsSync(logPath)) rotateOnce(logPath);
   } catch {
     // 轮转失败不阻断拉起。
   }
@@ -165,12 +167,14 @@ export async function stopSession(ent) {
   }
 }
 
-// typescript 多少秒没被写。文件缺失读作「没有活动证据」，不挡轮转。
+// typescript 多少秒没被写。文件缺失读作「没有任何活动证据」：Infinity 大
+// 于任何静默阈值，天然不挡换代与回收（哨兵值曾绑定 SESSION_IDLE_SECONDS
+// + 1，阈值调低后会悄悄翻转语义）。
 export function sessionLogIdleSeconds(logPath, cur) {
   try {
     return Math.max(0, cur - Math.floor(fs.statSync(logPath).mtimeMs / 1000));
   } catch {
-    return SESSION_IDLE_SECONDS + 1;
+    return Infinity;
   }
 }
 

package/src/tasks.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps } from './internals.mjs';
+import { deps, isPlainObject } from './internals.mjs';
 import { TASK_REL } from './paths.mjs';
 import {
   PRUNE_DIRS,
@@ -20,7 +20,7 @@ export function expandHome(p) {
   return p; // ~user 形式不支持（macOS 实践中不会出现）
 }
 
-function isDir(p) {
+export function isDir(p) {
   try {
     return fs.statSync(p).isDirectory();
   } catch {
@@ -36,22 +36,33 @@ function realpathOrNull(p) {
   }
 }
 
+// 宽容版 realpath：失败时退回词法绝对路径（输入须已绝对）。与
+// realpathOrNull 的「失败即 null」是两种降级口径：会话登记匹配（registry）
+// 与日志定位（logs）要的是一个还能用的路径，而不是 null。
+export function lexReal(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+// 任务文件是否还在：readTasks 读出 null 时区分「文件已消失」（一次性任务
+// 执行完被删的正常竞态）与「文件在但损坏」（要告警）。路径拼法归任务层，
+// 巡检与总览不必各自重建。
+export function taskFileExists(ws) {
+  return fs.existsSync(path.join(ws, TASK_REL));
+}
+
 // 路径在磁盘上真实存储的大小写形态；任何一段读不出时原样返回。
 // macOS 默认文件系统大小写不敏感，而 realpath 不规范化大小写：敲错大小
 // 写的路径照样通过 isDirectory，却与会话登记里真实大小写的 cwd 永远匹配
 // 不上。在扫描边界认回一次真实写法，下游就不必各自提防。
 export function onDiskCase(p) {
-  const parts = [];
-  let cur = path.resolve(p).replace(/\/+$/, '') || '/';
-  while (true) {
-    const head = path.dirname(cur);
-    const tail = path.basename(cur);
-    if (!tail || head === cur) break;
-    parts.push(tail);
-    cur = head;
-  }
-  // cur 停在根，自顶向下逐段认回磁盘上的真实条目名。
-  for (const name of parts.reverse()) {
+  // resolve 的输出不含双斜杠与尾部斜杠（根除外），按段拆开自顶向下认回。
+  const parts = path.resolve(p).split('/').filter(Boolean);
+  let cur = '/';
+  for (const name of parts) {
     let entries;
     try {
       entries = fs.readdirSync(cur);
@@ -91,16 +102,19 @@ export function* discover(roots, maxDepth) {
         ? []
         : entries.filter((e) => e.isDirectory() && !PRUNE_DIRS.has(e.name));
       const candidate = path.join(dirpath, TASK_REL);
-      const ws = realpathOrNull(dirpath);
       let isFile = false;
       try {
         isFile = fs.statSync(candidate).isFile();
       } catch {
-        isFile = false;
+        // 不存在按非文件处理。
       }
-      if (ws && isFile && !seen.has(ws)) {
-        seen.add(ws);
-        yield [ws, candidate];
+      // 先判有没有任务文件再 realpath：绝大多数目录没有，省一次 syscall。
+      if (isFile) {
+        const ws = realpathOrNull(dirpath);
+        if (ws && !seen.has(ws)) {
+          seen.add(ws);
+          yield [ws, candidate];
+        }
       }
       for (const d of subdirs) {
         yield* walk(path.join(dirpath, d.name));
@@ -110,10 +124,6 @@ export function* discover(roots, maxDepth) {
   }
 }
 
-function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-
 // 读一个工作区的任务列表，坏形状一律返回 null。
 export function readTasks(ws) {
   let doc;
@@ -245,11 +255,11 @@ export function minifyIds(tasks) {
 }
 
 // 一轮巡检对一个任务文件做的维护：renew（补 permanent）与 minify（id 改
-// 小）合并为同一次受 mtime 乐观锁保护的原子写。外壳与旧 renewWorkspace
-// 完全一致：先取 mtimeNs、清残留 .cron-up-tmp、loadTaskDoc round-trip 整
-// 文档；两项计数都为 0 时字节级不动。返回 {renewed,minified}；null 表示
-// 文件缺失/损坏；读到写间被改抛 TaskFileChanged。
-export function maintainWorkspace(taskfile, { renew = false, minify = false } = {}) {
+// 小）合并为同一次受 mtime 乐观锁保护的原子写。先取 mtimeNs、清残留
+// .cron-up-tmp、loadTaskDoc round-trip 整文档；两项计数都为 0 时字节级
+// 不动。返回 {renewed,minified}；null 表示文件缺失/损坏；读到写间被改抛
+// TaskFileChanged。
+export function maintainWorkspace(taskfile, { renew = false, minify = false }) {
   let mtimeNs;
   try {
     mtimeNs = fs.statSync(taskfile, { bigint: true }).mtimeNs;
@@ -285,10 +295,4 @@ export function maintainWorkspace(taskfile, { renew = false, minify = false } =
   return { renewed, minified };
 }
 
-// 手动 renew 的薄封装：只补 permanent（不改 id），保持 null/0/N 三态契约。
-export function renewWorkspace(taskfile) {
-  const r = maintainWorkspace(taskfile, { renew: true });
-  return r === null ? null : r.renewed;
-}
-
 Object.assign(deps, { discover, readTasks, loadTaskDoc });