cron-up 26.10.34 → 26.10.35

package/CONTRIBUTING.md

@@ -26,11 +26,12 @@ CI 在 macOS 上分别使用 Node 22、24 运行全部测试。需要本机联
 
 ## 文档同步要求
 
-用户可观察行为变化时，至少检查以下位置，避免命令、README 和实现各自描述一套口径：
+用户可观察行为或维护者操作边界变化时，至少检查以下位置，避免命令、文档和实现各自描述一套口径：
 
 | 变化 | 需要同步的位置 |
 | --- | --- |
 | 产品范围、安装、日常使用、限制、卸载或数据保留 | `README.md` |
+| 维护者可操作的机器范围或自动化执行边界 | 根目录 `CLAUDE.md`；相关流程只引用该节，不复制机器名单 |
 | 命令、选项、升级步骤或帮助文案 | `src/cli.mjs`，必要时包括 `src/overview.mjs` |
 | npm 包定位 | `package.json` 的 `description` |
 | 内部机制、生命周期常量、兼容性证据或投递算法 | `docs/internals.md` |

package/docs/migration.md

@@ -26,7 +26,7 @@
 为防止 pid 复用导致误杀，缺少进程启动指纹的旧条目不会被贸然发信号：
 
 - 对应进程已经退出时，不再需要停止它
-- 对应进程仍在运行且无法安全核实时，巡检会明确告警，不会把“未停止”记成“已回收”
+- 对应进程仍在运行且无法安全核实时，巡检会明确告警并保留旧状态，在后续轮次重试，不会把“未停止”记成“已回收”
 - 出现这类告警时，先用 `cron-up logs` 找到“旧版迁移”条目，记录其中的 pid、工作区或日志路径；旧版扁平状态不一定会出现在总览中
 - 再把下列命令中的 12345 换成实际 pid，核对进程启动时间、父进程和完整启动命令：
 

package/docs/release.md

@@ -60,7 +60,7 @@ npm 包设置中需要一次性登记：
 
 按 26.10.32 的实际发布记录，publish 成功后 registry 通常约两分钟可查，偶发需要七八分钟；带 provenance 时还要等待透明日志与后端入库，本机元数据缓存可能进一步滞后
 
-对每一台已有安装的机器分别执行：
+先按仓库根目录 `CLAUDE.md` 的「使用边界」确定本次允许操作的机器，再对范围内每一台已有安装的机器分别执行：
 
 ```bash
 npm i -g cron-up@<新版本> --prefer-online

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cron-up",
-  "version": "26.10.34",
+  "version": "26.10.35",
   "description": "为 Claude Code 定时任务在触发前按需预热交互会话",
   "type": "module",
   "bin": {

package/src/config.mjs

@@ -10,6 +10,7 @@ import {
   isPlainObject,
   isDecInt,
   ensurePrivateDir,
+  setOwn,
 } from './internals.mjs';
 import { PID_T_MAX, HEARTBEAT_STALE_FACTOR } from './constants.mjs';
 import { expandHome, isDir } from './tasks.mjs';
@@ -175,9 +176,9 @@ export function loadState() {
     const cleanBucket = {};
     for (const [taskId, raw] of Object.entries(bucket)) {
       const ent = cleanEntry(raw, ws, taskId);
-      if (ent) cleanBucket[taskId] = ent;
+      if (ent) setOwn(cleanBucket, taskId, ent);
     }
-    if (Object.keys(cleanBucket).length > 0) out[ws] = cleanBucket;
+    if (Object.keys(cleanBucket).length > 0) setOwn(out, ws, cleanBucket);
   }
   return out;
 }

package/src/cron.mjs

@@ -48,7 +48,9 @@ export function parseCronField(expr, lo, hi) {
       start = lo;
       end = hi;
     } else if (rng.includes('-')) {
-      const [a, b] = rng.split('-');
+      const bounds = rng.split('-');
+      if (bounds.length !== 2) throw new Error(`cron 区间格式无效：${rng}`);
+      const [a, b] = bounds;
       start = strictInt(a);
       end = strictInt(b);
     } else {
@@ -173,7 +175,7 @@ export class Cron {
 // CronCreate 产生的一次性任务形状像 'M H DoM Mon *'，作为没有 recurring
 // 标志时的兜底识别法。
 function cronLooksOneshot(expr) {
-  const parts = expr.split(/\s+/);
+  const parts = expr.trim().split(/\s+/);
   return parts.length === 5 && parts[4] === '*'
     && parts.slice(0, 4).every((p) => /^\d+$/.test(p));
 }

package/src/internals.mjs

@@ -26,6 +26,23 @@ export function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
 
+// state 的桶键来自外部任务 id。普通对象的 __proto__ 赋值会改原型而不是
+// 建条目，读取还会把继承来的 Object.prototype 当成 entry；所有外部键都
+// 通过自有属性访问，保持 JSON 形状不变，也无需特殊的任务 id 黑名单。
+export function getOwn(obj, key) {
+  return obj != null && Object.hasOwn(obj, key) ? obj[key] : undefined;
+}
+
+export function setOwn(obj, key, value) {
+  Object.defineProperty(obj, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+  return value;
+}
+
 // 严格十进制整数（可选负号 + 纯数字）：parseInt("5x")、Number("0x10") 都会
 // 静默给出错误结果，来自外部字符串的整数一律先过这个谓词再 parseInt。
 export function isDecInt(s) {

package/src/list.mjs

@@ -1,7 +1,7 @@
 // `cron-up list`：逐工作区列出任务的下次触发、节奏、类型、摘要与该任务
 // 的预热状态。
 
-import { deps } from './internals.mjs';
+import { deps, getOwn } from './internals.mjs';
 import { LEAD_SECONDS } from './constants.mjs';
 import { loadConfig, loadState, isCooling } from './config.mjs';
 import { taskKey } from './tasks.mjs';
@@ -70,7 +70,7 @@ export async function cmdList(args) {
       return {
         v,
         t,
-        tag: warmTag(t, v, state[ws]?.[taskKey(t)], liveSids, ws, cur),
+        tag: warmTag(t, v, getOwn(state[ws], taskKey(t)), liveSids, ws, cur),
       };
     });
     // 错过待补执行排最前，然后按下次时间升序，一年内无安排的垫底，无效
@@ -96,6 +96,9 @@ export async function cmdList(args) {
 
   blocks.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
   deps.print(`共 ${blocks.length} 个工作区、${total} 个定时任务`);
+  if (unreadable > 0) {
+    deps.print(`另有 ${unreadable} 个任务文件读不出，其中的定时任务不会执行`);
+  }
 
   // 列宽从全部实际文案动态算；cadence 是截断列，取固定上限。
   const statusW = Math.max(11,

package/src/logs.mjs

@@ -77,5 +77,8 @@ export function cmdLogs(args) {
   tailArgs.push(file);
   const r = deps.spawnSync('/usr/bin/tail', tailArgs, { stdio: 'inherit' });
   if (r.error) throw r.error;
-  if (r.status && r.status !== 0) throw new ExitError(r.status);
+  if (r.signal) {
+    throw new ExitError(1, `日志查看进程被信号 ${r.signal} 终止`);
+  }
+  if (r.status !== 0) throw new ExitError(r.status ?? 1);
 }

package/src/overview.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { deps, packageVersion } from './internals.mjs';
+import { deps, packageVersion, getOwn } from './internals.mjs';
 import {
   INTERVAL_SECONDS,
   LEAD_SECONDS,
@@ -87,7 +87,7 @@ function overviewTasks(cfg, cols, details, state) {
       // 承接，都不是异常；否则按 entry 的冷却/失败状态给一条可执行的告
       // 警。
       const key = taskKey(t);
-      const ent = state[ws]?.[key];
+      const ent = getOwn(state[ws], key);
       if (deps.creatorSessionAlive(t, liveSids) || entryHolds(ent, details, ws)) {
         continue;
       }

package/src/patrol.mjs

@@ -10,7 +10,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
-import { deps, packageVersion, isPlainObject } from './internals.mjs';
+import {
+  deps,
+  packageVersion,
+  isPlainObject,
+  getOwn,
+  setOwn,
+} from './internals.mjs';
 import {
   FAIL_LIMIT,
   COOLDOWN_SECONDS,
@@ -41,6 +47,7 @@ import {
   TaskFileChanged,
   taskFileExists,
   groupTasksByKey,
+  taskOwnedBy,
 } from './tasks.mjs';
 import { taskWanted, parseCronOrNone, wantedNow } from './cron.mjs';
 import {
@@ -381,7 +388,7 @@ export async function patrolWorkspace(
   for (const [key, group] of taskGroups) {
     if (group.length !== 1) continue;
     const t = group[0];
-    let ent = bucket[key] ?? null;
+    let ent = getOwn(bucket, key) ?? null;
     const logPath = sessionLogPath(ws, key);
     const ownerIsOurs = entryClaimed(ent)
       && typeof t.createdBySessionId === 'string'
@@ -476,9 +483,9 @@ export async function patrolWorkspace(
     // 盖印（跨轮老条目）：已认亲且任务归属还没盖到本代预热（活创建者
     // 已在 (a) 排除）。当轮新 spawn 的会话在第三步之后的轮内等待里认
     // 亲，由 cmdRun 的 stampClaimed 补盖，不走这里。
-    if (entryClaimed(ent)
-        && (!t.createdBySessionId || t.createdBySessionId !== ent.sessionId)) {
-      stamps.set(key, reownTarget(ent));
+    if (entryClaimed(ent)) {
+      const target = reownTarget(ent);
+      if (!taskOwnedBy(t, target)) stamps.set(key, target);
     }
 
     // warm 未到回收 / spawning 宽限内：本轮无事。
@@ -496,15 +503,15 @@ export async function patrolWorkspace(
     }
 
     if (fails >= FAIL_LIMIT) {
-      bucket[key] = {
+      const next = setOwn(bucket, key, {
         ...ent,
         ws,
         taskId: key,
         pid: null,
         fails,
         log: ent?.log ?? logPath,
-      };
-      enterCooldown(bucket[key], ws, key, fails, cur, stats);
+      });
+      enterCooldown(next, ws, key, fails, cur, stats);
       continue;
     }
 
@@ -520,7 +527,7 @@ export async function patrolWorkspace(
           scriptProcLogPath(procArgs) === logPath && deps.alive(procPid));
       if (adopted) {
         const [procPid] = adopted;
-        bucket[key] = {
+        setOwn(bucket, key, {
           ws,
           taskId: key,
           pid: procPid,
@@ -528,7 +535,7 @@ export async function patrolWorkspace(
           procStart: deps.procStartedAt(procPid),
           fails: 0,
           log: logPath,
-        };
+        });
         note('adopt', `接管 ${ws} 任务 ${key} pid=${procPid}：state 记录缺失，`
           + '但进程表里仍有本该任务的预热会话，重新纳入跟踪');
         pending.push({ ws, key, pid: procPid });
@@ -542,25 +549,25 @@ export async function patrolWorkspace(
     if (spawned?.pid == null) {
       const newFails = fails + 1;
       if (newFails >= FAIL_LIMIT) {
-        bucket[key] = {
+        const next = setOwn(bucket, key, {
           ws, taskId: key, pid: null, fails: newFails, log: logPath,
-        };
-        enterCooldown(bucket[key], ws, key, newFails, cur, stats);
+        });
+        enterCooldown(next, ws, key, newFails, cur, stats);
         continue;
       }
-      bucket[key] = {
+      setOwn(bucket, key, {
         ws,
         taskId: key,
         pid: null,
         startedAt: cur,
         fails: newFails,
         log: logPath,
-      };
+      });
       note('fail', `启动失败 ${ws} 任务 ${key}：会话进程没有拉起`
         + `（连续失败计数 ${newFails}）`);
       continue;
     }
-    bucket[key] = {
+    setOwn(bucket, key, {
       ws,
       taskId: key,
       pid: spawned.pid,
@@ -568,7 +575,7 @@ export async function patrolWorkspace(
       procStart: spawned.procStart,
       fails,
       log: logPath,
-    };
+    });
     note('spawn', `已启动 ${ws} 任务 ${key} pid=${spawned.pid}`
       + `（连续失败计数 ${fails}）`);
     pending.push({ ws, key, pid: spawned.pid });
@@ -588,8 +595,9 @@ export async function patrolWorkspace(
     }
     throw e;
   }
-  // 与 readTasks 不一致的极端竞态：保守不动，新 spawn 也全留跨轮路径。
-  if (result === null) return [];
+  // 与 readTasks 不一致的极端竞态：维护保守不动，但本轮新 spawn 仍要进入
+  // 等待认亲与补盖流程；丢掉 pending 会把同轮收尾无故推迟到下一轮。
+  if (result === null) return pending;
   if (result.renewed) {
     deps.log(`已续期 ${ws}：${result.renewed} 个周期任务标记为 permanent，`
       + '不再受 7 天过期限制');
@@ -628,7 +636,7 @@ async function awaitWarmups(pending, state, cur, stats) {
   const recognize = () => {
     const rest = [];
     for (const p of pending) {
-      const ent = state[p.ws]?.[p.key];
+      const ent = getOwn(state[p.ws], p.key);
       if (!ent || ent.pid !== p.pid) continue;
       if (!deps.trackedAlive(ent)) {
         // 启动即崩的典型窗口：真拉起过却死掉，计一次失败并置空 pid，条
@@ -696,10 +704,12 @@ function stampClaimed(claimedByWs, taskfiles, stats) {
 // 拉）；state.json 已丢的旧孤儿 script（日志是旧命名，不含任务键段）从
 // 进程表兜底清扫。只在 loadLegacyEntries 非空（确在跨版本）时执行。
 async function retireLegacy(legacy, stats) {
+  let retired = true;
   for (const ent of legacy) {
     if (deps.trackedAlive(ent)) {
       const stopped = await deps.stopSession(ent);
       if (!stopped) {
+        retired = false;
         bump(stats, 'warn');
         deps.log(`旧版迁移暂缓 ${ent.ws} pid=${ent.pid}：记录的进程仍存活，`
           + '本次无法安全停止目录级预热会话；本次不记为已回收');
@@ -721,6 +731,7 @@ async function retireLegacy(legacy, stats) {
     if (!deps.trackedAlive(ent)) continue;
     const stopped = await deps.stopSession(ent);
     if (!stopped) {
+      retired = false;
       bump(stats, 'warn');
       deps.log(`旧版迁移暂缓 pid=${pid}：记录的进程仍存活，本次无法安全停止`
         + `目录级预热孤儿会话（日志 ${file}）；本次不记为已回收`);
@@ -730,6 +741,7 @@ async function retireLegacy(legacy, stats) {
         + '升级后按任务重新预热');
     }
   }
+  return retired;
 }
 
 // 跑一轮巡检；抢不到锁返回 false。
@@ -793,8 +805,9 @@ export async function cmdRun(args) {
       deps.log(`告警：${registryAlert}`);
     }
 
-    // 旧版收尾必须先于一切 spawn 决策（state 轮末被新形状整体覆盖）。
-    if (legacy.length > 0) await retireLegacy(legacy, stats);
+    // 旧版收尾必须先于一切 spawn 决策。停止失败时轮末保留原 state，下轮
+    // 才能继续重试；本轮新会话可由任务专属日志认领，不会因未落盘而重拉。
+    const legacyRetired = legacy.length === 0 || await retireLegacy(legacy, stats);
 
     // 轮初把上轮末仍相信活着的条目分成三组：活、resume 脱离（script 已
     // 死但 sid 还在，不报退出）、真死（立即报）。带 deadSince 的旧报条
@@ -865,7 +878,7 @@ export async function cmdRun(args) {
         for (const d of died) {
           bump(stats, 'exit');
           deps.log(exitLine(d.ws, d.key,
-            { ...state[d.ws]?.[d.key], pid: d.pid }));
+            { ...getOwn(state[d.ws], d.key), pid: d.pid }));
         }
         stampClaimed(claimedByWs, taskfiles, stats);
       } catch (e) {
@@ -894,27 +907,23 @@ export async function cmdRun(args) {
     for (const [ws, bucket] of Object.entries(state)) {
       const out = {};
       for (const [taskId, ent] of Object.entries(bucket)) {
-        if (deps.trackedAlive(ent)) {
-          out[taskId] = ent;
-          continue;
-        }
-        if (typeof ent.sessionId === 'string'
-            && sidInDetails(ws, ent.sessionId)) {
-          out[taskId] = ent;
-          continue;
-        }
-        if (isCooling(ent, cur)) {
-          out[taskId] = ent;
+        if (deps.trackedAlive(ent)
+            || (typeof ent.sessionId === 'string'
+              && sidInDetails(ws, ent.sessionId))
+            || isCooling(ent, cur)) {
+          setOwn(out, taskId, ent);
           continue;
         }
         if ((ent.fails ?? 0) > 0) {
           ent.deadSince ??= cur;
-          if (cur - ent.deadSince < FAIL_TTL_SECONDS) out[taskId] = ent;
+          if (cur - ent.deadSince < FAIL_TTL_SECONDS) {
+            setOwn(out, taskId, ent);
+          }
         }
       }
-      if (Object.keys(out).length > 0) kept[ws] = out;
+      if (Object.keys(out).length > 0) setOwn(kept, ws, out);
     }
-    saveState(kept);
+    if (legacyRetired) saveState(kept);
 
     // 轮末汇总：一行交代这轮看见了什么、动了什么、花了多久，随后更新心跳。
     const actions = EVENT_LABELS

package/src/service.mjs

@@ -292,7 +292,10 @@ function scriptPathDirs(scriptPath) {
 export function launcherHealth() {
   if (!fs.existsSync(deps.paths.plistPath)) return null;
   const args = readPlistProgramArgs();
-  if (!args || args.length !== 1) return null;
+  if (!args || args.length !== 1) {
+    return `LaunchAgent ${deps.paths.plistPath} 的 ProgramArguments 无法解读，`
+      + '重跑 cron-up install 覆盖重生成';
+  }
   const [scriptPath] = args;
   if (!fs.existsSync(scriptPath)) {
     return `launchd 配置中的启动脚本已失效（${path.basename(scriptPath)} `

package/src/tasks.mjs

@@ -235,6 +235,14 @@ export function atomicWriteJson(file, doc, expectedMtimeNs) {
   fs.renameSync(tmp, file);
 }
 
+// 任务归属是否已完全等于盖印目标。巡检预判与实际写入共用同一判据，
+// 避免一层只看 sessionId、另一层比较三字段而逐渐漂移。
+export function taskOwnedBy(t, target) {
+  return t.createdBySessionId === target.sessionId
+    && t.createdByPid === target.pid
+    && t.createdByProcStart === target.procStart;
+}
+
 // 一轮巡检对一个任务文件做的维护：renew（补 permanent）与 reown（把任务
 // 归属盖给各自的预热会话）合并为同一次带 mtime 乐观检测的原子写。先取
 // mtimeNs、清残留 .cron-up-tmp、loadTaskDoc round-trip 整文档；两项计数
@@ -244,8 +252,8 @@ export function atomicWriteJson(file, doc, expectedMtimeNs) {
 // reown 形状：Map<taskKey, {sessionId, pid, procStart}>。一轮内同一文件的
 // 不同任务可盖向不同预热（一任务一会话）；内容相同但 id 不同的任务互不
 // 影响。同一个 taskKey 对应多条任务是病态输入，无法把 state/会话唯一对应
-// 到条目，这些键全部跳过盖印。只盖 createdBySessionId 不等于目标的任务，
-// 第二轮起字节级不动；pid/procStart 是登记里 claude 进程的 pid 与 lstart。
+// 到条目，这些键全部跳过盖印。归属三字段未完全等于目标时才写，第二轮起
+// 字节级不动；pid/procStart 是登记里 claude 进程的 pid 与 lstart。
 export function maintainWorkspace(taskfile, { reown = null } = {}) {
   let mtimeNs;
   try {
@@ -284,7 +292,7 @@ export function maintainWorkspace(taskfile, { reown = null } = {}) {
       const target = reown.get(key);
       // 没有 owner 字段的外部条目同样盖——窗口内任务统一归各自预热，语义
       // 不因条目来源留例外。
-      if (target && t.createdBySessionId !== target.sessionId) {
+      if (target && !taskOwnedBy(t, target)) {
         t.createdBySessionId = target.sessionId;
         t.createdByPid = target.pid;
         // ps lstart 原文（含「Oct  8」双空格），原样取自会话登记。