cron-up 26.10.25 → 26.10.27

package/package.json

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

package/src/args.mjs

@@ -0,0 +1,36 @@
+// 子命令选项规格与选项名转换。独立于 cli：install 的「未生效参数」名单
+// （service.mjs）从同一张选项表派生，新增可持久化选项时两处自动同步。
+
+// 选项类型：string 吃一个值；int 吃一个值且必须是严格十进制；bool 是无值
+// 开关；tri 支持 --name / --no-name（install 的 auto-renew、auto-min-id）。
+export const SPECS = {
+  install: {
+    options: {
+      roots: 'string',
+      interval: 'int',
+      lead: 'int',
+      force: 'bool',
+      'auto-renew': 'tri',
+      'auto-min-id': 'tri',
+      'session-retain': 'string',
+    },
+  },
+  uninstall: {
+    options: {
+      purge: 'bool',
+      'keep-sessions': 'bool',
+    },
+  },
+  list: { options: {} },
+  run: { options: {} },
+  renew: { options: {} },
+  logs: {
+    options: { follow: 'bool', f: 'bool' },
+    positionalMax: 1,
+  },
+};
+
+// 选项名统一成代码里用的 camelCase（--keep-sessions → keepSessions）。
+export function thisCamel(name) {
+  return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}

package/src/cli.mjs

@@ -4,46 +4,18 @@
 
 // 先引全量入口，保证所有业务模块都已向 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';
 import { cmdOverview } from './overview.mjs';
 import { cmdLogs } from './logs.mjs';
+import { SPECS, thisCamel } from './args.mjs';
 
-// 选项类型：string 吃一个值；int 吃一个值且必须是严格十进制；bool 是无值
-// 开关；tri 支持 --name / --no-name（install 的 auto-renew、auto-min-id）。
-const SPECS = {
-  install: {
-    options: {
-      roots: 'string',
-      interval: 'int',
-      lead: 'int',
-      force: 'bool',
-      'auto-renew': 'tri',
-      'auto-min-id': 'tri',
-      'session-retain': 'string',
-    },
-  },
-  uninstall: {
-    options: {
-      purge: 'bool',
-      'keep-sessions': 'bool',
-    },
-  },
-  list: { options: {} },
-  run: { options: {} },
-  renew: { options: {} },
-  logs: {
-    options: { follow: 'bool', f: 'bool' },
-    positionalMax: 1,
-  },
-};
-
-// 严格十进制整数命令行值：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);
@@ -102,11 +74,6 @@ function consumeOption(tok, tokens, i, spec, opts) {
   return inlineValue !== undefined ? i + 1 : i + 2;
 }
 
-// 选项名统一成代码里用的 camelCase（--keep-sessions → keepSessions）。
-function thisCamel(name) {
-  return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-}
-
 export function parseCli(argv) {
   let command = null;
   const opts = {};
@@ -157,7 +124,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,15 @@
 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,
+  ensurePrivateDir,
+} 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 +28,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) {
@@ -35,18 +37,31 @@ export function isInt(x) {
 // 宽容整型化（手改的 state/登记文件里字段可能是字符串或浮点）：纯十进制
 // 字符串接受，浮点截断，布尔拒绝；非法输入抛错由调用方按「字段不存在」
 // 处理。
-export function lenientInt(v) {
+function lenientInt(v) {
   if (typeof v === 'boolean') throw new Error('布尔不是整数字段');
   if (typeof v === 'number') {
     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 +151,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 {
@@ -157,18 +166,11 @@ export function loadState() {
   return out;
 }
 
-// 自产物按私密收紧（与会话日志、任务文件写入同一纪律）：state 含工作区路
-// 径与 pid，多用户机器上不给其他账号读面。chmod 顺带收回老版本留下的宽松
-// 权限——state 每轮都写、config 每次 install 都写，存量会自动跟进；失败维
-// 持现状。
+// state 含工作区路径与 pid，目录按 ensurePrivateDir 收紧；文件以 0600 原
+// 子替换——state 每轮都写、config 每次 install 都写，老版本留下的宽松权
+// 限会自动跟进。
 function atomicSave(file, doc) {
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, { recursive: true });
-  try {
-    fs.chmodSync(dir, 0o700);
-  } catch {
-    // 维持现状。
-  }
+  ensurePrivateDir(path.dirname(file));
   const tmp = `${file}.tmp`;
   // 以 0600 创建；残留的旧 tmp 更宽时也收回来，rename 保持该模式位。
   fs.writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, {
@@ -205,6 +207,23 @@ 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;
+}
+
+// 失败冷却的唯一判据：cooldownUntil 是秒级时间戳，0/缺省表示无冷却。巡检
+// 决策、kept 过滤与总览展示共用，冷却表示法只渗到这两个函数。
+export function isCooling(ent, cur) {
+  return (ent?.cooldownUntil ?? 0) > cur;
+}
+
+// 距冷却结束还有多少整分钟（已结束为 0），只用于总览文案。
+export function cooldownEtaMinutes(ent, cur) {
+  return Math.max(0, Math.floor(((ent?.cooldownUntil ?? 0) - cur) / 60));
+}
+
 export function saveConfig(cfg) {
   atomicSave(deps.paths.configPath, cfg);
 }
@@ -224,13 +243,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,7 +100,7 @@ export const CC_JITTER = {
 // maxN，常量只保留「目标延迟」这一个可调项。
 export const AUTO_MIN_ID_TARGET_DELAY_MS = 60 * 1000;
 
-// 投递尾窗判定的回看/前探窗口（wanted 与 predictedFire 共用，见
+// 投递尾窗判定的回看/前探窗口（wanted 与 nextDelivery 共用，见
 // src/cron.mjs 的 recurringTailWindow）：找上一落点用 prevAtOrBefore、算
 // 周期用 nextAfter，两个方向都要罩住月/年任务之外的 2 月 29 日——相邻落
 // 点隔 4 年，世纪非闰年（2100）隔 8 年；窗口小了尾窗会塌缩成零：落点已
@@ -111,5 +113,3 @@ export const SEARCH_DAYS = 7;
 // list/总览回答「下次何时触发」，要看到一年后：年度任务必须显示真实日期，
 // 不能误报成「无安排」。nextAfter 的日历快进让长窗口依然便宜。
 export const DISPLAY_SEARCH_DAYS = 366;
-// list 问「一次性任务是否被错过」，与巡检同一个补执行判定，只是不带前瞻。
-export const ZERO_LEAD_MS = 0;

package/src/cron.mjs

@@ -7,14 +7,15 @@ import {
   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);
 }
 
@@ -126,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);
@@ -162,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));
@@ -212,8 +213,7 @@ 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 分）。落点已过、抖动投递时刻未到的这段「投递尾窗」里会话仍必须在
@@ -244,41 +244,41 @@ 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 h = taskIdHash(task?.id);
-
+// 任务在展示语境里的「落点 → 预计实际投递」对：一次性任务是落点加网格
+// 提前量；周期任务在投递尾窗内属于上一落点（即将到来的这次延迟投递，
+// 不是 nextAfter 给出的下个落点——后者严格在未来，会把展示拐到明天），
+// 否则是下一落点 + 按 id 的抖动。先于窗口检查尾窗：2 月 29 日这类长周期
+// 任务的下一落点可能在展示窗口之外，正在等待的投递却依然成立。taskView
+// 的 nxt/fire 与 wanted 都以这里的落点为单一来源，两边不会各说各话。返回
+// {slot, fire}，均为 Date 或 null（窗口内没有落点时双双为 null）。cron 须
+// 已解析且 satisfiable。
+export function nextDelivery(cron, task, now, withinDays = DISPLAY_SEARCH_DAYS) {
   if (taskIsOneshot(task)) {
-    const i = cron.nextAfter(now, withinDays);
-    if (i === null) return null;
+    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())) };
   }
 
-  // 尾窗内的周期任务：下一次真实投递是「上一落点 + 抖动」，数分钟内就
-  // 到，不是 nextAfter 给出的下个落点——后者严格在未来，会把展示拐到明
-  // 天（list 的落点列由 taskView 用 recurringTailWindow 对齐同一落点）。
-  // 先于窗口检查：2 月 29 日这类长周期任务的下一落点可能在展示窗口之
-  // 外，正在等待的投递却依然成立。
   const tail = recurringTailWindow(cron, task?.id, now);
-  if (tail !== null) return new Date(tail[1]);
+  if (tail !== null) return { slot: tail[0], fire: new Date(tail[1]) };
 
-  const i = cron.nextAfter(now, withinDays);
-  if (i === null) return null;
+  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 秒。日/周/月任务周期远大于此，不
@@ -287,7 +287,7 @@ export function predictedFire(task, now, withinDays = DISPLAY_SEARCH_DAYS) {
 
 // 周期任务从某个落点起的投递延迟（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();
@@ -299,9 +299,9 @@ export function recurringDelayMs(cron, slot, taskId, withinDays = SEARCH_DAYS) {
 
 // 周期任务的「投递尾窗」判定：上一落点已过、按 id 算的延迟投递时刻未
 // 到。返回 [落点, 投递时刻 ms]；不在尾窗、找不到上一或下一落点返回
-// null。wanted（保活判定）与 predictedFire/taskView（展示）共用这一口径，
-// 两边不会各说各话；窗口取 TAIL_WINDOW_DAYS，理由见 constants。
-export function recurringTailWindow(cron, taskId, now) {
+// 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()

package/src/display.mjs

@@ -4,10 +4,8 @@ import {
   parseCronOrNone,
   taskIsOneshot,
   wanted,
-  predictedFire,
-  recurringTailWindow,
+  nextDelivery,
 } from './cron.mjs';
-import { DISPLAY_SEARCH_DAYS, ZERO_LEAD_MS } from './constants.mjs';
 
 // 等宽终端里的宽字符区间（CJK 文字、全角标点、谚文、常用 emoji）：启发式
 // 只覆盖任务摘要里真实出现的形态，区间外一律按 1 列——判错的代价仅是对
@@ -64,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) ?? '';
@@ -74,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) {
@@ -92,23 +90,21 @@ export function taskView(task, now, leadMs = undefined) {
   }
   const oneshot = taskIsOneshot(task);
   // nxt 按定义不晚于展示语境里的下一次投递，「已错过」完全由补执行判定
-  // 回答。
-  const missed = oneshot && wanted(cron, task, now, ZERO_LEAD_MS);
-  // 周期任务的投递尾窗内，即将到来的投递属于上一落点：展示落点对齐到
-  // 那个已过的 slot，箭头才画得出「09:00 → 09:30」，而不是从明天的落点
-  // 拐回来（2 月 29 日任务尾窗内 nextAfter 甚至找不到下一落点）。fire 与
-  // 落点同源，两边不会各说各话。
-  const tail = oneshot ? null : recurringTailWindow(cron, task?.id, now);
-  const nxt = tail ? tail[0] : cron.nextAfter(now, DISPLAY_SEARCH_DAYS);
+  // 回答：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 置 null，否则「一年内无」的判
     // 断和总览「最近」（fire ?? nxt）会把它当成明年同刻的安排。
-    nxt: missed ? null : 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，键的形状不随参数变化。
@@ -116,7 +112,7 @@ export function taskView(task, now, leadMs = undefined) {
     // 计入 Claude Code 投递抖动后的预计实际触发时刻；已错过的一次性任务
     // 没有未来触发，为 null；尾窗内的周期任务是即将到来的这次延迟投递。
     // 与 nxt 同为 Date 或 null。
-    fire: missed ? null : (tail ? new Date(tail[1]) : predictedFire(task, now)),
+    fire: missed ? null : fire,
   };
 }
 
@@ -126,11 +122,18 @@ function sameDay(a, b) {
     && a.getMonth() === b.getMonth()
     && a.getDate() === b.getDate();
 }
-function sameMinute(a, b) {
+// 「同一分钟」的唯一判据，fmtFireRange 的箭头省略与总览「设定」附注共用。
+export function sameMinute(a, b) {
   return sameDay(a, b) && a.getHours() === b.getHours()
     && a.getMinutes() === b.getMinutes();
 }
 
+// 两位数字补零：时间戳格式的公共零件，巡检日志的时间戳（patrol 的 log）
+// 也复用。
+export function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
 // 「设定落点 → 预计实际触发」文案。抖动四舍五入到秒（调度器秒级轮询）：
 // 同日省略第二个日期；预计值带非零秒时显示 HH:MM:SS（如 05:15:37）；落
 // 在同一分钟（无抖动）则只显示落点，不画无意义的箭头。
@@ -140,25 +143,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 secs = r.getSeconds() ? `:${pad2(r.getSeconds())}` : '';
   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())}${secs}`
+    : `${fmtMDHM(r)}${secs}`;
   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

@@ -6,7 +6,9 @@
 // 纯系统叶子的默认实现放这里；业务函数（discover、spawnSession…）由各自
 // 模块注册。
 
+import fs from 'node:fs';
 import { spawn, spawnSync, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { paths } from './paths.mjs';
 
 export class ExitError extends Error {
@@ -18,6 +20,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 = {}) {
@@ -52,6 +66,29 @@ function terminalWidth() {
   return Math.max(60, process.stdout.columns ?? 100);
 }
 
+// 自产物目录（state/config、会话日志）含工作区路径与会话记录，按私密收紧：
+// 建好后 chmod 0700，顺带收回老版本留下的宽松权限；失败维持现状。三处写入
+// 点共用这一条纪律。
+export function ensurePrivateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // 维持现状。
+  }
+}
+
+// 版本号读 package.json（用 fs 读而非 JSON import attribute，避免对 Node
+// 版本实验特性的依赖）；读不到返回 null，总览页降级显示。
+export function packageVersion() {
+  try {
+    const pkg = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(fs.readFileSync(pkg, 'utf-8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export const deps = {
   paths,
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),

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 若参与匹配，轮转过一次的工作区会永
@@ -47,12 +42,10 @@ export function resolveLogPath(workspace, announce) {
   const err = path.join(deps.paths.logDir, 'launchd.err.log');
   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}），巡检若异常先看它`);
+    const st = fs.statSync(err);
+    if (st.size > 0) {
+      say(`注：${err} 有内容（最后写入 ${fmtMDHM(st.mtime)}），`
+        + '巡检若异常先看它');
     }
   } catch {
     // err 不存在：无事。